|
Generated: 2023-02-09 |
Generated by man2html V0.26
page hit count: 637 |
|
TBW(1) Retro Project Manual 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 com- mand-line arguments to the VHDL code. All test benches in the Retro project use, therefore, fixed build-in generic file names. By conven- tion, 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 con- crete 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 configura- tion file. This mechanism allows for rlink based test benches to spec- ify '.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 control- ling 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 gener- ated 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 exe- cutables. 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 simu- lation 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 crite- ria 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), sym- link(7), fifo(7) AUTHOR Walter F.J. Mueller <W.F.J.Mueller@gsi.de> Retro Project 2016-10-02 TBW(1)
|
Generated: 2023-02-09 |
Generated by man2html V0.26
page hit count: 637 |
|