ihex: github.com/unixdj/ihex Index | Files

package ihex

import "github.com/unixdj/ihex"

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.


Package Files

data.go reader.go writer.go


const (
    FormatAuto  = iota      // Auto-detect format
    Format8bit              // 8-bit format, 16-bit address space
    Format16bit             // 16-bit format, 20-bit address space
    Format32bit             // 32-bit format, 32-bit address space
    FormatMask  = 0x03      // Mask for format
    ShortData   = 0x04      // 16 byte data records (default: 32 bytes)
    FlagsMask   = ShortData // Mask for flags

IHEX file formats and flags


var (
    ErrChecksum = errors.New("ihex: checksum error")
    ErrClosed   = errors.New("ihex: writer is closed")
    ErrFormat   = errors.New("ihex: invalid format")
    ErrRange    = errors.New("ihex: address out of range")
    ErrSyntax   = errors.New("ihex: invalid syntax")

type Chunk Uses

type Chunk struct {
    Addr uint32
    Data []byte

Chunk represents a contiguous area in the IHEX address space.

type ChunkList Uses

type ChunkList []Chunk

ChunkList is a slice of chunks.

func (*ChunkList) Normalize Uses

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 Uses

type IHex struct {
    // Flags describe the file format and flags.  Legal formats
    // for writing are Format8bit, Format16bit and Format32bit;
    // for reading, FormatAuto is also legal.  The format may be
    // 'or'ed with ShortData flag, which only influences writing.
    Flags byte

    // Start is the "start address".  For 32-bit format it
    // symbolizes 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 a start address.
    Start uint32

    // Chunks are the data written to the address space.
    Chunks ChunkList

IHex represents the contents of an IHEX file.

func (*IHex) ReadFrom Uses

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.Flags defines the format of the file being read. If ReadFrom is called with the format bits (ix.Flags & FormatMask) equal to FormatAuto (zero value) and a record specific to 16-bit or 32-bit format is encoutered, ix.Flags 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.Start is set to the value in the last such record.

func (*IHex) WriteTo Uses

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

WriteTo writes data from ix to an IHEX file. Using Writer of the format specified by ix.Flags (whose format bits may not be FormatAuto), it first writes ix.Chunks in order without any normalization, followed by ix.Start unless it's zero. ix.Start must be zero for 8-bit format files.

type Reader Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Writer Uses

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 Uses

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

NewWriter retutrns a new Writer writing to w. flags defines the IHEX file format (which may not be FormatAuto) and flags. If flags is invalid, ErrFormat is returned as error.

func (*Writer) Close Uses

func (w *Writer) Close() error

Close flushes data buffers of w and writes an EOF record to an 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 Uses

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 Uses

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 32 bytes (16 bytes if ShortData flag was set when calling NewWriter), never spanning a 32-byte address boundary. Writes are buffered as needed.

func (*Writer) WriteStart Uses

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

WriteStart sets the start address to addr. If the format of w is Format32bit, an 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 an 8-bit format is an error.

Package ihex imports 6 packages (graph). Updated 2016-07-20. Refresh now. Tools for package owners. This is an inactive package (no imports and no commits in at least two years).