firmware_tools/verification/tb_template
2022-03-11 14:43:23 +00:00
..
test ELGIP-186. tb_ctrl.vhd outputs 3 clocks which are delta times appart. Fix so that in sync as per a PLL so SIM matches real world 2022-03-11 14:43:23 +00:00
README.txt Added informaton to the README.txt of the tb_template for adding the EL HAL 2019-06-14 07:30:25 +01:00

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.