README

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. This license 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, as/m8c.l, and prog/rt.[ch] are distributed
under version 2 of the GPL, but have additional copyright holders.
Please refer directly to the respective file for details.

The following are contributed files and are copyrighted by their
respective copyright holders: prog/drv/ecb_ar91.[ch], sim/icestubs.c


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

  shared/
    Code shared among programs of this project

  bscan/
    Static connection checker that performs a boundary scan through
    ISSP (experimental)

  misc/
    Miscellaneous utilities and example programs

The home page of this package is at 
http://m8cutils.sourceforge.net/

Hardware designs for some of the programmers supported by
"m8cprog" are distributed in the m8cprogs package that can also
be found at
http://m8cutils.sourceforge.net/


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

If you wish to install the utilities in a location different from
/usr, edit INSTALL_PREFIX in Config.make.

Then just type "make". If your version of gcc doesn't agree with
the CFLAGS, edit them in Common.make.

The resulting executables are:

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

You can now run the regression tests with "make test". If satisfied
with the outcome, install everything with "make install". Note that
the utilities won't be able to find their support files by default,
unless you install them.

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


Uninstallation
--------------

"make uninstall" will remove all files installed and also the
directories created underneath $(INSTALL_PREFIX)/share


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.