ihex

README

ihex is a Go package implementing access to Intel HEX files.

Copyright (c) 2014-2015, 2020-2023 Vadim Vygonets <vadik@vygo.net>
Licensed under ISC License.

Installing:
go get github.com/unixdj/ihex 

Documentation:
http://godoc.org/github.com/unixdj/ihex

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
• Variables
• type Chunk
• type ChunkList
  • func (cl *ChunkList) Normalize()
• type IHex
  • func (ix *IHex) ReadFrom(r io.Reader) error
  • func (ix *IHex) WriteTo(w io.Writer) error
• type Reader
  • func NewPadReader(r io.Reader, format byte, padTo int64, gapFill byte) (*Reader, error)
  • func NewReader(r io.Reader, format byte) (*Reader, error)
  • func (r *Reader) Read(buf []byte) (int, error)
  • func (r *Reader) ReadStart() (uint32, error)
  • func (r *Reader) Seek(offset int64, whence int) (int64, error)
• type SyntaxError
  • func (e SyntaxError) Error() string
• type Writer
  • func NewWriter(w io.Writer, format byte, dataRecLen byte) (*Writer, error)
  • func (w *Writer) Close() error
  • func (w *Writer) Seek(offset int64, whence int) (int64, error)
  • func (w *Writer) Write(buf []byte) (int, error)
  • func (w *Writer) WriteStart(addr uint32) error

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")
)

Types

type Chunk

type Chunk struct {
	Addr uint32
	Data []byte
}

Chunk represents a contiguous area in the IHEX address space.

type ChunkList

type ChunkList []Chunk

ChunkList is a slice of Chunks.

func (*ChunkList) Normalize

func (cl *ChunkList) Normalize()

Normalize turns cl into a sorted list of nonadjacent non-zero-legth Chunks representing the address space as it would look after the data in cl would be written to it sequentially. Normalize may mutate data in place.

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

func (ix *IHex) ReadFrom(r io.Reader) error

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.

func (*IHex) WriteTo

func (ix *IHex) WriteTo(w io.Writer) error

WriteTo writes data from ix to an IHEX file, using a Writer with parameters specified by ix.Format ix.DataRecLength. It writes ix.Chunks in order, flushing the write buffer between Chunks. If ix.StartSet is true or ix.Start is not zero, it then sets the start address.

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

func NewPadReader(r io.Reader, format byte, padTo int64, gapFill byte) (*Reader, error)

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

func NewReader(r io.Reader, format byte) (*Reader, error)

NewReader returns a Reader reading from r. format must be one of FormatAuto, Format8Bit, Format16Bit or Format32Bit.

func (*Reader) Read

func (r *Reader) Read(buf []byte) (int, error)

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

func (r *Reader) ReadStart() (uint32, error)

ReadStart returns the start address, or zero if it has not been set. ReadStart may return an error from (*IHex).ReadFrom.

func (*Reader) Seek

func (r *Reader) Seek(offset int64, whence int) (int64, error)

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

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

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

func NewWriter(w io.Writer, format byte, dataRecLen byte) (*Writer, error)

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

func (w *Writer) Close() error

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

func (w *Writer) Seek(offset int64, whence int) (int64, error)

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

func (w *Writer) Write(buf []byte) (int, error)

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

func (w *Writer) WriteStart(addr uint32) error

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.