srecord.h File Reference

Low-level utility functions to create, read, write, and print Motorola S-Record binary records. License: Public Domain. More...

#include <stdio.h>
#include <stdlib.h>
#include <string.h>

Data Structures
struct	_SRecord
Typedefs
typedef _SRecord	SRecord
Enumerations
enum	SRecordErrors {   SRECORD_OK = 0, SRECORD_ERROR_FILE = -1, SRECORD_ERROR_EOF = -2, SRECORD_ERROR_INVALID_RECORD = -3,   SRECORD_ERROR_INVALID_ARGUMENTS = -4 }
enum	SRecordTypes {   SRECORD_TYPE_S0 = 0, SRECORD_TYPE_S1, SRECORD_TYPE_S2, SRECORD_TYPE_S3,   SRECORD_TYPE_S4, SRECORD_TYPE_S5, SRECORD_TYPE_S6, SRECORD_TYPE_S7,   SRECORD_TYPE_S8, SRECORD_TYPE_S9 }
Functions
int	New_SRecord (int type, uint32_t address, uint8_t data[], int dataLen, SRecord *srec)
int	Read_SRecord (SRecord *srec, FILE *in)
int	Write_SRecord (const SRecord srec, FILE *out)
void	Print_SRecord (const SRecord srec)
uint8_t	Checksum_SRecord (const SRecord srec)

---

Detailed Description

Low-level utility functions to create, read, write, and print Motorola S-Record binary records. License: Public Domain.

Author:

Vanya A. Sergeev <vsergeev@gmail.com>

Date:

December 24 2006

Version:

1.0.0

---

Typedef Documentation

typedef struct _SRecord SRecord

Alias "SRecord" for struct _SRecord, done for convenience and clarity.

---

Enumeration Type Documentation

enum SRecordErrors

All possible error codes the Motorola S-Record utility functions may return.

Enumerator:

SRECORD_OK	Error code for success or no error.
SRECORD_ERROR_FILE	Error code for error while reading from or writing to a file. You may check errno for the exact error if this error code is encountered.
SRECORD_ERROR_EOF	Error code for encountering end-of-file when reading from a file.
SRECORD_ERROR_INVALID_RECORD	Error code for error if an invalid record was read.
SRECORD_ERROR_INVALID_ARGUMENTS	Error code for error from invalid arguments passed to function.

enum SRecordTypes

Motorola S-Record Types S0-S9

Enumerator:

SRECORD_TYPE_S0	Header record, although there is an official format it is often made proprietary by third-parties. 16-bit address normally set to 0x0000 and header information is stored in the data field. This record is unnecessary and commonly not used.
SRECORD_TYPE_S1	Data record with 16-bit address
SRECORD_TYPE_S2	Data record with 24-bit address
SRECORD_TYPE_S3	Data record with 32-bit address
SRECORD_TYPE_S4	Extension by LSI Logic, Inc. See their specification for more details.
SRECORD_TYPE_S5	16-bit address field that contains the number of S1, S2, and S3 (all data) records transmitted. No data field.
SRECORD_TYPE_S6	24-bit address field that contains the number of S1, S2, and S3 (all data) records transmitted. No data field.
SRECORD_TYPE_S7	Termination record for S3 data records. 32-bit address field contains address of the entry point after the S-Record file has been processed. No data field.
SRECORD_TYPE_S8	Termination record for S2 data records. 24-bit address field contains address of the entry point after the S-Record file has been processed. No data field.
SRECORD_TYPE_S9	Termination record for S1 data records. 16-bit address field contains address of the entry point after the S-Record file has been processed. No data field.

---

Function Documentation

uint8_t Checksum_SRecord

(

const SRecord

srec

)

Calculates the checksum of a Motorola S-Record SRecord structure. See the Motorola S-Record specifications for more details on the checksum calculation.

Parameters:

srec

The Motorola S-Record structure that the checksum will be calculated of.

Returns:

The 8-bit checksum.

int New_SRecord	(	int	type,
		uint32_t	address,
		uint8_t	data[],
		int	dataLen,
		SRecord *	srec
	)

Sets all of the record fields of a Motorola S-Record structure.

Parameters:

	type	The Motorola S-Record type (integer value of 0 through 9).
	address	The 32-bit address of the data. The actual size of the address (16-,24-, or 32-bits) when written to a file depends on the S-Record type.
	data	The 8-bit array of data.
	dataLen	The size of the 8-bit data array.
	srec	A pointer to the target Motorola S-Record structure where these fields will be set.

Returns:

SRECORD_OK on success, otherwise one of the SRECORD_ERROR_ error codes.

Return values:

	SRECORD_OK	on success.
	SRECORD_ERROR_INVALID_ARGUMENTS	if srec does not point to a valid SRecord structure, or if the length of the 8-bit data array is out of range (less than zero or greater than the maximum data length allowed by record specifications, see SRecord.data).

void Print_SRecord

(

const SRecord

srec

)

Prints the contents of a Motorola S-Record structure to stdout. The record dump consists of the type, address, entire data array, and checksum fields of the record.

Parameters:

srec

The Motorola S-Record structure that will be printed to stdout.

Returns:

Always returns SRECORD_OK (success).

Return values:

SRECORD_OK

on success.

int Read_SRecord	(	SRecord *	srec,
		FILE *	in
	)

Reads a Motorola S-Record record from an opened file.

Parameters:

	srec	A pointer to the Motorola S-Record structure that will store the read record.
	in	A file pointer to an opened file that can be read.

Returns:

SRECORD_OK on success, otherwise one of the SRECORD_ERROR_ error codes.

Return values:

	SRECORD_OK	on success.
	SRECORD_ERROR_INVALID_ARGUMENTS	if srec does not point to a valid SRecord structure or the file pointer "in" is invalid.
	SRECORD_ERROR_EOF	if end-of-file has been reached.
	SRECORD_ERROR_FILE	if a file reading error has occured.
	SRECORD_INVALID_RECORD	if the record read is invalid (record did not match specifications or record checksum was invalid).

int Write_SRecord	(	const SRecord	srec,
		FILE *	out
	)

Writes a Motorola S-Record to an opened file.

Parameters:

	srec	The Motorola S-Record structure that will be written.
	in	A file pointer to an opened file that can be written to.

Returns:

SRECORD_OK on success, otherwise one of the SRECORD_ERROR_ error codes.

Return values:

	SRECORD_OK	on success.
	SRECORD_ERROR_INVALID_ARGUMENTS	if the file pointer "out" is invalid.
	SRECORD_ERROR_INVALID_RECORD	if the record's data length (the SRecord.dataLen variable of the record) is out of range (greater than the maximum data length allowed by record specifications, see SRecord.data).
	SRECORD_ERROR_FILE	if a file writing error has occured.

---