github.com/wfjm.w11
1
0
Fork 0
mirror of https://github.com/wfjm/w11.git synced 2026-01-13 23:47:36 +00:00
Code Issues Releases Wiki Activity

man pages: editorial changes [skip ci]

Browse Source
This commit is contained in:
wfjm 2022-05-15 11:38:43 +02:00
parent aa16a9e989
commit 8ddb2fd67e
37 changed files with 529 additions and 488 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

43
tools/man/man1/asm-11_expect.1
View File

@ -1,8 +1,8 @@
.\" -*- nroff -*-
.\" $Id: asm-11_expect.1 1233 2022-04-30 07:01:23Z mueller $
.\" $Id: asm-11_expect.1 1237 2022-05-15 07:51:47Z mueller $
.\" SPDX-License-Identifier: GPL-3.0-or-later
.\" Copyright 2014-2018 by Walter F.J. Mueller <W.F.J.Mueller@gsi.de>
.\"
.\" Copyright 2014-2022 by Walter F.J. Mueller <W.F.J.Mueller@gsi.de>
.\"
.\" ------------------------------------------------------------------
.
.TH ASM-11_EXPECT 1 2018-11-03 "Retro Project" "Retro Project Manual"
@ -22,7 +22,7 @@ asm-11_expect \- expect checker for asm-11 test bench
.
.\" ------------------------------------------------------------------
.SH DESCRIPTION
Reads one of more \fBasm-11\fP(1) listing files and checks for unexpected
Reads one of more \fBasm-11\fP(1) listing files and checks for unexpected
assembly errors and tests for expected address and generated data values.
What is expected is specified by comments, described in the
section EXPECT COMMENTS, which are added to the asm-11 source code.
@ -36,9 +36,9 @@ asm-11_expect produces at least a one-line summary per file like
asm-11_expect: test_0020_expr.lst OK
.EE
.PP
where each file is marked either \fBOK\fR or \fBFAILED\fR.
In case of detected errors additional output follows which describes
of each error and the affected listing line, like
where each file is marked either \fBOK\fR or \fBFAILED\fR.
In case of detected errors, additional output follows which describes
each error and the affected listing line, like
.PP
.EX
asm-11_expect: test_0110_op_gg.lst FAILED
@ -46,7 +46,7 @@ of each error and the affected listing line, like
in: 1 27 001042 067700 177736 add @pa,r0 ;;!! 067700 177734
.EE
.PP
Main application for asm-11_expect is to build a self-checking test benches
The main application for asm-11_expect is to build self-checking test benches
for \fBasm-11\fP(1).
.
.
@ -66,18 +66,18 @@ with
list of expected assembly error flags, given as a sequence of uppercase letters
without white space between letters.
.IP "\fBaddr\fP"
expected location counter (value of '.'), given as 6 digit octal number.
expected location counter (value of '.'), given as 6 digit octal number.
Note that all 6 digits must be specified, even leading zeros.
.IP "\fBdata\fP"
expected generated assembly output data, given as blank separated list
expected generated assembly output data, given as a blank-separated list
of either 3 (for byte output) or 6 (for word output) digit octal numbers.
Again, all 3 or 6 digits must be specified, even leading zeros.
This is checked against the data section of the assembly listing.
This is checked against the data section of the assembly listing.
.br
In general, this is used to check data emitted into the binary output.
However, some assembler statements, e.g. assignments or directives like .end,
indicate some result value in data section, and this can of course be
checked as well.
However, some assembler statements, e.g. assignments or directives like .end,
indicate some result value in the data section, and this can of course be
checked as well.
.PD
.PP
All three components are optional. Error flags are always tested, if no
@ -85,7 +85,7 @@ All three components are optional. Error flags are always tested, if no
been generated for the line. Address and data tests are only done in case
\fIaddr\fP or \fIdata\fP components have been given.
.PP
If a line starts with an expect comment it will be applied to the asm-11
If a line starts with an expect comment it will be applied to the asm-11
statement in the following line. Or it is simply appended to an asm-11
statement.
.SS Comment examples
@ -97,8 +97,8 @@ expect that the current location will be 001020, data not checked
expect that the listing data section shows two words, 074167 and 177762.
The address is not checked.
.IP "\fB;;!! 001004: 000207\fR"
expect that the current location will be 001004 and that the listing data section
shows one word with the value 000207.
expect that the current location will be 001004 and that the listing data
section shows one word with the value 000207.
.SS Some practical cases
.EX
@ -126,7 +126,7 @@ shows one word with the value 000207.
.
.\" ----------------------------------------------
.IP "\fB\-\-tline\fR"
Prints input lines from listing file as they are processed. Helpful to
Prints input lines from the listing file as they are processed. Helpful to
debug expect comments, e.g. in conjunction with the \fB-\-tcheck\fR
option.
.
@ -139,19 +139,20 @@ the content of the comment, like
exp: err=T | ;;!! T
exp: dot=001000 | ;;!! 001000:
exp: dat=060037 001000 | ;;!! 060037 001000
exp: dot=001006 dat=004767 | ;;!! 001006: 004767
exp: dot=001006 dat=004767 | ;;!! 001006: 004767
.EE
.
.\" ----------------------------------------------
.IP "\fB\-\-help\fR"
print full help text and exit.
.
.\" ------------------------------------------------------------------
.SH EXIT STATUS
In case of an error the exit codes are:
In case of an error, the exit codes are:
.RS
.PD 0
.IP \fB1\fP 3
run time errors, like bad option, file not found, etc
run time errors, like a bad option, file not found, etc
.IP \fB2\fP 3
at least one expect FAILed, test bench has FAILed
.PD

22
tools/man/man1/config_wrapper.1
View File

@ -1,8 +1,8 @@
.\" -*- nroff -*-
.\" $Id: config_wrapper.1 1234 2022-05-03 18:28:48Z mueller $
.\" $Id: config_wrapper.1 1237 2022-05-15 07:51:47Z mueller $
.\" SPDX-License-Identifier: GPL-3.0-or-later
.\" Copyright 2013- by Walter F.J. Mueller <W.F.J.Mueller@gsi.de>
.\"
.\" Copyright 2013-2022 by Walter F.J. Mueller <W.F.J.Mueller@gsi.de>
.\"
.\" ------------------------------------------------------------------
.
.TH CONFIG_WRAPPER 1 2013-01-02 "Retro Project" "Retro Project Manual"
@ -91,8 +91,8 @@ Configure an FPGA with XILINX ISE \fBimpact\fP. The input \fIFILE\fP must be in
.\" ----------------------------------------------
.IP \fBjconfig\fP
Configure an FPGA with \fBjtag\fP(1). The input \fIFILE\fP must be in
\fI.svf\fP format. This sub command is usually used for boards with a
Cypress FX2 USB controller, like the Digilent Nexys2, Nexys3 or Atlys,
\fI.svf\fP format. This subcommand is usually used for boards with a
Cypress FX2 USB controller, like the Digilent Nexys2, Nexys3, or Atlys,
and an FX2 firmware that emulates an Altera USB-Blaster programming cable.
The USB device path is defined by the environment variables \fBRETRO_FX2_VID\fP
@ -100,25 +100,25 @@ and \fBRETRO_FX2_PID\fP, or defaults to vid=16c0 and pid=03ef.
Use the \fBfx2load_wrapper\fP(1) command to ensure that the proper firmware
is loaded in the Cypress FX2 USB controller.
The \fBbit2svf\fP sub command can be used to create a \fI.svf\fP from
The \fBbit2svf\fP subcommand can be used to create a \fI.svf\fP from
a \fI.bit\fP file.
.
.\" ------------------------------------------------------------------
.SH EXIT STATUS
In case of an error an exit status 1 is returned.
In case of an error, an exit status 1 is returned.
.
.\" ------------------------------------------------------------------
.SH ENVIRONMENT
.IP "\fBRETRO_FX2_VID, RETRO_FX2_PID\fR" 4
Used by the \fBjconfig\fP sub command to define the USB path of the
Used by the \fBjconfig\fP subcommand to define the USB path of the
Cypress FX2 USB controller emulating an Altera USB-Blaster cable.
.IP \fBXILINX\fR
Path to current XILINX ISE installation. Required by all sub commands,
Path to current XILINX ISE installation. Required by all subcommands,
mainly to locate the \fI.bsdl\fP files which describe the JTAG commands
of all devices in the JTAG chain.
.br
Best is to use \fBconfig_wrapper\fP with the \fBxtwi\fP(1) wrapper, this will
automatically define this environment variable.
The best is to use \fBconfig_wrapper\fP with the \fBxtwi\fP(1) wrapper, this
will automatically define this environment variable.
.
.\" ------------------------------------------------------------------
.SH EXAMPLES

16
tools/man/man1/console_starter.1
View File

@ -1,8 +1,8 @@
.\" -*- nroff -*-
.\" $Id: console_starter.1 1233 2022-04-30 07:01:23Z mueller $
.\" $Id: console_starter.1 1237 2022-05-15 07:51:47Z mueller $
.\" SPDX-License-Identifier: GPL-3.0-or-later
.\" Copyright 2013-2014 by Walter F.J. Mueller <W.F.J.Mueller@gsi.de>
.\"
.\" Copyright 2013-2022 by Walter F.J. Mueller <W.F.J.Mueller@gsi.de>
.\"
.\" ------------------------------------------------------------------
.
.TH CONSOLE_STARTER 1 2010-07-09 "Retro Project" "Retro Project Manual"
@ -25,9 +25,9 @@ console_starter \- setup vt52/vt100 emulator windows for ti_rri or simh
.
.\" ------------------------------------------------------------------
.SH DESCRIPTION
Script to setup an \fBxterm\fP vt52 or vt100 emulator window which
Script to set up an \fBxterm\fP vt52 or vt100 emulator window which
will connect to a DL11 or DZ11 serial interface emulation port of
\fBti_rri\fP or a CPU emulator from the \fBsimh\fP suite,
\fBti_rri\fP or a CPU emulator from the \fBsimh\fP suite,
e.g. \fBpdp11\fP, via a \fBtelnet\fP connection.
If the connection to the interface emulation port fails or is terminated
@ -38,7 +38,7 @@ a message like
Trying 127.0.0.1...
telnet: Unable to connect to remote host: Connection refused
telnet failed with rc=256
enter q or <^D> to quit, otherwise hit <ENTER> to reconnect:
enter q or <^D> to quit, otherwise hit <ENTER> to reconnect:
.EE
is displayed in the \fBxterm\fP window. Entering a 'q' or 'Control-D'
@ -58,7 +58,7 @@ defines the terminal emulator type. Allowed values are:
.IP \fBvt100\fP 8
use VT100 emulation. The default.
.IP \fBvt52\fP
use VT52 emulation. Useful in conjunction with OS which do not have VT100
use VT52 emulation. Useful in conjunction with OS which does not have VT100
support, like early DEC RSX-11M versions.
.RE
.RE
@ -67,7 +67,7 @@ support, like early DEC RSX-11M versions.
.\" ----------------------------------------------
.IP "\fB\-d \fIdev\fR"
defines the serial interface emulation port to connect to. Supported
are currently primary and secondary DL11 interface and eight lines of
are currently primary and secondary DL11 interfaces and eight lines of
the first DZ11 interface. Allowed values for \fIdev\fP are:
.RS
.RS 3

43
tools/man/man1/create_disk.1
View File

@ -1,8 +1,8 @@
.\" -*- nroff -*-
.\" $Id: create_disk.1 1233 2022-04-30 07:01:23Z mueller $
.\" $Id: create_disk.1 1237 2022-05-15 07:51:47Z mueller $
.\" SPDX-License-Identifier: GPL-3.0-or-later
.\" Copyright 2013-2015 by Walter F.J. Mueller <W.F.J.Mueller@gsi.de>
.\"
.\" Copyright 2013-2022 by Walter F.J. Mueller <W.F.J.Mueller@gsi.de>
.\"
.\" ------------------------------------------------------------------
.
.TH CREATE_DISK 1 2015-06-04 "Retro Project" "Retro Project Manual"
@ -25,8 +25,8 @@ create_disk \- create disk container file for ti_w11
.
.\" ------------------------------------------------------------------
.SH DESCRIPTION
Creates a disk container file \fIFILE\fP with the proper size for a disk of
type \fItyp\fP.
Creates a disk container file \fIFILE\fP with the proper size for a disk of
type \fItyp\fP.
.
.\" ------------------------------------------------------------------
.SH OPTIONS
@ -34,23 +34,21 @@ type \fItyp\fP.
.\" ----------------------------------------------
.IP \fB\-\-typ=\fItyp\fR
determines disk type, must be specified.
The list of supported disk types can be obtained with the
.B \-\-help
option.
The list of supported disk types can be obtained with the \fB\-\-help\fP option.
.
.\" ----------------------------------------------
.IP \fB\-\-ini=\fIpat\fR
determines whether the container file will be initialized with a specific
data pattern. Note that the \fB\-\-bad\fP and \fB\-\-boot\fP options will
data pattern. Note that the \fB\-\-bad\fP and \fB\-\-boot\fP options will
overwrite the last track or the first sector(s) respectively.
The default without \fB\-\-ini\fR is to create a container with all zero data.
It is implemented by writing a single zero byte after positioning with
\fBlseek\fR(2) to the desired end. This creates a file with 'holes' and defers
the actual allocation of disk space to the point when sectors are written.
It is implemented by writing a single zero byte after positioning with
\fBlseek\fR(2) to the desired end. This creates a file with 'holes' and defers
the actual allocation of disk space to the point when sectors are written.
Allowed values for \fIpat\fP are
.RS
.IP \fBzero\fP
creates a disk with all sectors zero'ed. In this case zero's are explicitly
creates a disk with all sectors zero'ed. In this case, zero's are explicitly
written. The explicit allocation of disk space is the main effect of this
option.
.IP \fBones\fP
@ -60,7 +58,7 @@ creates a disk with an alternating 0xdead 0xbeaf pattern. Can be helpful
to diagnose whether an operating system accesses uninitialized parts of a disk.
.IP \fBtest\fP
creates a disk with a unique test pattern in each sector. The whole disk
is initialized with groups of 8 16bit words (in PDP-11 little endian) with
is initialized with groups of 8 16bit words (in PDP-11 little-endian) with
.RS
.RS 3
@ -84,9 +82,8 @@ number of sectors for disk type
.RE
.PD
.PP
A \fBhexdump\fP(1) of a RP06 disk image initialized with
\fB\-\-ini\fP=\fItest\fP
will look like
A \fBhexdump\fP(1) of an RP06 disk image initialized with
\fB\-\-ini\fP=\fItest\fP will look like
.EX
0000000 0000 0000 0000 0000 0000 032f 0013 0016
@ -104,7 +101,7 @@ will look like
.
.\" ----------------------------------------------
.IP \fB\-\-bad\fP
creates a DEC standard 044 compliant bad block table on the last track
creates a DEC standard 044 compliant bad block table on the last track
of the disk container file.
.
.\" ----------------------------------------------
@ -136,23 +133,21 @@ print full help, with list \fB\-\-typ\fP and \fB\-\-ini\fP options.
.
.\" ------------------------------------------------------------------
.SH EXIT STATUS
If the file
.I FILE
can not be created an exit status 1 is returned.
If the file \fIFILE\fP can not be created an exit status 1 is returned.
.\" ------------------------------------------------------------------
.SH EXAMPLES
.IP "\fBcreate_disk -typ=rk05 rk05.dsk\fR" 4
This will create a zero'ed disk contained sized for an RK05 disk. In most
cases it is sufficient to create such plain zero'ed disk images.
cases, it is sufficient to create such plain zero'ed disk images.
.
.IP "\fBcreate_disk -typ=rl02 -bad rl02.dsk\fR"
Creates an RL02 sized disk with a 'factory bad block table'. When using
Creates an RL02-sized disk with a 'factory bad block table'. When using
RLxx, RPxx, or RMxx type disks, especially in conjunction with DEC
operating systems, it is advisable to create disks with \fB\-\-bad\fP.
.
.IP "\fBcreate_disk -typ=rk05 -ini=test rk05_test.dsk\fR"
Creates an RK05 sized disk with test pattern.
Creates an RK05-sized disk with a test pattern.
.
.\" ------------------------------------------------------------------
.SH "SEE ALSO"

12
tools/man/man1/dmpcntanal.1
View File

@ -1,8 +1,8 @@
.\" -*- nroff -*-
.\" $Id: dmpcntanal.1 1231 2022-04-28 08:40:50Z mueller $
.\" $Id: dmpcntanal.1 1237 2022-05-15 07:51:47Z mueller $
.\" SPDX-License-Identifier: GPL-3.0-or-later
.\" Copyright 2018- by Walter F.J. Mueller <W.F.J.Mueller@gsi.de>
.\"
.\" Copyright 2018-2022 by Walter F.J. Mueller <W.F.J.Mueller@gsi.de>
.\"
.\" ------------------------------------------------------------------
.
.TH DMPCNTANAL 1 2018-10-21 "Retro Project" "Retro Project Manual"
@ -57,7 +57,7 @@ show the CPU events columns
instruction rate in MHz
.PD 0
.IP \fIvfetc\fP
vector fetch rate, sum of traps, exceptions, and interrupts.
vector-fetch rate, the sum of traps, exceptions, and interrupts.
.IP \fIirupt\fP
interrupt rate
.IP \fIi/b\fP
@ -94,7 +94,7 @@ write hit rate in %.
.IP \fIrwt\fP
average number of wait cycles per memory read (in miss case).
.IP \fIwwt\fP
average number of wait cycles per memory write (from back pressure).
average number of wait cycles per memory write (from backpressure).
.IP \fIwt/i\fP
average number of memory wait cycles per instruction.
.PD
@ -157,7 +157,7 @@ format in the form like \fIw.p\fR with a single-digit field width \fIw\fR
and single-digit precision \fIp\fR. If \fIp\fR is \fI0\fR no decimal point
is printed. If omitted \fI4.1\fR is assumed.
.IP \fBmul\fP
multiplier, given as integer of floating point number.
multiplier, given as integer of floating-point number.
If omitted 1. is assumed.
.IP \fBnum\fP
name of numerator counter

8
tools/man/man1/dmscntanal.1
View File

@ -1,8 +1,8 @@
.\" -*- nroff -*-
.\" $Id: dmscntanal.1 1231 2022-04-28 08:40:50Z mueller $
.\" $Id: dmscntanal.1 1237 2022-05-15 07:51:47Z mueller $
.\" SPDX-License-Identifier: GPL-3.0-or-later
.\" Copyright 2015- by Walter F.J. Mueller <W.F.J.Mueller@gsi.de>
.\"
.\" Copyright 2015-2022 by Walter F.J. Mueller <W.F.J.Mueller@gsi.de>
.\"
.\" ------------------------------------------------------------------
.
.TH DMSCNTANAL 1 2015-12-29 "Retro Project" "Retro Project Manual"
@ -23,7 +23,7 @@ dmscntanal \- analyze dmscnt data
.SH DESCRIPTION
Analyses converted dmscnt data, which was generated by \fBdmscntconv\fR(1)
from w11a dmscnt unit raw data. Currently, only some build-in statistics
is shown.
are shown.
.
.\" ------------------------------------------------------------------
.SH OPTIONS

10
tools/man/man1/dmscntconv.1
View File

@ -1,8 +1,8 @@
.\" -*- nroff -*-
.\" $Id: dmscntconv.1 1233 2022-04-30 07:01:23Z mueller $
.\" $Id: dmscntconv.1 1237 2022-05-15 07:51:47Z mueller $
.\" SPDX-License-Identifier: GPL-3.0-or-later
.\" Copyright 2015- by Walter F.J. Mueller <W.F.J.Mueller@gsi.de>
.\"
.\" Copyright 2015-2022 by Walter F.J. Mueller <W.F.J.Mueller@gsi.de>
.\"
.\" ------------------------------------------------------------------
.
.TH DMSCNTCONV 1 2015-12-29 "Retro Project" "Retro Project Manual"
@ -28,8 +28,8 @@ usually generated by a \fBti_w11\fR Tcl command \fIrw11::sc_read\fR
and contains counter index and counter values as hex data.
\fBdmscntconv\fR will convert this into a human-readable table of state
numbers, state names and state counts for kernel and non-kernel modes.
The state names are retrieved from the \fIpdp11_sequencer.vhd\fR source file,
the path to and name of the source file can be specified with the
The state names are retrieved from the \fIpdp11_sequencer.vhd\fR source file
and the path to and name of the source file can be specified with the
\fB\-\-src\fR option.
.
.\" ------------------------------------------------------------------

16
tools/man/man1/file2tap.1
View File

@ -1,8 +1,8 @@
.\" -*- nroff -*-
.\" $Id: file2tap.1 1233 2022-04-30 07:01:23Z mueller $
.\" $Id: file2tap.1 1237 2022-05-15 07:51:47Z mueller $
.\" SPDX-License-Identifier: GPL-3.0-or-later
.\" Copyright 2015- by Walter F.J. Mueller <W.F.J.Mueller@gsi.de>
.\"
.\" Copyright 2015-2022 by Walter F.J. Mueller <W.F.J.Mueller@gsi.de>
.\"
.\" ------------------------------------------------------------------
.
.TH FILE2TAP 1 2015-06-03 "Retro Project" "Retro Project Manual"
@ -28,16 +28,16 @@ file2tap \- create a tap format tape container from individual files
.
.\" ------------------------------------------------------------------
.SH DESCRIPTION
Creates (\fB-c\fR) a new or appends (\fB-a\fR) to an existing tap format tape
Creates (\fB-c\fR) a new or appends (\fB-a\fR) to an existing tap format tape
container file \fTNAM\fR and adds files. The tape record size is specified
with a \fB-b\fR option followed by the record size in units 512 bytes.
Each tape file is built from a comma-separated list of disk files \fIFLIST\fR,
which are concatenated and written with a record size given by the last
which are concatenated and written with a record size given by the last
\fB-b\fR option.
\fBfile2tap\fR writes to stdout a one-line message for each created file which
gives the file number, number of records, the record size in bytes and the
names of the disk files used to build the tape file.
\fBfile2tap\fR writes to \fIstdout\fP a one-line message for each created
file which gives the file number, number of records, the record size in bytes,
and the names of the disk files used to build the tape file.
.
.\" ------------------------------------------------------------------
.SH OPTIONS

16
tools/man/man1/fx2load_wrapper.1
View File

@ -1,8 +1,8 @@
.\" -*- nroff -*-
.\" $Id: fx2load_wrapper.1 1234 2022-05-03 18:28:48Z mueller $
.\" $Id: fx2load_wrapper.1 1237 2022-05-15 07:51:47Z mueller $
.\" SPDX-License-Identifier: GPL-3.0-or-later
.\" Copyright 2013-2022 by Walter F.J. Mueller <W.F.J.Mueller@gsi.de>
.\"
.\"
.\" ------------------------------------------------------------------
.
.TH FX2LOAD_WRAPPER 1 2013-01-05 "Retro Project" "Retro Project Manual"
@ -29,7 +29,7 @@ fx2load_wrapper \- auto-load firmware into Cypress FX2 USB controller
Checks firmware state of a Cypress FX2 USB controller and re-loads the
firmware in case of a mismatch of currently active and desired firmware.
The command locates a USB device with a USB path defined by the environment
The command locates a USB device with a USB path defined by the environment
variables \fBRETRO_FX2_VID\fP and \fBRETRO_FX2_PID\fP, or default vid=16c0 and
pid=03ef.
It inquires with \fBlsusb\fP(1) the 'iProduct' attribute of the currently
@ -38,10 +38,10 @@ of the firmware image given with \fB-\-file\fP it is assumed the proper
firmware is already active. Otherwise the firmware image is loaded with
either \fBfxload\fP(1) or \fBcycfx2prog\fP.
\fBNote:\fP after a firmware load the Cypress FX2 USB controller restarts.
This causes a USB re-enumeratation, the USB device disconnects and reconnects
\fBNote:\fP after a firmware load the Cypress FX2 USB controller restarts.
This causes a USB re-enumeration, the USB device disconnects and reconnects
with a new device descriptor. It can take some time till the Linux USB stack
shows the new device descriptor. The command sleeps for 1.5 seconds, this is
shows the new device descriptor. The command sleeps for 1.5 seconds, this is
usually enough to ensure that subsequent commands see the new state.
.
.\" ------------------------------------------------------------------
@ -78,7 +78,7 @@ Use \fBcycfx2prog\fP instead of \fBfxload\fP(1) to load the firmware.
.
.\" ----------------------------------------------
.IP \fB\-\-force\fP
Unconditionally load the firmware, even when a 'iProduct' attribute match
Unconditionally load the firmware, even when an 'iProduct' attribute match
is seen. Useful to reset the Cypress FX2 controller.
.
.\" ----------------------------------------------
@ -106,7 +106,7 @@ firmware path in case no \fB\-\-ihx_path\fP option is given.
.SH EXAMPLES
.IP "\fBfx2load_wrapper --board=nexys2 --file=nexys2_jtag_2fifo_ic.ihx\fR" 4
Checks whether the 'nexys2_jtag_2fifo_ic' version of the firmware is loaded
and in case not loads the firmware image.
and in case not, loads the firmware image.
.\" ------------------------------------------------------------------
.SH "SEE ALSO"

12
tools/man/man1/github_md2html.1
View File

@ -1,8 +1,8 @@
.\" -*- nroff -*-
.\" $Id: github_md2html.1 1233 2022-04-30 07:01:23Z mueller $
.\" $Id: github_md2html.1 1237 2022-05-15 07:51:47Z mueller $
.\" SPDX-License-Identifier: GPL-3.0-or-later
.\" Copyright 2017-2018 by Walter F.J. Mueller <W.F.J.Mueller@gsi.de>
.\"
.\" Copyright 2017-2022 by Walter F.J. Mueller <W.F.J.Mueller@gsi.de>
.\"
.\" ------------------------------------------------------------------
.
.TH GITHUB_MD2HTML 1 2018-11-03 "Retro Project" "Retro Project Manual"
@ -22,10 +22,10 @@ github_md2html \- convert markdown to HTML with GitHub API
Converts Markdown files to HTML using the GitHub converter API.
\fIFILE\fP can either be a file name or a directory name (e.g. '.').
If it's a directory, the whole sub-tree will be scanned and all files
with an extension of \fI.md\fP will be converted.
with an extension of \fI.md\fP will be converted.
The created HTML files have the extension \fI.md.html\fP.
Unless the \fB-force\fP option is given the script checks whether the
Unless the \fB-force\fP option is given the script checks whether the
\fI.md.html\fP
file already exists and converts only when the markdown file is newer than
the HTML file.
@ -55,7 +55,7 @@ print status of each inspected file. The default is to list only converted files
.
.\" ----------------------------------------------
.IP "\fB\-context \fIcont\fR"
defines the GitHub repository context.
defines the GitHub repository context.
.
.\" ----------------------------------------------
.IP "\fB\-dump\fR"

12
tools/man/man1/ip_create_br.1
View File

@ -1,8 +1,8 @@
.\" -*- nroff -*-
.\" $Id: ip_create_br.1 1231 2022-04-28 08:40:50Z mueller $
.\" $Id: ip_create_br.1 1237 2022-05-15 07:51:47Z mueller $
.\" SPDX-License-Identifier: GPL-3.0-or-later
.\" Copyright 2017- by Walter F.J. Mueller <W.F.J.Mueller@gsi.de>
.\"
.\" Copyright 2017-2022 by Walter F.J. Mueller <W.F.J.Mueller@gsi.de>
.\"
.\" ------------------------------------------------------------------
.
.TH IP_CREATE_BR 1 2017-04-14 "Retro Project" "Retro Project Manual"
@ -19,10 +19,10 @@ ip_create_br \- create bridge and re-connect ethernet interface
.SH DESCRIPTION
This script expects a default single Ethernet interface setup, creates
a bridge named 'br0', and re-connects Ethernet interface to this bridge.
a bridge named 'br0', and re-connects the Ethernet interface to this bridge.
The script bails out gracefully in case 'br0' already exists. In not, it
determines the name of the Ethernet interface, accepting both old 'eth*' and
determines the name of the Ethernet interface, accepting both old 'eth*' and
new 'en*' naming, and verifies that it is a single Ethernet configuration.
Then it creates a bridge device named 'br0' and re-connects the physical
Ethernet interface to the bridge, preserving all IP addresses and routes.
@ -31,7 +31,7 @@ This script is part of setting up tap devices with \fBip_create_tap\fR(1)
but can be used independently.
The script should be started as a normal user, but uses \fBsudo\fR(8) to
execute privileged commands and might therefore ask for the user password.
execute privileged commands, and might therefore ask for the user password.
.
.\" ------------------------------------------------------------------
.SH "SEE ALSO"

8
tools/man/man1/ip_create_tap.1
View File

@ -1,8 +1,8 @@
.\" -*- nroff -*-
.\" $Id: ip_create_tap.1 1231 2022-04-28 08:40:50Z mueller $
.\" $Id: ip_create_tap.1 1237 2022-05-15 07:51:47Z mueller $
.\" SPDX-License-Identifier: GPL-3.0-or-later
.\" Copyright 2017- by Walter F.J. Mueller <W.F.J.Mueller@gsi.de>
.\"
.\" Copyright 2017-2022 by Walter F.J. Mueller <W.F.J.Mueller@gsi.de>
.\"
.\" ------------------------------------------------------------------
.
.TH IP_CREATE_TAP 1 2017-04-14 "Retro Project" "Retro Project Manual"
@ -28,7 +28,7 @@ by default. The tap device will be accessible to the user which executes
the script. Finally, the created tap device is connected to bridge 'br0'.
The script should be started as a normal user, but uses \fBsudo\fR(8) to
execute privileged commands and might therefore ask for the user password.
execute privileged commands, and might therefore ask for the user password.
.
.\" ------------------------------------------------------------------

22
tools/man/man1/ldadump.1
View File

@ -1,14 +1,14 @@
.\" -*- nroff -*-
.\" $Id: ldadump.1 1188 2019-07-13 14:31:51Z mueller $
.\" $Id: ldadump.1 1237 2022-05-15 07:51:47Z mueller $
.\" SPDX-License-Identifier: GPL-3.0-or-later
.\" Copyright 2019- by Walter F.J. Mueller <W.F.J.Mueller@gsi.de>
.\"
.\" Copyright 2019-2022 by Walter F.J. Mueller <W.F.J.Mueller@gsi.de>
.\"
.\" ------------------------------------------------------------------
.
.TH DMPCNTANAL 1 2019-04-14 "Retro Project" "Retro Project Manual"
.TH LDADUMP 1 2019-04-14 "Retro Project" "Retro Project Manual"
.\" ------------------------------------------------------------------
.SH NAME
ldadump \- dump lda file (absolute loader papertape format)
ldadump \- dump lda file (absolute loader paper tape format)
.\" ------------------------------------------------------------------
.SH SYNOPSIS
.
@ -22,18 +22,18 @@ ldadump \- dump lda file (absolute loader papertape format)
.
.\" ------------------------------------------------------------------
.SH DESCRIPTION
Reads files in \fIlda\fP format, also known as absolute loader papertape
Reads files in \fBlda-11\fP(5) format, also known as absolute loader paper tape
format, and prints a dump of the memory image. The default dump format
is a compact with up to 8 words per line. The \fB\-\-lsm\fP option changes
this to a \fIlsmem\fP command style address data list with a single word
per line.
this \fBlsm-11\fP(5) format, an \fIlsmem\fP command style address data list
with a single word per line.
.\" ------------------------------------------------------------------
.SH OPTIONS
.
.\" ----------------------------------------------
.IP "\fB\-\-lsm\fR"
use one word per line \fIlsmem\fP command style output format.
use one word per line in \fBlsm-11\fP(5) format.
.
.\" ----------------------------------------------
.IP "\fB\-\-trec\fR"
@ -81,7 +81,9 @@ block 13, length 0 byte, address 000001:000000
.\" ------------------------------------------------------------------
.SH "SEE ALSO"
.BR asm-11 (1)
.BR asm-11 (1),
.BR lda-11 (5),
.BR lsm-11 (5)
.\" ------------------------------------------------------------------
.SH AUTHOR

16
tools/man/man1/njobihtm.1
View File

@ -1,8 +1,8 @@
.\" -*- nroff -*-
.\" $Id: njobihtm.1 1233 2022-04-30 07:01:23Z mueller $
.\" $Id: njobihtm.1 1237 2022-05-15 07:51:47Z mueller $
.\" SPDX-License-Identifier: GPL-3.0-or-later
.\" Copyright 2016- by Walter F.J. Mueller <W.F.J.Mueller@gsi.de>
.\"
.\" Copyright 2016-2022 by Walter F.J. Mueller <W.F.J.Mueller@gsi.de>
.\"
.\" ------------------------------------------------------------------
.
.TH NJOBIHTM 1 2016-10-01 "Retro Project" "Retro Project Manual"
@ -21,7 +21,7 @@ njobihtm \- number of jobs considering hyper-threading and memory
.SH DESCRIPTION
\fBnjobihtm\fP determines the number of CPU-intensive jobs based on the
number of CPU and memory resources. The 'ihtm' stands for 'intelligent
hyper-threading and memory'. The script
hyper-threading and memory'. The script
.RS 2
.PD 0
@ -30,8 +30,8 @@ determines the number of physical cores and the number of threads per core
.IP "-"
assumes that only a quarter of the additional hyper-threads are useful
.IP "-"
if \fB-m\fP is given. determines the memory size, assumes that at least
one GB should be available for general usage and limits the number of
if \fB-m\fP is given, determines the memory size, assumes that at least
one GB should be available for general usage, and limits the number of
jobs accordingly.
.PD
.RE
@ -44,7 +44,7 @@ The number of jobs is written to STDOUT, and can be used like `njobs`.
.\" -- --mem -------------------------------------
.IP \fB\-m\ \fIsize\fR
gives the required physical memory per job.
\fIsize\fP must be given as an integer with either a 'M' or 'G', indicating MB
\fIsize\fP must be given as an integer with either an 'M' or 'G', indicating MB
or GB.
.
.\" -- --verbose ---------------------------------
@ -54,7 +54,7 @@ if given the found system parameters and the reasoning is printed to STDERR.
.\" ------------------------------------------------------------------
.SH EXAMPLES
.IP "\fBmake -j `njobihtm` all\fR" 4
Start \fBmake\fR(1) with a reasonable number of jobs.
Start \fBmake\fR(1) with a reasonable number of jobs.
.IP "\fBnjobihtm -v -m=2G\fR" 4
Determines the number of jobs with 2 GB memory per job. On a system with 4 cores
and hyper-threading and 8 GB installed memory one gets due to the '-v' the

4
tools/man/man1/oskit_setup.1
View File

@ -1,8 +1,8 @@
.\" -*- nroff -*-
.\" $Id: oskit_setup.1 1188 2019-07-13 14:31:51Z mueller $
.\" $Id: oskit_setup.1 1237 2022-05-15 07:51:47Z mueller $
.\" SPDX-License-Identifier: GPL-3.0-or-later
.\" Copyright 2019- by Walter F.J. Mueller <W.F.J.Mueller@gsi.de>
.\"
.\"
.\" ------------------------------------------------------------------
.
.TH OSKIT_SETUP 1 2019-07-13 "Retro Project" "Retro Project Manual"

87
tools/man/man1/ostest.1
View File

@ -1,11 +1,11 @@
.\" -*- nroff -*-
.\" $Id: ostest.1 1234 2022-05-03 18:28:48Z mueller $
.\" $Id: ostest.1 1237 2022-05-15 07:51:47Z mueller $
.\" SPDX-License-Identifier: GPL-3.0-or-later
.\" Copyright 2019- by Walter F.J. Mueller <W.F.J.Mueller@gsi.de>
.\"
.\" Copyright 2019-2022 by Walter F.J. Mueller <W.F.J.Mueller@gsi.de>
.\"
.\" ------------------------------------------------------------------
.
.TH OSTEST 1 2019-07-20 "Retro Project" "Retro Project Manual"
.TH OSTEST 1 2022-05-09 "Retro Project" "Retro Project Manual"
.\" ------------------------------------------------------------------
.SH NAME
ostest \- oskit test driver
@ -14,7 +14,7 @@ ostest \- oskit test driver
.
.SY ostest
.RI [ OPTION ]...
.RI [ TEST ]...
.RI [ KIT ]...
.
.SY ostest
.B \-\-help
@ -22,22 +22,52 @@ ostest \- oskit test driver
.
.\" ------------------------------------------------------------------
.SH DESCRIPTION
\fBostest\fP organizes the automatized testing of operating systems.
It will
\fBostest\fP organizes the automatized testing of oskits. If no \fIKIT\fP
argument is given a default set of oskits is tested. The default set depends
on the available memory and thus on the board (specified with \fB\-\-sys\fP).
If \fIKIT\fP arguments are given only these oskits will be tested.
\fBostest\fP starts for each oskit the operating system and executes
some commands to verify basic system functionality.
The major steps are:
.
.RS 2
.PD 0
.IP "-" 2
configure the connected board if the \fB\-\-config\fP option is specified
determine the execution mode, either from the \fB\-\-mode\fP option or the
default \fIrri\fP, and load the execution mode package.
.IP "-"
determine, based on the available memory size, which operating systems
can be run on the board.
determine the target board, either from the \fB\-\-sys\fP option or from
the \fBEXPTEST_SYS\fP environment variable, and source the setup definition.
That defines board properties, like memory size, and the default set of oskits.
.IP "-"
check for each eligible operating system whether the oskit and the
required container files are available, and download or unpack them
in case they aren't.
configure the connected board if the \fB\-\-config\fP option is specified.
.IP "-"
boot each eligible operating system and execute a variety of system tests.
for each oskit:
.
.RS 2
.PD 0
.IP "-" 2
source the oskit definition. That loads os family-specific code and defines
oskit-specific parameters.
.IP "-"
verify in the preboot procedure whether all preconditions for the execution
of the oskit are met, e.g. a network environment.
.IP "-"
check whether disk/tape images for the oskit are loaded, and if not,
download and unpack them with \fBoskit_setup\fP(1).
.IP "-"
boot the operating system and set the system time.
.IP "-"
execute some tests.
.IP "-"
execute shutdown procedure.
.IP "-"
wait till the CPU enters the HALT state.
.PD
.RE
.PP
.
.PD
.RE
.PP
@ -49,11 +79,12 @@ boot each eligible operating system and execute a variety of system tests.
.\" ----------------------------------------------
.IP "\fB\-\-sys=\fIsys\fP"
Defines the system which is configured, or in case the \fB\-\-config\fP
is given, is to be configured.
is given, is to be configured. Must be specified if the \fBEXPTEST_SYS\fP
environment variable is not specified.
.
.\" ----------------------------------------------
.IP "\fB\-\-mode=\fImode\fP"
Defines the execution mode. The default is \fIrri\fP and currently the
Defines the execution mode. The default is \fIrri\fP and is currently the
only supported mode.
.
.\" ----------------------------------------------
@ -86,7 +117,7 @@ Defines root of all retro project files.
\" ------------------------------------------------------------------
.SH FILES
.IP "\fI$RETROBASE/tools/tcl/exptest_<mode>.tcl\fP" 4
Implementation for mode \fImode\fP.
Implementation for execution mode \fImode\fP.
.IP "\fI$RETROBASE/tools/exptest/sys/<sys>_setup.tcl\fP"
Setup file for system \fIsys\fP.
.IP "\fI$RETROBASE/tools/oskit/test/kit/<kit>_setup.tcl\fP"
@ -99,25 +130,35 @@ Path for execution environment for oskit \fIkit\fP.
.
.\" ------------------------------------------------------------------
.SH EXAMPLES
.IP "\fBostest --sys=sys_w11a_n4 -log\fP" 4
This command expects that a Digilent Nexys4 board is connected and already
configured with the \fIsys_w11a_n4\fP system. It will run tests for all
available operating systems and produce an output like
.IP "\fBostest --sys=sys_w11a_n4d -log\fP" 4
This command expects that a Digilent Nexys4 A7 board is connected and already
configured with the \fIsys_w11a_n4d\fP system. It will execute the set of
default tests for this board and produce output like
.EX
-I: log to ostest-2019-07-13-151006-sys_w11a_n4.log
-I: log to ostest-2019-07-13-151006-sys_w11a_n4d.log
----- 15:10:06 ( 0.0, 0.0): 211bsd_rpmin
----- 15:10:34 ( 27.9, 27.9): 211bsd_rk
----- 15:11:00 ( 53.9, 26.0): 211bsd_rl
----- 15:11:27 ( 80.7, 26.8): 211bsd_rp
----- 15:11:55 ( 109.0, 28.3): 211bsd_rpeth
-I: 'tap0' device required but not available
-I: skip kit '211bsd_rpeth'
-I: skip kit '211bsd_rpeth'
.EE
The \fI211bsd_rpeth\fP test was skipped because preconditions were not
fulfilled.
.IP "\fBostest --sys=sys_w11a_arty -log 211bsd_rpmin rsx11mp-30_rp\fP"
This command expects that a Digilent Arty board is connected and already
configured with the \fIsys_w11a_arty\fP system and executes the
\fI211bsd_rpmin\fP and \fIrsx11mp-30_rp\fP tests.
.\" ------------------------------------------------------------------
.SH "SEE ALSO"
.BR oskit_setup (1),
.BR mctest (1)
.\" ------------------------------------------------------------------
.SH AUTHOR
Walter F.J. Mueller <W.F.J.Mueller@gsi.de>

23
tools/man/man1/rm_dep.1
View File

@ -1,8 +1,8 @@
.\" -*- nroff -*-
.\" $Id: rm_dep.1 1188 2019-07-13 14:31:51Z mueller $
.\" $Id: rm_dep.1 1237 2022-05-15 07:51:47Z mueller $
.\" SPDX-License-Identifier: GPL-3.0-or-later
.\" Copyright 2010- by Walter F.J. Mueller <W.F.J.Mueller@gsi.de>
.\"
.\"
.\" ------------------------------------------------------------------
.
.TH RM_DEP 1 2010-07-24 "Retro Project" "Retro Project Manual"
@ -17,22 +17,19 @@ rm_dep \- remove vbomconv generated dependency files in a directory tree
.
.\" ------------------------------------------------------------------
.SH DESCRIPTION
.B rm_dep
removes all
.B vbomconv
generated dependency rule files from the whole directory tree starting
at the current working directory. Specifically, it removes
\fBrm_dep\fP removes all \fBvbomconv\fP generated dependency rule files
from the whole directory tree starting at the current working directory.
Specifically, it removes
.PP
.EX
*.dep_ghdl
*.dep_isim
*.dep_xst
*.dep_ghdl
*.dep_isim
*.dep_xst
*.dep_ucf_cpp
.EE
.PP
The script produces a log to
.I stdout
indicating all removed files, the messages are generated by '\fIrm -v\fP'.
The script produces a log to \fIstdout\fP indicating all removed files,
the messages are generated by '\fIrm -v\fP'.
.
.\" ------------------------------------------------------------------
.SH "SEE ALSO"

12
tools/man/man1/svn_set_ignore.1
View File

@ -1,8 +1,8 @@
.\" -*- nroff -*-
.\" $Id: svn_set_ignore.1 1231 2022-04-28 08:40:50Z mueller $
.\" $Id: svn_set_ignore.1 1237 2022-05-15 07:51:47Z mueller $
.\" SPDX-License-Identifier: GPL-3.0-or-later
.\" Copyright 2013- by Walter F.J. Mueller <W.F.J.Mueller@gsi.de>
.\"
.\" Copyright 2013-2022 by Walter F.J. Mueller <W.F.J.Mueller@gsi.de>
.\"
.\" ------------------------------------------------------------------
.
.TH SVN_SET_IGNORE 1 2010-04-26 "Retro Project" "Retro Project Manual"
@ -18,14 +18,14 @@ svn_set_ignore \- setup svn:ignore properties based on .gitignore files
.
.\" ------------------------------------------------------------------
.SH DESCRIPTION
Creates or updates a \fIsvn:ignore\fP property for the current directory
Creates or updates an \fIsvn:ignore\fP property for the current directory
and all sub-directories. The current directory must contain a
\fI.gitignore\fP file which defines the default list of ignore patterns for the
whole project. The local ignore pattern for each directory is the concatination
whole project. The local ignore pattern for each directory is the concatenation
of all \fI.gitignore\fP files found in the directory hierarchy.
.
If no \fIsvn:ignore\fP property exists or the existing one differs from
the ignore pattern list determined from the top level and local
the ignore pattern list determined from the top level and local
\fI.gitignore\fP file the property is set or updated.
.
.\" ------------------------------------------------------------------

23
tools/man/man1/tap2file.1
View File

@ -1,8 +1,8 @@
.\" -*- nroff -*-
.\" $Id: tap2file.1 1231 2022-04-28 08:40:50Z mueller $
.\" $Id: tap2file.1 1237 2022-05-15 07:51:47Z mueller $
.\" SPDX-License-Identifier: GPL-3.0-or-later
.\" Copyright 2015-2019 by Walter F.J. Mueller <W.F.J.Mueller@gsi.de>
.\"
.\" Copyright 2015-2022 by Walter F.J. Mueller <W.F.J.Mueller@gsi.de>
.\"
.\" ------------------------------------------------------------------
.
.TH TAP2FILE 1 2019-07-08 "Retro Project" "Retro Project Manual"
@ -23,14 +23,15 @@ tap2file \- split a tap format tape container into individual files
.
.\" ------------------------------------------------------------------
.SH DESCRIPTION
Reads the tap format tape container \fIFILE\fR and creates for tape file an
individual disk file. The created files are named \fIpref\fR_nn.dat, where
\fIpref\fR is either the prefix given with the \fB\-\-pref\fR option or the
Reads the tap format tape container \fIFILE\fR and creates for tape file an
individual disk file. The created files are named \fIpref\fR_nn.dat, where
\fIpref\fR is either the prefix given with the \fB\-\-pref\fR option or the
stem of \fIFILE\fR.
\fBtap2file\fR writes to stdout a one-line message for each created file which
gives the filename, the number of tape records, and the record length. In case
the record length is variable the minimal and the maximal record length is given.
\fBtap2file\fR writes to \fIstdout\fP a one-line message for each created file
which gives the filename, the number of tape records, and the record length.
In case the record length is variable the minimal and the maximal record
length is given.
.
.\" ------------------------------------------------------------------
.SH OPTIONS
@ -55,7 +56,7 @@ print full help text and exit.
.IP "\fBtap2file tmscptape.tap\fR" 4
reads the file \fItmscptape.tap\fR and creates a file for each tape file.
Because no \fB\-\-pref\fR option is given the output files will be named
"tmscptape_nn.dat". The stdout output might look like
"tmscptape_nn.dat". The \fIstdout\fP output might look like
.EX
tmscptape_00.dat: 73 records, length 512
@ -76,7 +77,7 @@ file contains a \fBtar\fR(1) archive.
.IP "\fBtap2file -v test.tap\fR" 4
reads the file \fItest.tap\fR and writes a one-line trace info for each record.
The stdout output might look like
The \fIstdout\fP output might look like
.EX
0, 0 : 80 : 00 00 00 00 50 00 06 07 08 09 0a 0b 0c 0d ...

47
tools/man/man1/tbfilt.1
View File

@ -1,8 +1,8 @@
.\" -*- nroff -*-
.\" $Id: tbfilt.1 1234 2022-05-03 18:28:48Z mueller $
.\" $Id: tbfilt.1 1237 2022-05-15 07:51:47Z mueller $
.\" SPDX-License-Identifier: GPL-3.0-or-later
.\" Copyright 2016-2022 by Walter F.J. Mueller <W.F.J.Mueller@gsi.de>
.\"
.\"
.\" ------------------------------------------------------------------
.
.TH TBFILT 1 2022-05-02 "Retro Project" "Retro Project Manual"
@ -36,8 +36,8 @@ as a filter during test bench execution, typically in a setup like
.EX
tbw <test_bench> 2>&1 | tbfilt --tee=<log_file>
.EE
tbfilt reads the output from the test bench via stdin and a pipe, filters
out the messages indicating a failure and shows them on stdout, and saves
tbfilt reads the output from the test bench via \fIstdin\fP and a pipe, filters
out the messages indicating a failure and shows them on \fIstdout\fP, and saves
the full test bench output to the file given in the \fB\-\-tee\fP option.
In this mode tbfilt works similar to a
.EX
@ -61,7 +61,7 @@ The exit status of tbfilt is 1 in case any of the tests is considered as
.PP
.
.SS Filter Criteria
A line that contains any of the following strings is considered as an
A line that contains any of the following strings is considered an
indication of a \fBFAIL\fPed test:
.RS 2
.PD 0
@ -83,7 +83,7 @@ hard to avoid in complex models and generally don't indicate a real issue.
.PD 0
.IP "-" 2
assertion warnings from IEEE libraries at startup (t=0ns). They are hard to
avoid in complex models and in general don't indicate a real issue. The best
avoid in complex models and in general, don't indicate a real issue. The best
is to suppress them in \fBghdl\fP(1) with the
option '--ieee-asserts=disable-at-0'.
That's usually done via the \fBTBW_GHDL_OPTS\fP environment variable used
@ -122,19 +122,19 @@ by a \fBbash\fP(1) 'time' command when
export TIMEFORMAT=$'real %3lR user %3lU sys %3lS'
.EE
is set. The wrapper scripts \fB\tbrun_tbw\fP(1) or \fBtbrun_tbwrri\fP(1)
are in general used to set this up correctly.
are in general used to set this up correctly.
.
.\" ------------------------------------------------------------------
.SH OPTIONS
.
.\" --------------------------------------------------------
.SS Filter Options
.SS Filter Options
.
.\" -- --tee -------------------------------------
.IP "\fB\-\-tee=\fIofile\fR"
All log file input is written to \fIofile\fP. Typically used to save the
test bench output in a file when tbfilt is used in filter mode in a pipeline
and reads from stdin.
and reads from \fIstdin\fP.
.
.\" -- --pcom ------------------------------------
.IP \fB\-\-pcom\fP
@ -153,7 +153,7 @@ This is functionally similar to a
.EE
pipeline.
When no '*' wildcard is found in \fIpatt\fR it is assumed to be a mode
When no '*' wildcard is found in \fIpatt\fR it is assumed to be a mode
specification and the pattern is prefixed by
.EX
.*/tb_.*_
@ -181,17 +181,17 @@ Selects summary mode. Only a single summary line per input file is written.
The format is configurable via the \fB\-\-format\fP, \fB\-\-wide\fP, and
\fB\-\-compact\fP options and via the \fBTBFILT_FORMAT\fP environment variable.
The precedence is (in increasing priority):
.RS
.RS
.PD 0
.IP " -" 4
build default ('%ec %pf %nf')
.IP " -"
.IP " -"
\fBTBFILT_FORMAT\fP option
.IP " -"
.IP " -"
\fB\-\-wide\fP option
.IP " -"
.IP " -"
\fB\-\-compact\fP option
.IP " -"
.IP " -"
\fB\-\-format\fP option
.PD
.RE
@ -208,14 +208,14 @@ on an 80 character wide line. Uses a format of "%fa %tg %sg %ec %pf %ns".
.
.\" -- --nohead ----------------------------------
.IP \fB\-\-nohead\fP
Suppresses the headline of summary outputs. Useful of summary output is
Suppresses the headline of summary outputs. Useful if the summary output is
piped into sort or other tools.
.
.\" -- --format ----------------------------------
.IP "\fB\-\-format=\fIfmt\fR"
Defined the format of the summary lines.
The format specification \fIfmt\fR string is a sequence of conversion
specifications of the form '%xx', which will be replaces by the respective
specifications of the form '%xx', which will be replaced by the respective
values and other characters which are simply copied (usually a blank as
delimiter).
The supported conversion specifications are:
@ -223,11 +223,11 @@ The supported conversion specifications are:
.PD 0
.IP \fB%fd\fP 5
modification date of input file (as yyyy-mm-dd)
.IP \fB%ft\fP
.IP \fB%ft\fP
modification time of input file (as hh:mm:ss)
.IP \fB%fs\fP
.IP \fB%fs\fP
modification time of input file short format (as hh:mm)
.IP \fB%fa\fP
.IP \fB%fa\fP
age of input file in seconds, minutes, hours or days
.IP \fB%tr\fP
real (wall clock) time of test bench run
@ -264,11 +264,11 @@ short file name (without path)
.
.\" ------------------------------------------------------------------
.SH EXIT STATUS
In case of an error the exit codes are:
In case of an error, the exit codes are:
.RS
.PD 0
.IP \fB1\fP 3
run time errors, like bad option, file not found, etc
run time errors, like a bad option, file not found, etc
.IP \fB2\fP 3
at least one test FAILed, test bench has FAILed
.PD
@ -280,7 +280,8 @@ at least one test FAILed, test bench has FAILed
Defines the default summary format and overwrites the build-in default of
"%ec %pf %nf".
.IP "\fBTBW_GHDL_OPTS\fR"
Used by \fBtbw\fP(1) to define additional options for GHDL based simulations.
Used by \fBtbw\fP(1) to define additional options for \fBghld\fP-based
simulations.
Usually set to "--unbuffered --ieee-asserts=disable-at-0", see \fBtbw\fP(1)
documentation.
.

81
tools/man/man1/tbrun.1
View File

@ -1,8 +1,8 @@
.\" -*- nroff -*-
.\" $Id: tbrun.1 1234 2022-05-03 18:28:48Z mueller $
.\" $Id: tbrun.1 1237 2022-05-15 07:51:47Z mueller $
.\" SPDX-License-Identifier: GPL-3.0-or-later
.\" Copyright 2016-2022 by Walter F.J. Mueller <W.F.J.Mueller@gsi.de>
.\"
.\"
.\" ------------------------------------------------------------------
.
.TH TBRUN 1 2022-05-02 "Retro Project" "Retro Project Manual"
@ -30,7 +30,7 @@ organizing the description in a well-structured manner. If no \fIDSCFILE\fP
is specified the file \fItbrun.yml\fP in the current working directory is
used.
.IP "-"
select based on the given \fB\-\-tag\fP and \fB\-\-exclude\fP options the
select based on the given \fB\-\-tag\fP and \fB\-\-exclude\fP options the
tests to be executed in a given run.
.IP "-"
determine based on the \fB\-\-mode\fP option the simulation engine and
@ -38,8 +38,8 @@ the simulation type, behavioral or post-synthesis or later. See section
MODES for details.
.IP "-"
execute the tests which as much parallelism as possible. The \fB\-\-jobs\fP
option specifies the maximal number of jobs and a locking logic prevents that
more than one test is run in one working directory.
option specifies the maximal number of jobs and a locking logic prevents
more than one test from running in a working directory.
.PD
.RE
.PP
@ -53,7 +53,7 @@ specifies the tags a test must match to be selected for execution.
\fItlist\fR can be a comma-separated list of tags, a test must match
all tags given in \fItlist\fR to be selected.
.br
\fB\-\-tag\fP can be specified multiple times, the selections are ored.
\fB\-\-tag\fP can be specified multiple times and the selections are ored.
In effect, a test must match all tags in the \fItlist\fR of one of the
specified \fB\-\-tag\fP options.
.br
@ -65,8 +65,8 @@ assumed, so all tests with the tag 'default' are executed.
specifies the tags a test must not match. \fItlist\fR can again be a
comma-separated list, a test that matches all the tags given is excluded.
.br
\fB\-\-exclude\fP can be specified multiple times, the rejections are ored.
In effect, a test is rejected if it matches all tags in the \fItlist\fR of
\fB\-\-exclude\fP can be specified multiple times and the rejections are ored.
In effect, a test is rejected if it matches all tags in the \fItlist\fR of
one of the specified \fB\-\-exclude\fP options.
.
.\" -- --all -------------------------------------
@ -77,19 +77,19 @@ combined with \fB\-\-exclude\fP but not with other \fB\-\-tag\fP options.
.\" -- --mode ------------------------------------
.IP \fB\-\-mode=\fImlist\fR
determines the simulation engine and the type of simulation. Can be a
comma separated list, if several modes are specified all of them will
comma-separated list, if several modes are specified all of them will
be executed.
.br
.br
If no \fB\-\-mode\fP is given the default value 'bsim' is used.
Note that unlike \fB\-\-tag\fP and \fB\-\-exclude\fP only a single
\fB\-\-mode\fP option is processed, if multiple are present only the
last one will be used.
.RS
Each mode specification has the format '[\fIengine\fP]_[\fItype\fP]'
Each mode specification has the format '[\fIengine\fP]_[\fItype\fP]'
and follows the model name suffix rules of the build system.
If the \fIengine\fP part is omitted \fBghdl\fP(1) is assumed as default.
If the \fIengine\fP part is omitted \fBghdl\fP(1) is assumed as the default.
If the \fItype\fP part is omitted 'bsim' is assumed as default.
Other supported values for \fIengine\fP are
.RS 2
@ -128,20 +128,20 @@ post-routing timing simulation
.IP \fB\-\-jobs=\fInjob\fR
.RS
specifies the maximal number of parallel jobs.
Without \fB\-\-jobs\fP option the tests are executed sequentially and
the test output is forwarded immediately to stdout.
Without the \fB\-\-jobs\fP option the tests are executed sequentially and
the test output is forwarded immediately to \fIstdout\fP.
With \fB\-\-jobs\fP 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.
With the \fB\-\-jobs\fP option a task dispatcher is used which starts the jobs,
received and buffers the test output, and forwards it to \fIstdout\fP 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
The task dispatcher displays also a progress line when \fIstdout\fP is a
terminal device of the format
.EX
#-I: t047: 5l 35.6s; t053: 5l 20.2s (26t,2w,31o)
.EE
where
where
.RS 2
.PD 0
.IP "t***:" 6
@ -165,10 +165,10 @@ buffering and progress line output even when \fInjob\fP is '1' !
.
.\" -- --tee -------------------------------------
.IP \fB\-\-tee=\fIoutfile\fR
if specified all output send to stdout except for the
if specified all output send to \fIstdout\fP except for the
progress line updates is also written in the file \fIoutfile\fR.
This is very convenient in conjunction with the \fB\-\-jobs\fP option
which generates progress line output only when stdout is a terminal
which generates progress line output only when \fIstdout\fP is a terminal
device.
Using shell pipes and \fBtee\fP(1) will therefore prevent progress lines,
use the \fB\-\-tee\fP instead to save the output into a file.
@ -180,7 +180,7 @@ list selected tags and quit.
.\" -- --dry -------------------------------------
.IP \fB\-\-dry\fP
dry run, prints the generated commands, but doesn't execute.
When used without \-\-jobs\fP option a commented list of shell commands
When used without the \-\-jobs\fP option a commented list of shell commands
is printed which describes the linear execution of the selected tests.
.br
When used together with \-\-jobs\fP this option mainly serves to debug
@ -193,37 +193,37 @@ prints additional information on job control.
.
.\" -- --nomake ----------------------------------
.IP \fB\-\-nomake\fP
don't execute make step of test bench.
Will be forwarded to \fBtbrun_tbw\fP(1) and \fBtbrun_tbwrri\fP(1)
don't execute make step of the test bench.
Will be forwarded to \fBtbrun_tbw\fP(1) and \fBtbrun_tbwrri\fP(1)
based test benches.
.
\" -- --norun -----------------------------------
.IP \fB\-\-norun\fP
don't execute run step of the test bench, useful to only execute make step.
Will be forwarded to \fBtbrun_tbw\fP(1) and \fBtbrun_tbwrri\fP(1)
Will be forwarded to \fBtbrun_tbw\fP(1) and \fBtbrun_tbwrri\fP(1)
based test benches.
.
\" -- --rlmon -----------------------------------
.IP \fB\-\-rlmon\fP
enable the rlink monitor, will be forwarded to \fBtbrun_tbwrri\fP(1)
enable the rlink monitor, will be forwarded to \fBtbrun_tbwrri\fP(1)
based test benches.
.
\" -- --rbmon -----------------------------------
.IP \fB\-\-rbmon\fP
enable the rbus monitor, will be forwarded to \fBtbrun_tbwrri\fP(1)
enable the rbus monitor, will be forwarded to \fBtbrun_tbwrri\fP(1)
based test benches.
.
.\" -- --bwait ----------------------------------
.IP \fB\-\-bwait=\fItwait\fR
specifies startup wait for behavioral simulations.
specifies startup wait for behavioral simulations.
\fItwait\fR must be an integer, the time unit is 1 ns. Will be forwarded
to \fBtbrun_tbwrri\fP(1) based test benches.
to \fBtbrun_tbwrri\fP(1)-based test benches.
.
.\" -- --swait ----------------------------------
.IP \fB\-\-swait=\fItwait\fR
specifies startup wait for post-synthesis and higher simulations.
specifies startup wait for post-synthesis and higher simulations.
\fItwait\fR must be an integer, the time unit is 1 ns. Will be forwarded
to \fBtbrun_tbwrri\fP(1) based test benches.
to \fBtbrun_tbwrri\fP(1)-based test benches.
.
\" -- --help -------------------------------------
.IP \fB\-\-help\fP
@ -231,11 +231,11 @@ print short help text.
.
.\" ------------------------------------------------------------------
.SH EXIT STATUS
In case of an error the exit codes are:
In case of an error, the exit codes are:
.RS
.PD 0
.IP \fB1\fP 3
run time errors, like bad option, file not found, etc
run time errors, like a bad option, file not found, etc
.IP \fB2\fP 3
at least one test FAILed, test bench has FAILed
.PD
@ -244,7 +244,8 @@ at least one test FAILed, test bench has FAILed
.\" ------------------------------------------------------------------
.SH ENVIRONMENT
.IP "\fBTBW_GHDL_OPTS\fR" 4
Used by \fBtbw\fP(1) to define additional options for GHDL based simulations.
Used by \fBtbw\fP(1) to define additional options for
\fBghdl\fP-based simulations.
Usually set to "--unbuffered --ieee-asserts=disable-at-0", see \fBtbw\fP(1)
documentation.
.
@ -252,12 +253,12 @@ documentation.
.SH EXAMPLES
.IP "\fBtbrun" 4
The simplest default case, will use the \fItbrun.yml\fP file in the current
working directory, assume \fI\-\-tag=default\fP, and \fI\-\-mode=bsim\fP
and this select all tests tagged with 'default' and run the behavioral
working directory, assume \fI\-\-tag=default\fP, and \fI\-\-mode=bsim\fP.
This selects all tests tagged with 'default' and runs the behavioral
simulation with \fBghdl\fP(1). Done in simple sequential mode.
.IP "\fBtbrun --jobs=2 --tag=viv,sys_w11a --mode=XSim" 4
Will select all tests which have a 'viv' and a 'sys_w11a' tag,
use XSim as simulation engine and run the behavioral simulation.
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.
.
.\" ------------------------------------------------------------------

16
tools/man/man1/tbrun_tbw.1
View File

@ -1,14 +1,14 @@
.\" -*- nroff -*-
.\" $Id: tbrun_tbw.1 1231 2022-04-28 08:40:50Z mueller $
.\" $Id: tbrun_tbw.1 1237 2022-05-15 07:51:47Z mueller $
.\" SPDX-License-Identifier: GPL-3.0-or-later
.\" Copyright 2016- by Walter F.J. Mueller <W.F.J.Mueller@gsi.de>
.\"
.\" Copyright 2016-2022 by Walter F.J. Mueller <W.F.J.Mueller@gsi.de>
.\"
.\" ------------------------------------------------------------------
.
.TH TBRUN_TBW 1 2016-08-21 "Retro Project" "Retro Project Manual"
.\" ------------------------------------------------------------------
.SH NAME
tbrun_tbw \- \fBtbw\fP based test bench starter
tbrun_tbw \- \fBtbw\fP-based test bench starter
.\" ------------------------------------------------------------------
.SH SYNOPSIS
.
@ -20,7 +20,7 @@ tbrun_tbw \- \fBtbw\fP based test bench starter
.
.\" ------------------------------------------------------------------
.SH DESCRIPTION
\fBtbrun_tbw\fP is a convenience script for starting \fBtbw\fP(1) based
\fBtbrun_tbw\fP is a convenience script for starting \fBtbw\fP(1)-based
test benches. It will
.RS 2
@ -30,7 +30,7 @@ issue a \fBmake\fP(1) command to (re)-build \fITBENCH\fP.
.IP "-"
build a \fBtbw\fP(1) command, using \fISTIMFILE\fP if specified.
.IP "-"
create a shell pipe to which runs tbw and handles the test bench output with
create a shell pipe which runs tbw and handles the test bench output with
\fBtbfilt\fP(1) to determine success or failure.
.PD
.RE
@ -39,7 +39,7 @@ create a shell pipe to which runs tbw and handles the test bench output with
.\" ------------------------------------------------------------------
.SH OPTIONS
Note: \fBtbrun_tbw\fP is implemented as a shell script. If options have an
argument it is separated white space and not by '='! So write '--ghw\ xxx'
argument it is separated by white space and not by '='! So write '--ghw\ xxx'
and not '--ghw=xxx' !
.
.\" -- --dry -------------------------------------
@ -71,7 +71,7 @@ write a ghw file with name '\fIfname\fP.ghw'
append \fIopts\fP to the \fBtbw\fP(1) command
.\" -- --pcom ------------------------------------
.IP \fB\-\-pcom\fR
enables that test bench comments are passed to stdout.
enables that test bench comments are passed to \fIstdout\fP.
.
.\" ------------------------------------------------------------------
.SH EXAMPLES

24
tools/man/man1/tbrun_tbwrri.1
View File

@ -1,14 +1,14 @@
.\" -*- nroff -*-
.\" $Id: tbrun_tbwrri.1 1231 2022-04-28 08:40:50Z mueller $
.\" $Id: tbrun_tbwrri.1 1237 2022-05-15 07:51:47Z mueller $
.\" SPDX-License-Identifier: GPL-3.0-or-later
.\" Copyright 2016- by Walter F.J. Mueller <W.F.J.Mueller@gsi.de>
.\"
.\" Copyright 2016-2022 by Walter F.J. Mueller <W.F.J.Mueller@gsi.de>
.\"
.\" ------------------------------------------------------------------
.
.TH TBRUN_TBWRRI 1 2016-09-17 "Retro Project" "Retro Project Manual"
.\" ------------------------------------------------------------------
.SH NAME
tbrun_tbw \- \fBti_rri\fP plus \fBtbw\fP based test bench starter
tbrun_tbw \- \fBti_rri\fP plus \fBtbw\fP-based test bench starter
.\" ------------------------------------------------------------------
.SH SYNOPSIS
.
@ -20,8 +20,8 @@ tbrun_tbw \- \fBti_rri\fP plus \fBtbw\fP based test bench starter
.
.\" ------------------------------------------------------------------
.SH DESCRIPTION
\fBtbrun_tbwrri\fP is a convenience script for starting \fBti_rri\fP(1) plus
\fBtbw\fP(1) based test benches. It will
\fBtbrun_tbwrri\fP is a convenience script for starting \fBti_rri\fP(1) plus
\fBtbw\fP(1)-based test benches. It will
.RS 2
.PD 0
@ -38,7 +38,7 @@ setup commands resulting from \fB\-\-cuff\fP, \fB\-\-fusp\fP, ...
.IP " -"
all optional \fICOMMANDS\fP
.IP "-" 2
create shell pipe to filter the output with \fBtbfilt\fP(1) to determine
create a shell pipe to filter the output with \fBtbfilt\fP(1) to determine
the success or failure.
.PD
.RE
@ -64,7 +64,7 @@ don't execute test bench (useful to only execute make step)
.
.\" -- --lsuf ------------------------------------
.IP \fB\-\-lsuf\ \fIsuff\fR
use '_\fIsuff\fR.log' as thesuffix for the log file. The default is '_bsim.log'
use '_\fIsuff\fR.log' as the suffix for the log file. The default is '_bsim.log'
.
.\" -- --stack -----------------------------------
.IP \fB\-\-stack\ \fInnn\fR
@ -98,18 +98,18 @@ For s3board, nexys2, and nexys3 designs.
.
.\" -- --sxon ------------------------------------
.IP \fB\-\-sxon\fR
switched\ XON: enable XON flow control with SWI(1), will generate
appropriate 'rlc oob' commands and ti_rri \-\-fifo options.
switched\ XON: enable XON flow control with SWI(1), will generate
appropriate 'rlc oob' commands and ti_rri \-\-fifo options.
For nexys4 designs.
.
.\" -- --hxon ------------------------------------
.IP \fB\-\-hxon\fR
hardwired\ XON: will generate appropriate \fBti_rri\fP \fB\-\-fifo\fP options.
hardwired\ XON: will generate appropriate \fBti_rri\fP \fB\-\-fifo\fP options.
For basys3 and arty designs.
.
.\" -- --pcom ------------------------------------
.IP \fB\-\-pcom\fR
enables that test bench comments are passed to stdout.
enables that test bench comments are passed to \fIstdout\fP.
.
.\" -- --rlmon -----------------------------------
.IP \fB\-\-rlmon\fR

59
tools/man/man1/tbw.1
View File

@ -1,14 +1,14 @@
.\" -*- nroff -*-
.\" $Id: tbw.1 1234 2022-05-03 18:28:48Z mueller $
.\" $Id: tbw.1 1237 2022-05-15 07:51:47Z mueller $
.\" SPDX-License-Identifier: GPL-3.0-or-later
.\" Copyright 2013-2016 by Walter F.J. Mueller <W.F.J.Mueller@gsi.de>
.\"
.\" 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
tbw \- wrapper script to start GHDL-based VHDL test benches
.\" ------------------------------------------------------------------
.SH SYNOPSIS
.
@ -24,14 +24,14 @@ tbw \- wrapper script to start GHDL based VHDL test benches
.
.\" ------------------------------------------------------------------
.SH DESCRIPTION
Executes the \fBghdl\fP based test bench \fITBPROG\fP in an environment
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
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
@ -40,7 +40,7 @@ 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
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
@ -50,15 +50,15 @@ or if defined to \fIFILEDEF\fP, and execute \fITBPROG\fP. In essence
.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
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
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 Test benches controlled with \fBti_rri\fP
@ -69,7 +69,7 @@ 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
The options \fB\-fifo\fP, \fB\-verbose\fP, and \fB\-norun\fP are processed
by tbw 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
@ -79,13 +79,13 @@ 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 GHDL. Therefore a '-R' option for XSim or a 'run all' command
for ISim is generated. The -norun option suppresses this.
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
available options for a \fBghdl\fP-generated executable can be inquired
with the "\fB\-\-help\fR" option. Some especially useful options are:
.
.\" ----------------------------------------------
@ -96,8 +96,8 @@ types with \fBgtkwave\fP(1).
.
.\" ----------------------------------------------
.IP "\fB\-\-stack-max-size\fP=\fIn\fR"
set maximum stack size. Very helpful in case of very large models. A value
of \fIn\fP=16384 is in general enough for all generated models, which usually
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.
.
.\" ----------------------------------------------
@ -116,14 +116,15 @@ display process name before each cycle.
.
.SH ENVIRONMENT
.IP \fBTBW_GHDL_OPTS\fP 4
Additional options which are passed to GHDL based simulations.
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 (stdout, stderr, and files opened for write) to
unbuffered mode. This is very helpful to keep output from the GHDL
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.
@ -133,8 +134,8 @@ Note: only available for GHDL 0.34dev after merge of Jonsba/master #100 on
.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
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
@ -160,7 +161,7 @@ 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
\fBrlink\fP-based test benches use the same generic names and have
a setup like
.EX
@ -180,12 +181,12 @@ For each checked response, the line contains the word \fICHECK\fP and either
an \fIOK\fP or a \fIFAIL\fP, 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 \fIFAIL\fP.
containing the word \fIFAIL\fP.
When the simulation stops a line with the word \fIDONE\fP is printed.
These test benches are usually run like
.EX
tbw <testbenchname> [stimfile] | tbfilt --tee <logfile>
tbw <testbenchname> [stimfile] | tbfilt --tee <logfile>
.EE
where
@ -203,15 +204,15 @@ 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
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
tbfilt --tee=tb_tst_rlink_n3_bsim.log
.EE
The convenience script \fBtbrun_tbwrri\fP(1) can be used in many cases to

32
tools/man/man1/ti_rri.1
View File

@ -1,8 +1,8 @@
.\" -*- nroff -*-
.\" $Id: ti_rri.1 1234 2022-05-03 18:28:48Z mueller $
.\" $Id: ti_rri.1 1237 2022-05-15 07:51:47Z mueller $
.\" SPDX-License-Identifier: GPL-3.0-or-later
.\" Copyright 2013-2022 by Walter F.J. Mueller <W.F.J.Mueller@gsi.de>
.\"
.\"
.\" ------------------------------------------------------------------
.
.TH TI_RRI 1 2017-01-08 "Retro Project" "Retro Project Manual"
@ -19,8 +19,8 @@ ti_rri \- \fBRlink\fP Backend Server
.
.\" ------------------------------------------------------------------
.SH DESCRIPTION
The \fBti_rri\fP command creates a \fBtclsh\fP(1) based \fBRlink\fP backend
server session. After loading all basic packages and shared libraries which
The \fBti_rri\fP command creates a \fBtclsh\fP(1)-based \fBRlink\fP backend
server session. After loading all basic packages and shared libraries that
implement the Tcl binding of the \fBRlink\fP server the command
.RS 2
@ -38,14 +38,14 @@ sets up connection timeout according to \fB\-\-tout\fP
.IP "-"
starts an additional process if requested with \fB\-\-run\fP
.IP "-"
opens a connection when requested with \fB\-\-fifo\fP,
opens a connection when requested with \fB\-\-fifo\fP,
\fB\-\-term\fP, or \fB\-\-cuff\fP
.IP "-"
and finally executes all remaining \fICOMMANDS\fP arguments as Tcl commands
.PD
.RE
.PP
If no \fICOMMANDS\fP are present or if the \fB\-\-int\fP options is given
If no \fICOMMANDS\fP are present or if the \fB\-\-int\fP options are given
an interactive mode is entered with all features of \fBtclsh\fP(1) with
tclreadline loaded.
.
@ -53,8 +53,8 @@ tclreadline loaded.
.SH OPTIONS
.\" ----------------------------------------------
.IP \fB\-\-pack=\fIplist\fR
load, with 'package require', additional packages. \fIplist\fP is a comma
separated list of package names. Note that the packages
load, with 'package require', additional packages. \fIplist\fP is a
comma-separated list of package names. Note that the packages
.BR rutiltpp ,
.BR rlinktpp ,
and
@ -63,13 +63,13 @@ are automatically loaded already by \fBti_rri\fP.
.
.\" -- --run -------------------------------------
.IP \fB\-\-run=\fIcmd\fR
execute the shell command \fIcmd\fP as subprocess before the \fBrlink\fP
port is opened. This is mainly used to start \fBghdl\fP(1) based test
execute the shell command \fIcmd\fP as a subprocess before the \fBrlink\fP
port is opened. This is mainly used to start \fBghdl\fP(1)-based test
benches, usually via the \fBtbw\fP(1) wrapper script.
.
.\" -- --fifo ------------------------------------
.IP \fB\-\-fifo\fR[=\fIname\fR[,\fIopts\fR]]
open a fifo type \fBrlink\fP port. It uses a named pipe, and is usually
open a fifo type \fBrlink\fP port. It uses a named pipe and is usually
employed in conjunction with the \fB\-\-run\fP option.
Optional arguments are
.RS
@ -103,7 +103,7 @@ open a serial port type \fBrlink\fP port. Optional arguments are
.IP \fBname\fP
tty device name, default is 'USB0'. If \fIname\fP does not start with '/'
the name is prefixed with '/dev/tty'. The special device name 'USBD'
triggers the auto-detection of a Digilent board with an FT2232C based
triggers the auto-detection of a Digilent board with an FT2232C-based
interface.
.IP \fBbaud\fP
serial port baud rate, default is '115k'. Allowed baud rate settings are:
@ -142,7 +142,7 @@ defer link initialization (debug or test benches)
open a USB via Cypress FX2 type \fBrlink\fP port. Optional arguments are
.RS
.IP \fBname\fP
USB path, default derived from environment variables \fBRETRO_FX2_VID\fP and
USB path, default derived from environment variables \fBRETRO_FX2_VID\fP and
\fBRETRO_FX2_PID\fP.
.IP \fBopts\fP
comma-separated list of further cuff port options:
@ -222,13 +222,13 @@ with eval.
.
.\" ------------------------------------------------------------------
.SH EXAMPLES
.IP "\fBti_rri --fifo --run='tbw tb_tst_rlink_n4'" 4
Starts the \fBghdl\fP(1) test bench 'tb_tst_rlink_n4' located in CWD via
.IP "\fBti_rri --fifo --run='tbw tb_tst_rlink_n4d'" 4
Starts the \fBghdl\fP(1) test bench 'tb_tst_rlink_n4d' located in CWD via
\fBtbw\fP(1). It is assumed that the local \fItbw.dat\fP file configures
fifo communication for the test bench.
.
.IP "\fBti_rri --fifo=,xon --run='tbw tb_tst_rlink_arty'" 4
Like above, starts arty rather n4 test bench. The rlink is operated with
Like above, starts arty rather n4d test bench. The rlink is operated with
software flow control. Note the comma in front of \fIxon\fP, required to
ensure that the default pipe name is used !

35
tools/man/man1/ti_w11.1
View File

@ -1,8 +1,8 @@
.\" -*- nroff -*-
.\" $Id: ti_w11.1 1231 2022-04-28 08:40:50Z mueller $
.\" $Id: ti_w11.1 1237 2022-05-15 07:51:47Z mueller $
.\" SPDX-License-Identifier: GPL-3.0-or-later
.\" Copyright 2013-2019 by Walter F.J. Mueller <W.F.J.Mueller@gsi.de>
.\"
.\" Copyright 2013-2022 by Walter F.J. Mueller <W.F.J.Mueller@gsi.de>
.\"
.\" ------------------------------------------------------------------
.
.TH TI_W11 1 2019-01-04 "Retro Project" "Retro Project Manual"
@ -22,27 +22,27 @@ ti_w11 \- Quick starter for \fBti_rri\fP with \fBw11\fP CPU designs
.SH DESCRIPTION
Generates the \fBti_rri\fP(1) commands for starting the \fBrri\fP backend
in standard configurations with \fBw11\fP CPU designs. Connections to
FPGA boards as well as to \fPghdl\fP based simulations are supported.
FPGA boards as well as to \fPghdl\fP-based simulations are supported.
Since \fBti_w11\fP is only a quick starter for \fBti_rri\fP(1) this man page
will only describe briefly the \fBti_w11\fP specific options, for any further
detail consult the \fBti_rri\fP(1) man page.
\fBti_w11\fP will print the generated \fBti_rri\fP(1) command to stdout before
executing it.
\fBti_w11\fP will print the generated \fBti_rri\fP(1) command to \fIstdout\fP
before executing it.
.
.\" ------------------------------------------------------------------
.SH OPTIONS
.SS "setup options for FPGA connects"
.SS "setup options for FPGA connections"
.IP \fB-u\fP
use \fB\-\-cuff\fP connect (USB via Cypress FX2)
.IP \fB-t\fIDN\fR[,\fIopts\fP]
use \fB\-\-term\fP connect.
\fID\fP specifies device name. \fIN\fP specifies
\fID\fP specifies device name. \fIN\fP specifies
the device number, or in the case of the character 'D' the auto-detection of a
Digilent board with an FT2232C based interface.
Digilent board with an FT2232C-based interface.
\fIopts\fP specified the additional options a \fB\-\-term\fP can hold
(e.g. break or xon).
(e.g. break or xon).
\fID\fP is mapped as
.RS
.PD 0
@ -82,7 +82,7 @@ start \fItb_w11a_br_arty\fP simulation (Arty, BRAM only, default \fB-fx\fP)
.PD
.IP \fB-f\fIm\fR
select communication mode for simulation. The \fB-f\fIm\fR can be used after
the \fB-b3\fP,...,\fB-s3\fP options to overwrite the default. Valid values
the \fB-b3\fP,...,\fB-s3\fP options to overwrite the default. Valid values
for mode \fIm\fP are
.RS
.PD 0
@ -120,7 +120,7 @@ batch mode
.IP "\fB-e \fR\fIfile\fR"
load and execute \fIfile\fP. If the file type is '.mac' the file will
be on the fly compiled with \fBasm-11\fP(1), for all other file types
it is assumed that they are in \fBlda\fP(5) format.
it is assumed that they are in \fBlda-11\fP(5) format.
.IP \fB-dry\fR
dry run, prints the commands but doesn't execute
.
@ -134,25 +134,26 @@ The typical way to start Nexys2 and Nexys3 boards.
.IP "\fBti_w11 -tu2,12M,break,cts @211bsd_rl_boot.tcl\fR" 4
Assumes an FPGA board with a \fBw11\fP CPU design already configured.
Connected via USB, communication via a USB UART. In this case the
Connected via USB, communication via a USB UART. In this case, the
device \fI/dev/ttyUSB2\fP will be used, with \fI12 MBaud\fP, \fIbreak\fP to
trigger auto-bauding, and \fIcts\fP to use hardware handshake.
\fBti_rri\fP(1) will be started and the given boot script executed.
.IP "\fBti_w11 -tuD,12M,break,cts @211bsd_rl_boot.tcl\fR" 4
Like above, but now the USB device will be autodetected.
Typical way to start a Nexys4 board.
The typical way to start a Nexys4 board.
.IP "\fBti_w11 -n3 -e $RETROBASE/tools/mcode/dl11/dl11echo.mac\fR"
Will start the \fItb_w11a_n3\fP test bench in \fBghdl\fP(1), on the fly
compile the \fIdz11echo.mac\fP test program with \fBasm-11\fP(1), load
Will start the \fItb_w11a_n3\fP test bench in \fBghdl\fP(1), on the fly
compile the \fIdz11echo.mac\fP test program with \fBasm-11\fP(1), load
and execute it. This little test code echos console input, just abort
with ^C if you have seen enough.
.
.\" ------------------------------------------------------------------
.SH "SEE ALSO"
.BR ti_rri (1),
.BR asm-11 (1)
.BR asm-11 (1),
.BR lda-11 (1)
.\" ------------------------------------------------------------------
.SH AUTHOR

150
tools/man/man1/vbomconv.1
View File

@ -1,9 +1,8 @@
.\" -*- nroff -*-
.\" $Id: vbomconv.1 1233 2022-04-30 07:01:23Z mueller $
.\" $Id: vbomconv.1 1237 2022-05-15 07:51:47Z mueller $
.\" SPDX-License-Identifier: GPL-3.0-or-later
.\" Copyright 2010-2018 by Walter F.J. Mueller <W.F.J.Mueller@gsi.de>
.\"
.\"
.\" Copyright 2010-2022 by Walter F.J. Mueller <W.F.J.Mueller@gsi.de>
.\"
.\" ------------------------------------------------------------------
.
.TH VBOMCONV 1 2018-11-09 "Retro Project" "Retro Project Manual"
@ -109,22 +108,22 @@ vbomconv \- generate files and actions from vbom manifest files
.SH DESCRIPTION
.
.\" --------------------------------------------------------
.SS Introduction
\fBvbomconv\fP is the central tool in a build system for
.SS Introduction
\fBvbomconv\fP is the central tool in a build system for
\fIVHDL\fP projects. Each \fIVHDL\fP source file has an associated
manifest file in \fBvbom\fP(5) format which contains a list of used
libraries and instantiated components, and the name of the
libraries and instantiated components, and the name of the
associated VHDL source file.
The instantiated components are defined via their \fBvbom\fP file.
All file names are relative to the current directory.
A recursive traversal through all \fBvbom\fP's
gives for each VHDL entity all the sources files needed to compile it,
with duplicates removed and in proper compilation order, thus libraries first
All file names are relative to the current directory.
A recursive traversal through all \fBvbom\fP's
gives for each VHDL entity all the source files needed to compile it,
with duplicates removed and in proper compilation order, thus libraries first
and top-level design last.
The \fBvbomconv\fP tool does this traversal of \fBvbom\fP
files and generates, depending on command line options, the files and/or
commands needed to run a synthesis tool or to build a simulation model.
files and generates, depending on command-line options, the files and/or
commands needed to run a synthesis tool or to build a simulation model.
Currently supported is synthesis with Xilinx ISE \fBxst\fP and Xilinx Vivado
and simulation with \fBghdl\fP(1), Xilinx ISE \fBISim\fP, or
Xilinx Vivado \fBxsim\fP.
@ -147,27 +146,27 @@ dependency files
.PP
The key advantage of this approach is that the individual \fBvbom\fP
files are easy to maintain. They reflect the libraries and components used
files are easy to maintain. They reflect the libraries and components used
in the VHDL source they describe, a structural change in the VHDL source
usually implies an update of the vbom. The project files are automatically
generated from this 'local' information, which can be of great help in
generated from this 'local' information, which can be of great help in
projects with many top-level designs with a large number of entities in
different constellations.
\fBvbomconv\fP is usually embedded in a GNU \fBmake\fP(1) based build system.
The \fIMakefile\fP's in general just contain a few definitions and includes,
the whole \fBvbomconv\fP magic is encapsulated in some pattern rules for
simulation and synthesis.
\fBvbomconv\fP is usually embedded in a GNU \fBmake\fP(1)-based build system.
The \fIMakefile\fP's in general just contain a few definitions and includes,
the whole \fBvbomconv\fP magic is encapsulated in some pattern rules for
simulation and synthesis.
Some are given in the EXAMPLES section.
.
.\" --------------------------------------------------------
.SS Principle of Operation
\fBvbomconv\fP will start with processing the \fIvbom\fP
file given as an argument.
Each file name extracted from a \fBvbom\fP is prepended with the directory
Each file name extracted from a \fBvbom\fP is prepended with the directory
path of the \fBvbom\fP.
This ensures that all file names are relative to the working directory under
which \fBvbomconv\fP was started, even though each \fBvbom\fP file holds
which \fBvbomconv\fP was started, even though each \fBvbom\fP file holds
only file names that are relative to the \fBvbom\fP.
\fBvbomconv\fP expects that the entries in the \fBvbom\fP's
@ -175,19 +174,19 @@ are ordered, libraries first, then the components in the order they are
instantiated, and finally the name of the associated source file.
Each \fI.vhd\fP file is added to a table of source files.
Each \fI.vbom\fP file is added to a list of \fBvbom\fP's
to be processed if it hasn't been processed yet.
The sub-\fBvbom\fP's are processed in the order they were found which
to be processed if it hasn't been processed yet.
The sub-\fBvbom\fP's are processed in the order they were found which
leads to breadth-first traversal of the \fBvbom\fP tree.
After all \fBvbom\fP's
are processed a ranking algorithm will generate an ordered list of source
files in proper compilation order. This ensures that libraries are compiled
before a source refers to them with a '\fIuse\fP' clause, and that entities
before a source refers to them with a '\fIuse\fP' clause, and that entities
are compiled before they are referred to by an explicit instatiation.
The \fBvbom\fP file format supports conditional inclusion of files via a
condition prefix.
The main purpose of this mechanism is to handle libraries and components
The main purpose of this mechanism is to handle libraries and components
which are only referred in
.EX
-- synthesis translate_off
@ -195,15 +194,15 @@ which are only referred in
.EE
sections and are used only for simulation.
The \fBvbom\fP file format has a logical name mechanism to support the
The \fBvbom\fP file format has a logical name mechanism to support the
\fIconfiguration\fP mechanism of VHDL. A logical name can be defined with
.EX
<lname> = <filename>
<lname> = <filename>
.EE
and it can be used with
.EX
${\fIlname\fP}
${\fIlname\fP := \fIdefault\fP}
${\fIlname\fP := \fIdefault\fP}
.EE
The first definition seen in the \fIvbom\fP
traversal is taken, all others are ignored. The filename in the usage clause
@ -217,8 +216,8 @@ allows to specify the top-level design name in case it differs from the
stem of the \fIvbom\fP file name.
.
.IP "\fB@lib\fP:\fIname\fP"
allows to specify additional system libraries. Currently used to indicate
that the \fIunisim\fP, \fIunimacro\fP or \fIsimprim\fP libraries are
allows to specify additional system libraries. Currently used to indicate
that the \fIunisim\fP, \fIunimacro\fP, or \fIsimprim\fP libraries are
needed by \fBghdl\fP.
.
.IP "\fB@xdc\fP:\fIfile\fP"
@ -226,13 +225,13 @@ specifies that \fIfile\fP is a constraint file for Vivado synthesis and should
be included in the constraints fileset.
.
.IP "\fB@tcl\fP:\fIfile\fP"
specifies that \fIfile\fP is a Tcl script to be executed when building
specifies that \fIfile\fP is a Tcl script to be executed when building
the Vivado project. The Tcl script generated by \fB\-\-vsyn_prj\fP
will contain statements with source \fIfile\fP.
.
.IP "\fB@ucf_cpp\fP:\fIfile\fP"
specifies that a \fIfile\fP.ucf file is to be generated by \fBcpp\fP(1)
from a \fIfile\fP.ucf_cpp source file. This allows to modularize ISE ucf files.
from a \fIfile\fP.ucf_cpp source file. This allows modularizing ISE ucf files.
.PP
The full description of the file format and examples are given in a
separate man page \fBvbom\fP(5).
@ -242,8 +241,8 @@ separate man page \fBvbom\fP(5).
The \fBvbomconv\fP command has the form
.IP "" 4
.B vbomconv
.RI [ options ]
.RI [ action ]
.RI [ options ]
.RI [ action ]
.I vbom
.PP
and must be called, except for the \fB\-\-help\fP case, with
@ -255,17 +254,17 @@ exactly one \fIvbom\fP file.
.IP \fB\-\-trace\fP
Gives a detailed trace, written to \fIstderr\fP,
of the vbom file traversal and processing, the process of source file ranking
to determine the compilation order, and of the final internal file list and
to determine the compilation order, and of the final internal file list and
property table.
.
.\" ----------------------------------------------
.TP
.BI \-\-xlpath \fR=\fPpath
Defines the location where the \fBghdl\fP compiled Xilinx unisim, unimacro
or simprim libraries are located. This option is mandatory for
\fB\-\-ghdl_a\fP and \fB\-\-ghdl_m\fP commands when the design contains
Defines the location where the \fBghdl\fP compiled Xilinx unisim, unimacro,
or simprim libraries are located. This option is mandatory for
\fB\-\-ghdl_a\fP and \fB\-\-ghdl_m\fP commands when the design contains
a \fB@lib\fP directive.
These compiled libs are typically created with the
These compiled libs are typically created with the
\fBxviv_ghdl_unisim\fP(1) command for Vivado and
\fBxise_ghdl_unisim\fP(1) or \fBxise_ghdl_simprim\fP(1) commands
for ISE environments.
@ -275,7 +274,7 @@ for ISE environments.
.P
.\" ----------------------------------------------
.IP \fB\-\-help\fP
Prints a usage summary to \fIstdout\fP and quits. This action is the only
Prints a usage summary to \fIstdout\fP and quits. This action is the only
one not requiring a \fIvbom\fP file.
.
.\" ----------------------------------------------
@ -289,8 +288,8 @@ one not requiring a \fIvbom\fP file.
.B \-\-dep_vsyn
.TQ
.B \-\-dep_vsim
These four actions write to \fIstdout\fP dependency rules for inclusion in
\fIMakefile\fPs.
These four actions write to \fIstdout\fP dependency rules for inclusion in
\fIMakefile\fPs.
Together with an appropriate pattern rule, they allow to automatize
the dependency handling, see the EXAMPLES section for practical usage.
@ -312,15 +311,14 @@ synthesis make flows and produces the following types of dependencies
with \fB*\fP indicating that one rule will be generated for each file
involved.
If a \fB@ucf_cpp\fP directive was found also rules describing the
.I ucf
If a \fB@ucf_cpp\fP directive was found also rules describing the \fIucf\fP
file handling are added
.EX
<stem>.ncd : <stem>.ucf
include sys_w11a_n2.dep_ucf_cpp
.EE
If this mechanism is used the \fIMakefile\fP must contain, usually via
another include, a pattern rule to create the \fI.dep_ucf_cpp\fP file,
If this mechanism is used the \fIMakefile\fP must contain, usually via
another include, a pattern rule to create the \fI.dep_ucf_cpp\fP file,
for example
.EX
%.dep_ucf_cpp : %.ucf_cpp
@ -360,7 +358,7 @@ based simulation models and produces the following types of dependencies
.TQ
.B \-\-ghdl_i
The \fB\-\-ghdl_i_cmd\fP action writes to \fIstdout\fP
a \fB"ghdl -i"\fP command for the \fBghdl\fP inspection step with all
a \fB"ghdl -i"\fP command for the \fBghdl\fP inspection step with all
source file names in proper compilation order. The \fB\-\-ghdl_i\fP
action immediately executes this command via \fBexec\fP(3).
.
@ -369,8 +367,8 @@ action immediately executes this command via \fBexec\fP(3).
.B \-\-ghdl_a_cmd
.TQ
.B \-\-ghdl_a
The \fB\-\-ghdl_a_cmd\fP action writes to \fIstdout\fP a list of
\fB"ghdl -a"\fP commands for the \fBghdl\fP analysis step.
The \fB\-\-ghdl_a_cmd\fP action writes to \fIstdout\fP a list of
\fB"ghdl -a"\fP commands for the \fBghdl\fP analysis step.
The commands are in proper compilation order. The \fB\-\-ghdl_a\fP
action immediately executes these commands via \fBexec\fP(3).
.
@ -380,7 +378,7 @@ action immediately executes these commands via \fBexec\fP(3).
.TQ
.B \-\-ghdl_m
The \fB\-\-ghdl_m_cmd\fP action writes to \fIstdout\fP
a \fB"ghdl -m"\fP command for the \fBghdl\fP inspection make with all
a \fB"ghdl -m"\fP command for the \fBghdl\fP inspection make with all
required library and external object file qualifiers.
The \fB\-\-ghdl_m\fP action immediately executes this command via
\fBexec\fP(3).
@ -391,7 +389,7 @@ The \fB\-\-ghdl_m\fP action immediately executes this command via
.TQ
.B \-\-isim_prj
These two actions write to \fIstdout\fP a project file suitable for ISE
\fBxst\fP or \fBISim\fP, respectively.
\fBxst\fP or \fBISim\fP, respectively.
The VHDL source files are in proper compilation order. See
the EXAMPLES section for practical usage in a make flow.
.
@ -401,7 +399,7 @@ the EXAMPLES section for practical usage in a make flow.
This action writes to \fIstdout\fP a Tcl script suitable as project definition
for Vivado synthesis. This script is source'ed or eval'ed and defines the
source fileset and the constraints fileset. The VHDL source files are in
proper compilation order.
proper compilation order.
.
.\" ----------------------------------------------
.TP
@ -439,18 +437,17 @@ Write an alphabetically sorted list of all source and vbom files to
\fIstdout\fP.
This information for example helps to build a project export tool.
Note that in contrast to most other actions the files are not in compilation
but alphabetic order, and that also the \fBvbom\fP files are included
but in alphabetic order, and that also the \fBvbom\fP files are included
in this list.
.
.\" ------------------------------------------------------------------
.SH EXIT STATUS
Returns a non-zero exit status when the
.I vbom
Returns a non-zero exit status when the \fIvbom\fP
file is not found or readable or none or multiple actions are given.
.PP
The \fB\-\-ghdl_a\fP, \fB\-\-ghdl_i\fP, or \fB\-\-ghdl_m\fP
actions use \fBexec\fP(3) to execute the \fBghdl\fP command.
In these cases the caller will see the exit status of \fBghdl\fP.
actions use \fBexec\fP(3) to execute the \fBghdl\fP command.
In these cases, the caller will see the exit status of \fBghdl\fP.
.
.\" ------------------------------------------------------------------
.SH ENVIRONMENT
@ -467,12 +464,12 @@ taken to enable optimization (is not default for gcc backend!) and debug
symbols (needed for assertion failure backtrace).
.
.IP \fBVBOMCONV_GHDL_GCOV\fP
If defined and set to '1' \fBghdl\fP(1) models will be compiled with
If defined and set to '1' \fBghdl\fP(1) models will be compiled with
\fBgcov\fP(1) coverage support. This option is only available when ghdl
was compiled with gcc backend, the llvm and mcode backend do not support
coverage analysis. The generated ghdl options will be appended after the
ones given by \fBVBOMCONV_GHDL_OPTS\fP. Note that no default options are
assume, so -Ox or -g options must be explicitly given via
assumed, so '-Ox' or '-g' options must be explicitly given via
\fBVBOMCONV_GHDL_OPTS\fP.
The additional ghdl options are
.EX
@ -486,11 +483,8 @@ The additional ghdl options are
.IP \(bu 2
Duplicate file elimination fails when one source file is refered to by
different \fIvbom\fP's
with different paths, like for example the file
.I aa/bb/cc/foo.vdh
seen from
.I aa/xx/yy
via
with different paths, like for example the file \fIaa/bb/cc/foo.vdh\fP
seen from \fIaa/xx/yy\fP via
.EX
../../bb/cc/foo.vhd
../../../aa/bb/cc/foo.vdh
@ -510,13 +504,13 @@ is a kludge and should be revised.
.
.\" --------------------------------------------------------
.SS Auto-Dependency Generation
The \fB\-\-dep_xst\fP, \fB\-\-dep_ghdl\fP and \fB\-\-dep_isim\fP
actions allow to setup together with the auto-rebuild and restart semantics
The \fB\-\-dep_xst\fP, \fB\-\-dep_ghdl\fP, and \fB\-\-dep_isim\fP
actions allow to set up together with the auto-rebuild and restart semantics
of the GNU \fBmake\fP(1) \fIinclude\fP directive to fully automatize the
proper generation of dependencies.
proper generation of dependencies.
Just add to the \fIMakefile\fP
a pattern rule to create the dependency rule files from the \fBvbom\fP
files and include them. In case they don't yet exist or are out of date
a pattern rule to create the dependency rule files from the \fBvbom\fP
files and include them. In case they don't yet exist or are out of date
\fBmake\fP(1) will (re-)create them and restart. Example for using
\fB\-\-dep_xst\fP in a \fIMakefile\fP :
.PP
@ -536,30 +530,30 @@ will do that recursively for a whole directory tree.
.
.\" --------------------------------------------------------
.SS Xst Synthesis
A simple \fBmake\fP(1) flow for synthesis with \fBxst\fP using
ISE \fBxflow\fP and the \fB\-\-xst_prj\fP action and a pattern
rule looks like
A simple \fBmake\fP(1) flow for synthesis with \fBxst\fP using
ISE \fBxflow\fP and the \fB\-\-xst_prj\fP action and a pattern
rule looks like
.PP
.EX
%.ngc: %.vbom
if [ ! -d ./ise ]; then mkdir ./ise; fi
(cd ./ise; vbomconv --xst_prj ../$< > $*.prj)
(cd ./ise; touch $*.xcf)
xtwi xflow -wd ise -synth xst_vhdl.opt $*.prj
xtwi xflow -wd ise -synth xst_vhdl.opt $*.prj
(cd ./ise; chmod -x *.* )
if [ -r ./ise/$*.ngc ]; then cp -p ./ise/$*.ngc .; fi
if [ -r ./ise/$*_xst.log ]; then cp -p ./ise/$*_xst.log .; fi
.EE
.PP
It creates a working directory \fI./ise\fP, the xst project file, runs
\fBxst\fP via ISE \fBxflow\fP, and copies the \fIngc\fP and \fIlog\fP files
back into the working directory.
It creates a working directory \fI./ise\fP, the xst project file, runs
\fBxst\fP via ISE \fBxflow\fP, and copies the \fIngc\fP and \fIlog\fP files
back into the working directory.
The ISE environment is started with \fBxtwi\fR(1) wrapper.
.
.\" --------------------------------------------------------
.SS Ghdl Simulation
A simple \fBmake\fP(1) flow for building a \fBghdl\fP simulation model from
the sources described by a \fBvbom\fP file is given by the following
A simple \fBmake\fP(1) flow for building a \fBghdl\fP simulation model from
the sources described by a \fBvbom\fP file is given by the following
pattern rule:
.PP
.EX

23
tools/man/man1/xise_ghdl_simprim.1
View File

@ -1,8 +1,8 @@
.\" -*- nroff -*-
.\" $Id: xise_ghdl_simprim.1 1233 2022-04-30 07:01:23Z mueller $
.\" $Id: xise_ghdl_simprim.1 1237 2022-05-15 07:51:47Z mueller $
.\" SPDX-License-Identifier: GPL-3.0-or-later
.\" Copyright 2010-2016 by Walter F.J. Mueller <W.F.J.Mueller@gsi.de>
.\"
.\" Copyright 2010-2022 by Walter F.J. Mueller <W.F.J.Mueller@gsi.de>
.\"
.\" ------------------------------------------------------------------
.
.TH XISE_GHDL_SIMPRIM 1 2016-07-02 "Retro Project" "Retro Project Manual"
@ -20,12 +20,12 @@ xise_ghdl_simprim \- compile Xilinx ISE SIMPRIM libraries for GHDL
.SH DESCRIPTION
\fBxise_ghdl_simprim\fP compiles the Xilinx ISE/WebPack SIMPRIM libraries
for \fBghdl\fP.
The object files generated by \fBghdl\fP are stored in the directory
The object files generated by \fBghdl\fP are stored in the directory
tree of the currently active version of ISE/WebPack under
\fI$XILINX/ghdl/simprim\fP.
Since direct calls to ISE tools are in general encapsulated with \fBxtwi\fP(1)
the \fI$XTWI_PATH\fP is used instead of \fI$XILINX\fP.
Since direct calls to ISE tools are in general encapsulated with \fBxtwi\fP(1)
the \fI$XTWI_PATH\fP is used instead of \fI$XILINX\fP.
This allows using this script and \fBghdl\fP without an \fBxtwi\fP wrapper.
Just use the \fBghdl\fP option
@ -38,7 +38,7 @@ to link to the SIMPRIM library.
Up to ISE 10 the VITAL models were all concatenated in one large file
\fIsimprim_VITAL.vhd\fP.
In this case the \fBxilinx_vhdl_chop\fP
In this case, the \fBxilinx_vhdl_chop\fP
helper script will create individual source files for each model.
For ISE 11 and later the modules are shipped as separate files.
@ -64,15 +64,16 @@ points to the root of the currently active ISE/WebPack installation.
.IP \fI$XTWI_PATH/ISE_DS/ISE/vhdl/src/simprims\fP
The VHDL sources for the SIMPRIM library are looked for in this directory tree.
.IP \fI$XTWI_PATH/ISE_DS/ISE/ghdl/simprim\fP
The created object files will be written into this directory. The directory
is created if not yet existing. Note that the \fI$XTWI_PATH\fP
directory must be writable for the script.
The created object files will be written into this directory.
The directory is created if it does not exist yet.
Note that the \fI$XTWI_PATH\fP directory must be writable for the script.
.
.\" ------------------------------------------------------------------
.SH "SEE ALSO"
.BR xtwi (1),
.BR ghdl (1),
.BR xise_ghdl_unisim (1)
.BR xise_ghdl_unisim (1),
.BR xilinx_vhdl_memcolltype_fix (1)
.
.\" ------------------------------------------------------------------
.SH AUTHOR

14
tools/man/man1/xise_ghdl_unisim.1
View File

@ -1,7 +1,7 @@
.\" -*- nroff -*-
.\" $Id: xise_ghdl_unisim.1 1233 2022-04-30 07:01:23Z mueller $
.\" $Id: xise_ghdl_unisim.1 1236 2022-05-14 10:11:35Z mueller $
.\" SPDX-License-Identifier: GPL-3.0-or-later
.\" Copyright 2010-2016 by Walter F.J. Mueller <W.F.J.Mueller@gsi.de>
.\" Copyright 2010-2022 by Walter F.J. Mueller <W.F.J.Mueller@gsi.de>
.\"
.\" ------------------------------------------------------------------
.
@ -60,16 +60,18 @@ The VHDL sources for the Xilinx ISE UNISIM library
.IP \fI$XTWI_PATH/ISE_DS/ISE/vhdl/src/unimacro\fP
The VHDL sources for the Xilinx ISE UNIMACRO library
.IP \fI$XTWI_PATH/ISE_DS/ISE/ghdl\fP
The created object files will be written into this directory. The directory
is created if not yet existing. Note that the \fI$XTWI_PATH\fP
directory must be writable for the script.
The created object files will be written into this directory.
The directory is created if it does not exist yet.
Note that the \fI$XTWI_PATH\fP directory must be writable for the script.
.
.\" ------------------------------------------------------------------
.SH "SEE ALSO"
.BR xtwi (1),
.BR ghdl (1),
.BR xise_ghdl_simprim (1),
.BR xviv_ghdl_unisim (1)
.BR xviv_ghdl_unisim (1),
.BR xilinx_vhdl_memcolltype_fix (1)
.
.\" ------------------------------------------------------------------
.SH AUTHOR

8
tools/man/man1/xise_msg_filter.1
View File

@ -1,7 +1,7 @@
.\" -*- nroff -*-
.\" $Id: xise_msg_filter.1 1233 2022-04-30 07:01:23Z mueller $
.\" $Id: xise_msg_filter.1 1236 2022-05-14 10:11:35Z mueller $
.\" SPDX-License-Identifier: GPL-3.0-or-later
.\" Copyright 2014-2015 by Walter F.J. Mueller <W.F.J.Mueller@gsi.de>
.\" Copyright 2014-2022 by Walter F.J. Mueller <W.F.J.Mueller@gsi.de>
.\"
.\" ------------------------------------------------------------------
.TH XISE_MSG_FILTER 1 2015-01-30 "Retro Project" "Retro Project Manual"
@ -32,8 +32,8 @@ xise_msg_filter will print all non-matching messages.
All filter rules which do not match a message are also listed, these
messages are considered missing.
Matched messages are considered accepted.
In normal operation they will not create output.
xise_msg_filter is useful for example in \fBmake\fP(1) based flows to
In normal operation, they will not create any output.
xise_msg_filter is useful for example in \fBmake\fP(1)-based flows to
create a short summary from the log files.
The accepted values for \fITYPE\fP are:

12
tools/man/man1/xtwi.1
View File

@ -1,5 +1,5 @@
.\" -*- nroff -*-
.\" $Id: xtwi.1 1234 2022-05-03 18:28:48Z mueller $
.\" $Id: xtwi.1 1235 2022-05-07 12:47:28Z mueller $
.\" SPDX-License-Identifier: GPL-3.0-or-later
.\" Copyright 2014-2022 by Walter F.J. Mueller <W.F.J.Mueller@gsi.de>
.\"
@ -67,16 +67,16 @@ $XTWI_PATH/ISE_DS/settings64.sh
ISE setup script located and sourced on 32 or 64 bit systems
.
.\" ------------------------------------------------------------------
.SH EXAMPLES
.IP "\fBxtwi netgen -sim -intstyle xflow -ofmt vhdl -w test.ngc" 4
Starts the ISE netlister and generates a VHDL model from \fItest.ngc\fP.
.
.\" ------------------------------------------------------------------
.SH "NOTES"
If both ISE and Vivado are used \fBxtwi\fP and \fBxtwv\fP(1) offer a convenient
way to have both tools available in one session without interference.
.
.\" ------------------------------------------------------------------
.SH EXAMPLES
.IP "\fBxtwi netgen -sim -intstyle xflow -ofmt vhdl -w test.ngc" 4
Starts the ISE netlister and generates a VHDL model from \fItest.ngc\fP.
.
.\" ------------------------------------------------------------------
.SH "SEE ALSO"
.BR xtwv (1)
.

12
tools/man/man1/xtwv.1
View File

@ -1,5 +1,5 @@
.\" -*- nroff -*-
.\" $Id: xtwv.1 1234 2022-05-03 18:28:48Z mueller $
.\" $Id: xtwv.1 1235 2022-05-07 12:47:28Z mueller $
.\" SPDX-License-Identifier: GPL-3.0-or-later
.\" Copyright 2014-2022 by Walter F.J. Mueller <W.F.J.Mueller@gsi.de>
.\"
@ -66,11 +66,6 @@ $XTWV_PATH/settings64.sh
Vivado setup script located and sourced on 32 or 64 bit systems
.
.\" ------------------------------------------------------------------
.SH EXAMPLES
.IP "\fBxtwv vivado -mode batch -source test.tcl" 4
Starts Vivado in batch mode and executes the script \fItest.tcl\fP.
.
.\" ------------------------------------------------------------------
.SH "NOTES"
Vivado is a lot less intrusive than ISE, but it's still a good precaution to
wrap calls of Vivado tools with \fBxtwv\fP.
@ -79,6 +74,11 @@ If both Vivado and ISE are used \fBxtwv\fP and \fBxtwi\fP(1) offer a convenient
way to have both tools available in one session without interference.
.
.\" ------------------------------------------------------------------
.SH EXAMPLES
.IP "\fBxtwv vivado -mode batch -source test.tcl" 4
Starts Vivado in batch mode and executes the script \fItest.tcl\fP.
.
.\" ------------------------------------------------------------------
.SH "SEE ALSO"
.BR xtwi (1)
.

16
tools/man/man1/xviv_ghdl_unisim.1
View File

@ -1,7 +1,7 @@
.\" -*- nroff -*-
.\" $Id: xviv_ghdl_unisim.1 1233 2022-04-30 07:01:23Z mueller $
.\" $Id: xviv_ghdl_unisim.1 1236 2022-05-14 10:11:35Z mueller $
.\" SPDX-License-Identifier: GPL-3.0-or-later
.\" Copyright 2015-2016 by Walter F.J. Mueller <W.F.J.Mueller@gsi.de>
.\" Copyright 2015-2022 by Walter F.J. Mueller <W.F.J.Mueller@gsi.de>
.\"
.\" ------------------------------------------------------------------
.
@ -35,7 +35,7 @@ Just use the \fBghdl\fP option
.EE
to link to the UNISIM or UNIMACRO library.
\fBghdl\fP can be used without a \fBxtwv\fP wrapper.
\fBghdl\fP can be used without an \fBxtwv\fP wrapper.
The Xilinx source code has since many releases some buggy statements with
self-referential initializations. They seem to be tolerated by the commercial
@ -61,14 +61,16 @@ The VHDL sources for the Xilinx Vivado UNISIM library
.IP \fI$XTWV_PATH/data/vhdl/src/unimacro\fP
The VHDL sources for the Xilinx Vivado UNIMACRO library
.IP \fI$XTWV_PATH/ghdl\fP
The created object files will be written into this directory. The directory
is created if not yet existing. Note that the \fI$XTWV_PATH\fP
directory must be writable for the script.
The created object files will be written into this directory.
The directory is created if it does not exist yet.
Note that the \fI$XTWV_PATH\fP directory must be writable for the script.
.
.\" ------------------------------------------------------------------
.SH "SEE ALSO"
.BR xtwv (1),
.BR ghdl (1)
.BR ghdl (1),
.BR xilinx_vhdl_memcolltype_fix (1)
.
.\" ------------------------------------------------------------------
.SH AUTHOR

22
tools/man/man1/xviv_msg_filter.1
View File

@ -1,8 +1,8 @@
.\" -*- nroff -*-
.\" $Id: xviv_msg_filter.1 1233 2022-04-30 07:01:23Z mueller $
.\" $Id: xviv_msg_filter.1 1237 2022-05-15 07:51:47Z mueller $
.\" SPDX-License-Identifier: GPL-3.0-or-later
.\" Copyright 2016-2018 by Walter F.J. Mueller <W.F.J.Mueller@gsi.de>
.\"
.\" Copyright 2016-2022 by Walter F.J. Mueller <W.F.J.Mueller@gsi.de>
.\"
.\" ------------------------------------------------------------------
.TH XVIV_MSG_FILTER 1 2018-12-24 "Retro Project" "Retro Project Manual"
.\" ------------------------------------------------------------------
@ -25,14 +25,14 @@ xviv_msg_filter \- message filter for Xilinx Vivado tool chain log files
.SH DESCRIPTION
.\" ----------------------------------------------
Scans the log file \fILOGFILE\fP generated by Xilinx Vivado for messages and
compares these messages against a set of message filter rules defined in the
compares these messages against a set of message filter rules defined in the
\fIVMFSET\fP file and selected by \fITYPE\fP.
xviv_msg_filter will print all non-matching messages.
All filter rules which do not match a message are also listed, these
messages are considered missing.
Matched messages are considered accepted.
Matched messages are considered accepted.
In normal operation, they will not create output.
xviv_msg_filter is useful for example in \fBmake\fP(1) based flows to
xviv_msg_filter is useful for example in \fBmake\fP(1)-based flows to
create a short summary from the log files.
The accepted values for \fITYPE\fP are:
@ -52,7 +52,7 @@ Vivado bitfile generation step
.SH OPTIONS
.\" ----------------------------------------------
.IP \fB\-\-pacc\fP
Print a summary of all accepted messages. The match count for each rule is
Print a summary of all accepted messages. The match count for each rule is
listed.
.
.IP \fB\-\-pcnt\fP
@ -65,7 +65,7 @@ print full help.
.\" ------------------------------------------------------------------
.SH MESSAGE FILTER FILE FORMAT
.\" ----------------------------------------------
Simply a list of match rules structured by section headers
Simply a list of match rules structured by section headers
of the form "[TYPE]". '#' is interpreted as a comment delimiter, everything
after a '#' in a line will be ignored.
xviv_msg_filter will extract the rules of the section matching the
@ -99,7 +99,7 @@ determines how the rule is applied
.IP \fBI\fP 4
matching messages are ignored
.IP \fBi\fP 4
matching messages are not printed, if no matching message is found a
matching messages are not printed, if no matching message is found a
notification is printed.
.IP \fBc\fP 4
matching messages are counted, only a summary of the message counts is
@ -112,9 +112,9 @@ notification is printed.
.IP \fBname\fP
Vivado message name, enclosed in [] brackets
.IP \fBpattern\fP
regular expression to match the message text. This field is optional, if
regular expression to match the message text. This field is optional, if
omitted all messages with the given name will match. '[' and ']' characters
are escaped to '\\[' and '\\]', because [] is very often part of signal
are escaped to '\\[' and '\\]', because [] is very often part of signal
names. Character set matches are therefore not possible, unfortunately.
.SS Example message filter file

6
tools/man/man1/xviv_msg_summary.1
View File

@ -1,8 +1,8 @@
.\" -*- nroff -*-
.\" $Id: xviv_msg_summary.1 1188 2019-07-13 14:31:51Z mueller $
.\" $Id: xviv_msg_summary.1 1237 2022-05-15 07:51:47Z mueller $
.\" SPDX-License-Identifier: GPL-3.0-or-later
.\" Copyright 2016- by Walter F.J. Mueller <W.F.J.Mueller@gsi.de>
.\"
.\" Copyright 2016-2022 by Walter F.J. Mueller <W.F.J.Mueller@gsi.de>
.\"
.\" ------------------------------------------------------------------
.TH XVIV_MSG_SUMMARY 1 2016-06-05 "Retro Project" "Retro Project Manual"
.\" ------------------------------------------------------------------

8
tools/man/man1/xviv_sim_vhdl_cleanup.1
View File

@ -1,8 +1,8 @@
.\" -*- nroff -*-
.\" $Id: xviv_sim_vhdl_cleanup.1 1233 2022-04-30 07:01:23Z mueller $
.\" $Id: xviv_sim_vhdl_cleanup.1 1237 2022-05-15 07:51:47Z mueller $
.\" SPDX-License-Identifier: GPL-3.0-or-later
.\" Copyright 2016- by Walter F.J. Mueller <W.F.J.Mueller@gsi.de>
.\"
.\" Copyright 2016-2022 by Walter F.J. Mueller <W.F.J.Mueller@gsi.de>
.\"
.\" ------------------------------------------------------------------
.TH XVIV_SIM_VHDL_CLEANUP 1 2016-06-05 "Retro Project" "Retro Project Manual"
.\" ------------------------------------------------------------------
@ -19,7 +19,7 @@ xviv_sim_vhdl_cleanup \- cleanup Vivado generated VHDL for GHDL
.SH DESCRIPTION
.\" ----------------------------------------------
The Vivado \fIwrite_vhdl\fP command generates code that violates a VHDL
language rule.
language rule.
Attributes of port signals are declared in the architecture but should be in
the entity declaration. xsim and other simulators accept this, but
\fBghdl\fP(1) doesn't. This script simply filters out lines like

47
tools/man/man5/vbom.5
View File

@ -1,8 +1,8 @@
.\" -*- nroff -*-
.\" $Id: vbom.5 1233 2022-04-30 07:01:23Z mueller $
.\" $Id: vbom.5 1237 2022-05-15 07:51:47Z mueller $
.\" SPDX-License-Identifier: GPL-3.0-or-later
.\" Copyright 2010-2018 by Walter F.J. Mueller <W.F.J.Mueller@gsi.de>
.\"
.\" Copyright 2010-2022 by Walter F.J. Mueller <W.F.J.Mueller@gsi.de>
.\"
.\" ------------------------------------------------------------------
.
.TH VBOM 5 2018-11-09 "Retro Project" "Retro Project Manual"
@ -15,7 +15,7 @@ vbom \- vhdl manifest file format - 'vhdl bill of material'
\fBvbom\fP files describe the sources needed to build a \fIVHDL\fP
entity. The source files are either given directly in the case of libraries
or via other \fBvbom\fP's in the case of instantiated components.
They are used by \fBvbomconv\fP(1) to build project descriptions
They are used by \fBvbomconv\fP(1) to build project descriptions
for synthesis and simulation tools.
\fBvbomconv\fP expects that the entries in the \fBvbom\fP's
@ -30,12 +30,12 @@ Each line starting with '\fB#\fP' is treated as a comment and ignored.
.
.\" ----------------------------------------------
.IP "\fBFile names\fP"
Either source files or nested \fBvbom\fP's. The file names must be given
Either source files or nested \fBvbom\fP's. The file names must be given
as relative path names from the directory the \fBvbom\fP file is located in.
Absolute path names are not allowed, nor is an expansion of environment
variables.
Currently the following file types are accepted:
Currently, the following file types are accepted:
.RS
.IP "\fB.vbom\fP" 6
refers to a nested \fBvbom\fP. Usually used for instantiated components.
@ -50,7 +50,7 @@ described by this \fBvbom\fP file.
.TQ
.B "\fB.sv\fP"
refers to a Verilog or System Verilog source file. Accepted by the Vivado
xsim simulator. Typically used for DPI wrappers or simprim based models
xsim simulator. Typically used for DPI wrappers or simprim-based models
in Vivado.
.
.IP "\fB.c\fP"
@ -70,11 +70,11 @@ File names can be followed by a list of attributes of the form
Currently, the following attributes are recognized
.RS
.IP "\fB-UUT\fP" 6
Signals that the \fIvbom\fP descibes a test bench and that file is
the 'unit under test'. This allows to split the sources into a simulation
only test bench part and a synthesizable 'unit under test' part. The file
is typically a \fIvbom\fP in case of a behavioural simulation or the file
name of a generated model for a functional or timing simulation.
Signals that the \fIvbom\fP describes a test bench and that file is
the 'unit under test'. This allows splitting the sources into a
simulation-only test bench part and a synthesizable 'unit under test' part.
The file is typically a \fIvbom\fP in case of a behavioral simulation or the
file name of a generated model for a functional or timing simulation.
.
.IP "\fB-SCOPE_REF[:\fIentity\fP]\fP" 6
Signals that the xdc file should be 'scoped to reference' to \fIentity\fP.
@ -92,7 +92,7 @@ File names can be preceded by a condition prefix of the form
[\fItag\fP,\fItag\fP,...]filename
.EE
The main purpose of this mechanism is to handle libraries and components
The main purpose of this mechanism is to handle libraries and components
which are only referred in
.EX
-- synthesis translate_off
@ -131,18 +131,19 @@ A logical name can be defined with
\fIlname\fP = \fIfilename\fP
.EE
The first definition of a logical name encountered in the traversal of the
\fBvbom\fP's by \fBvbomconv\fP(1) is taken, all later definitions are ignored.
\fBvbom\fP's by \fBvbomconv\fP(1) is taken, and all later definitions
are ignored.
A logical name can be used with
.EX
${\fIlname\fP}
${\fIlname\fP := \fIdefault\fP}
${\fIlname\fP := \fIdefault\fP}
.EE
In the first form, \fIlname\fP must have been defined before.
The second form allows specifying a \fIdefault\fP which is used when
\fIlname\fP hasn't been defined so far.
Again, the filenames must be given as relative path name from the directory
Again, the filenames must be given as relative path names from the directory
the \fBvbom\fP file is located in.
.\" ----------------------------------------------
@ -150,13 +151,13 @@ the \fBvbom\fP file is located in.
Directives start with a '\fB@\fP', currently implemented are:
.RS
.IP "\fB@top\fP:\fIname\fP" 4
Specifies the top level design name. Mainly used when it is different
Specifies the top-level design name. Mainly used when it is different
from the stem of the \fBvbom\fP file name.
.
.IP "\fB@lib\fP:\fIname\fP"
Specifies an additional system library. Allowed values for \fIname\fP are
\fIunisim\fP, \fIunimacro\fP, and \fIsimprim\fP.
Currently used to generate the appropriate -L options for \fBghdl\fP commands,
Currently used to generate the appropriate -L options for \fBghdl\fP commands,
e.g. generated by the \fBvbomconv\fP action \fB\-\-ghdl_m\fP.
.
.IP "\fB@xdc\fP:\fIfile\fP"
@ -164,8 +165,8 @@ Specifies that \fIfile\fP is a constraint file for Vivado synthesis and should
be included in the constraints fileset.
.
.IP "\fB@tcl\fP:\fIfile\fP"
specifies that \fIfile\fP is a Tcl script to be executed when building
the Vivado project. The Tcl script generated by the \fBvbomconv\fP action
specifies that \fIfile\fP is a Tcl script to be executed when building
the Vivado project. The Tcl script generated by the \fBvbomconv\fP action
\fB\-\-vsyn_prj\fP will contain statements with source \fIfile\fP.
.
.IP "\fB@ucf_cpp\fP:\fIfile\fP"
@ -178,7 +179,7 @@ from a \fIfile\fP.ucf_cpp source file. This allows modularizing ISE ucf files.
.SS Simple entity
A simple VHDL entity named \fIbp_2l4l\fP which is defined in the source
file \fIbp_2l4l.vhd\fP, which uses the library \fIslvtypes\fP and
instantiates \fIbp_2line\fP and \fIbp_4line\fP, might have a
instantiates \fIbp_2line\fP and \fIbp_4line\fP, might have a
\fIbp_2l4l.vbom\fP like
.PP
.EX
@ -192,8 +193,8 @@ instantiates \fIbp_2line\fP and \fIbp_4line\fP, might have a
.EE
.PP
Note that the VHDL source file \fIbp_2l4l.vhd\fP is always given in the
\fBvbom\fP file which describes this source file.
The comments are put in by convention to help the human reader and
\fBvbom\fP file which describes this source file.
The comments are put in by convention to help the human reader and
are not interpreted by \fBvbomconv\fP.
.
.\" ------------------------------------------------------------------