diff --git a/tools/man/man1/asm-11_expect.1 b/tools/man/man1/asm-11_expect.1 index 87513804..775095eb 100644 --- a/tools/man/man1/asm-11_expect.1 +++ b/tools/man/man1/asm-11_expect.1 @@ -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 -.\" +.\" Copyright 2014-2022 by Walter F.J. Mueller +.\" .\" ------------------------------------------------------------------ . .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 diff --git a/tools/man/man1/config_wrapper.1 b/tools/man/man1/config_wrapper.1 index 6131b363..63875cc9 100644 --- a/tools/man/man1/config_wrapper.1 +++ b/tools/man/man1/config_wrapper.1 @@ -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 -.\" +.\" Copyright 2013-2022 by Walter F.J. Mueller +.\" .\" ------------------------------------------------------------------ . .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 diff --git a/tools/man/man1/console_starter.1 b/tools/man/man1/console_starter.1 index ef3edfd7..7ac8b655 100644 --- a/tools/man/man1/console_starter.1 +++ b/tools/man/man1/console_starter.1 @@ -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 -.\" +.\" Copyright 2013-2022 by Walter F.J. Mueller +.\" .\" ------------------------------------------------------------------ . .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 to reconnect: + enter q or <^D> to quit, otherwise hit 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 diff --git a/tools/man/man1/create_disk.1 b/tools/man/man1/create_disk.1 index e8d48c5d..edcfeb39 100644 --- a/tools/man/man1/create_disk.1 +++ b/tools/man/man1/create_disk.1 @@ -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 -.\" +.\" Copyright 2013-2022 by Walter F.J. Mueller +.\" .\" ------------------------------------------------------------------ . .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" diff --git a/tools/man/man1/dmpcntanal.1 b/tools/man/man1/dmpcntanal.1 index 1fb936e3..f9b2e8a3 100644 --- a/tools/man/man1/dmpcntanal.1 +++ b/tools/man/man1/dmpcntanal.1 @@ -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 -.\" +.\" Copyright 2018-2022 by Walter F.J. Mueller +.\" .\" ------------------------------------------------------------------ . .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 diff --git a/tools/man/man1/dmscntanal.1 b/tools/man/man1/dmscntanal.1 index 841686f9..496b5ebf 100644 --- a/tools/man/man1/dmscntanal.1 +++ b/tools/man/man1/dmscntanal.1 @@ -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 -.\" +.\" Copyright 2015-2022 by Walter F.J. Mueller +.\" .\" ------------------------------------------------------------------ . .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 diff --git a/tools/man/man1/dmscntconv.1 b/tools/man/man1/dmscntconv.1 index d2d54826..de8ae0fb 100644 --- a/tools/man/man1/dmscntconv.1 +++ b/tools/man/man1/dmscntconv.1 @@ -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 -.\" +.\" Copyright 2015-2022 by Walter F.J. Mueller +.\" .\" ------------------------------------------------------------------ . .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. . .\" ------------------------------------------------------------------ diff --git a/tools/man/man1/file2tap.1 b/tools/man/man1/file2tap.1 index 927d596e..cbcdab6d 100644 --- a/tools/man/man1/file2tap.1 +++ b/tools/man/man1/file2tap.1 @@ -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 -.\" +.\" Copyright 2015-2022 by Walter F.J. Mueller +.\" .\" ------------------------------------------------------------------ . .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 diff --git a/tools/man/man1/fx2load_wrapper.1 b/tools/man/man1/fx2load_wrapper.1 index 8ca89f85..341ad010 100644 --- a/tools/man/man1/fx2load_wrapper.1 +++ b/tools/man/man1/fx2load_wrapper.1 @@ -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 -.\" +.\" .\" ------------------------------------------------------------------ . .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" diff --git a/tools/man/man1/github_md2html.1 b/tools/man/man1/github_md2html.1 index 6e3b31a1..3b4c29d1 100644 --- a/tools/man/man1/github_md2html.1 +++ b/tools/man/man1/github_md2html.1 @@ -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 -.\" +.\" Copyright 2017-2022 by Walter F.J. Mueller +.\" .\" ------------------------------------------------------------------ . .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" diff --git a/tools/man/man1/ip_create_br.1 b/tools/man/man1/ip_create_br.1 index c1a4317b..c2c18dc7 100644 --- a/tools/man/man1/ip_create_br.1 +++ b/tools/man/man1/ip_create_br.1 @@ -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 -.\" +.\" Copyright 2017-2022 by Walter F.J. Mueller +.\" .\" ------------------------------------------------------------------ . .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" diff --git a/tools/man/man1/ip_create_tap.1 b/tools/man/man1/ip_create_tap.1 index cb653e14..44942f5c 100644 --- a/tools/man/man1/ip_create_tap.1 +++ b/tools/man/man1/ip_create_tap.1 @@ -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 -.\" +.\" Copyright 2017-2022 by Walter F.J. Mueller +.\" .\" ------------------------------------------------------------------ . .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. . .\" ------------------------------------------------------------------ diff --git a/tools/man/man1/ldadump.1 b/tools/man/man1/ldadump.1 index 72715567..0f7053cd 100644 --- a/tools/man/man1/ldadump.1 +++ b/tools/man/man1/ldadump.1 @@ -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 -.\" +.\" Copyright 2019-2022 by Walter F.J. Mueller +.\" .\" ------------------------------------------------------------------ . -.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 diff --git a/tools/man/man1/njobihtm.1 b/tools/man/man1/njobihtm.1 index cc142a84..e13fe884 100644 --- a/tools/man/man1/njobihtm.1 +++ b/tools/man/man1/njobihtm.1 @@ -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 -.\" +.\" Copyright 2016-2022 by Walter F.J. Mueller +.\" .\" ------------------------------------------------------------------ . .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 diff --git a/tools/man/man1/oskit_setup.1 b/tools/man/man1/oskit_setup.1 index 30a06b8d..c616d6a2 100644 --- a/tools/man/man1/oskit_setup.1 +++ b/tools/man/man1/oskit_setup.1 @@ -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 -.\" +.\" .\" ------------------------------------------------------------------ . .TH OSKIT_SETUP 1 2019-07-13 "Retro Project" "Retro Project Manual" diff --git a/tools/man/man1/ostest.1 b/tools/man/man1/ostest.1 index b8098952..c51006bc 100644 --- a/tools/man/man1/ostest.1 +++ b/tools/man/man1/ostest.1 @@ -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 -.\" +.\" Copyright 2019-2022 by Walter F.J. Mueller +.\" .\" ------------------------------------------------------------------ . -.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_.tcl\fP" 4 -Implementation for mode \fImode\fP. +Implementation for execution mode \fImode\fP. .IP "\fI$RETROBASE/tools/exptest/sys/_setup.tcl\fP" Setup file for system \fIsys\fP. .IP "\fI$RETROBASE/tools/oskit/test/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 diff --git a/tools/man/man1/rm_dep.1 b/tools/man/man1/rm_dep.1 index f9695f6e..197661ff 100644 --- a/tools/man/man1/rm_dep.1 +++ b/tools/man/man1/rm_dep.1 @@ -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 -.\" +.\" .\" ------------------------------------------------------------------ . .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" diff --git a/tools/man/man1/svn_set_ignore.1 b/tools/man/man1/svn_set_ignore.1 index 36556dad..4459f7d3 100644 --- a/tools/man/man1/svn_set_ignore.1 +++ b/tools/man/man1/svn_set_ignore.1 @@ -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 -.\" +.\" Copyright 2013-2022 by Walter F.J. Mueller +.\" .\" ------------------------------------------------------------------ . .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. . .\" ------------------------------------------------------------------ diff --git a/tools/man/man1/tap2file.1 b/tools/man/man1/tap2file.1 index 2a4c5cda..667ff968 100644 --- a/tools/man/man1/tap2file.1 +++ b/tools/man/man1/tap2file.1 @@ -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 -.\" +.\" Copyright 2015-2022 by Walter F.J. Mueller +.\" .\" ------------------------------------------------------------------ . .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 ... diff --git a/tools/man/man1/tbfilt.1 b/tools/man/man1/tbfilt.1 index d769af55..a20e00ed 100644 --- a/tools/man/man1/tbfilt.1 +++ b/tools/man/man1/tbfilt.1 @@ -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 -.\" +.\" .\" ------------------------------------------------------------------ . .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 2>&1 | tbfilt --tee= .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. . diff --git a/tools/man/man1/tbrun.1 b/tools/man/man1/tbrun.1 index 1ea7a91b..db665fcb 100644 --- a/tools/man/man1/tbrun.1 +++ b/tools/man/man1/tbrun.1 @@ -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 -.\" +.\" .\" ------------------------------------------------------------------ . .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. . .\" ------------------------------------------------------------------ diff --git a/tools/man/man1/tbrun_tbw.1 b/tools/man/man1/tbrun_tbw.1 index 8fec1827..0da24345 100644 --- a/tools/man/man1/tbrun_tbw.1 +++ b/tools/man/man1/tbrun_tbw.1 @@ -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 -.\" +.\" Copyright 2016-2022 by Walter F.J. Mueller +.\" .\" ------------------------------------------------------------------ . .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 diff --git a/tools/man/man1/tbrun_tbwrri.1 b/tools/man/man1/tbrun_tbwrri.1 index 01949309..21c96a53 100644 --- a/tools/man/man1/tbrun_tbwrri.1 +++ b/tools/man/man1/tbrun_tbwrri.1 @@ -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 -.\" +.\" Copyright 2016-2022 by Walter F.J. Mueller +.\" .\" ------------------------------------------------------------------ . .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 diff --git a/tools/man/man1/tbw.1 b/tools/man/man1/tbw.1 index 9ebf1b5b..a76b8f60 100644 --- a/tools/man/man1/tbw.1 +++ b/tools/man/man1/tbw.1 @@ -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 -.\" +.\" Copyright 2013-2022 by Walter F.J. Mueller +.\" .\" ------------------------------------------------------------------ . .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 \'_stim\'. The default -stimulus file is named \'_stim.dat\'. \fBtbw\fP will simply +stimulus file is named \'_stim.dat\'. \fBtbw\fP will simply define \'_stim\' as a symlink referring to \'_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\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 [stimfile] | tbfilt --tee + tbw [stimfile] | tbfilt --tee .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 diff --git a/tools/man/man1/ti_rri.1 b/tools/man/man1/ti_rri.1 index d7f8ea74..ba0b953f 100644 --- a/tools/man/man1/ti_rri.1 +++ b/tools/man/man1/ti_rri.1 @@ -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 -.\" +.\" .\" ------------------------------------------------------------------ . .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 ! diff --git a/tools/man/man1/ti_w11.1 b/tools/man/man1/ti_w11.1 index 053eb77b..17cf3e18 100644 --- a/tools/man/man1/ti_w11.1 +++ b/tools/man/man1/ti_w11.1 @@ -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 -.\" +.\" Copyright 2013-2022 by Walter F.J. Mueller +.\" .\" ------------------------------------------------------------------ . .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 diff --git a/tools/man/man1/vbomconv.1 b/tools/man/man1/vbomconv.1 index 1f18cb53..55efff53 100644 --- a/tools/man/man1/vbomconv.1 +++ b/tools/man/man1/vbomconv.1 @@ -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 -.\" -.\" +.\" Copyright 2010-2022 by Walter F.J. Mueller +.\" .\" ------------------------------------------------------------------ . .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 - = + = .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 .ncd : .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 diff --git a/tools/man/man1/xise_ghdl_simprim.1 b/tools/man/man1/xise_ghdl_simprim.1 index 91cd5336..500aeb88 100644 --- a/tools/man/man1/xise_ghdl_simprim.1 +++ b/tools/man/man1/xise_ghdl_simprim.1 @@ -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 -.\" +.\" Copyright 2010-2022 by Walter F.J. Mueller +.\" .\" ------------------------------------------------------------------ . .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 diff --git a/tools/man/man1/xise_ghdl_unisim.1 b/tools/man/man1/xise_ghdl_unisim.1 index 1ff993a6..781cbbb2 100644 --- a/tools/man/man1/xise_ghdl_unisim.1 +++ b/tools/man/man1/xise_ghdl_unisim.1 @@ -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 +.\" Copyright 2010-2022 by Walter F.J. Mueller .\" .\" ------------------------------------------------------------------ . @@ -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 diff --git a/tools/man/man1/xise_msg_filter.1 b/tools/man/man1/xise_msg_filter.1 index 186a5573..bc2316ae 100644 --- a/tools/man/man1/xise_msg_filter.1 +++ b/tools/man/man1/xise_msg_filter.1 @@ -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 +.\" Copyright 2014-2022 by Walter F.J. Mueller .\" .\" ------------------------------------------------------------------ .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: diff --git a/tools/man/man1/xtwi.1 b/tools/man/man1/xtwi.1 index 663aeb10..66a69801 100644 --- a/tools/man/man1/xtwi.1 +++ b/tools/man/man1/xtwi.1 @@ -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 .\" @@ -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) . diff --git a/tools/man/man1/xtwv.1 b/tools/man/man1/xtwv.1 index cb86da46..e259ab67 100644 --- a/tools/man/man1/xtwv.1 +++ b/tools/man/man1/xtwv.1 @@ -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 .\" @@ -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) . diff --git a/tools/man/man1/xviv_ghdl_unisim.1 b/tools/man/man1/xviv_ghdl_unisim.1 index 9957b9c4..291fc6bd 100644 --- a/tools/man/man1/xviv_ghdl_unisim.1 +++ b/tools/man/man1/xviv_ghdl_unisim.1 @@ -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 +.\" Copyright 2015-2022 by Walter F.J. Mueller .\" .\" ------------------------------------------------------------------ . @@ -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 diff --git a/tools/man/man1/xviv_msg_filter.1 b/tools/man/man1/xviv_msg_filter.1 index 2d71ed7f..010fd839 100644 --- a/tools/man/man1/xviv_msg_filter.1 +++ b/tools/man/man1/xviv_msg_filter.1 @@ -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 -.\" +.\" Copyright 2016-2022 by Walter F.J. Mueller +.\" .\" ------------------------------------------------------------------ .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 diff --git a/tools/man/man1/xviv_msg_summary.1 b/tools/man/man1/xviv_msg_summary.1 index 10fe723f..84493d17 100644 --- a/tools/man/man1/xviv_msg_summary.1 +++ b/tools/man/man1/xviv_msg_summary.1 @@ -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 -.\" +.\" Copyright 2016-2022 by Walter F.J. Mueller +.\" .\" ------------------------------------------------------------------ .TH XVIV_MSG_SUMMARY 1 2016-06-05 "Retro Project" "Retro Project Manual" .\" ------------------------------------------------------------------ diff --git a/tools/man/man1/xviv_sim_vhdl_cleanup.1 b/tools/man/man1/xviv_sim_vhdl_cleanup.1 index 1a2e3d34..c2b5f9d5 100644 --- a/tools/man/man1/xviv_sim_vhdl_cleanup.1 +++ b/tools/man/man1/xviv_sim_vhdl_cleanup.1 @@ -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 -.\" +.\" Copyright 2016-2022 by Walter F.J. Mueller +.\" .\" ------------------------------------------------------------------ .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 diff --git a/tools/man/man5/vbom.5 b/tools/man/man5/vbom.5 index 78d99082..f709af77 100644 --- a/tools/man/man5/vbom.5 +++ b/tools/man/man5/vbom.5 @@ -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 -.\" +.\" Copyright 2010-2022 by Walter F.J. Mueller +.\" .\" ------------------------------------------------------------------ . .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. . .\" ------------------------------------------------------------------