Subversion Repositories light52

Until a proper design document is made, this quickstart file will help you
set up one of the included software demos on a development board. Plus, there's
a brief explanation of the cosimulation verification scheme.

All of this stuff will eventually be properly explained in a design document.
This file is just a stopgap until that document is written.

Software demos
===============

All the demos included in the project (in directory /test) come pre-compiled
(that is, the repository includes the object code package necessary to build the
system), so it isn't necessary to install any MCS51 assembler or compiler if all
you want to do is play a little with the core.

The project includes ready-made support files for the following development 
boards:

* Terasic's DE-1 (Cyclone-2):           directory /boards/terasic_de1
* Avnet's Spartan-3A Evaluation Kit:    directory /boards/avnet_s3aeval    

For each board, the following is supplied:

1.- A suitable project file is included for Quartus-2 or ISE Webpack. 
2.- A 'top entity' VHDL module with a light52 MCU instance connected to 
    the on-board devices (most of which are unused).
3.- A constraints file, including the pin locations. This info is already in 
    the project file but is supplied separately for convenience.


The project files in all cases use the object code package from the Dhrystone
demo. It is trivially easy to set up the project for some other demo: replace
the object code package (file obj_code_pkg.vhdl).

The demos only use a serial port connector (when available) and some LEDs and
7-segment displays (when available). It would be very easy to port the demos 
to some other development board.

FPGA configuration files are NOT included, so you will need a synthesis tool.



How a software simulator has been used as a verification tool
==============================================================

This project includes a software simulator for the light52 core called b51. B is
for 'batch', because the simulator is not interactive; it runs from reset to
the end of the program (identified by a timeout or a single-instruction loop),
logging the execution as it goes along, and then quits.

This simulator can be found in directory /tools/b51, together with a CodeBlocks
project file. The simulator has been developed on Win32/Cygwin but should work
on Linux unmodified (only a Win32 binary is provided).

The simulator is meant to be used as a cosimulation tool: you run the same
program in b51 and in a Modelsim vhdl test bench.
Each of the simulations will log its evolution on a text file ('sw_log.txt' for
b51 and 'hw_sim_log.txt' for Modelsim). If the hardware model matches the
software model, the log files should be identical (this is a little trickier
than it seems, as will be explained in the design document).
Thus, the software model can be used as a 'golden model' of sorts.

I'm calling this scheme 'cosimulation', even though the simulations don't
interact directly (you have to match the log files yourself).

The b51 simulator is still not finished but it already can execute all the
software demos included with this project. Each demo includes a DOS BAT file
for launching the simulator. Until better documentation is available, you
are referred to those BAT files and the source code of b51 for details.
The log file format will also be described eventually in the design document.


Why a software simulator?
--------------------------

By using a software simulator as a 'golden model' that the hardware must match
closely, we can use far simpler test benches than would otherwise be necessary.
Besides, development and debugging become much easier and quicker.

The downside, of course, is that an accurate software model has to be developed
in addition to the hardware design. In this project, it has been built from
scratch -- and yet I think I have saved an awful lot of development time.

This scheme (software model + hardware simulation + software-only test bench)
is nothing new; it has been used to test new computers since at least the 70's.