Documentation ¶
Overview ¶
Package ihex implements access to Intel HEX files.
IHEX files consist of records representing instructions for a PROM programmer to write data to memory locations (referred to here as "the address space") and set certain registers ("the start address"), along with record types this package only handles internally (EOF and extended addressing). As these records may appear in a file in any order and are defined to have peculiar corner cases, this package only presents the user a simplified view of the address space, losing details of a particular representation on input and generating conservative output. Documentation for (*IHex).ReadFrom describes the abstraction in more detail.
IHEX files come in three formats. The format termed "8-bit" has, naturally, contiguous 16-bit address space (64KB), "16-bit" format has crazy Intel-segmeted 20-bit address space (1MB) and "32-bit" has 32-bit (4GB) addressing which is contiguous but the high 16 bits of the address are still set separately. This package only allows Extended Segment Address and Start Segment Address records in 16-bit files and Extended Linear Address and Start Linear Address records in 32-bit files.
Index ¶
Constants ¶
const ( FormatAuto = iota // Reading: auto-detect format; writing: I8HEX Format8Bit // I8HEX format, 16-bit address space Format16Bit // I16HEX format, 20-bit address space Format32Bit // I32HEX format, 32-bit address space )
IHEX file formats
Variables ¶
var ( ErrArgs = errors.New("ihex: invalid arguments") ErrChecksum = errors.New("ihex: checksum error") ErrClosed = errors.New("ihex: writer is closed") ErrFormat = errors.New("ihex: invalid record for format") ErrRange = errors.New("ihex: address out of range") ErrRecord = errors.New("ihex: unknown record type") ErrSyntax = errors.New("ihex: invalid syntax") )
Functions ¶
This section is empty.
Types ¶
type IHex ¶
type IHex struct { // Format describes the file format. Legal formats are // FormatAuto, Format8Bit, Format16Bit and Format32Bit; // for writing, FormatAuto is equivalent to Format8Bit. Format byte // DataRecLen is the maximum number of bytes in a Data // record length generated by WriteTo. Must be a power // of two or 0. In the latter case the default length of // 16 is used. DataRecLen byte // Start is the "start address". For 32-bit format it // represents the contents of EIP on 80386, and for // 16-bit, the pair of 16-bit registers CS:IP on 8086. // 8-bit format does not support setting the start // address. Start uint32 // StartSet indicates that Start has been set by // ReadFrom, or should be written by WriteTo even if it's // zero. StartSet bool // Chunks are the data written to the address space. Chunks ChunkList }
IHex represents the contents of an IHEX file.
func (*IHex) ReadFrom ¶
ReadFrom reads an IHEX file from r, filling ix. ReadFrom returns nil on success, ErrSyntax or ErrChecksum in case of invalid input and anything else on read errors. ReadFrom may overread r.
ix.Format defines the format of the file being read. If ReadFrom is called with the ix.Format equal to FormatAuto (zero value) and a record specific to 16-bit or 32-bit format is encoutered, ix.Format is set accordingly. Due to different semantics of Data records spanning 64KB address boundaries, such records are disallowed with FormatAuto (however, one shouldn't expect to encounter such records the wild).
ix.Chunks is set to a sorted list of nonadjacent contiguous data areas representing programmed areas in a (potentially sparse) address space of a target machine, with later writes overwriting results of earlier ones. This does not necessarily represent the behaviour of actual hardware; e.g., a location in flash memory contains conjunction (binary AND) of all values written to it since last erase. If ix.Chunks is non-empty before calling ReadFrom, it is normalized to allow interleaving reads from several files with direct data manipulation. If any Start Segment/Linear Address records are encountered, ix.StartSet is set to true, and ix.Start to the value in the last such record.
type Reader ¶
type Reader struct {
// contains filtered or unexported fields
}
Reader provides a simple interface for reading an IHEX file from an underlying reader. It reads the whole file by calling (*IHex).ReadFrom on the first Read or ReadStart call. A slightly more detailed represetation of IHEX file is provided by type IHex.
Reader's Read method reads from a contiguous address space spanning from address 0 to the end address, which is normally the address immediately after the topmost byte written by the programmer, with gaps between written memory filled with zeros. For readers created by NewPadReader, the end address is set to padTo if the latter is higher, and the filler byte is set to gapFill.
func NewPadReader ¶
NewPadReader returns a Reader reading from r. The returned Reader has its address space padded to at least padTo, with any gaps filled with gapFill.
func NewReader ¶
NewReader returns a Reader reading from r. format must be one of FormatAuto, Format8Bit, Format16Bit or Format32Bit.
func (*Reader) Read ¶
Read reads from the address space represented by r. Read returns io.EOF at the end of address space, ErrRange out of the address space or an error from (*IHex).ReadFrom on syntax or read errors.
func (*Reader) ReadStart ¶
ReadStart returns the start address, or zero if it has not been set. ReadStart may return an error from (*IHex).ReadFrom.
func (*Reader) Seek ¶
Seek causes the next Read to return data from the specified address. Seek returns ErrRange if whence is invalid or the resulting address is negative. Seeking to an address beyond the end of the address space represented by r will cause next Read to return ErrRange. Seek is compatible with io.Seeker.
type SyntaxError ¶ added in v1.1.0
type SyntaxError struct { Err error // ErrChecksum, ErrFormat, ErrRecord or ErrSyntax Line int // 0 for missing EOF record, otherwise input line number Format byte // Active IHEX format Record string // "" for missing EOF record, otherwise input line }
func (SyntaxError) Error ¶ added in v1.1.0
func (e SyntaxError) Error() string
Error returns the error formatted as one of:
"ihex: <invalid syntax/checksum error> on line <n>" "ihex: invalid record for <unspecified/I8HEX/I16HEX/I32HEX> format on line <n>" "ihex: missing EOF record"
type Writer ¶
type Writer struct {
// contains filtered or unexported fields
}
Writer writes an IHEX file to an underlying writer. Records are written in the order in which Writer's methods are called. After all data are written to the Writer, Close must be called.
func NewWriter ¶
NewWriter returns a new Writer writing to w. format defines the IHEX file format. dataRecLen is the maximum number of bytes in a Data record generated, which must be a power of two or 0. In the latter case the default length of 16 is used. If any argument is invalid, ErrArgs is returned as error.
func (*Writer) Close ¶
Close flushes data buffers of w and writes an EOF record to the underlying writer. It may return non-nil if any of the writes fail. After Close is called, further calls to Close will return nil, and calls to other methods of w will return ErrClosed as an error.
func (*Writer) Seek ¶
Seek causes the next Write to write data to the specified address in the address space. Its arguments are compliant with the io.Seeker interface. If the resulting address is out of the legal address space for w's format, an error is returned. Seek flushes the write buffer but otherwise does not generate any records.
func (*Writer) Write ¶
Write writes data from buf as Data records. Extended Segment or Linear Address records are generated as needed. Writes beyond the address space valid for the current format generate an error. Data are written in chunks of up to the number of bytes set by the dataRecLen argument to NewWriter, never spanning a dataRecLen address boundary. Writes are buffered as needed.
func (*Writer) WriteStart ¶
WriteStart sets the start address to addr. If the format of w is Format32Bit, a Start Linear Address record is generated, setting EIP to addr. For Format16Bit, the Start Segment Address written sets CS to the high 16 bits of addr and IP to its low 16 bits. Attempting to set a start address for a Format8Bit writer is an error.