M8C Utilities
=============

Copyright
---------

With the exceptions noted below, all files are
Copyright 2006 Werner Almesberger

The files in this package are distributed under the terms of the
GNU General Public License (GPL), version 2, or an augmented
version thereof. For details, please refer to the README file in
the respective directory. Version 2 of the GPL is included in
the file ../COPYING.GPLv2.

shared/cpp.h, shared/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.

libfdr/ (Red-black trees)
  Copyright 2001 James S. Plank

  The files in as/libfdr/ are distributed under the GNU Lesser General
  Public License. See the file libfdr/LICENSE for details.

Common.make, libfdr/Makefile, and as/m8c.l have additional copyright
holders. Please refer directly to the respective file for details.


Overview
--------

This is a collection of utilities for programming the Cypress(r) M8C
family of microcontrollers, and in particular the PSoC(tm) (CY8C2xxxx)
series, see http://www.cypress.com/psoc


This collection consists of the following parts:

  as/
    An assembler for the M8C assembly language

  das/
    A disassembler for the M8C assembly language

  sim/
    A simulator for some M8C CPU features (very experimental)

  prog/
    A programmer, with drivers for different types of programmer
    hardware

  waspic/
    A simple PIC-based programmer that communicates via RS-232C

  watsp/
    An even simpler bit-banging programmer that connects to the
    RS-232C port

  shared/
    Code shared among programs of this project


Installation
------------

Just type "make". If you don't have gputils installed, the build
will eventually fail in waspic/. If your version of gcc doesn't
agree with the CFLAGS, edit them in Common.make.

There is no "make install" yet. The resulting executables are:

- assembler: as/m8cas
- disassembler: das/m8cdas
- simulator: sim/m8csim
- programmer (host side): prog/m8cprog
- programmer (firmware): waspic/waspic.hex

By default, "make" output is terse, making it easy to see what is
done, but now showing how. You can enable full output, e.g., to
debug build problems, by putting V=1 on the command line when
invoking "make", e.g.,
% make V=1 all

There are also schematics and PCB layouts for programmer hardware
in waspic/ and watsp/.


Testing
-------

Once everything is built, you can run the regression tests with
"make test" from the top-level directory (i.e., this one). They
can also be run individually per component, by running "make
test" in the respective directory.
