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

With the exceptions noted below, all files in this directory are
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.

cpp.h, cpp.c:
  Copyright 2002,2003 California Institute of Technology
  Copyright 2004 Werner Almesberger

  This package is free software; you can redistribute it and/or modify
  it under the terms of the GNU General Public License as published by
  the Free Software Foundation; either version 2 of the License, or
  (at your option) any later version.


Overview
--------

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
- cpp: helper functions to read standard input or a file through CPP
- interact: verbosity control and progress bars

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
- cpp: none (this code has been thoroughly tested in tcng and umlsim)
- interact: 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.
