mirror of
https://github.com/wfjm/w11.git
synced 2026-05-03 14:49:57 +00:00
251 lines
9.1 KiB
Groff
251 lines
9.1 KiB
Groff
.\" -*- nroff -*-
|
|
.\" $Id: tbw.1 1250 2022-07-10 10:21:03Z mueller $
|
|
.\" SPDX-License-Identifier: GPL-3.0-or-later
|
|
.\" Copyright 2013-2022 by Walter F.J. Mueller <W.F.J.Mueller@gsi.de>
|
|
.\"
|
|
.\" ------------------------------------------------------------------
|
|
.
|
|
.TH TBW 1 2016-10-02 "Retro Project" "Retro Project Manual"
|
|
.\" ------------------------------------------------------------------
|
|
.SH NAME
|
|
tbw \- wrapper script to start GHDL-based VHDL test benches
|
|
.\" ------------------------------------------------------------------
|
|
.SH SYNOPSIS
|
|
.
|
|
.SY tbw
|
|
.I TBPROG
|
|
.RI [ OPTION ]...
|
|
.RI [ FILEDEF ]...
|
|
.RI [ GHDL-OPTION ]...
|
|
.
|
|
.SY tbw
|
|
.B \-\-help
|
|
.YS
|
|
.
|
|
.\" ------------------------------------------------------------------
|
|
.SH DESCRIPTION
|
|
Executes the \fBghdl\fP-based test bench \fITBPROG\fP in an environment
|
|
defined by the descriptor file \fItbw.dat\fP and the \fIFILEDEF\fP
|
|
arguments. Any additional options \fIGHDL-OPTIONS\fP are passed on to the test
|
|
bench executable.
|
|
|
|
.SS Background
|
|
The VHDL implementation in \fBghdl\fP 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 \fBsymlink\fP(7)) which are set up by
|
|
\fBtbw\fP to point to a specific file prior to the execution of the
|
|
test bench.
|
|
|
|
.SS Default behavior
|
|
In the simplest case, \fBtbw\fP 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\'. \fBtbw\fP will simply
|
|
define \'<TBPROG>_stim\' as a symlink referring to \'<TBPROG>_stim.dat\',
|
|
or if defined to \fIFILEDEF\fP, and execute \fITBPROG\fP. In essence
|
|
|
|
.EX
|
|
ln -s -f <TBPROG>_stim.dat <TBPROG>_stim
|
|
<TBPROG> <GHDL-OPTIONS>
|
|
.EE
|
|
.
|
|
.SS Using a \fItbw.dat\fP 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
|
|
\fItbw.dat\fP and is searched in the directory of the test bench program
|
|
\fITBPROG\fP.
|
|
The format is described in section FILES.
|
|
|
|
In this case, the \fIFILEDEF\fP 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.
|
|
.
|
|
.SS Using inline configurations
|
|
A \fIFILEDEF\fP 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 \fBtbw\fP command line and is for example used by \fBtbrun_tbwrri\fP(1).
|
|
The '-sxon' option of \fBtbrun_tbwrri\fP(1) creates for example
|
|
.EX
|
|
_conf={.sdata 08 0002;.sdata 10 0002;}
|
|
.EE
|
|
which generates two 'simbus' configuration cycles before the simulation body
|
|
starts.
|
|
.
|
|
.SS Test benches controlled with \fBti_rri\fP
|
|
In this case, the communication between the test bench and the controlling
|
|
\fBti_rri\fP is done via two named pipes (see \fBfifo\fP(7)). The test
|
|
bench might open in addition a configuration file. This setup is also
|
|
defined via the \fItbw.dat\fP file, for details see section FILES.
|
|
.
|
|
.\" ------------------------------------------------------------------
|
|
.SH OPTIONS
|
|
The options \fB\-fifo\fP, \fB\-verbose\fP, and \fB\-norun\fP are processed
|
|
by \fBtbw\fP itself. They must be the first options after \fITBPROG\fP.
|
|
.IP \fB\-fifo\fR
|
|
Forces usage of rlink_cext fifo in case no \fItbw.dat\fP is found or no section
|
|
matching \fITBPROG\fP is found in tbw.dat.
|
|
.IP \fB\-verbose\fR
|
|
Show the used tag,value settings before execution
|
|
.IP \fB\-norun\fR
|
|
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 \fBghdl\fP. Therefore a '-R' option for XSim or a 'run all'
|
|
command for ISim is generated. The -norun option suppresses this.
|
|
|
|
.\" ------------------------------------------------------------------
|
|
.SH GHDL OPTIONS
|
|
All options are passed on to the test bench executable. The list of
|
|
available options for a \fBghdl\fP-generated executable can be inquired
|
|
with the "\fB\-\-help\fR" option. Some especially useful options are:
|
|
.
|
|
.\" ----------------------------------------------
|
|
.IP "\fB\-\-wave=\fIfile\fR"
|
|
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 \fBgtkwave\fP(1).
|
|
.
|
|
.\" ----------------------------------------------
|
|
.IP "\fB\-\-stack-max-size\fP=\fIn\fR"
|
|
set maximum stack size. Very helpful in the case of very large models. A value
|
|
of \fIn\fP=16384 is in general enough for all generated models, which usually
|
|
have a large number of very simple processes.
|
|
.
|
|
.\" ----------------------------------------------
|
|
.IP "\fB\-\-stop-time\fI=t\fR"
|
|
stop the simulation at time \fIt\fP (in VHDL notation, e.g. 100ns).
|
|
.
|
|
.\" ----------------------------------------------
|
|
.IP "\fB\-\-disp-time\fR"
|
|
display time as simulation advances.
|
|
.
|
|
.\" ----------------------------------------------
|
|
.IP "\fB\-\-trace-processes\fR"
|
|
display process name before each cycle.
|
|
.
|
|
.\" ------------------------------------------------------------------
|
|
.
|
|
.SH ENVIRONMENT
|
|
.IP \fBTBW_GHDL_OPTS\fP 4
|
|
Additional options that are passed to \fBghdl\fP-based simulations.
|
|
Of particular value are
|
|
.RS
|
|
.IP "\fB\-\-ieee\-asserts=disable\-at\-0\fP" 4
|
|
suppresses assertion warnings from the ieee libraries at startup time (t=0ns).
|
|
.IP "\fB\-\-unbuffered\fP"
|
|
sets output at all files (\fIstdout\fP, \fIstderr\fP, and files opened for
|
|
write) to unbuffered mode.
|
|
This is very helpful to keep output from the \fBghdl\fP
|
|
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.
|
|
.RE
|
|
.
|
|
.\" ------------------------------------------------------------------
|
|
.SH FILES
|
|
.IP "\fI./tbw.dat\fR" 4
|
|
This configuration file is searched for in the directory of the test bench
|
|
program \fITBPROG\fP and holds associations between generic file names and
|
|
concrete file names for one or more test bench executables. It contains
|
|
sections of the format
|
|
|
|
.EX
|
|
[\fITBPROG\fP]
|
|
<generic name 1> = <concrete file name 1>
|
|
<generic name 2> = <concrete file name 2>
|
|
...
|
|
.EE
|
|
|
|
.RS
|
|
.IP "\fBUsage with Stimulus file based test benches\fR" 4
|
|
\fBtbw\fP will create a \fBsymlink\fP(7) with the generic name which
|
|
refers to the given concrete file name. A typical example is
|
|
|
|
.EX
|
|
[tb_nx_cram_memctl_as]
|
|
tb_nx_cram_memctl_stim = tb_nx_cram_memctl_stim.dat
|
|
.EE
|
|
|
|
.IP "\fBUsage with test benches controlled with ti_rri\fR"
|
|
The special token \fI<fifo>\fP indicates that a named pipe is used
|
|
rather than a normal file. In this case, \fBtbw\fP will create a
|
|
\fBfifo\fP(7) rather than a symlink. Another special token is
|
|
\fI<null>\fP, it simply translates to \fI/dev/null\fP and can be
|
|
used as a default value for configuration files. Currently, all
|
|
\fBrlink\fP-based test benches use the same generic names and have
|
|
a setup like
|
|
|
|
.EX
|
|
[tb_w11a_n3]
|
|
rlink_cext_fifo_rx = <fifo>
|
|
rlink_cext_fifo_tx = <fifo>
|
|
rlink_cext_conf = <null>
|
|
.EE
|
|
|
|
.RE
|
|
.
|
|
.\" ------------------------------------------------------------------
|
|
.SH EXAMPLES
|
|
.SS 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
|
|
|
|
.EX
|
|
tbw <testbenchname> [stimfile] | tbfilt --tee <logfile>
|
|
.EE
|
|
|
|
where
|
|
.RS 2
|
|
.PD 0
|
|
.IP "\-" 2
|
|
\fBtbw\fP sets up the stimulus file and runs the test bench executable
|
|
.IP "\-"
|
|
\fBtbfilt\fP ensures that the full log is saved and the PASS/FAIL criteria
|
|
are extracted
|
|
.PD
|
|
.RE
|
|
|
|
The convenience script \fBtbrun_tbw\fP(1) can be used in many cases to create
|
|
such a pipeline.
|
|
|
|
.SS Test benches controlled with \fBti_rri\fP
|
|
In these cases, the test bench is started via \fBti_rri\fP using the
|
|
\fB\-\-run\fP and \fB\-\-fifo\fP options. Also here usually a pipe with
|
|
\fBtbfilt\fP(1) is used, a typical example is
|
|
|
|
.EX
|
|
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
|
|
.EE
|
|
|
|
The convenience script \fBtbrun_tbwrri\fP(1) can be used in many cases to
|
|
create these sometimes rather lengthy constructs.
|
|
|
|
.
|
|
.\" ------------------------------------------------------------------
|
|
.SH "SEE ALSO"
|
|
.BR tbrun_tbw (1),
|
|
.BR tbfilt (1),
|
|
.BR ti_rri (1),
|
|
.BR tbrun_tbwrri (1),
|
|
.BR gtkwave (1),
|
|
.BR symlink (7),
|
|
.BR fifo (7)
|
|
|
|
.\" ------------------------------------------------------------------
|
|
.SH AUTHOR
|
|
Walter F.J. Mueller <W.F.J.Mueller@gsi.de>
|