TEMPLATE TEST BENCH
===================
1. Introduction
2. Files
3. Building and Running
4. Customising the test bench
5. Test bench API
6. Compilation Tools
7. Adding the EL HAL
1. Introduction
---------------
This directory contains a bare bones VProc based test bench. It will compile
and run as is, but no UUT is instantiated and it is meant to be copied and
customised for a particular test environment.
The top level test bench contains a control block for processor control of
simulation and error status, an address decode block (auto-generated), a local
register block (auto-generated) and the a virtual processor, wrapped in the
Avalon BFM. The processor has a single CSR port in the instantiation, but a
sequence bus can also be added (see the avsvproc.vhd port list).
The test bench has two generics, GUI_RUN and CLK_FREQ_MHZ. The first is set by
the execution scripts. The second determines the clock frequency of the clocks
from the control block. This produces a system clock signal (clk) which will
run at the stated frequency (in units of MHz), a double clock (clkx2) and half
clock (clk_div2). If other clocks are needed for a particular UUT, then the
control block can be customised, or a clock generation procedure (clk_gen) is
available in tb_pkg.vhd. Note that, if CLK_FREQ_MHZ is changed, then the
definintion SYS_CLK_PERIOD_NS in tb.h must be changed to match to get accurate
timings from calls to sleep functions.
2. Test bench files
-------------------
The files in this directory, and what they do, are:
test/
doc/
test.json -- Testbech register definitions for auto-generation of code
src/
tb.h -- Testbench basic definitions for C/C++ code
utils.h -- Header for testbench ultilty functions
utils.cpp -- Testbench utility function source code
VUserMain0.cpp -- Top level VProc entry point code and virtualisation functions
VUserMain0.h -- Header for VUserMain0
autogen.bat -- DOS batch file for auto-generation of source code (both TB and---if defined---UUT)
compile.do -- ModelSIM 'do' script for plain HDL simulayion compilation (called from makefile)
file.tcl -- List of VHDL files for compilation of the TB, including UUT if defined
files_vlog.tcl -- List of verilog files for compilation of the TB, including VProc, and UUT if defined
makefile -- Top level compilation make file
sim.do -- ModelSIM do script for running batch simulation (called from makefile)
simg.do -- ModelSIM do script for running GUI simulation (called from makefile)
tb.vhd -- Top level test bench VHDL
tb_ctrl.vhd -- Test bench peripheral for simulation control
tb_pkg.vhd -- Test bench VHDL definitions
vusermain.cfg -- VUserMain0 'command line' configuration file
wave.do -- Top level ModelSIM do script for setting up signals in GUI
3. Building and Running
-----------------------
Building and running of the test bench is expected to be through the use of the
make file. The following command lines commands are supported:
* mingw32-make -- Compiles, if needed, the C/C++ code (produces VProc.so)
* mingw32-make run -- Compiles C/C++ and HDL and then runs a batch simulation
* mingw32-make gui -- Compiles C/C++ and HDL and then runs a GUI simulation. Can also type mingw32-make rungui
* mingw32-make clean -- Cleans all generated and compiled files
The make file calls modelSIM 'do' scripts which can be used directly if desired.
They do not compile the C/C++ code, which can be done with make compile, as
described above. These scripts are:
* compile.do -- For HDL compilation (assumes work/ has already been created by a vlib command)
* sim.do -- Compile and run a batch simulation
* simg.do -- Compile and run a GUI simulation. Uses wave.do, which can be extended or customised
4. Customising the test bench
-----------------------------
As this is a bare bones template, it will need customising to add UUT files,
such as the HDL source, location of tools (if different from the default) and
test C/C++ code, including a HAL if to be used. To customise the make file:
* Add user C/C++ code to makefile by appending .cpp or .c files to USERCODE
* Change location of fw_development_tools (where VProc and memory model are located) by updating FWDEVTOOLS
* Change location of simulator by updating MODELSIMDIR
* Add JSON auto-generation scripts by
* Appending JSON files to JSONFILES
* Updating autogen.bat to add commands for auto-generation of custom files
* Add a search directory for custom includes not in src/ by updating EXTINCLDIR (e.g. for a HAL)
HDL source code is appended to the files.tcl (for HDL) and files_vlog.tcl (for
Verilog) as appropriate.
5. Test bench API
-----------------
No HAL is supplied in this test bench. Access from the processor code is via a
simple API provided in VUserMain0.cpp, and declared in the VUserMain0.h header.
Access to the memory space is via these functions:
* uint32_t csrReadMem (uint32_t addr, uint32_t* data); -- Memory read over simulation CSR bus
* void csrWriteMem (uint32_t addr, uint32_t data); -- Memory write over simulation CSR bus
* uint32_t directReadMem (uint32_t addr, uint32_t* data); -- Direct read from memory model (no simmulation time)
* void directWriteMem (uint32_t addr, uint32_t data); -- Direct write to memory model (no simulation time)
Note that the direct accesses functions are restricted to the memory space
occupied by the memory and TB or UUT registers etc. can't be accessed with
these methods. The memory model address offset is defined as MEM_BASE_ADDR
(tb.h), and the UUT at CORE_BASE_ADDR (VUserMain.h). These can, of course, be
customised. Timing of the simulation from C/C++ code is provided by the
following two functions:
* void usleepSim (unsigned time); -- Sleep (i.e. advance simulation) by specifed number of microseconds
* void nsleepSim (unsigned time); -- Sleep (i.e. advance simulation) by specifed number of nanoseconds
Simulation control is normally done by the test bench, but the following
functions can be called from anywhere in the user C/C++ code.
* void stopSim (bool error); -- Stop the simulation (but simulator remains active)
* void finishSim (int error); -- Finish simulation and close simulator
6. Compilation Tools
--------------------
The test bench is dependent on the mingw tools. A repository exists with the
required sub-set of mingw at git@hydra:GIS_Embedded_Logic/mingw. This would
normally to be checked out at C:\MinGW, but can be any where. Two paths need
to be added to the PATH variable to pick up the appropriate tools. Assuming
C:\MinGW as the location of the checkout:
* set PATH=%PATH%;C:\MinGW\bin;C:\MinGW\msys\bin
7. Adding the EL HAL
--------------------
This bare bones test bench does not include a HAL but in this section will be
discussed how this may be added with the use of examples.
We will assume that the test/ directory is in an EL repository at
firmware/top/src/test. Assuming the repository has JSON files for the CSR bus
and that we want the generated code to be in a directory ./src/hal (relative
to the makefile location). Then the following command can be used to generated
the HAL code.
py -3 e:\git\fw_development_tools\logic_memory_mapper\gen_elhal.py -r ..\..\..\.. -b csr -o .\src\hal
The -r ..\..\..\.. argument specifies the top level relative to the test/
directory. The -b option specifies the busses so can be extended with, say,
a seq bus. The -o option specifies that the output should be put in src/hal
(and assumes the directory already exists). The command can be added to the
autogen.bat file for building along with the test bench files.
If the command is successful, this will generate a set of files of two forms,
for each of the peripherals of the JSON spec. One set will be a set of defini-
tions of offsets in a file of the form, for example addr_gen.h. An example
output is as shown:
// Block name: addr_gen, using byte offsets
// Offset in core for bus csr : 0x00004000
#include <stdint.h>
#ifndef __ADDR_GEN_H__
#define __ADDR_GEN_H__
#define CSR_ADDR_GEN_IP_ID 0x00000000
#define CSR_ADDR_GEN_IP_ID_IP_NUMBER 0
#define CSR_ADDR_GEN_IP_ID_IP_NUMBER_WIDTH 8
#define CSR_ADDR_GEN_IP_ID_IP_NUMBER_MASK 0x000000ff
#define CSR_ADDR_GEN_IP_ID_MFR_NUMBER 8
#define CSR_ADDR_GEN_IP_ID_MFR_NUMBER_WIDTH 8
#define CSR_ADDR_GEN_IP_ID_MFR_NUMBER_MASK 0x0000ff00
#define CSR_ADDR_GEN_IP_VER 0x00000004
#define CSR_ADDR_GEN_IP_VER_MINOR_NUMBER 0
#define CSR_ADDR_GEN_IP_VER_MINOR_NUMBER_WIDTH 8
#define CSR_ADDR_GEN_IP_VER_MINOR_NUMBER_MASK 0x000000ff
#define CSR_ADDR_GEN_IP_VER_MAJOR_NUMBER 8
#define CSR_ADDR_GEN_IP_VER_MAJOR_NUMBER_WIDTH 8
#define CSR_ADDR_GEN_IP_VER_MAJOR_NUMBER_MASK 0x0000ff00
#define CSR_ADDR_GEN_CPU_CONTROL 0x00000008
#define CSR_ADDR_GEN_CPU_CONTROL_START_TILE 0
#define CSR_ADDR_GEN_CPU_CONTROL_START_TILE_WIDTH 1
#define CSR_ADDR_GEN_CPU_CONTROL_START_TILE_MASK 0x00000001
#define CSR_ADDR_GEN_CPU_CONTROL_EDGE 1
#define CSR_ADDR_GEN_CPU_CONTROL_EDGE_WIDTH 1
#define CSR_ADDR_GEN_CPU_CONTROL_EDGE_MASK 0x00000002
#define CSR_ADDR_GEN_STATUS 0x0000000c
#define CSR_ADDR_GEN_STATUS_BUSY 0
#define CSR_ADDR_GEN_STATUS_BUSY_WIDTH 1
#define CSR_ADDR_GEN_STATUS_BUSY_MASK 0x00000001
#define CSR_ADDR_GEN_CPU_TILE_COUNT 0x00000010
#define CSR_ADDR_GEN_CPU_COL_WRAP 0x00000014
#endif
If the block is hierarchical, and has sub-blocks, then offsets to these blocks
will be present. An example fragment is shown below:
#define CSR_CORE_DATA_STREAMER_0 0x00000000
#define CSR_CORE_DATA_STREAMER_1 0x00001000
#define CSR_CORE_DATA_STREAMER_2 0x00002000
#define CSR_CORE_DATA_STREAMER_3 0x00003000
#define CSR_CORE_ADDR_GEN 0x00004000
#define CSR_CORE_PIXEL_SERIALISER_0 0x00005000
#define CSR_CORE_LOCAL 0x00006000
The second type of file is of the form, for example, CAddrGenAuto.h and
contains a class definition of the same name (CAddrGenAuto). Creating an object
with one of these gives access to the registers and/or sub-blocks where
appropriate. In the example below a top level core is instantiated, which has
its own registers and also an AddrGen sub-block:
#include "CCoreAuto.h"
extern "C" void VUserMain0()
{
CCoreAuto* pCore = new CCoreAuto(CORE_BASE_ADDR);
uint32_t coreIpId = pCore->pIpId->GetIpId(); // Get whole register
uint32_t addrGenIpNum = pCore->pAddrGen->pIpId->GetIpNumber(); // Get register sub-field
uint32_t addrGenMfrId = pCore->pAddrGen->pIpId->GetMfrNumber(); // Get register sub-field
pCore->pStartAddr->SetStartAddr(0x12345678); // Set a writable register
}
Of course one can just use the offsets in the definitions files directly in the
test code and use the TB API. Note that the auto-generated classes automat-
ically pick up access to the VProc I/O API when compiled for simulation, and so
make accesses over the bus in simulation.
As the auto-generated files are all headers they do not need to be specifically
compiled, but the directory where they are generated needs to be specified in
the make file with the EXTINCLDIR make variable. In addition the JSONFILES
make variable needs extending with the relevant JSON files that the HAL is
dependant on. This is discussed in section 4 above.