TBRUN(1)

NAME
tbrun - test bench driver

SYNOPSIS
tbrun [OPTION]... [DSCFILE]

DESCRIPTION
tbrun organizes the execution of large sets of test benches. It will
    -   read the file DSCFILE, which describes the full set of test benches. The top-level DSCFILE typically includes other files which allow organizing the description in a well-structured manner. If no DSCFILE is specified the file tbrun.yml in the current working directory is used.
    -   select based on the given --tag and --exclude options the tests to be executed in a given run.
    -   determine based on the --mode option the simulation engine and the simulation type, behavioral or post-synthesis or later. See section MODES for details.
    -   execute the tests which as much parallelism as possible. The --jobs option specifies the maximal number of jobs and a locking logic prevents more than one test from running in a working directory.

OPTIONS

--tag=tlist
    specifies the tags a test must match to be selected for execution. tlist can be a comma-separated list of tags, a test must match all tags given in tlist to be selected.
    --tag can be specified multiple times and the selections are ored. In effect, a test must match all tags in the tlist of one of the specified --tag options.
    If no --tag option is given an implicit --tag=default is assumed, so all tests with the tag 'default' are executed.

--exclude=tlist
    specifies the tags a test must not match. tlist can again be a comma-separated list, a test that matches all the tags given is excluded.
    --exclude can be specified multiple times and the rejections are ored. In effect, a test is rejected if it matches all tags in the tlist of one of the specified --exclude options.

--all
    is simply a shortcut for --tag=".*" and selects all tags. Can be combined with --exclude but not with other --tag options.

--mode=mlist
    determines the simulation engine and the type of simulation. Can be a comma-separated list, if several modes are specified all of them will be executed.
    If no --mode is given the default value 'bsim' is used. Note that unlike --tag and --exclude only a single --mode option is processed, if multiple are present only the last one will be used.
    Each mode specification has the format '[engine]_[type]' and follows the model name suffix rules of the build system. If the engine part is omitted ghdl(1) is assumed as the default. If the type part is omitted 'bsim' is assumed as default. Other supported values for engine are
        ISim
            the Xilinx ISE build-in simulator
        XSim
            the Xilinx Vivado build-in simulator
    The type part has the following supported values
        bsim
            behavioral simulation
        ssim
            post-synthesis functional simulation
        fsim
            post-map simulation (only ISE)
        osim
            post-optimize functional simulation (only Vivado)
        rsim
            post-routing functional simulation (only Vivado)
        esim
            post-synthesis timing simulation (only Vivado)
        psim
            post-optimize timing simulation (only Vivado)
        tsim
            post-routing timing simulation

--jobs=njob
    specifies the maximal number of parallel jobs. Without the --jobs option the tests are executed sequentially and the test output is forwarded immediately to stdout. With the --jobs option a task dispatcher is used which starts the jobs, received and buffers the test output, and forwards it to stdout when the job completes. The test outputs are always in the original selection order, thus not affected by the completion order. The task dispatcher displays also a progress line when stdout is a terminal device of the format
            #-I: t047: 5l 35.6s; t053: 5l 20.2s (26t,2w,31o)
    where
        t***:
            specifies the current task number
        **l number of output lines collected for this task
        *.*s
            run time (as real time) of the task (running since time)
        **t number of tasks still waiting for execution
        *w  number of tasks currently running
        *o  number of tasks in the pending output queue
    Note that --jobs enables the task dispatcher and thus output buffering and progress line output even when njob is '1' !

--tee=outfile
    if specified all output send to stdout except for the progress line updates is also written in the file outfile. This is very convenient in conjunction with the --jobs option which generates progress line output only when stdout is a terminal device. Using shell pipes and tee(1) will therefore prevent progress lines, use the --tee instead to save the output into a file.

--list
    list selected tags and quit.

--dry
    dry run, prints the generated commands, but doesn't execute. When used without the --jobs option a commented list of shell commands is printed which describes the linear execution of the selected tests.
    When used together with --jobs this option mainly serves to debug the task dispatcher. A random wait of 0.2 to 1.8 sec is generated for each selected test.

--trace
    prints additional information on job control.

--nomake
    don't execute make step of the test bench. Will be forwarded to tbrun_tbw(1) and tbrun_tbwrri(1) based test benches.

--norun
    don't execute run step of the test bench, useful to only execute make step. Will be forwarded to tbrun_tbw(1) and tbrun_tbwrri(1) based test benches.

--rlmon
    enable the rlink monitor, will be forwarded to tbrun_tbwrri(1) based test benches.

--rbmon
    enable the rbus monitor, will be forwarded to tbrun_tbwrri(1) based test benches.

--bwait=twait
    specifies startup wait for behavioral simulations. twait must be an integer, the time unit is 1 ns. Will be forwarded to tbrun_tbwrri(1)-based test benches.

--swait=twait
    specifies startup wait for post-synthesis and higher simulations. twait must be an integer, the time unit is 1 ns. Will be forwarded to tbrun_tbwrri(1)-based test benches.

--help
    print short help text.

EXIT STATUS
In case of an error, the exit codes are:
    1   run time errors, like a bad option, file not found, etc
    2   at least one test FAILed, test bench has FAILed

ENVIRONMENT

TBW_GHDL_OPTS
    Used by tbw(1) to define additional options for ghdl-based simulations. Usually set to "--unbuffered --ieee-asserts=disable-at-0", see tbw(1) documentation.

EXAMPLES

tbrun
    The simplest default case, will use the tbrun.yml file in the current working directory, assume --tag=default, and --mode=bsim. This selects all tests tagged with 'default' and runs the behavioral simulation with ghdl(1). Done in simple sequential mode.

tbrun --jobs=2 --tag=viv,sys_w11a --mode=XSim
    Will select all tests which have a 'viv' and a 'sys_w11a' tag, use XSim as the simulation engine and run the behavioral simulation. Will use the task dispatcher and will try to run 2 tests in parallel.

SEE ALSO
tbrun_tbw(1), tbrun_tbwrri(1), tbfilt(1)

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