Welcome to GTKWave

Future development and maintenance of GTKWave is now continuing at the AMULET Group . This has been a very fun and rewarding project, but due to purported conflicts of interest at work and other reasons, the time to pass on the torch has arrived. This is the last official release in the 1.3.x series and will be the last release in which I am the maintainer. Thanks for all the constructive feedback from everyone since the initial release in 1998. With that being said, the information and source/binaries available on this page exist solely for historical reasons.

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 LXT 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 real valued single-bit traces. When used upon multi-bit vectors that contain 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 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 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. ASCII will step through all highlighted traces and ensure that vectors with this qualifier will be displayed with ASCII 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. Time Warp Submenu Warp Marked offsets all highlighted traces by the amount of time entered in the requester. (Positive values will shift traces to the right.) Note that warp operations to not persist after a combine operation. Attempting to shift greater than the absolute value of total simulation time will cap the shift magnitude at the length of simulation. Unwarp Marked removes all offsets on all highlighted traces. Unwarp All unconditionally removes all offsets on all traces. 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. Sort Submenu Alphabetize All alphabetizes all displayed traces. Blank traces are sorted to the bottom. Alphabetize All (CaseIns) alphabetizes all displayed traces without regard to case. Blank traces are sorted to the bottom. Sigsort All sorts all displayed traces with the numeric parts being taken into account. Blank traces are sorted to the bottom. Reverse All reverses all displayed traces unconditionally.

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. "Mark" and "Clear" are used to modify the normal time vertical markings such that they can be used to indicate all the times that a specific pattern search condition is true (e.g., every upclock of a specific signal). 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. [Recently this function has been kneecapped such that it will return a maximum of 10000 hits. This is because the performance of gtkclists degrade significantly past lists of that size.] 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 trace to be displayed if the "From" and "To" times do not match the actual bounds of the trace. Fetch Left decreases the "From" time, which allows more of the trace to be displayed if the "From" and "To" times do not match the actual bounds of the trace. Discard Right decreases the "To" time, which allows less of the trace to be displayed. Discard Left increases the "From" time, which allows less of the trace 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. Remove Pattern Marks removes any vertical traces on the display caused by the Mark feature in pattern search and reverts to the normal format.

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.

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...

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

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.