Google

"http://www.w3.org/TR/REC-html40/loose.dtd">

Welcome to GTKWave

Please note that this documentation is currently out of synch with this GTKWave release

GTKWave is a fully featured GTK+ v1.2 based wave viewer for Unix and Win32 which reads LXT files as well as standard Verilog VCD/EVCD files and allows their viewing.

A sample trace with the Thin Ice theme and user-defined colors.

Online Help

Online help is available for every menu function in GTKWave. In order to access online help, select Help-Wave Help from the menu and then select any menu option in order to see the menu option's description. Click the Close Help button in the help requester to revert to normal GTKWave menu operation.

What follows below is the listing of every menu item description.

File Menu
  • Open New Viewer will open a file requester that will ask for the name of a VCD or AET file to view. This will fork off a new viewer process. (Unix only.)
  • Print To File will open up a requester that will allow you to select print options (PS or MIF; Letter, A4, or Legal; Full or Minimal). After selecting the options you want, a file requester will ask for the name of the output file to generate that reflects the current main window display's contents.

    [A sample ps file generated by this option may be grabbed by clicking on the picture below..]


  • Read Save File will open a file requester that will ask for the name of a GTKWave save file. The contents of the save file will determine which traces and vectors as well as their format (binary, decimal, hex, reverse, etc.) are to be appended to the display. Note that the marker positional data and zoom factor present in the save file will replace any current settings.

  • Write Save File will open a file requester that will ask for the name of a GTKWave save file. The contents of the save file generated will be the traces as well as their format (binary, decimal, hex, reverse, etc.) which are currently a part of the display. Marker positional data and the zoom factor are also a part of the save file.
  • Quit exits GTKWave after an additional confirmation requester is given the OK to quit.


    • Edit Menu
  • Set Trace Max Hier sets the maximum hierarchy depth (counting from the right with bit numbers or ranges ignored) that is displayable for trace names. Zero indicates that no truncation will be performed (default). Note that any aliased signals (prefix of a "+") will not have truncated names.
  • Insert Blank inserts a blank trace after the last highlighted trace. If no traces are highlighted, the blank is inserted after the last trace. Note that this function is disabled when Pattern Search is active.

  • Insert Comment inserts a comment trace after the last highlighted trace. If no traces are highlighted, the comment is inserted after the last trace. Note that this function is disabled when Pattern Search is active.

  • Alias Highlighted Trace only works when at least one trace has been highlighted. With this function, you will be prompted for an alias name for the first highlighted trace. After successfully aliasing a trace, the aliased trace will be unhighlighted. Single bits will be marked with a leading "+" and vectors will have no such designation. The purpose of this is to provide a fast method of determining which trace names are real and which ones are aliases. Note that this function is disabled when Pattern Search is active.

  • Remove Highlighted Aliases only works when at least one trace has been highlighted. Any aliased traces will have their names restored to their original names. As vectors get their names from aliases, vector aliases will not be removed. Note that this function is disabled when Pattern Search is active.

  • Cut removes highlighted signals from the display and places them in an offscreen cut buffer for later Paste operations. Cut implicitly destroys the previous contents of the cut buffer. Note that this function is disabled when Pattern Search is active.

  • Paste pastes signals from an offscreen cut buffer and places them in a group after the last highlighted signal, or at the end of the display if no signal is highlighted. Paste implicitly destroys the previous contents of the cut buffer. Note that this function is disabled when Pattern Search is active.
  • Expand decomposes the highlighted signals into their individual bits. The resulting bits are converted to traces and inserted after the last highlighted trace. The original unexpanded traces will be placed in the cut buffer. It will function seemingly randomly when used upon atomic_vector or real valued single-bit traces. When used upon multi-bit vectors that contain atomic_vector traces or real valued traces, those traces will expand to their normal "correct" values, not individual bits. Note that this function is disabled when Pattern Search is active.

  • Combine Down coalesces the highlighted signals into a single vector named "(Vector)" in a top to bottom fashion placed after the last highlighted trace. The original traces will be placed in the cut buffer. It will function seemingly randomly when used upon atomic_vector or real valued single-bit traces. Note that this function is disabled when Pattern Search is active.

  • Combine Up coalesces the highlighted signals into a single vector named "(Vector)" in a bottom to top fashion placed after the last highlighted trace. The original traces will be placed in the cut buffer. It will function seemingly randomly when used upon atomic_vector or real valued single-bit traces. Note that this function is disabled when Pattern Search is active.

  • Reduce Single Bit Vectors decomposes the highlighted traces into their individual bits only if the highlighted traces are one bit wide vectors. In effect, this function allows single-bit vectors to be viewed as signals. The resulting bits are converted to traces and inserted after the last converted trace with the pre-conversion traces being placed in the cut buffer. Note that this function is disabled when Pattern Search is active.
    Data Format Submenu
  • Hex will step through all highlighted traces and ensure that vectors with this qualifier will be displayed with hexadecimal values.

  • Decimal will step through all highlighted traces and ensure that vectors with this qualifier will be displayed with decimal values.

  • Signed Decimal will step through all highlighted traces and ensure that vectors with this qualifier will be displayed as sign extended decimal values.

  • Binary will step through all highlighted traces and ensure that vectors with this qualifier will be displayed with binary values.

  • Octal will step through all highlighted traces and ensure that vectors with this qualifier will be displayed with octal values.

  • Right Justify-On will step through all highlighted traces and ensure that vectors with this qualifier will be displayed right justified.

  • Right Justify-Off will step through all highlighted traces and ensure that vectors with this qualifier will not be displayed right justified.

  • Invert-On will step through all highlighted traces and ensure that bits and vectors with this qualifier will be displayed with 1's and 0's inverted.

  • Invert-Off will step through all highlighted traces and ensure that bits and vectors with this qualifier will not be displayed with 1's and 0's inverted.

  • Reverse Bits-On will step through all highlighted traces and ensure that vectors with this qualifier will be displayed in reversed bit order.

  • Reverse Bits-Off will step through all highlighted traces and ensure that vectors with this qualifier will not be displayed in reversed bit order.

  • Show-Change All Highlighted provides an easy means of changing trace attributes en masse. Various functions are provided in a Show-Change requester.

  • Show-Change First Highlighted provides a means of changing trace attributes for the first highlighted trace. Various functions are provided in a Show-Change requester. When a function is applied, the trace will be unhighlighted.
  • Exclude causes the waveform data for all currently highlighted traces to be blanked out.

  • Show causes the waveform data for all currently highlighted traces to be displayed as normal if the exclude attribute is currently set on the highlighted traces.
  • Highlight Regexp brings up a text requester that will ask for a regular expression that may contain POSIX regular expressions. All traces meeting this criteria will be highlighted.

  • UnHighlight Regexp brings up a text requester that will ask for a regular expression that may contain text with POSIX regular expressions. All traces meeting this criteria will be unhighlighted if they are currently highlighted.

  • Highlight All simply highlights all displayed traces.

  • UnHighlight All simply unhighlights all displayed traces.


    • Search Menu
  • Pattern Search only works when at least one trace is highlighted. A requester will appear that lists all the selected traces (maximum of 500) and allows various criteria to be specified for each trace. Searches can go forward or backward from the primary (unnamed) marker. If the primary marker has not been set, the search starts at the beginning of the displayed data ("From") for a forwards search and starts at the end of the displayed data ("To") for a backwards search.

  • Signal Search Regexp provides an easy means of adding traces to the display. Various functions are provided in the Signal Search requester which allow searching using POSIX regular expressions and bundling (coalescing individual bits into a single vector). Note that this function is disabled when Pattern Search is active.

  • Signal Search Hierarchy provides an easy means of adding traces to the display in a text based treelike fashion. Note that this function is disabled when Pattern Search is active.

  • Signal Search Tree provides an easy means of adding traces to the display. Various functions are provided in the Signal Search Tree requester which allow searching a treelike hierarchy and bundling (coalescing individual bits into a single vector). Note that this function is disabled when Pattern Search is active.
  • Autocoalesce when enabled allows the wave viewer to reconstruct split vectors. Split vectors will be indicated by a "[]" prefix in the search requesters.

  • Autocoalesce Reversal causes split vectors to be reconstructed in reverse order (only if autocoalesce is also active). This is necessary with some simulators. Split vectors will be indicated by a "[]" prefix in the search requesters.

  • Autoname Bundles On modifies the bundle up/down operations in the hierarchy and tree searches such that a NULL bundle name is implicitly created which informs GTKWave to create bundle and signal names based on the position in the hierarchy.

  • Autoname Bundles Off modifies the bundle up/down operations in the hierarchy and tree searches such that a NULL bundle name is not implicitly created. This informs GTKWave to create bundle and signal names based on the position in the hierarchy only if the user enters a zero-length bundle name. This behavior is the default.

  • Search Hierarchy Grouping when enabled ensures that new members added to the ``Tree Search'' and ``Hierarchy Search'' widgets are added alphanumerically: first hierarchy names as a group followed by signal names as a group. This is the default and is recommended. When disabled, hierarchy names and signal names are interleaved together in strict alphanumerical ordering. Note that due to the caching mechanism in ``Tree Search'', dynamically changing this flag when the widget is active may not produce immediately obvious results. Closing the widget then opening it up again will ensure that it follows the behavior of this flag.


    • Time Menu
  • Move To Time scrolls the waveform display such that the left border is the time entered in the requester.

    Zoom Submenu
  • Zoom Amount allows entry of zero or a negative value for the display zoom. Zero is no magnification.

  • Zoom Base allows entry of a zoom base for the zoom (magnification per integer step) Allowable values are 1.5 to 10.0. Default is 2.0.

  • Zoom In is used to increase the zoom factor.

  • Zoom Out is used to decrease the zoom factor.

  • Zoom Best Fit attempts a "best fit" to get the whole trace onscreen. Note that the trace may be more or less than a whole screen since this isn't a "perfect fit." This works much better than it did in previous versions of GTKWave since the zoom amounts are floating point now. NOTE: You can also use the 3rd mouse button to do a "drag zoom" that allows an extremely fine granularity for zooming. This is similar to the zooming allowed on HP storage scopes.

  • Zoom To Start is used to jump scroll to the trace's beginning.

  • Zoom To End is used to jump scroll to the trace's end.

  • Undo Zoom is used to revert to the previous zoom value used. Undo only works one level deep.

  • Fetch Size brings up a requester which allows input of the number of ticks used for fetch/discard operations. Default is 100.

  • Fetch Right increases the "To" time, which allows more of the AET to be displayed if the "From" and "To" times do not match the actual bounds of the AET.

  • Fetch Left decreases the "From" time, which allows more of the AET to be displayed if the "From" and "To" times do not match the actual bounds of the AET.

  • Discard Right decreases the "To" time, which allows less of the AET to be displayed.

  • Discard Left increases the "From" time, which allows less of the AET to be displayed.

  • Shift Right scrolls the display window right one tick worth of data. The net action is that the data scrolls left a tick.

  • Shift Left scrolls the display window left one tick worth of data. The net action is that the data scrolls right a tick.

  • Page Right scrolls the display window right one page worth of data. The net action is that the data scrolls left a page.

  • Page Left scrolls the display window left one page worth of data. The net action is that the data scrolls right a page.


    • Markers Menu
  • Show-Change Marker Data displays and allows the modification of the times for all 26 named markers. The time for each marker must be unique.

  • Drop Named Marker drops a named marker where the current primary (unnamed) marker is placed. A maximum of 26 named markers are allowed and the times for all must be different.

  • Collect Named Marker collects a named marker where the current primary (unnamed) marker is placed if there is a named marker at its position.

  • Collect All Named Markers simply collects any and all named markers which have been dropped.

  • Delete Primary Marker removes the primary marker from the display if present.
  • Wave Scrolling On allows movement of the primary marker beyond screen boundaries which causes the wave window to scroll.

  • Wave Scrolling Off disallows movement of the primary marker beyond screen boundaries.


    • View Menu
  • Show Grid enables the drawing of gridlines in the waveform display if they are turned off.

  • Hide Grid disables the drawing of gridlines in the waveform display if they are turned on.
  • Show Base Symbols enables the display of leading base symbols ('$' for hex, '%' for binary, '#' for octal if they are turned off. Base symbols are displayed by default.

  • Hide Base Symbols disables the drawing of leading base symbols if they are turned on.
  • Enable Dynamic Resize allows GTKWave to dynamically resize the signal window for you. This can be helpful during numerous signal additions and/or deletions. This is the default behavior.

  • Disable Dynamic Resize disallows GTKWave to dynamically resize the signal window for you.
  • Center Zooms configures zoom in/out operations such that all zooms use the center of the display as the fixed zoom origin if the primary (unnamed) marker is not present, otherwise, the primary marker is used as the center origin. (Center Zooms the default zoom behavior.)

  • Left Justified Zooms configures zoom in/out operations such that all zooms use the left margin of the display as the fixed zoom origin.
  • Toggle Max-Marker allows you to switch between the maximum time and marker time for display in the upper right corner of the main window. Default behavior is that the maximum time is displayed.
  • Enable Constant Marker Update- allows GTKWave to dynamically show the changing values of the traces under the primary marker while it is being dragged across the screen. This works best with dynamic resizing disabled.

  • Disable Constant Marker Update- restricts GTKWave to only update the trace values when the left mouse button is initially pressed then again when it is released. This is the default behavior.
  • Draw Flatcapped Vectors- draws vector transitions that have sharp edges. This is the default.

  • Draw Roundcapped Vectors- draws vector transitions that have sloping edges.
  • Left Justify Signals- draws signal names flushed to the left border of the signal window.

  • Right Justify Signals- draws signal names flushed to the right ("equals") side of the signal window.
  • Zoom Pow10 Snap- snaps time values to a power of ten boundary when active. Fractional zooms are internally stored, but what is actually displayed will be rounded up/down to the nearest power of 10. This only works when the ticks per frame is greater than 100 units.
  • Full Precision- does not round time values when the number of ticks per pixel onscreen is greater than 10 when active. The default is that this feature is disabled.


    • Help Menu

  • Wave Help is already active. It's this window. (To exit, simply hit the "Close Help" button at the bottom of the window.)

  • Wave Version merely brings up a requester which indicates the current version of this program.


    • Environment Customization

    Customizing your environment in gtkwave is quite easy with the .gtkwaverc file. The search path for the file is first the current working directory then the effective user's home directory. It is simply a series of variable definitions, one per line, which modify the behavior of specific features in GTKWave. A sample .gtkwaverc file that works well with modelsim may be found in the examples/vcd_mti directory. Note that you will probably want to edit the file so that the max_hier is 0 (infinite). The format for each line is:

    variable value

    ...where at least one space separates the case insensitive variable name from its value. (NOTE: multiple word variable names will have an underscore between words and you may substitute the case insensitive strings of ON and any Y prefixed word for the value of 1 [enable feature], and OFF and any N prefixed word for the value of 0 [disable feature].)

    Lines that start with # are considered comment lines and are ignored.

    Currently supported variables are listed in the table below...

    Environment Variables
  • anna_compatibility- A nonzero value indicates that the time value in an .aet format trace should be divided by ten in order to present the same display as anna (default). A zero value indicates that the time value should be taken literally.

  • append_vcd_hier- Allows the specification of a prefix hierarchy for VCD files. This can be done in "pieces," so that multiple layers of hierarchy are prepended to symbol names with the most significant addition occurring first (see .gtkwaverc in the examples/vcd directory). The intended use of this is to have the ability to add "project" prefixes which allow easier selection of everything from the tree hierarchy.

  • atomic_vectors- Speeds up vcd loading and takes up less memory. The downside is that atomic vectors are treated internally as a single bit and can't be coalesced into larger vectors or split up. Because of this single bit nature, the bundle down and bundle up operations when used in Signal Search Regexp, Signal Search Hierarchy, and Signal Search Tree will perfom seemingly unpredictably.

    Note that savefiles are largely incompatible between atomic and non-atomic modes (i.e., signal information is stored differently). This variable normally defaults to "on" and it is suggested that it remain there unless vector splitting is a necessity.

  • autocoalesce- A nonzero value enables autocoalescing of VCD vectors when applicable. This may be toggled dynamically during wave viewer usage.

  • autocoalesce_reversal causes split vectors to be reconstructed in reverse order (only if autocoalesce is also active).

  • autoname_bundles- A nonzero value indicates that GTKWave will create its own bundle names rather than prompting the user for them.

    Environment Variables for Color
    The colors available to the wave window graphics contexts are also adjustable by listing one of the following color variables trailed by at least one space then a six digit hex RGB number (e.g., color_back ffffff). Additionally, standard X11 color value strings can be used (e.g., color_back steel blue), but don't put them in quotation marks as spaces are handled properly:
  • color_back- background color

  • color_grid- grid color (use Alt-G/Shift-Alt-G to show/hide grid)

  • color_trans- trace color when transitioning

  • color_high- trace color when high

  • color_low- trace color when low

  • color_mid- trace color when floating ("Z")

  • color_x- trace color when undefined ("X")

  • color_xfill- trace color (inside of box) when undefined ("X")

  • color_vbox- vector color (horizontal)

  • color_vtrans- vector color (verticals/transitions)

  • color_value- text color for vector values

  • color_time- text color for timebar

  • color_timeb- text color for timebar's background

  • color_umark- color of the unnamed (primary) marker

  • color_mark- color of the named markers

    ...if the above variables are unspecified, the defaults (standard GTK color shadings) are used on a per-unspecified variable basis.

  • constant_marker_update- A nonzero value indicates that the values for traces listed in the signal window are to be updated constantly when the left mouse button is being held down rather than only when it is first pressed then when released (which is the default).

  • convert_to_reals- Converts all integer and parameter VCD declarations to real-valued ones when set to a nonzero/yes value. The positive aspect of this is that integers and parameters will take up less space in memory and will automatically display in decimal format. The negative aspect of this is that integers and parameters will only be displayable as decimals and can't be bit reversed, inverted, etc.

  • disable_tooltips- A nonzero value indicates that tooltip pop up bubbles should be disabled. A zero value indicates that tooltips should be active (default).

  • do_initial_zoom_fit- A nonzero value indicates that the trace should initially be crunched to fit the screen. A zero value indicates that the initial zoom should be zero (default).

  • dynamic_resizing- A nonzero value indicates that dynamic resizing should be initially enabled (default). A zero value indicates that dynamic resizing should be initially disabled.

  • enable_ghost_marker- lets the user turn on/off the ghost marker during primary marker dragging. Default is enabled.

  • enable_horiz_grid- A nonzero value indicates that when grid drawing is enabled, horizontal lines are to be drawn. This is the default.

  • enable_vcd_autosave- causes the vcd loader to automatically generate a .sav file (vcd_autosave.sav) in the cwd if a save file is not specified on the command line. Note that this mirrors the VCD $var defs and no attempt is made to coalesce split bitvectors back together.

  • enable_vert_grid- A nonzero value indicates that when grid drawing is enabled, vertical lines are to be drawn. This is the default. Note that all possible combinations of enable_horiz_grid and enable_vert_grid values are acceptable.

  • force_toolbars- When enabled, this forces everything above the signal and wave windows to be rendered as toolbars. This allows for them to be detached which allows for more usable wave viewer space. By default this is off.

  • hier_delimeter- This allows characters other than '/' to be used to delimit levels in the hierarchy. Only the first character in the value is significant.

  • hier_max_level- Sets the maximum hierarchy depth (from the right side) to display for trace names. Note that a value of zero displays the full hierarchy name.

  • hpane_pack- A nonzero value indicates that the horizontal pane should be constructed using the gtk_paned_pack functions (default and recommended). A zero value indicates that gtk_paned_add will be used instead.

  • initial_window_x- Sets the size of the initial width of the wave viewer window. Values less than or equal to zero will set the initial width equal to -1 which will let GTK determine the minimum size.

  • initial_window_y- Sets the size of the initial height of the wave viewer window. Values less than or equal to zero will set the initial width equal to -1 which will let GTK determine the minimum size.

  • left_justify_sigs- When nonzero, indicates that the signal window signal name justification should default to left, else the justification is to the right (default).

  • page_divisor- Sets the scroll amount for page left and right operations. (The buttons, not the hscrollbar.) Values over 1.0 are taken as 1/x and values equal to and less than 1.0 are taken literally. (i.e., 2 gives a half-page scroll and .67 gives 2/3). The default is 1.0.

  • ps_maxveclen- sets the maximum number of characters that can be printed for a value in the signal window portion of a postscript file (not including the net name itself). Legal values are 4 through 66 (default).

  • show_base_symbols- A nonzero value (default) indicates that the numeric base symbols for hexadecimal ('$'), binary ('%'), and octal ('#') should be rendered. Otherwise they will be omitted.

  • show_grid- A nonzero value (default) indicates that a grid should be drawn behind the traces. A zero indicates that no grid should be drawn.

  • use_aet- A nonzero value indicates that if a suffix match on .aet, .vcd, .dmp, and their gzipped counterparts is not encountered, default to using the aet loader.

  • use_big_fonts- A nonzero value indicates that any text rendered into the wave window will use fonts that are four points larger in size than normal. This can enhance readability. A zero value indicates that normal font sizes should be used.

  • use_full_precision- does not round time values when the number of ticks per pixel onscreen is greater than 10 when active. The default is that this feature is disabled.

  • use_larger_scale- A nonzero value indicates that the hashmarks used for the timescales should be based around 50 pixels rather than 40/48 pixels.

  • use_maxtime_display- A nonzero value indicates that the maximum time will be displayed in the upper right corner of the screen. Otherwise, the current primary (unnamed) marker time will be displayed. This can be toggled at any time with the Toggle Max-Marker menu option.

  • use_nonprop_fonts- Allows accelerated redraws of the signalwindow that can be done because the font width is constant. Default is off.

  • use_roundcaps- A nonzero value indicates that vector traces should be drawn with rounded caps rather than perpendicular ones. The default for this is zero.

  • use_scrollbar_only- A nonzero value indicates that the page, shift, fetch, and discard buttons should not be drawn (i.e., time manipulations should be through the scrollbar only rather than front panel buttons). The default for this is zero.

  • use_vcd- A nonzero value indicates that if a suffix match on .aet, .vcd, .dmp, and their gzipped counterparts is not encountered, default to using the VCD loader if use_aet is not selected. Note that if both use_aet and use_vcd are both set to zero, VCD is used by default.

  • vcd_explicit_zero_subscripts- indicates that signal names should be stored internally as name.bitnumber when enabled. When disabled, a more "normal" ordering of name[bitnumber] is used. Note that when disabled, the Bundle Up and Bundle Down options are disabled in the Signal Search Regexp, Signal Search Hierarchy, and Signal Search Tree options. This is necessary as the internal data structures for signals are represented with one "less" level of hierarchy than when enabled and those functions would not work properly. This should not be an issue if atomic_vectors are enabled. Default for vcd_explicit_zero_subscripts is disabled.

  • vector_padding- indicates the number of pixels of extra whitespace that should be added to any strings for the purpose of calculating text in vectors. Permissible values are 0 to 16 with the default being 4.

  • wave_scrolling- a nonzero value enables scrolling by dragging the marker off the left or right sides of the wave window. A zero value disables it.

  • zoom_base- allows setting of the zoom base with a value between 1.5 and 10.0. Default is 2.0.

  • zoom_center- a nonzero value enables center zooming, a zero value disables it.

  • zoom_pow10_snap- corresponds to the Zoom Pow10 Snap menu option listed above. Default for this is disabled (zero).

    • Even more customization is planned on being added incrementally and new features will be available in the future.


    Known Bugs

    AIX requires -bmaxdata:0x80000000 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. 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. I have a trace that goes out to 45 billion ticks that causes problems. 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.

    Caveat Architecture: GTKWave works fine under the x86 version of Linux using glibc, however it is not guaranteed that it will work properly with all microprocessor architectures, libc variants, or operating systems as it is only regularly tested on RedHat Intel and AIX for the PowerPC. Every attempt has been made to write portable bug-free code, but compatibility issues occasionally manifest themselves on one architecture but not another due to issues such as varying machine word lengths, virtual memory page sizes, and memory allocation algorithms. Crashes that occur on a specific operating system but not another given the same sequence of operations should be considered reportable bugs.


    20jul00 bybell@daggit.pagecreator.com / bybell@xxedgexx.com