//
// ac_hexfile.h - functons for handling intel hex files
//
// Copyright (C) 2006  Nathan (Acorn) Pooley
// 
// This program is free software; you can redistribute it and/or
// modify it under the terms of the GNU General Public License
// version 2 as published by the Free Software Foundation.
// 
// This program is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU General Public License (gpl.txt) for more details. 
// 
// You should have received a copy of the GNU General Public License
// along with this program; if not, write to the Free Software
// Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
// 
// You can contact the author, Nathan (Acorn) Pooley, by writing
// to Nathan (Acorn) Pooley, 949 Buckeye Drive, Sunnyvale, CA  94086, USA
// or through the form at http://www.rawbw.com/~acorn/wand/feedback.html
//
#ifndef AC_HEXFILE_H
#define AC_HEXFILE_H

//#@DOC@ functons for handling intel hex files

//###########################################################################
//############################### NOTES #####################################
//###########################################################################
//
//  H   H   OOO   W   W        TTTTT   OOO        U   U   SSSS  EEEE
//  H   H  O   O  W W W          T    O   O       U   U  S      E
//  HHHHH  O   O  W W W          T    O   O       U   U   SSS   EEE
//  H   H  O   O  WWWWW          T    O   O       U   U      S  E
//  H   H   OOO    W W           T     OOO         UUU   SSSS   EEEEE
//
// 1) Load a file using
//       AcHexFile *hx = AcHexLoadFile("filename",0);
//
// 2) Read data with
//       #define ADDR ???   // file offset
//       #define LEN ???    // number of bytes to get
//       char buf[LEN];
//       AcHexGetBytes(hx, ADDR, buf, LEN);
//       
// 3) Clean up after with
//      AcHexDelete(hx);
//
//  OTHER INFO
//   use AcHexGetRegion() to get info about a region of contiguous bytes
//   use AcHexPrint() to print entire file (for debug)
//   use AcHexSetBytes() to set a range of bytes (existing or nonexisting)
//   set debug=1 to see debug spew

//###########################################################################
//############################### DEFINES ###################################
//###########################################################################

#define AC_HEX_INVALID_OFFSET   (~0UL)
#define AC_HEX_INVALID_ADDRESS  (~0UL)

//###########################################################################
//############################### TYPEDEFS ##################################
//###########################################################################

typedef struct AcHexFileRec AcHexFile;
typedef unsigned long AcHexAddress;
typedef unsigned long AcHexOffset;

typedef unsigned char AcHexByte;

//###########################################################################
//############################### PROTOTYPES ################################
//###########################################################################

AcHexFile *AcHexLoadFile(const char *filename, int format);
AcHexFile *AcHexCreate(void);
void AcHexDelete(AcHexFile *f);

AcHexOffset AcHexGetBytes(
                AcHexFile *f, 
                AcHexAddress addr, 
                void *data, 
                AcHexOffset bytes);
int AcHexSetBytes(
                AcHexFile *f, 
                AcHexAddress addr, 
                const void *data, 
                AcHexOffset bytes);
int AcHexDeleteBytes(
                AcHexFile *f, 
                AcHexAddress addr, 
                AcHexOffset bytes);

AcHexOffset AcHexGetRegion(
                AcHexFile *f,
                AcHexAddress addr,
                AcHexAddress *start,
                AcHexAddress *end);

void AcHexPrint(AcHexFile *f, int showdata);
const char *AcHexGetFilename(AcHexFile *f);

void AcBytePrint(void *buf,
                unsigned long len,
                unsigned long addr,
                int rpt);

#endif // AC_HEXFILE_H