gtkwave - Visualization tool for VCD, LXT, LXT2, VZT, FST, and GHW files
gtkwave [option]... [DUMPFILE] [SAVEFILE] [RCFILE]
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.
- -n,--nocli <directory name>
- Use file requester for dumpfile name.
- -f,--dump <filename>
- Specify dumpfile name.
- 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.
- 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).
- Assume savefile is suffix modified dumpfile name (i.e., remove and replace
- -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.
- 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).
- 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.
- 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
- Enable Tcl command line on stdio. All script commands can be typed in on
- -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.
- 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.
- Specify single rc variable values individually. These take effect after
any other rc variables have been loaded from internal defaults or from
- Specify sst exclusion filter filename.
- 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
- 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.
- 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.
- 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
- 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.
- 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.
- Display version banner then exit.
- Display help then exit.
- Exit after loading trace (for loader benchmarking).
- 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.
- 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
- 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.
Anthony Bybell <firstname.lastname@example.org>