wfjm.w11/tools/man/man1/gwstart.1

.\"  -*- nroff -*-
.\"  $Id: gwstart.1 1369 2023-02-08 18:59:50Z mueller $
.\" SPDX-License-Identifier: GPL-3.0-or-later
.\" Copyright 2022-2023 by Walter F.J. Mueller <W.F.J.Mueller@gsi.de>
.\"
.\" ------------------------------------------------------------------
.
.TH GWSTART 1 2023-02-07 "Retro Project" "Retro Project Manual"
.\" ------------------------------------------------------------------
.SH NAME
gwstart \- gtkwave starter
.\" ------------------------------------------------------------------
.SH SYNOPSIS
.
.SY gwstart
.RI [ -nw ]
.I FILE
.YS
.
.\" ------------------------------------------------------------------
.SH DESCRIPTION
\fBgwstart\fP starts \fBgtkwave\fP(1) with wave file \fIFILE\fP and adds
several Tcl commands that provide a convenient interface for the inspection
of the signal hierarchy generated by \fBghdl\fP(1) and the definition of
display traces. The additional Tcl commands are:

.RS 2
.PD 0
.IP "\fBgwlssig\fP" 12
list signals
.IP "\fBgwaddsig\fP" 12
add a signal trace to the display
.IP "\fBgwaddcom\fP" 12
add a comment separator to the display
.IP "\fBgwadd\fP" 12
add a signal definition set to the display
.PD
.RE
.PP
The typical usage is to first explore the signal hierarchy interactively
with \fBgwlssig\fP and to create a display with the relevant signals with
\fBgwaddsig\fP. In a second step, signal definition sets, usually just
lists of \fBgwaddsig\fP and \fBgwaddcom\fP commands, are defined and stored
in project-specific files. After that, \fBgwstart\fP is usually started with
the environment variable \fBGWSTART_LIB\fP, which points to the directory
of the project-specific signal definition set files.
The definition of a display is then quickly done with one or more
\fPgwadd\fP commands.

.\" ------------------------------------------------------------------
.SH OPTIONS
.
.\" ----------------------------------------------
.IP "\fB\-nw\fP"
Disables Tcl command line input on \fIstdio\fP.
.
.\" ------------------------------------------------------------------
.SH TCL COMMANDS

.\" ----------------------------------------------
.SY gwlssig
.RI [ -re ]
.RI [ SIGNAM ]...
.YS
Lists all signals that match \fISIGNAM\fP. By default \fISIGNAM\fP is
interpreted as a glob pattern, where a '*' wildcard matches name components
between the hierarchy separator '.' and a '**' wildcard matches name components
across hierarchy separator boundaries.
If the \fB-re\fP option is specified, \fISIGNAM\fP is interpreted as a regular
expression.
If no \fISIGNAM\fP is specified, all available signals are listed.
See EXAMPLES - TCL section.

.\" ----------------------------------------------
.SY gwaddsig
.RI [ OPTION ]...
.RI [ SIGNAM ]...
.YS
Adds all signals that match \fISIGNAM\fP to the display. The \fISIGNAM\fP
name syntax is the same as for the \fBgwlssig\fP command. The available
\fIOPTION\fPs are
.RS 2
.PD 0
.IP "\fB-re\fP" 6
interpret \fISIGNAM\fP as regular expression, default is glob
.IP "\fB-bin\fP" 6
use binary as data format
.IP "\fB-oct\fP" 6
use octal as data format
.IP "\fB-dec\fP" 6
use decimal as data format
.IP "\fB-sdec\fP" 6
use signed decimal as data format
.IP "\fB-hex\fP" 6
use hexadecimal as data format
.IP "\fB-asc\fP" 6
use ASCII as data format
.PD
.RE
.\" ----------------------------------------------
.SY gwaddcom
.I TEXT
.YS
Add a comment separator with text \fITEXT\fP to the display.

.\" ----------------------------------------------
.SY gwadd
.I SETNAME
.YS
Process the signal definition set \fISETNAME\fP. The command searches for a
file \fISETNAME\fP.tcl in the gwadd search path and sources it.
The file must contain Tcl commands that are valid in the \fBgtkwave\fP(1)
environment. Usually, these files contain only \fBgwaddcom\fP and
\fBgwaddsig\fP commands. The search path is defined via the
\fBGWSTART_LIB\fP environment variable.
.
.\" ------------------------------------------------------------------
.SH ENVIRONMENT
.IP \fBGWSTART_LIB\fP 4
Defines a ':' separated path list used by the \fBgwadd\fP command.
If not defined, the default '.' is used.
.
.\" ------------------------------------------------------------------
.SH EXAMPLES - COMMAND
.IP "\fBgwstart  tb_w11a_c7.ghw\fP" 4
Starts \fBgtkwave\fP(1) with Tcl command line input enabled on \fIstdio\fP
and reads the file \fItb_w11a_c7.ghw\fP.
.
.\" ------------------------------------------------------------------
.SH EXAMPLES - TCL
Some examples for the additional Tcl commands provided by \fBgwstart\fP. 
.IP "\fBgwlssig {**.clk}\fP" 4
Lists all signals with the name \fIclk\fP. The leading \fI**.\fP matches
all instances of the hierarchy.
.
.IP "\fBgwlssig -re {.*\.clk}\fP" 4
Same result as previous example, now with regular expression match instead
of glob match. Lists all signals with the name \fIclk\fP.
.
.IP "\fBgwlssig {**.treq_*}\fP" 4
Lists all signals with a name starting with \fItreq_\fP. Output like

.EX
  top.tb_cmoda7_sram.uut.sys70.w11a.seq.r_status.treq_mmu
  top.tb_cmoda7_sram.uut.sys70.w11a.seq.r_status.treq_tbit
  top.tb_cmoda7_sram.uut.sys70.w11a.seq.r_status.treq_ysv
.EE

.IP "\fBgwaddsig {**.seq.r_status.treq_*}\fP" 4
Add all signals with a name starting with \fItreq_\fP of the entity
\fI**.seq.r_status\fP to the display. A leading '**.' is often used to
shorten the name pattern and write only the minimal required for uniqueness.
.
.IP "\fBgwaddsig -oct {**.vmbox.vm_addr}\fP" 4
Add the signal \fIaddr\fP from entity \fI**.vmbox\fP to the display and use
octal as data format.
.
.IP "\fBgwaddcom mmu\fP" 4
Adds a comment separator titled "mmu" to the display.
.
.IP "\fBgwadd vmbox\fP" 4
Process the signal definition set \fIvmbox\fP. The command will search for a
file \fImmu.tcl\fP in the gwadd seach path and source it.
.
.\" ------------------------------------------------------------------
.SH "SEE ALSO"
.BR gtkwave (1),
.BR ghdl (1)
.
.\" ------------------------------------------------------------------
.SH AUTHOR
Walter F.J. Mueller <W.F.J.Mueller@gsi.de>