gtkwave - Visualization tool for VCD, LXT, LXT2, VZT, FST, and GHW files

Authors

       Anthony Bybell <bybell@rocketmail.com>

Bugs

       AIX requires  -bmaxdata:0x80000000 (-bmaxdata:0xd0000000/dsa for AIX 5.3) to be added to your list of
       compiler flags for xlc if you want GTKWave to be able to access more than 256MB of virtual memory. The
       value shown allows the VMM to use up to 2GB (3.25GB AIX5.3). This may be necessary for very large traces.

       Shift and Page operations using the wave window hscrollbar may be nonfunctional as you move away from the
       dump start for very large traces. A trace that goes out to 45 billion ticks has been known to exhibit
       this problem. This stems from using the gfloat element of the horizontal slider to encode the time value
       for the left margin. The result is a loss of precision for very large values. Use the hotkeys or buttons
       at the top of the screen if this is a problem.

       When running under Cygwin, it is required to enable Cygserver if shared memory IPC is being used.
       Specifically, this occurs when rtlbrowse(1) is launched as a helper process.  See the Cygwin
       documentation for more information on how to enable Cygserver.

Description

       Visualization  tool  for  VCD, LXT, LXT2, VZT, FST, and GHW.  VCD is an industry standard simulation dump
       format. LXT, LXT2, VZT, and FST have been designed specifically for use with gtkwave.  GHW is the  native
       VHDL  format  generated  by  GHDL.  Native dumpers exist in Icarus Verilog and the open source version of
       VeriWell for the LXT formats so conversion with vcd2lxt(1) or vcd2lxt2(1) is not necessary to take direct
       advantage of LXT with those simulators.  AET2 files can also  be  processed  provided  that  libae2rw  is
       available but this is only of interest to people who use IBM EDA toolsets.

Examples

       To run this program the standard way type:
              gtkwave dumpfile.vcd

       Alternatively you can run it with a save file as:
              gtkwave dumpfile.vcd dumpfile.gtkw

       To run interactively using shared memory handle 0x00050003:
              gtkwave -I 00050003 dumpfile.gtkw

       To pick up a dumpfile automatically from a save file (e.g., when launching from an icon):
              gtkwave --save dumpfile.gtkw

       To run from the app bundle gtkwave.app in OSX using /bin/sh:
              GTKWAVE_CHDIR=`pwd`;export GTKWAVE_CHDIR;open -n -W -a gtkwave --args --chdir dummy --dump des.vzt
              --save des.gtkw

       Alternatively, run the following Perl script gtkwave.app/Contents/Resources/bin/gtkwave to process
       command line arguments from OSX shell scripts.

       Note that to pass non-flag items which start with a dash, that it is required to specify -- in order to
       turn off flag parsing.  A second -- will disable parsing of any following arguments such that they can be
       passed on to Tcl scripts and retrieved via gtkwave::getArgv.

       Command line options are not necessary for representing the dumpfile, savefile, and rcfile  names.   They
       are merely provided to allow specifying them out of order.

Files

~/.gtkwaverc (see manpage gtkwaverc(5))

Name

       gtkwave - Visualization tool for VCD, LXT, LXT2, VZT, FST, and GHW files

Options

-n,--nocli <directoryname>
Use file requester for dumpfile name.

-f,--dump <filename>
Specify dumpfile name.

-F,--fastload
generate/use VCD recoder fastload files. This is similar to the -g,--giga option, however the
spill file generated is not deleted. Reloading the VCD file another time (either through pressing
the reload button or by re-invoking gtkwave at a later time) will use this generated spill file
rather than read the value change section of the VCD file. This will speed up reloads on large
files greatly as only the variable declaration section needs to be parsed. Note that the spill
file contains the file size and modification date of the VCD file in order to detect if it is
stale and needs to be regenerated.

-o,--optimize
optimize VCD to FST. This will automatically call vcd2fst(1) to perform the file conversion.
This option is highly recommended with large VCD files in order to cut down on the memory usage
required for file viewing. Can be used in conjunction with -v,--vcd.

-a,--save <filename>
Specify savefile name. Useful suffixes for desktop integration are .gtkw and .sav (deprecated).

-A,--autosavename
Assume savefile is suffix modified dumpfile name (i.e., remove and replace with ".gtkw").

-r,--rcfile <filename>
Specify override .gtkwaverc filename.

-l,--logfile <filename>
Specify simulation logfile name. Multiple logfiles may be specified by preceding each with the
command flag. By selecting the numbers in the text widget, the marker will immediately zoom to
the specific time value.

-d,--defaultskip
If there is not a .gtkwaverc file in the home directory or current directory and it is not
explicitly specified on the command line, when this option is enabled, do not use an implicit
configuration file and instead default to the old "whitescreen" behavior.

-D,--dualid <which>
Specify multisession identifier information. The format of "which" is m+nnnnnnnn where m is the
session number 0 or 1 and nnnnnnnn is a hexadecimal value indicating the shared memory ID of an
array of two gtkwave_dual_ipc_t data structures. The intended use of this flag is for front ends
such as twinwave(1).

-s,--start <time>
Specify start time for LXT2/VZT block skip.

-e,--end <time>
Specify end time for LXT2/VZT block skip.

-t,--stems <filename>
Specify stems file for source code annotation. This will automatically launch the rtlbrowse(1)
helper process. See xml2stems(1) for information on stems file generation.

-c,--cpu <numcpus>
Specify number of CPUs available for parallelizable ops (e.g., block prefetching on VZT reads).

-N,--nowm
Disable window manager for most windows. The intended use of this is to be used in conjunction
with the --script option, however this also can be used to reparent into an alternate window
manager.

-M,--nomenus
Do not render menubar. This is mainly used for making a restricted applet that cannot initiate
file I/O on its own, however it also can be used as a workaround in earlier versions of GTK+ that
do not handle GTKSocket/GTKPlug focus interactions properly.

-S,--script <filename>
Specify Tcl command script file for execution.

-T,--tcl_init <filename>
Specify Tcl command script to be loaded on startup. Implies --wish command flag.

-W,--wish
Enable Tcl command line on stdio. All script commands can be typed in on stdin.

-R,--repscript <filename>
Specify Tcl command script for periodic execution.

-P,--repperiod <value>
Specifies delay in milliseconds between successive executions of the repscript. Default is 500.

-X,--xid <XID>
Specify XID (in hexadecimal) of window for a GtkPlug to connect to. GTKWave does not directly
render to a window but instead renders into a GtkPlug expecting a GtkSocket at the other end.
Note that there are issues with accelerators working properly so menus are disabled in the
componentized version of GTKWave when it functions as a plug-in.

-1,--rpcid <RPCID>
Specify RPCID of GConf (or GSettings) session. This is a decimal value zero or greater and is the
identifier used by GConf to know what update data to listen to. This option only works if --with-gconf (or --with-gsettings) was specified during ./configure.

-2,--chdir <DIRNAME>
Specify new current working directory. This is typically used in OSX to run gtkwave if it was
compiled and placed in an .app bundle. Note that if the environment variable GTKWAVE_CHDIR is
defined, the argument is a dummy argument. This is to support OSX in that the open command has
difficulty in passing spaces as command line arguments and it is possible for pwd(1) to return
spaces.

-3,--restore
Restore previous default (0) or --rpcid RPCID numbered session. This only works for one
dumpfile, savefile, rcfile, and current working directory so it has the effect of restoring the
most recently loaded file. If used in conjunction with the --rpcid option, that option must be
specified earlier in the command line than the --restore option. If RPCID is not specified, then
the default of 0 is used. This option only works if --with-gconf (or --with-gsettings) was
specified during ./configure. Note that for GSettings, limitations in its implementation allow it
only to restore the previous session.

-4,--rcvar
Specify single rc variable values individually. These take effect after any other rc variables
have been loaded from internal defaults or from configuration files.

-5,--sstexclude
Specify sst exclusion filter filename.

-6,--dark
Set gtk-application-prefer-dark-theme = TRUE.

-7,--saveonexit
At exit, a requester is brought up to prompt user to write a save file. Canceling the requester
prevents from writing the file.

-I,--interactive
Specifies that "interactive" VCD mode is to be used which allows a viewer to navigate a VCD trace
while GTKWave is processing the VCD file. When this option is used, the filename is overloaded
such that it is the hexadecimal value for the shared memory ID of a writer. Note that the shared
memory ID can be passed straight from stdin by using the --vcd option; see the manpage for
shmidcat(1) for more details.

-L,--legacy
Specifies that the viewer should use legacy VCD mode rather than the VCD recoder. Note that using
legacy mode will require considerably more memory than the recoder and its use is discouraged for
very large traces.

-g,--giga
Specifies that the viewer should use gigabyte mempacking when recoding (possibly slower). This is
equivalent to setting the vlist_spill and vlist_prepack flags in the rc file.

-C,--comphier
Specifies that the viewer should use compressed hierarchy names when loading the dumpfile
(available for VCD recoder, LXT, LXT2, and VZT). This will use less memory at the expense of
compression/decompression delay.

-v,--vcd
Use stdin as a VCD dumpfile.

-O,--output <filename>
Specify filename for stdout/stderr redirect. To disable messages to the console, use /dev/null as
the filename.

-z,--slider-zoom
Enable slider stretch zoom for the horizontal time slider. Clicking then dragging the very left
or right edge of the slider can be used to provide fine-grained real-time zooming.

-V,--version
Display version banner then exit.

-h,--help
Display help then exit.

-x,--exit
Exit after loading trace (for loader benchmarking).

Syntax

       gtkwave [option]... [DUMPFILE] [SAVEFILE] [RCFILE]