w11 - /man/cat1/gwstart.0

GWSTART(1)                   Retro Project Manual                   GWSTART(1)


NAME
       gwstart - gtkwave starter

SYNOPSIS
       gwstart [-nw] FILE

DESCRIPTION
       gwstart starts gtkwave(1) with wave file FILE and adds several Tcl com-
       mands that provide a convenient interface for  the  inspection  of  the
       signal  hierarchy  generated  by  ghdl(1) and the definition of display
       traces. The additional Tcl commands are:

         gwlssig     list signals
         gwaddsig    add a signal trace to the display
         gwaddcom    add a comment separator to the display
         gwadd       add a signal definition set to the display

       The typical usage is to first explore  the  signal  hierarchy  interac-
       tively  with  gwlssig and to create a display with the relevant signals
       with gwaddsig. In a second step, signal definition sets,  usually  just
       lists  of  gwaddsig  and  gwaddcom  commands, are defined and stored in
       project-specific files. After that, gwstart is usually started with the
       environment  variable GWSTART_LIB, which points to the directory of the
       project-specific signal definition set files.  The definition of a dis-
       play is then quickly done with one or more gwadd commands.


OPTIONS
       -nw    Disables Tcl command line input on stdio.

TCL COMMANDS
       gwlssig [-re] [SIGNAM]...
       Lists  all  signals that match SIGNAM. By default SIGNAM 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 -re option is specified,
       SIGNAM  is interpreted as a regular expression.  If no SIGNAM is speci-
       fied, all available signals are listed.  See EXAMPLES - TCL section.


       gwaddsig [OPTION]...  [SIGNAM]...
       Adds all signals that match SIGNAM to the display. The SIGNAM name syn-
       tax is the same as for the gwlssig command. The available OPTIONs are
         -re   interpret SIGNAM as regular expression, default is glob
         -bin  use binary as data format
         -oct  use octal as data format
         -dec  use decimal as data format
         -sdec use signed decimal as data format
         -hex  use hexadecimal as data format
         -asc  use ASCII as data format

       gwaddcom TEXT
       Add a comment separator with text TEXT to the display.


       gwadd SETNAME
       Process  the  signal definition set SETNAME. The command searches for a
       file SETNAME.tcl in the gwadd search path and  sources  it.   The  file
       must contain Tcl commands that are valid in the gtkwave(1) environment.
       Usually, these files contain only gwaddcom and gwaddsig  commands.  The
       search path is defined via the GWSTART_LIB environment variable.

ENVIRONMENT
       GWSTART_LIB
           Defines  a  ':'  separated path list used by the gwadd command.  If
           not defined, the default '.' is used.

EXAMPLES - COMMAND
       gwstart  tb_w11a_c7.ghw
           Starts gtkwave(1) with Tcl command line input enabled on stdio  and
           reads the file tb_w11a_c7.ghw.

EXAMPLES - TCL
       Some examples for the additional Tcl commands provided by gwstart.

       gwlssig {**.clk}
           Lists  all  signals  with the name clk. The leading **. matches all
           instances of the hierarchy.

       gwlssig -re {.*.clk}
           Same result as previous example, now with regular expression  match
           instead of glob match. Lists all signals with the name clk.

       gwlssig {**.treq_*}
           Lists all signals with a name starting with treq_. Output like

             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


       gwaddsig {**.seq.r_status.treq_*}
           Add  all  signals  with  a  name  starting with treq_ of the entity
           **.seq.r_status to the display. A leading '**.' is  often  used  to
           shorten  the  name  pattern and write only the minimal required for
           uniqueness.

       gwaddsig -oct {**.vmbox.vm_addr}
           Add the signal addr from entity **.vmbox to the display and use oc-
           tal as data format.

       gwaddcom mmu
           Adds a comment separator titled "mmu" to the display.

       gwadd vmbox
           Process  the  signal  definition set vmbox. The command will search
           for a file mmu.tcl in the gwadd seach path and source it.

SEE ALSO
       gtkwave(1), ghdl(1)

AUTHOR
       Walter F.J. Mueller <W.F.J.Mueller@gsi.de>


Retro Project                     2023-02-07                        GWSTART(1)