/****************************************************************************/
/*	Copyright (c) 2006 Bendor Research Pty. Ltd.	All rights reserved.	*/
/*	Permission is granted to use this software for any purpose whatsoever	*/
/*	as long as this copyright notice is preserved. The code is provided		*/
/*	"as is", with no explicit, implicit or implied warranty or guarantee	*/
/*	of any kind and Bendor Research Pty. Ltd. can not be held liable for	*/
/*	any loss or damages arising out of the use of this software.			*/
/****************************************************************************/
/*																			*/
/*	Hex file interface														*/
/*	~~~~~~~~~~~~~~~~~~														*/
/*																			*/
/*	2006 Mar	ZK		Original											*/
/*																			*/
/****************************************************************************/

#ifndef __HEXIO_H__
#define	__HEXIO_H__

/*
*	A record descriptor
*	~~~~~~~~~~~~~~~~~~~
*	This descriptor is used for all I/O to/from the hex file.
*
*	If you are reading from the file, then you fill the structure
*	as follows:

*			data:	Pointer to a 255 byte buffer. If the pointer is NULL,
*					then the data will not be stored but it will otherwise
*					be processed and the return fields in the struct filled.
*
*		When the call returs, you will get:
*
*			addr:	The address of the first byte of the record
*			rlen:	The number of bytes in the record
*			line:	The line number in the file that supplied this record
*
*	If you are writing to the file, then you have to fill the structure
*	completely:
*
*			data:	Pointer to a block of data you want to write into the file
*			addr:	The address of the first byte of the block
*			rlen:	The number of bytes you want to write (can be any number)
*			line:	The max. number of chars per line (>=16)
*
*		When the call returs, you will get:
*
*			line:	The number of lines written into the file so far.
*
*	The stat field of the record is privately owned by the hex I/O system
*	and you MUST NOT change it *ever*.
*/

typedef	struct {

	struct s_hexio	*stat;				/* Hex I/O state descriptor			*/
	unsigned char	*data;				/* Pointer to a data buffer			*/
	unsigned int	rlen;				/* Length of the data/record		*/
	unsigned int	addr;				/* Address of record				*/
	unsigned int	line;				/* Last line processed				*/

} HEXIO;

/*
*	Return codes for all hexio functions
*/

#define	HEXERR_OK		1				/* Everything went fine				*/
#define	HEXERR_DONE		0				/* Last record of file was read		*/
#define	HEXERR_OMEM		-1				/* Out of memory error				*/
#define	HEXERR_OPEN		-2				/* Error opening the file			*/
#define	HEXERR_FORM		-3				/* Hex record format violation		*/
#define	HEXERR_CSUM		-4				/* Hex record checksum error		*/
#define	HEXERR_MODE		-5				/* Wrong command for the mode		*/
#define	HEXERR_DEAD		-6				/* Already closed file				*/
#define	HEXERR_IEOF		-7				/* Illegal EOF in the hex file		*/
#define	HEXERR_RLEN		-8				/* Record length error				*/
#define	HEXERR_WERR		-9				/* Write error						*/

/*
*	Pointers to functions to excercise the hex I/O
*/

typedef	struct {

	/*
	*	Opens a hexfile for reading
	*	~~~~~~~~~~~~~~~~~~~~~~~~~~~
	*	Returns a negative error code if there was an error.
	*	Returns HEXERR_OK in case of success. In that case the HEXIO
	*	object pointed by recp is also prepared. If the 'data' field
	*	of *recp was set to non-NULL, then if the S-record file had
	*	an S0 record, its content will be presented as the data. If
	*	the data field was set to NULL, then the content of the S0
	*	record (if present) is discarded.
	*/

	int		(*open)( HEXIO *recp, const char *name );

	/*
	*	Reads a data record from the hexfile
	*	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
	*	Returns a negative error code if there was an error.
	*	Returns HEXERR_DONE if an end record was read (or EOF was reched),
	*	in that case the addr field of the record structure is set to whatever
	*	address the end record specified.
	*	Returns HEXERR_OK if a data record was read.
	*/

	int		(*read)( HEXIO *recp );

	int		(*create)( HEXIO *recp, const char *name );

	int		(*write)( HEXIO *recp );
	int		(*close)( HEXIO *recp );

} HEXFUNC;

/*
*	Function set to deal with Motorola S-record files
*/

extern	const	HEXFUNC		srec_func;

/*
*	Function set to deal with Intel hex files
*/

extern	const	HEXFUNC		ihex_func;

#endif

