This README file is work in progress.  In particular, there are a lot
of tests to document, and I'm only about half-way through the list.
Please, if you have questions, ask.  The more questions I know about,
the more I will answer here.

All of the tests here have been verified with Icarus Verilog.
In principle, they will also work with any other IEEE-1364
standards-compliant software, but that needs to verified.
In particular, there is some POSIX-compliant C code in here
that gloms into the Verilog PLI subsystem, and Microsoft's
claimed POSIX compatibility layer is inadequate to run it.

Icarus Verilog is Free Software, and can be used on a large
variety of machines.  My test machine is Linux, and I install
iverilog from source.  If you go to
   ftp://icarus.com/pub/eda/verilog/0.7/
you will find both source code (universal) and ready-to-install
binaries for a variety of machines.  For example, on a vanilla
Red Hat 7.3 Linux machine, you can download verilog-0.7-0.i386.rpm
from the RPMS subdirectory, and "rpm -ivh verilog-0.7-0.i386.rpm".

Many of the tests, besides printing out some essential status
information, will also dump all internal logic signals to a VCD file.
To debug problems, it is essential to view these.  On Unix/X-Windows,
I heartily recommend the (Free) GTKWave Analyzer program.  You can get
a copy from 
  ftp://icarus.com/pub/eda/gtkwave/
or
  http://www.cs.man.ac.uk/amulet/tools/gtkwave/

It would sure be nice to have tests spit out simple go/no-go status.
In fact, kcm_test comes pretty close.  Actually doing this for more
complex subsystems is a bother both practically and theoretically.
For effectively analog computations, one does not demand exact bit
patterns for output: the measures of success are signal/noise ratio,
and number of pipeline stages -- it's not a logic error to change
your mind about the number of pipeline stages to take for a computation.
And it's certainly not an error to improve the signal/noise.  You can
see an element of this complexity in the cordic tests.  Its output at
the moment is
 test covers 8205 points, full scale is 26980 bits
 peak error   8.68 bits, 0.032 %
 rms  error   2.09 bits, 0.008 %
where the number of implementation pipeline stages is hard-coded into
the test bench.

On a full-featured Unix machine, no other additional software
(besides verilog and a waveform viewer) should be needed to run
these simulations.  I assume the following as standard:
   make
   cc
   sh
   awk
   grep
   sleep
   cat
   bc
   awk
   diff

All of the details of how the various verilog and C code get linked
are buried inside the Makefile.  This file only describes what
to "make", so you can run the tests.

kcm_test
   exercises the dynamic Konstant Coefficient Multiplier code.  Uses that
   code to multiply over 300 random numbers, and checks them with bc.  Each
   such line should end with "pass" -- failure would be marked with "FAIL".

cordic_test
   exercises the CORDIC code, which computes sin and cos for the DDS block.
   Unlike the multiplier test, exact answers are not possible, so peak-peak
   and rms error need to be computed for the range of angles from 0 to 2*pi.
   For quick reassurance that this test did what it's supposed to, try following
   it by running gnuplot and 'load "cordic_gnuplot"'.  Two cosine curves should
   overlap perfectly.

adctest_test
   full-featured simulation of the interaction between the host and FPGA.
   The reads and writes coded in adctest_exercise.dat will set up the
   timing registers and trigger an RF pulse.  History buffers will get
   read out at the end.  After running this test, the llrf.vcd file will
   have very informative traces of the state machine that sequences events
   within the RF pulse.

fdbk_loop2
   simple but effective simulation of the feedback code with a live cavity,
   where the cavity simulation is written in 100% verilog.  Features of the
   system that are simulated this way are: 1000 ns delay, 45-degree phase
   shift, and a 3.2 us cavity pole.  Only the setpoint and feedback modules
   are used; the timing is created by the testbench.  Nevertheless, you can
   see the feedback system lock in to the setpoint.

nanoengine_test
   TBW

llrf_test
   TBW

fdbk_loop
   TBW