Code shared among programs of the m8cutils project
==================================================

Copyright 2006 Werner Almesberger

The files in this directory are distributed under the terms of the
GNU General Public License (GPL), version 2. This license is
included in the file ../COPYING.GPLv2.


The library libm8cutils.a contains functions used by more than
one programm in this project:

- file: reading and writing of program data in binary, "ROM", and
  Intel HEX format
- disasm: (non-symbolic) single-instruction disassembler
- chips: chip characteristics database

Note: there are regression tests here. The respective tests are
distributed as follows:

- file input: ../das (partially, need to check error handling)
- file output: none yet
- disassembly: ../das
- chips: none yet


File formats
------------

File I/O is supported for the following three formats:

- an Intel HEX file, containing a program, security data, and a checksum.
  The latter two are optional.
- a raw binary file containing a program
- a "ROM" file containing pairs of hex digits representing a program

On input, the format is auto-detected. An Intel HEX file must begin with
a colon and a ROM file must begin with a hex digit. In an Intel HEX file
and ROM file, hex digits can be upper or lower case. In a ROM file,
there can be any amount of whitespace between bytes and at the end,
including none. Records in an Intel HEX file can be of any length
between 1 and 255 bytes, as long as they are sequential and contiguous
in each area (program, security, and checksum). Areas can appear in any
order.

On output, ROM files have eight bytes (in upper case) per line, separated
by one space. Intel HEX files are in upper case, with 64 bytes per
program and security record.
