README
¶
IHEX
Library for reading and writing Intel HEX files according to the specification outlined in Wikipedia's Article.
Features
- Reading and Writing HEX files
- HEX Record Types
- Automatic HEX record type validation including:
- checksum generation and validation
- syntax checking and data integrity validation
- record and file type compatibility validation
- Supports I8HEX, I16HEX, and I32HEX file specifications
Coming Soon-ish
- Search HEX file by record address
Examples
New code examples coming soon!
Documentation
¶
Overview ¶
Package ihex provides a library of structs for reading and writing Intel HEX files To learn more about the Intel HEX format, view the the Wikipedia article on the HEX file format at: https://en.wikipedia.org/wiki/Intel_HEX
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func WriteFile ¶
WriteFile resets an IHEX file to the beginning record. Then it writes the file's contents in appropriate IHEX format to the provided writer. This also automatically handles creating checksums for each record in the file based on the record data. Returns any errors generated by the provided writer during the writing process.
Types ¶
type File ¶
type File interface {
GetType() FileType
ReadNext() (Record, bool)
Reset()
Add(r Record) error
AddRecords(r ...Record) error
}
File is the base interface for all IHEX file formats. All IHEX files must be able to do the following: Provide their file type. Read each record one at a time. Reset reading to the starting record of the file. Add one or more record(s) to the file.
type FileType ¶
type FileType byte
FileType defines which HEX format a HEX file is in. Its integer value corresponds to the HEX format.
const ( // I8HEX is the I8HEX file format. // The I8HEX file format supports up to 16 bit memory addresses. I8HEX FileType = 8 // I16HEX is the I16HEX file format. // The I16HEX file format supports up to 20 bit memory addresses. I16HEX FileType = 16 // I32HEX is the I32HEX file format. // The I32HEX file format supports up to 32 bit memory addresses. I32HEX FileType = 32 )
type FileWriter ¶
type FileWriter struct {
// contains filtered or unexported fields
}
FileWriter writes a stream of bytes into HEX file format. The data is organized into records of fixed width with continuously incrementing addresses.
func NewFileWriter ¶
func NewFileWriter(w io.Writer, recordSize int) (*FileWriter, error)
NewFileWriter is equivalent to calling NewFileWriterType(w, recordSize, I32HEX) I32HEX is the default HEX format chosen to provide the largest supported record address range (4 GB) with maximum compatibility.
func NewFileWriterType ¶
NewFileWriterType create and initialize a new FileWriter with the specified underlying writer to write HEX data into. All records written by this FileWriter will have data size of recordSize bytes. Returns a newly created and initialized FileWriter or an error if recordSize exceeds the maximum HEX data length (255 bytes)
func (*FileWriter) Close ¶
func (me *FileWriter) Close() error
Close closes this writer and flushes any remaining buffered data to the underling writer. This also closes the underlying writer if possible and writes the final EOF record to the writer. Returns any errors encountered during closing or when closing the underlying writer.
func (*FileWriter) Write ¶
func (me *FileWriter) Write(p []byte) (n int, err error)
Write writes the provided binary data in HEX format to the underlying writer. If len(p) exceeds the recordSize of this FileWriter, multiple records will be written to the stream Returns the number of bytes written (including the address and other header bytes of the record) or any errors encountered during writing.
type I16HEXFile ¶
type I16HEXFile struct {
// contains filtered or unexported fields
}
I16HEXFile is a HEX file in I16HEX format
func NewI16HEXFile ¶
func NewI16HEXFile() *I16HEXFile
NewI16HEXFile creates and initializes a new I16HEX file Returns the newly created I16HEX file
func (*I16HEXFile) Add ¶
func (me *I16HEXFile) Add(r Record) error
Add adds a new record to the end of this HEX file Returns an error if the record is incompatible with this file type
func (*I16HEXFile) AddRecords ¶
func (me *I16HEXFile) AddRecords(r ...Record) error
AddRecords adds a set of records to the end of this HEX file Returns an error if any of the records are incompatible with this file type
func (*I16HEXFile) GetType ¶
func (me *I16HEXFile) GetType() FileType
GetType returns the file type of this HEX file
func (*I16HEXFile) ReadNext ¶
func (me *I16HEXFile) ReadNext() (Record, bool)
ReadNext advances to the next record in this HEX file and returns it with a boolean flag of true. If there are no more records in the file, a dummy record is returned along with the boolean flag of false.
func (*I16HEXFile) Reset ¶
func (me *I16HEXFile) Reset()
Reset resets this file back to the first record in the file to be ready to read again.
type I32HEXFile ¶
type I32HEXFile struct {
// contains filtered or unexported fields
}
I32HEXFile is a HEX file in I32HEX format
func NewI32HEXFile ¶
func NewI32HEXFile() *I32HEXFile
NewI32HEXFile creates and initializes a new I32HEX file Returns the newly created I32HEX file
func (*I32HEXFile) Add ¶
func (me *I32HEXFile) Add(r Record) error
Add adds a new record to the end of this HEX file Returns an error if the record is incompatible with this file type
func (*I32HEXFile) AddRecords ¶
func (me *I32HEXFile) AddRecords(r ...Record) error
AddRecords adds a set of records to the end of this HEX file Returns an error if any of the records are incompatible with this file type
func (*I32HEXFile) GetType ¶
func (me *I32HEXFile) GetType() FileType
GetType returns the file type of this HEX file
func (*I32HEXFile) ReadNext ¶
func (me *I32HEXFile) ReadNext() (Record, bool)
ReadNext advances to the next record in this HEX file and returns it with a boolean flag of true. If there are no more records in the file, a dummy record is returned along with the boolean flag of false.
func (*I32HEXFile) Reset ¶
func (me *I32HEXFile) Reset()
Reset resets this file back to the first record in the file to be ready to read again.
type I8HEXFile ¶
type I8HEXFile struct {
// contains filtered or unexported fields
}
I8HEXFile is a HEX file in I8HEX format
func NewI8HEXFile ¶
func NewI8HEXFile() *I8HEXFile
NewI8HEXFile creates and initializes a new I8HEX file Returns the newly created I8HEX file
func (*I8HEXFile) Add ¶
Add adds a new record to the end of this HEX file Returns an error if the record is incompatible with this file type
func (*I8HEXFile) AddRecords ¶
AddRecords adds a set of records to the end of this HEX file Returns an error if any of the records are incompatible with this file type
type IndexedRecordError ¶
IndexedRecordError an error that occurred at a particular record index
func (*IndexedRecordError) Error ¶
func (me *IndexedRecordError) Error() string
Error returns the error message for this error
type InvalidRecordError ¶
type InvalidRecordError struct {
Message string
}
InvalidRecordError error indicating that a HEX record is formatted incorrectly in some way
func (*InvalidRecordError) Error ¶
func (me *InvalidRecordError) Error() string
Error returns the error message for this error
type InvalidRecordTypeError ¶
type InvalidRecordTypeError struct {
InvalidRecordType RecordType
InvaildFileType FileType
}
InvalidRecordTypeError error indicating a record type is incompatible with the HEX file format the record was found in
func (*InvalidRecordTypeError) Error ¶
func (me *InvalidRecordTypeError) Error() string
Error returns the error message for this error
type Record ¶
type Record struct {
Type RecordType
AddressOffset uint16
Data []byte
}
Record is a single record in an Intel HEX file. An IHEX record contains the following: The record type. A 16 bit record address (or address offset for I16HEX and I32HEX files). Up to 255 bytes of data. A checksum for validating record data integrity. This library handles checksum validation and generation automatically. Thus the checksum is excluded from the struct.
type RecordType ¶
type RecordType byte
RecordType defines what the type of a single record in a HEX file.
const ( // RecordData indicates the record contains data and a 16-bit starting address for the data. // The byte count specifies number of data bytes in the record. RecordData RecordType = 0x00 // RecordEOF indicates that this record is the end of the HEX file. Must occur exactly once. // The data field is empty (thus byte count is 00) and the address field is typically 0000. RecordEOF RecordType = 0x01 // RecordExtSegment is the extended segment address record type. Usable by I16HEX files only. // The data field contains a 16-bit segment base address (thus byte count is always 02) compatible with 80x86 real mode addressing. // The address field (typically 0000) is ignored. // The segment address from the most recent 02 record is multiplied by 16 and added to each subsequent data record address to form the physical starting address for the data. // This allows addressing up to one megabyte of address space. RecordExtSegment RecordType = 0x02 // RecordStartSegment is the start segment address record type. Usable by I16HEX files only. // For 80x86 processors, specifies the initial content of the CS:IP registers (i.e., the starting execution address). // The address field is 0000, the byte count is always 04, the first two data bytes are the CS value, the latter two are the IP value. RecordStartSegment RecordType = 0x03 // RecordExtLinear is the extended linear address record type. Usable by I32HEX files only. // Allows for 32 bit addressing (up to 4GiB). The record's address field is ignored (typically 0000) and its byte count is always 02. // The two data bytes (big endian) specify the upper 16 bits of the 32 bit absolute address for all subsequent type 00 records; these upper address bits apply until the next 04 record. // The absolute address for a type 00 record is formed by combining the upper 16 address bits of the most recent 04 record with the low 16 address bits of the 00 record. // If a type 00 record is not preceded by any type 04 records then its upper 16 address bits default to 0000. RecordExtLinear RecordType = 0x04 // RecordStartLinear is the start linear address record type. Usable by I32HEX files only. // The address field is 0000 (not used) and the byte count is always 04. // The four data bytes represent a 32-bit address value (big-endian). // In the case of 80386 and higher CPUs, this address is loaded into the EIP register. RecordStartLinear RecordType = 0x05 )
Source Files