1GTKWAVE(1)                  Simulation Wave Viewer                  GTKWAVE(1)
2
3
4

NAME

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

SYNTAX

10       gtkwave [option]... [DUMPFILE] [SAVEFILE] [RCFILE]
11
12

DESCRIPTION

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

OPTIONS

25       -n,--nocli <directory name>
26              Use file requester for dumpfile name.
27
28       -f,--dump <filename>
29              Specify dumpfile name.
30
31       -F,--fastload
32              generate/use VCD recoder fastload files.  This is similar to the
33              -g,--giga  option,  however  the  spill  file  generated  is not
34              deleted.  Reloading the VCD file another  time  (either  through
35              pressing  the reload button or by re-invoking gtkwave at a later
36              time) will use this generated spill file rather  than  read  the
37              value  change  section  of  the  VCD  file.   This will speed up
38              reloads on large files greatly as only the variable  declaration
39              section  needs  to be parsed.  Note that the spill file contains
40              the file size and modification date of the VCD file in order  to
41              detect if it is stale and needs to be regenerated.
42
43       -o,--optimize
44              optimize VCD to FST.  This will automatically call vcd2fst(1) to
45              perform the file conversion.  This option is highly  recommended
46              with  large  VCD  files in order to cut down on the memory usage
47              required for file viewing.  Can  be  used  in  conjunction  with
48              -v,--vcd.
49
50       -a,--save <filename>
51              Specify  savefile name.  Useful suffixes for desktop integration
52              are .gtkw and .sav (deprecated).
53
54       -A,--autosavename
55              Assume savefile is suffix modified dumpfile name  (i.e.,  remove
56              and replace with ".gtkw").
57
58       -r,--rcfile <filename>
59              Specify override .gtkwaverc filename.
60
61       -l,--logfile <filename>
62              Specify simulation logfile name.  Multiple logfiles may be spec‐
63              ified by preceding each with the command flag.  By selecting the
64              numbers  in the text widget, the marker will immediately zoom to
65              the specific time value.
66
67       -d,--defaultskip
68              If there is not a .gtkwaverc file in the home directory or  cur‐
69              rent directory and it is not explicitly specified on the command
70              line, when this option is enabled, do not use an  implicit  con‐
71              figuration  file  and  instead  default to the old "whitescreen"
72              behavior.
73
74       -D,--dualid <which>
75              Specify multisession  identifier  information.   The  format  of
76              "which"  is  m+nnnnnnnn where m is the session number 0 or 1 and
77              nnnnnnnn is a hexadecimal value indicating the shared memory  ID
78              of  an  array  of  two  gtkwave_dual_ipc_t data structures.  The
79              intended use of this flag is for front ends such as twinwave(1).
80
81       -s,--start <time>
82              Specify start time for LXT2/VZT block skip.
83
84       -e,--end <time>
85              Specify end time for LXT2/VZT block skip.
86
87       -t,--stems <filename>
88              Specify stems file for source code annotation.  This will  auto‐
89              matically   launch   the   rtlbrowse(1)   helper  process.   See
90              xml2stems(1) for information on stems file generation.
91
92       -c,--cpu <numcpus>
93              Specify number of CPUs available for parallelizable  ops  (e.g.,
94              block prefetching on VZT reads).
95
96       -N,--nowm
97              Disable  window  manager  for most windows.  The intended use of
98              this is to be used in conjunction with the --script option, how‐
99              ever  this also can be used to reparent into an alternate window
100              manager.
101
102       -M,--nomenus
103              Do not  render  menubar.  This  is  mainly  used  for  making  a
104              restricted applet that cannot initiate file I/O on its own, how‐
105              ever it also can be used as a workaround in earlier versions  of
106              GTK+  that  do  not  handle GTKSocket/GTKPlug focus interactions
107              properly.
108
109       -S,--script <filename>
110              Specify Tcl command script file for execution.
111
112       -T,--tcl_init <filename>
113              Specify Tcl command script to be  loaded  on  startup.   Implies
114              --wish command flag.
115
116       -W,--wish
117              Enable  Tcl  command  line on stdio.  All script commands can be
118              typed in on stdin.
119
120       -R,--repscript <filename>
121              Specify Tcl command script for periodic execution.
122
123       -P,--repperiod <value>
124              Specifies delay in milliseconds between successive executions of
125              the repscript.  Default is 500.
126
127       -X,--xid <XID>
128              Specify  XID (in hexadecimal) of window for a GtkPlug to connect
129              to.  GTKWave does not directly render to a  window  but  instead
130              renders  into  a GtkPlug expecting a GtkSocket at the other end.
131              Note that there are issues with accelerators working properly so
132              menus  are disabled in the componentized version of GTKWave when
133              it functions as a plug-in.
134
135       -1,--rpcid <RPCID>
136              Specify RPCID of GConf (or GSettings) session.  This is a  deci‐
137              mal value zero or greater and is the identifier used by GConf to
138              know what update data to listen to.  This option only  works  if
139              --with-gconf  (or  --with-gsettings) was specified during ./con‐
140              figure.
141
142       -2,--chdir <DIRNAME>
143              Specify new current working directory.  This is  typically  used
144              in  OSX  to run gtkwave if it was compiled and placed in an .app
145              bundle.  Note that if the environment variable GTKWAVE_CHDIR  is
146              defined,  the  argument  is a dummy argument. This is to support
147              OSX in that the open command has difficulty in passing spaces as
148              command  line  arguments and it is possible for pwd(1) to return
149              spaces.
150
151       -3,--restore
152              Restore previous default (0) or  --rpcid RPCID numbered session.
153              This  only works for one dumpfile, savefile, rcfile, and current
154              working directory so it has the effect  of  restoring  the  most
155              recently  loaded  file.  If used in conjunction with the --rpcid
156              option, that option must be specified  earlier  in  the  command
157              line than the --restore option.  If RPCID is not specified, then
158              the default of 0 is used.  This option  only  works  if  --with-
159              gconf  (or  --with-gsettings)  was specified during ./configure.
160              Note that for GSettings, limitations in its implementation allow
161              it only to restore the previous session.
162
163       -4,--rcvar
164              Specify  single  rc  variable  values  individually.  These take
165              effect after any other rc variables have been loaded from inter‐
166              nal defaults or from configuration files.
167
168       -5,--sstexclude
169              Specify sst exclusion filter filename.
170
171       -I,--interactive
172              Specifies that "interactive" VCD mode is to be used which allows
173              a viewer to navigate a VCD trace while GTKWave is processing the
174              VCD  file.  When this option is used, the filename is overloaded
175              such that it is the hexadecimal value for the shared  memory  ID
176              of  a  writer.   Note  that  the  shared memory ID can be passed
177              straight from stdin by using the --vcd option; see  the  manpage
178              for shmidcat(1) for more details.
179
180       -L,--legacy
181              Specifies that the viewer should use legacy VCD mode rather than
182              the VCD recoder.  Note that using legacy mode will require  con‐
183              siderably  more  memory than the recoder and its use is discour‐
184              aged for very large traces.
185
186       -g,--giga
187              Specifies that the viewer should use  gigabyte  mempacking  when
188              recoding  (possibly  slower).  This is equivalent to setting the
189              vlist_spill and vlist_prepack flags in the rc file.
190
191       -C,--comphier
192              Specifies that the viewer should use compressed hierarchy  names
193              when loading the dumpfile (available for VCD recoder, LXT, LXT2,
194              and VZT).  This will use less memory at the expense of  compres‐
195              sion/decompression delay.
196
197       -v,--vcd
198              Use stdin as a VCD dumpfile.
199
200       -O,--output <filename>
201              Specify  filename  for  stdout/stderr redirect.  To disable mes‐
202              sages to the console, use /dev/null as the filename.
203
204       -z,--slider-zoom
205              Enable slider stretch  zoom  for  the  horizontal  time  slider.
206              Clicking then dragging the very left or right edge of the slider
207              can be used to provide fine-grained real-time zooming.
208
209       -V,--version
210              Display version banner then exit.
211
212       -h,--help
213              Display help then exit.
214
215       -x,--exit
216              Exit after loading trace (for loader benchmarking).
217

FILES

219       ~/.gtkwaverc (see manpage gtkwaverc(5))
220
221

EXAMPLES

223       To run this program the standard way type:
224              gtkwave dumpfile.vcd
225
226       Alternatively you can run it with a save file as:
227              gtkwave dumpfile.vcd dumpfile.gtkw
228
229       To run interactively using shared memory handle 0x00050003:
230              gtkwave -I 00050003 dumpfile.gtkw
231
232       To pick up a dumpfile  automatically  from  a  save  file  (e.g.,  when
233       launching from an icon):
234              gtkwave --save dumpfile.gtkw
235
236       To run from the app bundle gtkwave.app in OSX using /bin/sh:
237              GTKWAVE_CHDIR=`pwd`;export  GTKWAVE_CHDIR;open  -n -W -a gtkwave
238              --args --chdir dummy --dump des.vzt --save des.gtkw
239
240       Alternatively,  run  the   following   Perl   script   gtkwave.app/Con‐
241       tents/Resources/bin/gtkwave  to process command line arguments from OSX
242       shell scripts.
243
244       Note that to pass non-flag items which start with a dash,  that  it  is
245       required  to specify -- in order to turn off flag parsing.  A second --
246       will disable parsing of any following arguments such that they  can  be
247       passed on to Tcl scripts and retrieved via gtkwave::getArgv.
248
249       Command  line  options are not necessary for representing the dumpfile,
250       savefile, and rcfile names.  They are merely provided to allow specify‐
251       ing them out of order.
252

BUGS

254       AIX  requires   -bmaxdata:0x80000000  (-bmaxdata:0xd0000000/dsa for AIX
255       5.3) to be added to your list of compiler flags for  xlc  if  you  want
256       GTKWave  to  be  able  to access more than 256MB of virtual memory. The
257       value shown allows the VMM to use up to 2GB (3.25GB AIX5.3).  This  may
258       be necessary for very large traces.
259
260       Shift  and Page operations using the wave window hscrollbar may be non‐
261       functional as you move away from the dump start for very large  traces.
262       A  trace  that  goes  out to 45 billion ticks has been known to exhibit
263       this problem. This stems from using the gfloat element of the  horizon‐
264       tal  slider to encode the time value for the left margin. The result is
265       a loss of precision for very large values. Use the hotkeys  or  buttons
266       at the top of the screen if this is a problem.
267
268       When running under Cygwin, it is required to enable Cygserver if shared
269       memory IPC is being used.  Specifically, this occurs when  rtlbrowse(1)
270       is launched as a helper process.  See the Cygwin documentation for more
271       information on how to enable Cygserver.
272

AUTHORS

274       Anthony Bybell <bybell@rocketmail.com>
275

SEE ALSO

277       gtkwaverc(5) lxt2vcd(1) vcd2lxt(1)  vcd2lxt2(1)  vzt2vcd(1)  vcd2vzt(1)
278       xml2stems(1) rtlbrowse(1) twinwave(1) shmidcat(1)
279
280
281
282Anthony Bybell                      3.3.98                          GTKWAVE(1)
Impressum