Introduction to C-simulation Environment
------------------------------------------


C-Simulator
===========

The C-simulation of the RDP is a register-accurate, bit-accurate simulation of
the Reality Display Processor.  The reason for having a C-sim at all is simple:
the Verilog simulation, which may contain instanced gate-level models of
certain logic is too slow to process the volume of test cases we intend to run 
through the simulator.  The C-sim is faster because it basically is less flexible
and does less than Verilog.  

Verilog uses an event-based simulation algorithm. In this type of simulator, 
changes in one signal cause other dependent signals to be re-evaluated. This
process can happen many times per clock in the worst case.  Verilog also
has the capability of simulating timing accurately (although we are not
using Verilog as the RDP timing verifier, rather we are using Compass Qsim).
Finally, Verilog is an interactive debugger.  The simulation may be stopped,
single-stepped, and varaibles accessed at any time by the user.

The C-sim on the other hand, evaluates every register input signal at most
two times per clock.  The C-sim assumes that signals will be valid at the
clock boundaries.  The basic C-sim mechanism is simlar to the Verilog non-
blocking assignment.  In this model, a register has two parts: an input or
next-state value, and an output or current-state value.  This simple
mechanism ensures that simulation code is *not* order dependent, that is,
you may calulate the next-state input of a register at any time without
affecting calculations that use the output of that register later.  This
increases the ease of coding and reliability of the model.  An additional
feature of the C-sim is that asynchronous logic such as a mux or AND gate may
be placed between the output register and the output 'pin' of the module.
This requires an additional evaluation of the module each clock (two instead of
one without this feature) but improves flexibility.  The C-sim is a compiled
simulator.  Different behaviour may be obtained by passing command line
arguments.   It is up to the modules in the simulation to interpret these
arguments and do the right thing.

C-sim modules have an associated structure which contains all input signals, 
output signals, and internal registers.  Each module has two functions which 
define its operation: an initialization function, and the actual model function.  
These functions are passed pointers to their memory structures.  This allows 
multiple instances of modules, if necessary.  The initialization function
parses command line arguments, initializes any of the modules internal memory,
etc.  The model function implements the functionality of the hardware being modeled.

A complete C-simulation will consist of a colection of modules, tied together with
a netlist that defines that connectivity of the modules.  We are using the ECS
schematic capture program to create this netlist information.  A utility called
'xnet' translates this netlist information, along with a configuration file into 
an executive main function (either C or Verilog).  

The configuration file basically assiciates a function name with an instance name
in  the schematic and groups instances into a particular process.  C modules should
not be in the same process with Verilog modules.  Several library modules, which don't
need to be placed in the schematic, are the 'ck' (clock generator) and 'la' (logic
analyzer) modules. The clock generator module drives a global signal in the schematic
called 'CLK'.  The logic ananlyzer module can be used to dump output from the
wires connecting modules in the schematic.  The logic analyzer module cannot dump
register internal to other modules.  See the formatted_dump function below.

The executive function basically allocates memory for each module, calls the init 
function for each module, and then enters the main program loop.  This loop passes 
values between modules, and calls each module's model function.  It also calls a 
predefined 'formatted_dump' function.  This functions allows any register in the 
simulation to be output.  The executive function also handles shared memory 
communication between multiple processes.



Tabular Files
=============

In our current approach to simulating the RDP, each module can tested by applying
input directly and observing the output of any register in the module. Since the
C-sim is a register level simulator, input stimulus must be provided every clock.
The collection of input (and output) data for one clock period is called a 'vector'.
Vectors for testing may be created using C programs, Verilog programs, or entered
by hand using an editor.  Since this data is useful as input to other tools, such as
Verilog or Qsim, we have defined a tabular file format that allows convenient
translation to these tool's input format.  A description of the tabular file
format can be found in PR/hw/doc/tab_format.doc.

Several tools exist presently that operate on tab files:

	o tab2vmem - this converts a tabular file into a Verilog driver that
	  can driver the Verilog model of the circuit in the Verilog environment.
	  The driver applies inputs and tests outputs with the expected results
	  from the C-sim.  Errors are reported.  Notation in the tab file allows
	  signals to be tested only when they are known to be valid.  This avoids
	  erroneous errors when singals have yet to propagate down the pipeline,
	  for example.

	o  tab2wvs - converts a tab file to a Wave script.  Wave is a Compass tool
	   that allows description of waveforms using the Wave language.  We are
	   using Wave as a temporary way to get Qsim scripts since Wave can provide
	   this output.  Eventually, we will write a convertor 'tab2sim' that is
	   both faster and more direct (in progress).

In summary, tab files provide a way of passing vectors between the C-sim, Verilog, and
Qsim.


Directory Structure
===================

The purpose of the directory structure is to group related tests (input data, memory data,
output data) together, as well as provide automatic running of tests and comparison with
previously archived results.  Each module or group of modules will have its own directory
under PR/rdpsim/test, e.g. PR/rdpsim/test/tctm for the test for the Texture Coordinate and
Texture Memory modules.  Under these directories will be others that contain input vectors
or programs that generate input vectors, memory data, output data, and netlist data.  Makefiles
are used to create and run the tests.  Rather than attempt to give test targets descriptive
names, we have decided to use a simple numbering system: test001 for example.  A script
called 'desc' will take a test target as an argument and print out the comments of all
files involved in the test.  In this way, you can get a better description of what the
test does than if you used a long file name.

Each module or group of modules to be tested will have an associated 'driver'.  The purpose
of the driver is to read tab files (or other input files) and apply stimulus to the
circuit.  The driver will also have an formatted dumps of output that will help the
designer and verifier find bugs, etc.  Other modules may be added, such as a module
for writing the pixel output to a frame buffer.