GTKWAVE(1)                  Simulation Wave Viewer                  GTKWAVE(1)

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

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


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.

OPTIONS
       -n,--nocli <directory name>
              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).

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


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.

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.

AUTHORS
       Anthony Bybell <bybell@rocketmail.com>

SEE ALSO
       gtkwaverc(5) lxt2vcd(1) vcd2lxt(1) vcd2lxt2(1) vzt2vcd(1) vcd2vzt(1)
       xml2stems(1) rtlbrowse(1) twinwave(1) shmidcat(1)

Anthony Bybell                      3.3.101                         GTKWAVE(1)