GTKWave

https://gtkwave.github.io/gtkwave/
Admin
GTKWave is a fully featured wave viewer for analyzing and debugging Verilog and VHDL simulation...
Tokens:39,207
Snippets:553
Trust Score:9.7
Update:6 months ago
Show doc for...
Tokens:
Raw
### List example directory contents

Source: https://gtkwave.github.io/gtkwave/quickstart/sample.html

Displays the files available in the examples directory of the source distribution.

```bash
$ cd examples
$ ls -al
total 132
drwxrwxr-x 2 bybell bybell  4096 Apr 30 14:12 .
drwxr-xr-x 8 bybell bybell  4096 Apr 29 22:05 ..
-rw-rw-r-- 1 bybell bybell   187 Apr 29 22:09 des.sav
-rw-r--r-- 1 bybell bybell 47995 Apr 29 22:05 des.v
-rw-rw-r-- 1 bybell bybell 68801 Apr 29 22:06 des.vzt
```

--------------------------------

### Compile and Install

Source: https://gtkwave.github.io/gtkwave/install/unix_linux.html

Commands to compile the source code and install the resulting binaries to the system.

```bash
make -j
```

```bash
sudo make install
```

--------------------------------

### Install GTKWave

Source: https://gtkwave.github.io/gtkwave/install/unix_linux_4.html

Installs the compiled GTKWave application onto the system using Meson with superuser privileges.

```bash
sudo meson install -C build

```

--------------------------------

### Get command line arguments

Source: https://gtkwave.github.io/gtkwave/tcl/commands.html

Returns a list of arguments used to start GTKWave.

```tcl
set argvs [ gtkwave::getArgv ]
puts "$argvs"
```

--------------------------------

### Install GTKWave Dependencies with Homebrew

Source: https://gtkwave.github.io/gtkwave/install/mac.html

Installs necessary libraries and tools for GTKWave using Homebrew. Ensure Homebrew is installed first.

```bash
brew install desktop-file-utils shared-mime-info gobject-introspection gtk-mac-integration meson ninja pkg-config gtk+3 gtk4 json-glib

```

--------------------------------

### Install GTKWave Dependencies on Debian/Ubuntu

Source: https://gtkwave.github.io/gtkwave/install/unix_linux_4.html

Installs essential build tools and development libraries for GTKWave on Debian-based systems using apt.

```bash
sudo apt install \
    build-essential \
    git \
    meson \
    gperf \
    flex \
    desktop-file-utils \
    libbz2-dev \
    libgtk-3-dev \
    libgtk-4-dev \
    libgirepository1.0-dev \
    libjson-glib-dev

```

--------------------------------

### Run GTKWave

Source: https://gtkwave.github.io/gtkwave/install/mac.html

Launches the GTKWave application from the terminal after installation.

```bash
gtkwave

```

--------------------------------

### Install File Filter

Source: https://gtkwave.github.io/gtkwave/tcl/commands.html

Installs a file filter for highlighted traces. Use `which = 0` to remove the filter. Returns the number of traces updated.

```tcl
set num_updated [ gtkwave::installFileFilter 0 ]
puts "$num_updated"
```

--------------------------------

### Install Process Filter

Source: https://gtkwave.github.io/gtkwave/tcl/commands.html

Installs a process filter for highlighted traces. Use `which = 0` to remove the filter. Returns the number of traces updated.

```tcl
set num_updated [ gtkwave::installProcFilter 0 ]
puts "$num_updated"
```

--------------------------------

### Install GTKWave Dependencies on Fedora

Source: https://gtkwave.github.io/gtkwave/install/unix_linux_4.html

Installs necessary build tools and development libraries for GTKWave on Fedora systems using dnf.

```bash
sudo dnf install \
    gcc \
    gcc-c++ \
    tcl \
    meson \
    gperf \
    flex \
    desktop-file-utils \
    glib2-devel \
    gtk3-devel \
    gtk4-devel \
    gobject-introspection-devel \
    json-glib-devel

```

--------------------------------

### Install GTKWave via Package Manager

Source: https://gtkwave.github.io/gtkwave/install/unix_linux.html

Commands to install GTKWave on various Linux distributions using native package managers or Flatpak.

```bash
sudo apt install gtkwave # for Debian, Ubuntu
# Or
sudo pacman -Syu gtkwave # for Arch, Manjaro
# Or install using flatpak for any distro
flatpak install flathub io.github.gtkwave.GTKWave
```

--------------------------------

### Example Usage of lxt2miner

Source: https://gtkwave.github.io/gtkwave/man/lxt2miner.1.html

This example demonstrates how to match a hexadecimal value and print only the facility name to stdout, generating a gtkwave-compatible save file.

```bash
lxt2miner dumpfile.lxt2 –hex 20470000 -n
```

--------------------------------

### Install Transaction Filter

Source: https://gtkwave.github.io/gtkwave/tcl/commands.html

Installs a transaction filter for highlighted traces. Use `which = 0` to remove the filter. Returns the number of traces updated.

```tcl
set num_updated [ gtkwave::installTransFilter 0 ]
puts "$num_updated"
```

--------------------------------

### Install Cygwin build dependencies

Source: https://gtkwave.github.io/gtkwave/install/win.html

Commands to install required packages for GTKWave compilation within the Cygwin environment.

```bash
.\setup-x86_64.exe -q -P gcc-g++,gperf,libbz2-devel
.\setup-x86_64.exe -q -P liblzma-devel,zlib-devel,libgtk3-devel
.\setup-x86_64.exe -q -P make,git,xinit,tcl-tk-devel
```

--------------------------------

### Install Homebrew Package Manager

Source: https://gtkwave.github.io/gtkwave/install/mac.html

Installs Homebrew, a package manager for macOS, if not already installed. This script should be run in the Terminal.

```bash
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

```

--------------------------------

### Configure Build Options

Source: https://gtkwave.github.io/gtkwave/install/unix_linux.html

Configure the build process with specific installation prefixes or default settings.

```bash
./configure --enable-gtk3 --enable-judy --prefix=/opt
```

```bash
./configure --enable-gtk3 --enable-judy
```

--------------------------------

### Configure GTKWave Build Globally

Source: https://gtkwave.github.io/gtkwave/install/unix_linux_4.html

Sets up the build environment using Meson for a default global installation.

```bash
meson setup build

```

--------------------------------

### Multi-bit Encoding Example

Source: https://gtkwave.github.io/gtkwave/internals/vcd-recoding.html

Example of time-delta and value changes for multi-bit signals.

```text
#1000 val = 1010 index = n
#1001 n + 1
#1010 n + 2
#1013 n + 3
#1100 val = 1zz0 n + 4
```

--------------------------------

### Get Window Start Time

Source: https://gtkwave.github.io/gtkwave/tcl/commands.html

Retrieves the start time currently displayed in the waveform window. This is the leftmost time boundary of the visible waveform.

```tcl
set wst [ gtkwave::getWindowStartTime ]
puts "$wst"
```

--------------------------------

### Install MSYS2 build dependencies

Source: https://gtkwave.github.io/gtkwave/install/win.html

Commands to update the system and install necessary build tools and libraries for GTKWave in the MSYS2 MINGW64 shell.

```bash
pacman -Syuu
pacman -Syuu  # Please run this twice as recommended.
# Or mingw-w64-ucrt-x86_64 for UCRT64
pacman -S mingw-w64-x86_64-gcc base-devel mingw-w64-x86_64-tk
pacman -S mingw-w64-x86_64-gtk3 mingw-w64-x86_64-gperf git
```

--------------------------------

### Configure GTKWave Build with Custom Prefix

Source: https://gtkwave.github.io/gtkwave/install/unix_linux_4.html

Sets up the build environment using Meson, specifying a custom installation prefix (e.g., /opt).

```bash
meson setup build --prefix=/opt

```

--------------------------------

### LXT2 Delta Calculation Example

Source: https://gtkwave.github.io/gtkwave/internals/lxt-file-format.html

Example demonstrating the calculation of rle_delta values for clock compression based on a sequence of values. This shows how deltas are derived from consecutive changes.

```text
base = 82
rle_delta[1] = 82 - 81 == 01
rle_delta[0] = 81 - 80 == 01

```

--------------------------------

### Configure and Compile GTKWave with Meson

Source: https://gtkwave.github.io/gtkwave/install/mac.html

Sets up the build environment using Meson and compiles GTKWave. Use --prefix to specify an installation path, or omit for the default path.

```bash
# Use --prefix to specify the installation path
meson setup build --prefix=/opt
# Or install to default path (/usr/local):
# meson setup build
meson compile -C build # Start compile
sudo meson install -C build # Install gtkwave

```

--------------------------------

### getArgv

Source: https://gtkwave.github.io/gtkwave/tcl/commands.html

Retrieves the list of arguments used to start GTKWave from the command line.

```APIDOC
## gtkwave::getArgv

### Description
Returns a list of arguments which were used to start gtkwave from the command line.

### Syntax
`set argvlist [ gtkwave::getArgv ]`

### Request Example
```tcl
set argvs [ gtkwave::getArgv ]
puts "$argvs"
```

### Response
* **argvlist** (list) - A Tcl list of command-line arguments.
```

--------------------------------

### Install Build Dependencies

Source: https://gtkwave.github.io/gtkwave/install/unix_linux.html

Required packages for compiling GTKWave on Debian and Ubuntu systems.

```bash
sudo apt install build-essential libbz2-dev liblzma-dev
sudo apt install gperf libgtk-3-dev automake
sudo apt install tcl-dev tk-dev
sudo apt install libjudy-dev # optional
```

--------------------------------

### GTKWave External Process Filter Example (C)

Source: https://gtkwave.github.io/gtkwave/quickstart/filters.html

A C code example demonstrating how to interface with an external process filter in GTKWave. It reads hexadecimal values from stdin, disassembles them, and prints the result to stdout. Ensure `fflush(stdout)` is used and every input line generates an output line to prevent hangs.

```c
int main(int argc, char **argv)
{
    char buf[1025], buf2[1025];
    while (!feof(stdin)) {
        buf[0] = 0;
        fscanf(stdin, "%s", buf);
        if (buf[0]) {
            int hx;
            sscanf(buf, "%x", &hx);
            rv32_dasm_one(buf2, 0, hx);
            printf("%s\n", buf2);
            fflush(stdout);
        }
     }
    return 0;
}


```

--------------------------------

### Run GTKWave from OSX app bundle

Source: https://gtkwave.github.io/gtkwave/man/gtkwave.1.html

This example shows how to run GTKWave from an OSX .app bundle by setting the GTKWAVE_CHDIR environment variable and using the open command. The --chdir argument is used with a dummy value to handle potential spaces in paths.

```bash
GTKWAVE_CHDIR=`pwd`;export GTKWAVE_CHDIR;open -n -W -a gtkwave --args --chdir dummy --dump des.vzt --save des.gtkw
```

--------------------------------

### Install Xcode Command Line Tools

Source: https://gtkwave.github.io/gtkwave/install/mac.html

Required for building software on macOS. Run this command in the Terminal.

```bash
xcode-select --install

```

--------------------------------

### setWindowStartTime API

Source: https://gtkwave.github.io/gtkwave/tcl/commands.html

Scrolls the traces so that the specified start time is at the left margin, if the zoom level permits.

```APIDOC
## `gtkwave::setWindowStartTime`

### Description
Scrolls the traces such that the start time is at the left margin (as long as the zoom level permits this).

### Syntax
`gtkwave::setWindowStartTime start_time`

### Parameters
#### Path Parameters
- **start_time** (integer) - Required - The time to set as the start of the visible window.

### Request Example
```tcl
gtkwave::setWindowStartTime 100
```
```

--------------------------------

### fstminer Example: Match Hex Value and Print Facname

Source: https://gtkwave.github.io/gtkwave/man/fstminer.1.html

This example demonstrates how to use fstminer to match a specific hexadecimal value within an FST file and print only the facname to stdout. This output can be used to generate a gtkwave compatible save file for importing specific traces.

```bash
fstminer dumpfile.fst –hex 20470000 -n
```

--------------------------------

### LXT File Structure Example

Source: https://gtkwave.github.io/gtkwave/internals/lxt-file-format.html

Visual representation of the byte sequence in an LXT file, showing the header, body, and trailer.

```text
01 38 00 01* ...file body... *B4
```

--------------------------------

### Build macOS Application Bundle

Source: https://gtkwave.github.io/gtkwave/install/mac.html

Builds a macOS application bundle for GTKWave. Ensure all dependencies are installed before running this script.

```bash
./macos/build.sh

```

--------------------------------

### Retrieve Stems Filename

Source: https://gtkwave.github.io/gtkwave/tcl/commands.html

Gets the name of the current stems file.

```Tcl
set stemsname [ gtkwave::getStemsFileName ]
puts "$stemsname"
```

--------------------------------

### Convert VCD to LXT with Clock Packing and Zlib Compression

Source: https://gtkwave.github.io/gtkwave/man/vcd2lxt.1.html

This example demonstrates converting a VCD file to an LXT file using clock packing, zlib compression, and dictionary encoding. It's useful for reducing dumpfile size and improving access speed.

```bash
vcd2lxt dumpfile.vcd dumpfile.lxt -clockpack -chgpack -dictpack 18
```

--------------------------------

### Get displayed signals

Source: https://gtkwave.github.io/gtkwave/tcl/commands.html

Returns a list of all signals currently on display.

```tcl
set display_list [ gtkwave::getDisplayedSignals ]
puts "$display_list"
```

--------------------------------

### Signal and Filter Management

Source: https://gtkwave.github.io/gtkwave/tcl/commands.html

Functions for highlighting signals and installing various types of filters.

```APIDOC
## POST /api/signals/highlight

### Description
Highlights the signals (facilities) contained in the provided list.

### Method
POST

### Endpoint
`/api/signals/highlight`

### Parameters
#### Request Body
- **list** (array of strings) - Required - A list of signal names to highlight.

### Response
#### Success Response (200)
- **num_highlighted** (integer) - The number of signals successfully highlighted.

### Response Example
```json
{
  "num_highlighted": 2
}
```
```

```APIDOC
## POST /api/filters/file

### Description
Installs a file filter for the highlighted traces. Using 0 for `which` removes the filter.

### Method
POST

### Endpoint
`/api/filters/file`

### Parameters
#### Request Body
- **which** (integer) - Required - The file filter number to install. Use 0 to remove the filter.

### Response
#### Success Response (200)
- **num_updated** (integer) - The number of traces updated with the new filter.

### Response Example
```json
{
  "num_updated": 15
}
```
```

```APIDOC
## POST /api/filters/process

### Description
Installs a process filter for the highlighted traces. Using 0 for `which` removes the filter.

### Method
POST

### Endpoint
`/api/filters/process`

### Parameters
#### Request Body
- **which** (integer) - Required - The process filter number to install. Use 0 to remove the filter.

### Response
#### Success Response (200)
- **num_updated** (integer) - The number of traces updated with the new filter.

### Response Example
```json
{
  "num_updated": 15
}
```
```

```APIDOC
## POST /api/filters/transaction

### Description
Installs a transaction filter for the highlighted traces. Using 0 for `which` removes the filter.

### Method
POST

### Endpoint
`/api/filters/transaction`

### Parameters
#### Request Body
- **which** (integer) - Required - The transaction filter number to install. Use 0 to remove the filter.

### Response
#### Success Response (200)
- **num_updated** (integer) - The number of traces updated with the new filter.

### Response Example
```json
{
  "num_updated": 15
}
```
```

--------------------------------

### fstminer CLI Usage

Source: https://gtkwave.github.io/gtkwave/man/fstminer.1.html

Documentation for the fstminer command-line interface, including options and usage examples.

```APIDOC
## fstminer

### Description
Mines FST files for specific data values and generates gtkwave save files to stdout for future reload.

### Syntax
fstminer [option]... [FSTFILE]

### Options
- **-d, --dumpfile** <filename> - Specify FST input dumpfile.
- **-m, --match** <value> - Specifies “bitwise” match data (binary, real, string).
- **-x, --hex** <value> - Specifies hexadecimal match data that will automatically be converted to binary for searches.
- **-n, --namesonly** - Indicates that only facnames should be printed in a gtkwave savefile compatible format.
- **-c, --comprehensive** - Indicates that results are not to stop after the first match.
- **-h, --help** - Show help screen.

### Request Example
fstminer dumpfile.fst --hex 20470000 -n
```

--------------------------------

### Start TwinWave Session

Source: https://gtkwave.github.io/gtkwave/tools/twinwave.html

Invoke twinwave with arguments for each gtkwave session, separated by a plus sign. This allows two sessions to be open at once in a single window.

```bash
twinwave a.vcd a.gtkw + b.vcd b.gtkw
```

--------------------------------

### Retrieve From Entry Time

Source: https://gtkwave.github.io/gtkwave/tcl/commands.html

Gets the time value string currently set in the 'From:' box.

```Tcl
set from_entry [ gtkwave::getFromEntry ]
puts "$from_entry"
```

--------------------------------

### Clone and Prepare Source

Source: https://gtkwave.github.io/gtkwave/install/unix_linux.html

Commands to retrieve the GTKWave source code and initialize the build environment.

```bash
git clone https://github.com/gtkwave/gtkwave/ -b lts gtkwave
cd gtkwave/gtkwave3-gtk3 && ./autogen.sh
```

--------------------------------

### Convert VCD to LXT in Linear Mode with Dictionary Encoding

Source: https://gtkwave.github.io/gtkwave/man/vcd2lxt.1.html

This example shows how to convert a VCD file to an LXT file using linear mode for smaller file sizes, combined with dictionary encoding. This is an alternative to the default interlaced format.

```bash
vcd2lxt dumpfile.vcd dumpfile.lxt -clockpack -linear -dictpack 18
```

--------------------------------

### GTKWave Process Filter with X11 Color Prefixes

Source: https://gtkwave.github.io/gtkwave/quickstart/filters.html

Example of using X11 color names prefixed with '?' to modify trace background colors when using process filters in GTKWave.

```plaintext
?CadetBlue?isync
?red?xor r0,r0,r0
?lavender?lwz r2,0(r7)


```

--------------------------------

### Facility Name Section Example

Source: https://gtkwave.github.io/gtkwave/internals/lxt-file-format.html

Illustrates the structure of the LT_SECTION_FACNAME, showing how facility names are stored with prefix lengths and zero-terminated suffix strings. This section defines the names of facilities and their memory requirements.

```text
00000020: _00 00 00 04_ _00 00 00 1d_ **00 00** 61 6c 70 68 61 00 ..........alpha.
00000030: **00 01** 70 70 6c 65 00 **00 04** 69 63 61 74 69 6f 6e ..pple...ication
00000040: 00 **00 00** 7a 65 72 6f 00 00 00 00 01 00 00 00 00 ...zero.........
```

--------------------------------

### Real and String Encoding Example

Source: https://gtkwave.github.io/gtkwave/internals/vcd-recoding.html

Byte-level representation of a real value (4, “3.14159”) using delta and null-terminated ASCII.

```text
0x84 [variable length integer for delta of 4]
0x33 0x2e 0x31 0x34 0x31 0x35 0x39 0x00 ["3.14159" with null
termination]
```

--------------------------------

### VCD Input Format for Transaction Filters

Source: https://gtkwave.github.io/gtkwave/quickstart/filters.html

Example of the simplified VCD file format sent to the external process via stdin, including custom comments for metadata.

```vcd
$comment data_start 0x124c0798 $end
$comment name val[7:0] $end
$timescale 1ms $end
$comment min_time 0 $end
$comment max_time 348927 $end
$comment max_seqn 1 $end
$comment args "0" $end
$scope module top $end
$comment seqn 1 top.val[7:0] $end
$var wire 8 1 val[7:0] $end
$upscope $end
$enddefinitions $end
#0
$dumpvars
b10000000 1
$end
#1
b10000101 1
#2
b10001010 1
...
#348927
b110010 1
$comment data_end 0x124c0798 $end
```

--------------------------------

### Initialize LXT Trace

Source: https://gtkwave.github.io/gtkwave/internals/lxt-file-format.html

Opens an LXT file and returns a context pointer for subsequent API calls.

```c
struct lt_trace *lt_init(const char *name)
```

--------------------------------

### Run GTKWave with a dumpfile

Source: https://gtkwave.github.io/gtkwave/man/gtkwave.1.html

The standard way to run GTKWave is by providing the dumpfile as an argument.

```bash
gtkwave dumpfile.vcd
```

--------------------------------

### Display help and exit

Source: https://gtkwave.github.io/gtkwave/man/gtkwave.1.html

The --help option displays the GTKWave help message and then exits.

```bash
gtkwave --help
```

--------------------------------

### Retrieve Save Filename

Source: https://gtkwave.github.io/gtkwave/tcl/commands.html

Gets the name of the current save file.

```Tcl
set savename [ gtkwave::getSaveFileName ]
puts "$savename"
```

--------------------------------

### Run GTKWave with dumpfile and save file

Source: https://gtkwave.github.io/gtkwave/man/gtkwave.1.html

You can specify both the dumpfile and a save file to load GTKWave with previous session settings.

```bash
gtkwave dumpfile.vcd dumpfile.gtkw
```

--------------------------------

### Retrieve Total Traces

Source: https://gtkwave.github.io/gtkwave/tcl/commands.html

Gets the total number of traces currently displayed.

```Tcl
set totnum [ gtkwave::getTotalNumTraces ]
puts "$totnum"
```

--------------------------------

### Open GTKWave with Stems File and FST

Source: https://gtkwave.github.io/gtkwave/man/xml2stems.1.html

Launches GTKWave, loading the generated stems file ('des.stems') and the simulation results file ('des.fst'). This enables source code annotation.

```bash
gtkwave -t des.stems des.fst
```

--------------------------------

### Retrieve Number of Tabs

Source: https://gtkwave.github.io/gtkwave/tcl/commands.html

Gets the number of tabs currently displayed in the viewer.

```Tcl
set ntabs [ gtkwave::getNumTabs ]
puts "number of tabs: $ntabs"
```

--------------------------------

### Retrieve Min Time

Source: https://gtkwave.github.io/gtkwave/tcl/commands.html

Gets the numeric value of the first time in the dumpfile.

```Tcl
set min_time [ gtkwave::getMinTime ]
puts "$min_time"
```

--------------------------------

### Retrieve Max Time

Source: https://gtkwave.github.io/gtkwave/tcl/commands.html

Gets the numeric value of the final time in the dumpfile.

```Tcl
set max_time [ gtkwave::getMaxTime ]
puts "$max_time"
```

--------------------------------

### GTKWave CLI Options

Source: https://gtkwave.github.io/gtkwave/man/gtkwave.1.html

A comprehensive list of command line flags for configuring GTKWave behavior.

```APIDOC
## GTKWave Command Line Interface

### Description
Configure GTKWave startup behavior, file loading, and environment settings using command line flags.

### Parameters
- **-n, --nocli** (directory name) - Optional - Use file selection dialog for dumpfile or savefile.
- **-f, --dump** (filename) - Optional - Specify dumpfile name.
- **-F, --fastload** (flag) - Optional - Generate/use VCD recoder fastload files for faster reloads.
- **-o, --optimize** (flag) - Optional - Optimize VCD to FST format using vcd2fst.
- **-a, --save** (filename) - Optional - Specify savefile name (.gtkw).
- **-A, --autosavename** (flag) - Optional - Assume savefile is suffix modified dumpfile name.
- **-r, --rcfile** (filename) - Optional - Specify override .gtkwaverc filename.
- **-l, --logfile** (filename) - Optional - Specify simulation logfile name.
- **-d, --defaultskip** (flag) - Optional - Disable implicit configuration file usage.
- **-D, --dualid** (which) - Optional - Specify multisession identifier (m+nnnnnnnn).
- **-s, --start** (time) - Optional - Specify start time for LXT2/VZT block skip.
- **-e, --end** (time) - Optional - Specify end time for LXT2/VZT block skip.
- **-t, --stems** (filename) - Optional - Specify stems file for source code annotation.
- **-c, --cpu** (numcpus) - Optional - Specify number of CPUs for parallelizable ops.
- **-N, --nowm** (flag) - Optional - Disable window manager for most windows.
- **-M, --nomenus** (flag) - Optional - Do not render menubar.
- **-S, --script** (filename) - Optional - Specify Tcl command script file for execution.
- **-T, --tcl_init** (filename) - Optional - Specify Tcl command script to be loaded on startup.
- **-W, --wish** (flag) - Optional - Enable Tcl command line on stdio.
- **-R, --repscript** (filename) - Optional - Specify Tcl command script for periodic execution.
- **-P, --repperiod** (value) - Optional - Delay in milliseconds between periodic script executions.
- **-X, --xid** (XID) - Optional - Specify XID of window for GtkPlug connection.
- **-1, --rpcid** (RPCID) - Optional - Specify RPCID of GConf/GSettings session.
- **-2, --chdir** (DIRNAME) - Optional - Change working directory.
```

--------------------------------

### Get facility direction

Source: https://gtkwave.github.io/gtkwave/tcl/commands.html

Returns the direction string for a given facility number.

```tcl
set nfacs [ gtkwave::getNumFacs ]
for {set i 0} {$i < $nfacs } {incr i} {
    set facdir [ gtkwave::getFacDir $i ]
    puts "$i: $facdir"
}
```

--------------------------------

### Display version and exit

Source: https://gtkwave.github.io/gtkwave/man/gtkwave.1.html

The --version option displays the GTKWave version banner and then exits.

```bash
gtkwave --version
```

--------------------------------

### Set Translation Process

Source: https://gtkwave.github.io/gtkwave/tcl/commands.html

Sets the executable for translation and returns the identifier for filter installation.

```tcl
set which_f [ gtkwave::setCurrentTranslateProc ./zzz.exe ]
puts "$which_f"
```

--------------------------------

### Present Window

Source: https://gtkwave.github.io/gtkwave/tcl/commands.html

Brings the main GTKWave window to the front of the stacking order or deiconifies it if it was minimized. Ensures the GUI is visible.

```tcl
gtkwave::presentWindow
```

--------------------------------

### Retrieve Trace Flags by Name

Source: https://gtkwave.github.io/gtkwave/tcl/commands.html

Gets the decimal sum of flags for a trace by its name.

```Tcl
set tflags [ gtkwave::getTraceFlagsFromName {top.des.k1x[1:48]} ]
puts "$tflags"
```

--------------------------------

### Launch GTKWave with VCD and Save Files

Source: https://gtkwave.github.io/gtkwave/quickstart/launching.html

Launches GTKWave with options to automatically convert VCD files and load a GTKWave save file. The `-o` option is for VCD conversion, and `-t` specifies the stems file.

```bash
$ gtkwave -o -t des.stems des.vcd des.gtkw
GTKWave Analyzer v3.3.118 (w)1999-2023 BSI
FSTLOAD | Processing 1432 facs.
FSTLOAD | Built 1287 signals and 145 aliases.
FSTLOAD | Building facility hierarchy tree.
FSTLOAD | Sorting facility hierarchy tree.


```

--------------------------------

### Retrieve Primary Marker Position

Source: https://gtkwave.github.io/gtkwave/tcl/commands.html

Gets the numeric time value of the primary marker.

```Tcl
set marker_time [ gtkwave::getMarker ]
puts "$marker_time"
```

--------------------------------

### Retrieve Max Hierarchy Level

Source: https://gtkwave.github.io/gtkwave/tcl/commands.html

Gets the maximum hierarchy level configured in the viewer.

```Tcl
set max_level [ gtkwave::getHierMaxLevel ]
puts "$max_level"
```

--------------------------------

### GTKWave Configuration Parameters

Source: https://gtkwave.github.io/gtkwave/man/gtkwaverc.5.html

A collection of configuration settings for the GTKWave application.

```APIDOC
## Configuration Parameters

### Description
These parameters control the behavior and appearance of the GTKWave interface.

### Parameters
- **ruler_origin** (value) - Sets the zero origin for alternate time tick marks.
- **ruler_step** (value) - Sets the left/right step value for alternate time tick marks. Zero disables them.
- **scale_to_time_dimension** (value) - Sets time dimension conversion (m, u, n, f, p, s). Default is * (disabled).
- **show_base_symbols** (value) - Nonzero enables numeric base symbols ($, %, #). Default is nonzero.
- **show_grid** (value) - Nonzero draws a grid behind traces. Default is nonzero.
- **splash_disable** (value) - Nonzero disables the splash screen. Default is on (splash enabled).
- **sst_dbl_action_type** (value) - Sets double-click action in SST pane (insert, replace, append, prepend, none). Default is insert.
- **sst_dynamic_filter** (value) - True enables real-time filtering in SST dialog. Default is true.
- **sst_expanded** (value) - True allows SST dialog to start expanded. Default is true.
- **strace_repeat_count** (value) - Sets iteration count for edge and pattern searches.
- **use_big_fonts** (value) - Nonzero increases font size by four points in the wave window.
- **use_fat_lines** (value) - Nonzero sets line width to two pixels.
- **use_frequency_delta** (value) - Nonzero switches to frequency display instead of delta time. Default is off.
- **use_gestures** (value) - Enables touch gestures (on, off, maybe). Default is maybe.
- **use_full_precision** (value) - Nonzero disables rounding of time values. Default is disabled.
- **use_maxtime_display** (value) - Nonzero displays maximum time in the corner. Default is off.
- **use_nonprop_fonts** (value) - Nonzero enables accelerated redraws using constant width fonts. Default is off.
- **use_pango_fonts** (value) - Nonzero uses anti-aliased pango fonts. Default is on.
- **use_roundcaps** (value) - Nonzero uses rounded caps for vector traces. Default is zero.
- **use_scrollbar_only** (value) - Nonzero hides front panel buttons. Default is zero.
- **use_scrollwheel_as_y** (value) - Nonzero maps scroll wheel to vertical signal scrolling. Default is zero.
- **use_standard_trace_select** (value) - Nonzero prevents deselection on mouse click. Default is disabled.
```

--------------------------------

### Retrieve Font Height

Source: https://gtkwave.github.io/gtkwave/tcl/commands.html

Gets the current font height used for signal names.

```Tcl
set font_height [ gtkwave::getFontHeight ]
puts "$font_height"
```

--------------------------------

### Get facility name

Source: https://gtkwave.github.io/gtkwave/tcl/commands.html

Returns the facility name corresponding to a given facility number.

```tcl
set nfacs [ gtkwave::getNumFacs ]
for {set i 0} {$i < $nfacs } {incr i} {
    set facname [ gtkwave::getFacName $i ]
    puts "$i: $facname"
}
```

--------------------------------

### Launch X session in Cygwin

Source: https://gtkwave.github.io/gtkwave/install/win.html

Initiates an X session required to run the GTKWave graphical interface in Cygwin.

```bash
startxwin
```

--------------------------------

### Get baseline marker time

Source: https://gtkwave.github.io/gtkwave/tcl/commands.html

Returns the numeric value of the baseline marker time.

```tcl
set baseline [ gtkwave::getBaselineMarker ]
puts "$baseline"
```

--------------------------------

### Compile Verilog and Generate XML

Source: https://gtkwave.github.io/gtkwave/man/xml2stems.1.html

Compiles Verilog source files and generates an XML AST. Use -Wno-fatal to suppress fatal errors and --bbox-sys for system bounding box.

```bash
verilator -Wno-fatal des.v -xml-only –bbox-sys
```

--------------------------------

### Retrieve Trace Flags by Index

Source: https://gtkwave.github.io/gtkwave/tcl/commands.html

Gets the decimal sum of flags for a trace at a specific index.

```Tcl
set tflags [ gtkwave::getTraceFlagsFromIndex 0 ]
puts "$tflags"
```

--------------------------------

### Retrieve To Entry Time

Source: https://gtkwave.github.io/gtkwave/tcl/commands.html

Gets the time value string currently set in the 'To:' box.

```Tcl
set to_entry [ gtkwave::getFromEntry ]
puts "$to_entry"
```

--------------------------------

### Use gigabyte mempacking

Source: https://gtkwave.github.io/gtkwave/man/gtkwave.1.html

The --giga option enables gigabyte mempacking when recoding, which may be slower. This is equivalent to setting vlist_spill and vlist_prepack flags in the rc file.

```bash
gtkwave --giga
```

--------------------------------

### Retrieve Time Zero

Source: https://gtkwave.github.io/gtkwave/tcl/commands.html

Gets the numeric value representing time #0, if defined in the dumpfile.

```Tcl
set zero_time [ gtkwave::getTimeZero ]
puts "$zero_time"
```

--------------------------------

### Retrieve Time Dimension

Source: https://gtkwave.github.io/gtkwave/tcl/commands.html

Gets the first character of the time unit (e.g., 'u' for us).

```Tcl
set dimch [ gtkwave::getTimeDimension ]
puts "$dimch"
```

--------------------------------

### Convert VCD to VZT with Custom Compression and Break Size

Source: https://gtkwave.github.io/gtkwave/man/vcd2vzt.1.html

Sets the compression level to 9 and defines a break size of 1GB for the output file.

```bash
vcd2vzt dumpfile.vcd dumpfile.lxt –depth 9 –break 1073741824
```

--------------------------------

### Retrieve Longest Name Length

Source: https://gtkwave.github.io/gtkwave/tcl/commands.html

Gets the character count of the longest signal name in the dumpfile.

```Tcl
set longest [ gtkwave::getLongestName ]
puts "$longest"
```

--------------------------------

### xml2stems CLI Usage

Source: https://gtkwave.github.io/gtkwave/man/xml2stems.1.html

Command line interface documentation for the xml2stems conversion utility.

```APIDOC
## xml2stems

### Description
Converts Verilator XML AST representation to stems file for use with rtlbrowse. Intended to replace the obsolete vermin.

### Syntax
xml2stems [option]... INFILE [OUTFILE]

### Options
- **-V, --vl_sim** - Adds TOP hierarchy for Verilator sim.
- **-h, --help** - Display help then exit.

### Usage Example
verilator -Wno-fatal des.v -xml-only --bbox-sys
xml2stems obj_dir/Vdes.xml des.stems
gtkwave -t des.stems des.fst
```

--------------------------------

### GTKWave Configuration Parameters

Source: https://gtkwave.github.io/gtkwave/man/gtkwaverc.5.html

A collection of configuration parameters used to control GTKWave's behavior, including VCD/FST file handling, zoom settings, and UI preferences.

```APIDOC
## Configuration Parameters

### Description
These parameters control the internal behavior of GTKWave, such as how VCD files are parsed, how data is compressed, and how the UI handles zooming and scrolling.

### Parameters
- **vcd_explicit_zero_subscripts** (value) - Optional - Stores signal names as name.bitnumber when enabled.
- **vcd_preserve_glitches** (value) - Optional - Prevents compression of repeat equal values in VCD/FST files.
- **vcd_preserve_glitches_real** (value) - Optional - Prevents compression of repeat equal values for real nets.
- **vcd_warning_filesize** (value) - Optional - Triggers a warning if VCD file size exceeds the specified MB.
- **vector_padding** (value) - Optional - Sets extra whitespace pixels for vector text (0-16).
- **vlist_compression** (value) - Optional - Sets zlib compression level for vlist processing (-1 to 9).
- **vlist_prepack** (value) - Optional - Enables pre-compression of data for vlists.
- **vlist_spill** (value) - Optional - Enables spilling vlists to disk to save memory.
- **wave_scrolling** (value) - Optional - Enables/disables scrolling by dragging the marker.
- **zoom_base** (value) - Optional - Sets the zoom base (1.5 to 10.0).
- **zoom_center** (value) - Optional - Enables/disables center zooming.
- **zoom_dynamic** (value) - Optional - Enables/disables dynamic full zooming for incremental loaders.
- **zoom_dynamic_end** (value) - Optional - Enables/disables dynamic zoom to end for incremental loaders.
- **zoom_pow10_snap** (value) - Optional - Enables/disables Zoom Pow10 Snap menu option.
```

--------------------------------

### Run twinwave with synchronized viewers in one window

Source: https://gtkwave.github.io/gtkwave/man/twinwave.1.html

Uses a single plus sign separator to embed two GTKWave sessions into one window.

```bash
twinwave filename1.vcd filename1.sav + filename2.vcd filename2.sav
```

--------------------------------

### Get facility variable type

Source: https://gtkwave.github.io/gtkwave/tcl/commands.html

Returns the variable type string for a given facility number.

```tcl
set nfacs [ gtkwave::getNumFacs ]
```

--------------------------------

### Set Transaction Translation Process

Source: https://gtkwave.github.io/gtkwave/tcl/commands.html

Sets the executable for transaction translation and returns the identifier for filter installation.

```tcl
set which_f [ gtkwave::setCurrentTranslateTransProc ./zzz.exe ]
puts "$which_f"
```

--------------------------------

### Load File

Source: https://gtkwave.github.io/gtkwave/tcl/commands.html

Loads a new waveform file into GTKWave. The specified filename must be accessible.

```tcl
gtkwave::loadFile "$filename"
```

--------------------------------

### Set Translation File

Source: https://gtkwave.github.io/gtkwave/tcl/commands.html

Sets the current translation file and returns the identifier for use with filter installation.

```tcl
set which_f [ gtkwave::setCurrentTranslateFile ./zzz.txt ]
puts "$which_f"
```

--------------------------------

### Run twinwave with synchronized viewers in two windows

Source: https://gtkwave.github.io/gtkwave/man/twinwave.1.html

Uses a double plus sign separator to open two synchronized GTKWave sessions in separate windows.

```bash
twinwave filename1.vcd filename1.sav ++ filename2.vcd filename2.sav
```

--------------------------------

### Compile GTKWave

Source: https://gtkwave.github.io/gtkwave/install/unix_linux_4.html

Compiles the GTKWave source code using Meson after the build environment has been set up.

```bash
meson compile -C build

```

--------------------------------

### Trace Information Retrieval

Source: https://gtkwave.github.io/gtkwave/tcl/commands.html

Functions to get information about traces, such as their names, scrollbar values, and values at specific markers.

```APIDOC
## GET /api/traces/name

### Description
Returns the name of a trace when given the index value.

### Method
GET

### Endpoint
`/api/traces/name`

### Parameters
#### Query Parameters
- **trace_number** (integer) - Required - The index of the trace.

### Response
#### Success Response (200)
- **trace_name** (string) - The name of the trace.

### Response Example
```json
{
  "trace_name": "example_trace_name"
}
```
```

```APIDOC
## GET /api/traces/scrollbar

### Description
Returns the scrollbar value, which corresponds to the trace index for the topmost trace on screen.

### Method
GET

### Endpoint
`/api/traces/scrollbar`

### Response
#### Success Response (200)
- **scroller_value** (integer) - The scrollbar value.

### Response Example
```json
{
  "scroller_value": 10
}
```
```

```APIDOC
## GET /api/traces/value_at_marker_from_index

### Description
Returns the value under the marker for the trace numbered by the trace index.

### Method
GET

### Endpoint
`/api/traces/value_at_marker_from_index`

### Parameters
#### Query Parameters
- **trace_number** (integer) - Required - The index of the trace.

### Response
#### Success Response (200)
- **ascii_value** (string) - The value of the trace at the marker.

### Response Example
```json
{
  "ascii_value": "0x1A"
}
```
```

```APIDOC
## GET /api/traces/value_at_marker_from_name

### Description
Returns the value under the primary marker for the given trace name.

### Method
GET

### Endpoint
`/api/traces/value_at_marker_from_name`

### Parameters
#### Query Parameters
- **fac_name** (string) - Required - The name of the trace.

### Response
#### Success Response (200)
- **ascii_value** (string) - The value of the trace at the marker.

### Response Example
```json
{
  "ascii_value": "1.234e-9"
}
```
```

```APIDOC
## GET /api/traces/value_at_named_marker_from_name

### Description
Returns the value under the named marker for the given trace name.

### Method
GET

### Endpoint
`/api/traces/value_at_named_marker_from_name`

### Parameters
#### Query Parameters
- **which** (string) - Required - The marker identifier (A-Z or a-z).
- **fac_name** (string) - Required - The name of the trace.

### Response
#### Success Response (200)
- **ascii_value** (string) - The value of the trace at the named marker.

### Response Example
```json
{
  "ascii_value": "HIGH"
}
```
```

--------------------------------

### Enable Clock Compression

Source: https://gtkwave.github.io/gtkwave/internals/lxt-file-format.html

Enables clock compression heuristics for the current trace.

```c
void lt_set_clock_compress(struct lt_trace *lt)
```
Tokens:
Raw