TBW(1)

NAME
tbw - wrapper script to start GHDL-based VHDL test benches

SYNOPSIS
tbw TBPROG [OPTION]... [FILEDEF]... [GHDL-OPTION]...
tbw --help

DESCRIPTION
Executes the ghdl-based test bench TBPROG in an environment defined by the descriptor file tbw.dat and the FILEDEF arguments. Any additional options GHDL-OPTIONS are passed on to the test bench executable.

  Background
The VHDL implementation in ghdl has no direct support for passing command-line arguments to the VHDL code. All test benches in the Retro project use, therefore, fixed build-in generic file names. By convention, they refer to symlinks (see symlink(7)) which are set up by tbw to point to a specific file prior to the execution of the test bench.

  Default behavior
In the simplest case, tbw assumes a test bench with a single stimulus file which is opened by convention as '<TBPROG>_stim'. The default stimulus file is named '<TBPROG>_stim.dat'. tbw will simply define '<TBPROG>_stim' as a symlink referring to '<TBPROG>_stim.dat', or if defined to FILEDEF, and execute TBPROG. In essence
        ln -s -f <TBPROG>_stim.dat <TBPROG>_stim
        <TBPROG> <GHDL-OPTIONS>

  Using a tbw.dat configuration file
When the generic file name or the stimulus file name does not follow the simple default pattern or more than one input file is required a configuration file can be used to define the setup. It has the fixed name tbw.dat and is searched in the directory of the test bench program TBPROG. The format is described in section FILES. In this case, the FILEDEF argument can be specified as 'tag=value' pairs where 'tag' refers to a generic name and 'value' gives the concrete file name. Useful when several input files are to be specified.

  Using inline configurations
A FILEDEF argument can have the form 'tag={line1;line2;...}'. In that case, a temporary file is created with the given lines and the name of the temporary file is associated with the tag as described above. This is often used in conjunction with the tag referring to the configuration file. This mechanism allows for rlink based test benches to specify '.scntl', '.sdata', 'rlmon', 'rbmon', and '.wait' startup commands on the tbw command line and is for example used by tbrun_tbwrri(1). The '-sxon' option of tbrun_tbwrri(1) creates for example
      _conf={.sdata 08 0002;.sdata 10 0002;}
which generates two 'simbus' configuration cycles before the simulation body starts.

  Test benches controlled with ti_rri
In this case, the communication between the test bench and the controlling ti_rri is done via two named pipes (see fifo(7)). The test bench might open in addition a configuration file. This setup is also defined via the tbw.dat file, for details see section FILES.

OPTIONS
The options -fifo, -verbose, and -norun are processed by tbw itself. They must be the first options after TBPROG.

-fifo
    Forces usage of rlink_cext fifo in case no tbw.dat is found or no section matching TBPROG is found in tbw.dat.

-verbose
    Show the used tag,value settings before execution

-norun
    Start simulator in interactive mode. The default for _XSim or _ISim tb's is to ensure that the simulation runs till the end, as for ghdl. Therefore a '-R' option for XSim or a 'run all' command for ISim is generated. The -norun option suppresses this.

GHDL OPTIONS
All options are passed on to the test bench executable. The list of available options for a ghdl-generated executable can be inquired with the "--help" option. Some especially useful options are:

--wave=file
    dump signal values into a wave file (use file type .ghw). Far superior to the VCD format and allows for inspecting all VHDL records and all data types with gtkwave(1).

--stack-max-size=n
    set maximum stack size. Very helpful in the case of very large models. A value of n=16384 is in general enough for all generated models, which usually have a large number of very simple processes.

--stop-time=t
    stop the simulation at time t (in VHDL notation, e.g. 100ns).

--disp-time
    display time as simulation advances.

--trace-processes
    display process name before each cycle.

ENVIRONMENT

TBW_GHDL_OPTS
    Additional options that are passed to ghdl-based simulations. Of particular value are

    --ieee-asserts=disable-at-0
        suppresses assertion warnings from the ieee libraries at startup time (t=0ns).

    --unbuffered
        sets output at all files (stdout, stderr, and files opened for write) to unbuffered mode. This is very helpful to keep output from the ghdl simulation and other programs in a co-simulation environment in synch. Note: only available for GHDL 0.34dev after merge of Jonsba/master #100 on 2016-06-26.

FILES

./tbw.dat
    This configuration file is searched for in the directory of the test bench program TBPROG and holds associations between generic file names and concrete file names for one or more test bench executables. It contains sections of the format
            [TBPROG]
            <generic name 1> = <concrete file name 1>
            <generic name 2> = <concrete file name 2>

    Usage with Stimulus file based test benches
        tbw will create a symlink(7) with the generic name which refers to the given concrete file name. A typical example is
                [tb_nx_cram_memctl_as]
                tb_nx_cram_memctl_stim = tb_nx_cram_memctl_stim.dat

    Usage with test benches controlled with ti_rri
        The special token <fifo> indicates that a named pipe is used rather than a normal file. In this case, tbw will create a fifo(7) rather than a symlink. Another special token is
         <null>, it simply translates to /dev/null and can be used as a default value for configuration files. Currently, all rlink-based test benches use the same generic names and have a setup like
                [tb_w11a_n3]
                rlink_cext_fifo_rx = <fifo>
                rlink_cext_fifo_tx = <fifo>
                rlink_cext_conf = <null>

EXAMPLES

  Stimulus file based test benches
Test benches are usually self-checking and produce a comprehensive log file. For each checked response, the line contains the word "CHECK" and either an "OK" or a "FAIL", in the latter case in general with an indication of what's wrong. Other unexpected behavior, like timeouts, will also result in a line containing the word "FAIL". When the simulation stops a line with the word "DONE" is printed. These test benches are usually run like
      tbw <testbenchname> [stimfile] | tbfilt --tee <logfile>
where
    -   tbw sets up the stimulus file and runs the test bench executable
    -   tbfilt ensures that the full log is saved and the PASS/FAIL criteria are extracted
The convenience script tbrun_tbw(1) can be used in many cases to create such a pipeline.

  Test benches controlled with ti_rri
In these cases, the test bench is started via ti_rri using the --run and --fifo options. Also here usually a pipe with tbfilt(1) is used, a typical example is
      ti_rri --run="tbw tb_tst_rlink_n3" --fifo --logl=3 -- \
            "package require tst_rlink" \
            "tst_rlink::setup" "tst_rlink::test_all" |\
         tbfilt --tee=tb_tst_rlink_n3_bsim.log
The convenience script tbrun_tbwrri(1) can be used in many cases to create these sometimes rather lengthy constructs.

SEE ALSO
tbrun_tbw(1), tbfilt(1), ti_rri(1), tbrun_tbwrri(1), gtkwave(1), symlink(7), fifo(7)

AUTHOR
Walter F.J. Mueller <W.F.J.Mueller@gsi.de>