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: 562
Valid CSS Valid XHTML 1.0 Strict