GTKWAVE(1)

📦
version 3.3.128 · 3 versions
, in arch rolling, epel 10, fedora 44, nixos 26.05, nixpkgs unstable, ubuntu resolute, ubuntu stonking

💖 GTKWAVE(1) — Simulation Wave Viewer 💖

okay so this is the manual page for gtkwave(1), and bestie, if you're about to open up a waveform viewer you came to the right place. grab a snack, we're going in 🫶

✨ NAME ✨

gtkwave — the visualization tool for VCD, LXT, LXT2, VZT, FST, and GHW files. that's it, that's the whole vibe 💅

📜 SYNTAX 📜

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

🌸 DESCRIPTION 🌸

okay so, gtkwave is literally the visualization tool for VCD, LXT, LXT2, VZT, FST, and GHW. and if you're like "what are those" — don't worry, I got you:

  • VCD is an industry standard simulation dump format. the classic. the main character.
  • LXT, LXT2, VZT, and FST were designed specifically for use with gtkwave. they're the home team 💖
  • GHW is the native VHDL format generated by GHDL.

and here's the tea 🍓: native dumpers already exist in Icarus Verilog and in the open source version of VeriWell for the LXT formats — so you do NOT need to do the whole conversion song and dance with vcd2lxt(1) or vcd2lxt2(1) in order to take direct advantage of LXT with those simulators. no cap, it just works.

also! AET2 files can be processed too, as long as libae2rw is available. but ngl that one's only of interest to the people using IBM EDA toolsets. if that's you, hi bestie, love your work 💜

👑 OPTIONS 👑

one bullet per flag, no skips, we're doing all of them because that's what icons do 💅

  • -n, --nocli <directory name> — use a file requester to pick the dumpfile name. cute, clicky, no typing.
  • -f, --dump <filename> — specify the dumpfile name. plain and simple.
  • -F, --fastload — generate/use VCD recoder fastload files. this is similar to the -g, --giga option, except the spill file that gets generated is not deleted. so when you reload the VCD file another time — whether by pressing the reload button or by re-invoking gtkwave at a later time — it uses that generated spill file instead of reading the value change section of the VCD file. this speeds up reloads on large files greatly because 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, so it can detect if it's stale and needs to be regenerated. iconic.
  • -o, --optimize — optimize VCD to FST. this automatically calls vcd2fst(1) to do 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 the savefile name. useful suffixes for desktop integration are .gtkw and .sav (⚠️ the .sav one is deprecated).
  • -A, --autosavename — assume the savefile is a suffix modified dumpfile name, i.e. remove the suffix and replace it with ".gtkw".
  • -r, --rcfile <filename> — specify an override .gtkwaverc filename.
  • -l, --logfile <filename> — specify the simulation logfile name. you can specify multiple logfiles by preceding each one with the command flag. and the cute part? by selecting the numbers in the text widget, the marker will immediately zoom to that specific time value. obsessed ✨
  • -d, --defaultskip — if there is no .gtkwaverc file in the home directory or current directory, and it's not explicitly specified on the command line, then when this option is enabled: do not use an implicit configuration file, and instead default to the old "whitescreen" behavior. the vibes of yesteryear.
  • -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). (yes, twinwave. two waves. slay 💅)
  • -s, --start <time> — specify the start time for LXT2/VZT block skip.
  • -e, --end <time> — specify the end time for LXT2/VZT block skip.
  • -t, --stems <filename> — specify a stems file for source code annotation. this will automatically launch the rtlbrowse(1) helper process. see xml2stems(1) for info on stems file generation.
  • -c, --cpu <numcpus> — specify the number of CPUs available for parallelizable ops (e.g., block prefetching on VZT reads). multitasking queen behavior 🧚
  • -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 the 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. 🙈
  • -H, --noheader — do not use headerbars (the ones that provide hamburger style menus rendered in the toolbar), but revert back to non-headerbar operation. this is for GTK 3 only.
  • -S, --script <filename> — specify the Tcl command script file for execution.
  • -T, --tcl_init <filename> — specify the Tcl command script to be loaded on startup. this implies the --wish command flag.
  • -W, --wish — enable the Tcl command line on stdio. all script commands can be typed in on stdin.
  • -R, --repscript <filename> — specify the Tcl command script for periodic execution.
  • -P, --repperiod <value> — specifies the delay in milliseconds between successive executions of the repscript. default is 500.
  • -X, --xid <XID> — specify the XID (in hexadecimal) of the 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 the RPCID of the GConf (or GSettings) session. this is a decimal value of zero or greater, and it's 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 a 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, because the open command has difficulty passing spaces as command line arguments, and it's possible for pwd(1) to return spaces. tragic, honestly.
  • -3, --restore — restore the 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. and heads up: for GSettings, limitations in its implementation allow it to only 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. order matters, bestie.
  • -5, --sstexclude — specify the sst exclusion filter filename.
  • -6, --dark — set gtk-application-prefer-dark-theme = TRUE. dark mode era 🖤 iconic, no notes.
  • -7, --saveonexit — at exit, a requester is brought up to prompt the user to write a save file. canceling the requester prevents it from writing the file. so polite of it.
  • -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. proceed with caution bestie.
  • -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. tradeoffs, we love them.
  • -v, --vcd — use stdin as a VCD dumpfile. piping queen 💅
  • -O, --output <filename> — specify the filename for stdout/stderr redirect. to disable messages to the console, use /dev/null as the filename. shhh 🤫
  • -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. so satisfying fr fr ✨
  • -V, --version — display the version banner, then exit.
  • -h, --help — display help, then exit.
  • -x, --exit — exit after loading the trace (for loader benchmarking). speedrun mode 🏃‍♀️

📁 FILES 📁

  • ~/.gtkwaverc — (see manpage gtkwaverc(5)) your personal config, your personal vibe.

🌈 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, 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. double dash = double the power, iykyk.

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. so chill of them honestly.

💀 BUGS 💀

okay bestie, listen, even iconic software has ✨quirks✨ and we're gonna spill all the tea:

  • On AIX, you gotta add -bmaxdata:0x80000000 (or -bmaxdata:0xd0000000/dsa if you're on AIX 5.3) to your compiler flags for xlc if you want GTKWave to be able to access more than 256MB of virtual memory. The value shown lets the VMM use up to 2GB (or 3.25GB on AIX5.3). You might lowkey need this for very large traces, no cap.
  • Shift and Page operations using the wave window hscrollbar? Yeah, they may be nonfunctional as you move away from the dump start for very large traces 😭. Like, a trace that goes out to 45 billion ticks has been known to exhibit this problem. It's giving precision loss, fr fr — this stems from using the gfloat element of the horizontal slider to encode the time value for the left margin, so the result is a loss of precision for very large values. If this is a problem, just use the hotkeys or buttons at the top of the screen, periodt.
  • 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 info on how to enable Cygserver.

👑 AUTHORS 👑

Anthony Bybell <bybell@rocketmail.com> — the main character who made all this happen, we stan 💖

🌈 SEE ALSO 🌈

and that's a wrap on the whole page, bestie!! 🎀 this was version 3.3.126, dated 3.3.126, and written by the one and only Anthony Bybell 🦋 go forth and slay your waveforms 💅✨

📦 where this page comes from