LED - A SPLASH2 Tutorial Example

Introduction

LED is a simple tutorial designed to demonstrate the use of pipelining in the SPLASH array. Data is read from the input file xinput and fed into SPLASH by the XL processor. It is passed around from PE to PE until it returns to the XR processor whereupon it is written to the output file xoutput. It is called the LED tutorial since each PE has a single LED output on the back of SPLASH. The signal leading to this LED (XP_LED) is driven from the LSB of the data coming in to the left side of the PE. By watching the LED's on the back of SPLASH one can determine whether the execution is proceeding correctly.

The code for this example lives in the directory $SPLASH2/tutorial/LED and consists of the following required files:

led.vhd
This is the VHDL code for this simple processor design. This same design is used for all 16 PE's on a single SPLASH board.
system.vhd
This represents the SPLASH system which must be compiled with any design done for SPLASH for simulation to work. It is simply a copy of the file $SPLASH2/simulator/system/system.vhd.
config.vhd
This is the configuration VHDL file. It pulls together the required library elements along with the LED entity to make a complete system simulation possible. This is the file where you specify how many boards are in the SPLASH you want to simulate, what files should be used for input to the array, etc.
xinput
This file contains the data which should be pumped through the array.
xoutput
This file contains the results which are returned to XR from the SPLASH array..

The VHDL Code

The file led.vhd contains the VHDL code. It has been commented to indicate required elements. Data is pumped in from the left channel, through two registers and out the right channel. This use of registers for all input and output values is recommended by Jeff Arnold, one of the SPLASH developers

The input data is 36 bits wide. The top 4 bits are tag bits while the lower 32 bits are the actual data. See the discussion below on the input file format to understand the use of the tag bits and how to encode them in the input file.

Finally, note that XP_LED = left_reg(0) which means that the LSB of the data input from the left port is tied to the LED on the back of SPLASH.

The Configuration File

The file config.vhd contains the VHDL configuration to create a full SPLASH system for simulation. It has been commented to show how it could be changed to accomodate other designs. Important elements include: Remember that all these are simply for the simulation environment and will have no bearing on the actual SPLASH execution of the algorithm.

Further down in this file you find the various XILINX chip specifications. Note that for each XILINX chip a specific VHDL entity/architecture is defined. In the case of this example, all of the chips get the entity work.Xilinx_Processing_Part and its associated architecture led. This is the VHDL design contained in the file led.vhd. Note that for each processor, an entity/architecture must also be specified for each Memory_Part. For this example we use the dynamic architecture which is a pre-defined model provided by SRC.

The Input File

The file xinput contains the input data. Each line contains 2 HEX numbers. The first is the 32 bits of data to be pumped into the array and the second is a 4 bit tag specified as a single HEX digit. The idea is that it is often useful to send control information through the pipeline along with the data. The tag bits are used for this purpose. An interesting side note is that although the simulation models will automatically set the MSB of the tag bits before sending the data through the array, this does not happen in the execution environment so you might as well set the MSB of the tag to a '1' as it will be needed later during execution.

The output file format is the same as the input file format.

Compiling the VHDL Description

The command to compile the above files to prepare for simulation is: 

   vhdlan system led config
This will create the file TOP.sim which is the file which will be simulated using VHDLDBX.

At times the license server will be down when you attempt to run the VHDL analyzer. If you are informed it is down when you attempt to compile, you may execute the UNIX command /etc/rc.synopsys to restart it (this only works on fpga at the current time).

Simulating the Design Using VHDLDBX

You start up the simulation by typing: 
   vhdldbx TOP
The command file cmds.sim may be used to drive the simulation like this: 
   include cmds.sim
where cmds.sim contains the needed commands to exercise the design. After simulating, the output file xoutput should contain the same data as was found in xinput to begin with.

Compiling Your Design to a BIT File

Once the simulation is working to your satisfaction you may compile it in preparation for downloading it into SPLASH. This is done by: 
   vhdl2xnf led.vhd
If all goes well the above should result in the file led.xnf. Currently, when I run I get errors of the form: 
   Error: Cannot find resolution function 'resolved'.
        Resolution function ignored. (HDL-165)
It seems these can be safely ignored.

At this point you may finish the compilation process by typing: 

   xnf2bit led
which should result in the file led.bit. In the process of creating the BIT file, this script does the physical place and route step (PPR). If the CAD software's license server is down then PPR will attempt to restart it. Watch closely to see if this happens. In order for the license server to be restarted, you must have a login on newt, one of the department HP 700's. In addition, your .rhosts file must be set to allow the machine you are running xnf2bit on to rlogin to newt.

If you use XBLOX elements in your designs, you should refer to Processing Designs with XBLOX to find out how to process the designs.

Executing Your Design on splash

At this point you must move to splash, the host for SPLASH. Ensure that your environment is set up correctly before proceeding.

Copy Over the Needed Files

If your home directory is the same between splash and the HP 700's this step is not necessary. Otherwise, you must copy the files generated in the previous steps to splash. All that is absolutely required to copy over are the files led.vhd, led.bit, led.sym, and xinput.

Creating the Symbol Table

To create the needed symbol table, execute the following: 
   symtobsym led.sym
The files led.bsym and led.bsym.dis will result and may be used during t2 execution to look up signal values in the SPLASH array.

The SPLASH Driver

A device driver for SPLASH must be running on splash before you may execute on SPLASH. To determine whether the driver is currently loaded, execute: 
   /usr/etc/modstat
and look to see if the SPLASH2 driver is listed as running. If not, you may execute: 
   /etc/splash2/reload
to load a new one. In order to avoid kicking another user off SPLASH, you should only restart the driver if you are certain one is not running or are certain no-one else is running on SPLASH.

Running SPLASH Diagnostics With robocop

It is possible to run diagnostics on SPLASH to determine whether it is operational. This can be done by executing: 
   $SPLASH2/bin/robocop -a
on splash. This will run diagnostics indefinitely so you will have to kill it after a while of watching the results.

Executing on SPLASH using t2

The program t2 is an interactive program allowing you to execute your design on SPLASH. The alternative, which will be shown later, is to write a C program to drive SPLASH.

A series of commands, contained in the file cmds.t2 which you may use to drive your t2 execution is explained below (you run the commands by executing source cmds.t2 in t2):

OpenAndInit
This command opens SPLASH and gets it ready to run.
Associate 0 * led
This will inform t2 that you wish every processor on board 0 in SPLASH to execute the design found in led.bit.
Merge 0
This will merge the bitstreams for all the processors on board 0 of SPLASH into a file suitable for downloading.
SaveRaw led.raw
This will save the merged bitstreams into the file led.raw so that in subsequent runs you may simply execute the command LoadRaw led.raw rather than doing the association and merging as shown above.
ConfigArray 0
This will configure board 0 of the SPLASH array by downloading the bitstreams.
SetFreq 5.0
Set the clock frequency to 5.0MHz.
StepAscIO xinput xoutput 100
This will read lines of input from the file xinput, pump them into the array one data item per clock cycle, and write any valid results that come out of the array into the file xoutput. In this example, this will be done 100 times or until the input file is exhausted. Since I know of no way in t2 to clock the array and write outputs to an output file, we must pad the end of the xinput with dummy data values to flush the array. Otherwise we may see no output.
CloseStepFile xoutput
Close the output file.
Quit
Exit the program.
The use of readback to monitor signals internal to the PE's is shown in the second tutorial.

Differences Between Simulation and t2 Execution

There are a number of differences between the simulation and t2 execution environment:
  1. The file config.vhd controls the number of processors and SPLASH array configuration for simulation. The t2 commands Associate, Merge, and ConfigArray perform this function for execution.
  2. During simulation the clock free runs. During execution the clock is usually single-stepped under software control. The functionality of the StepAscIO is to read a data item from the input file, write it to the SPLASH array, and then single step the clock.
  3. The XL and XR chips on the interface board are programmable for simulation. For execution we currently use the interface board exclusively in bypass mode wherein software is used to write and read values from the SIMD and RBUS busses in SPLASH. At the current time, it is not possible to use the interface board in any other way.
  4. During simulation, the XL model attaches valid bits to data read from the input file. Also, XR writes only data thus tagged to the output file. When executing this is not done. Thus, the xinput file must contain the VALID tag bit set if the array is to get valid tag bits. Also, the output file may contain data items in addition to the desired ones since the command StepAscIO writes the values from RBUS to the output file on every clock cycle .
  5. There is no command to simply clock the SPLASH array and write valid data items from RBUS to an output file. Thus, to flush all results from the array requires that the input file contain trailing filler data items. These can then be pumped into the array with StepAscIO while collecting the final results into the output file.

Executing on SPLASH With a C-based Driver

Instead of using t2 for execution you may write a custom C-based driver program. Although tracing signals during execution is easier in t2, in other ways the custom driver is preferable. For example, the feeding of data into the array, clocking, and monitoring array results is more easily controlled in the custom driver code.

The file drive.c is a sample driver created for this tutorial example. It was written to exactly mimic the operation of the t2 commands above. The comments in the code should explain its operation. A Makefile is also included to compile the driver code to execute on splash.

Looking Forward

There are a number of important features of SPLASH not explained in this tutorial which are covered in the next tutorial including:
Last modified: Mon Jul 6 14:36:07 MDT 1998
Brent Nelson
nelson@ee.byu.edu