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 demos are meant to run on a development board, for which a top vhdl entity

is supplied, plus a constraints file for the pin location assignment.

The only development board directly supported in the present state of this

project is Terasic's DE-1 board for altera Cyclone-2 FPGAs. It would be very

easy to port the demos to some other board, since the core uses no board

features other than FPGA internal resources, a serial port and a reset button

(plus a few LEDs that can be safely ignored).

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

How to build one of the software demos on a development board

==============================================================

In order to build a demo using one of the supported development boards, you need

to follow the indications given in sections 1 and 2 below. Basically, you need

to know what source files to include and where is the pin location data.

Directory /vhdl/demos includes a subdirectory for each of the development boards

this project has been tested on. for each board, a 'top' entity is provided,

together with a pin location file and a basic test bench for the top entity.

The test bench is meant to be used with Modelsim script /sim/light52_c2sb_tb.do

(suitably modified and renamed for the different target boards). It is provided

as a convenience 'as is', in case you need to debug some basic fault on a demo.

The object code package, the tool that builds it and the cosimulation feature

of this project need to be explained separately, this file can't enter in any

more detail.

All the demos use the basic configuration of the UART, which is 19200/8/N/1, and

assume a clock rate of 50MHz. This is configured in the top vhdl entity.

1.- VHDL source files

------------------------

In order to build the 'Dhrystone' demo for the DE-1 board, the project should

include the following VHDL files:

    *.- All the core vhdl files:            /vhdl/*.vhdl.

    *.- Top entity SoC file for the board:  /vhdl/demos/c2sb/c2sb_soc.vhdl

    *.- Object code package file:           /test/dhrystone/obj_code_pkg.vhdl

    ('C2SB' here stands for 'Cyclone-2 Starter Board')

When other target boards become 'supported' by this project, suitable top

entities will be added to the /vhdl/demos directory.

Of course you can easily modify this c2sb_soc entity to suit your target

hardware.

When building some demo other than Dhrystone, the only difference is that you

need to use the proper object code package file. The name of the object code

package, and the name of the object code constant, are hardwired on the vhdl

top entity but they can be easily changed by editing the demo makefile. This may

be necessary if some project uses more than one light52 core, for instance.

2.- Pin location constraints

-------------------------------

The constraints file for the DE-1 board is in file:

    *.- /vhdl/demos/c2sb/c2sb_pins.csv

When using Quartus-2, this csv file can be directly imported into the project

constraints.

Note that no constraints other than pin locations are used in the present

version of the project!

When a new board target is added to the project, the pin location file will be

included too; its format will depend on the target chip toochain, of course.

These top entities and constraint files are only included as a convenience to

build quick demos around the light52 core. A real project will not need them

at all.

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.