vcd.gtkw

GTKWave save file generator.

This module provides tools for generating GTKWave save files.

GTKWave is an application for viewing VCD data. When opening a VCD file with GTKWave, by default, no VCD variables (signals) are displayed. It is thus useful to have an accompanying “save” file which configures various aspects of how GTKWave shows the VCD data, including which variables are displayed, variable aliases, color information, and more.

class vcd.gtkw.GTKWSave(savefile: IO[str])[source]

Write GTKWave save files.

This class provides methods for writing the various pieces of a GTKWave save file. A GTKWave save file compliments a VCD dump file with dump file specific configuration GTKWave uses to display the dump file.

A GTKWave save file is line-oriented ASCII text. Each line consists of a single configuration directive. All directives are optional.

Some directives, such as dumpfile(), are for general GTKWave configuration. These general directives may be added anywhere in the save file and in any order relative to other directives. Directives may also be duplicated–the last one added will be used by GTKWave.

The trace(), trace_bits(), group(), and blank() directives add signals to the “Signals” list which are traced in the “Waves” frame. The order in which these signal traces are added determines the order in GTKWave.

comment(*comments) → None[source]

Add comment line(s) to save file.

dumpfile(dump_path: str, abspath: bool = True) → None[source]

Add VCD dump file path to save file.

The [dumpfile] must be in the save file in order to only have to specify the save file on the gtkwave command line. I.e.:

$ gtkwave my.gtkw

If the [dumpfile] is not present in the save file, both the dump and save files must be specified to gtkwave:

$ gtkwave my.vcd my.gtkw
Parameters:
  • dump_path – path to VCD dump file or None to produce special “(null)” value in the save file.
  • abspath (bool) – convert dump_path to an absolute path.
dumpfile_mtime(mtime: Union[float, time.struct_time, datetime.datetime, None] = None, dump_path: Optional[str] = None) → None[source]

Add dump file modification time to save file.

Configuring the dump file’s modification time is optional.

dumpfile_size(size: Optional[int] = None, dump_path: Optional[str] = None) → None[source]

Add dump file size annotation to save file.

Configuring the dump file’s size is optional.

savefile(save_path: Optional[str] = None, abspath: bool = True) → None[source]

Add the path of the save file to the save file.

With no parameters, the output file’s name will be used.

Configuring the [savefile] is optional.

Parameters:
  • save_path – path to this save file. None will use the output file’s path.
  • abspath (bool) – determines whether to make the path absolute.
timestart(timestamp: int = 0) → None[source]

Add simulation start time to the save file.

zoom_markers(zoom: float = 0.0, marker: int = -1, **kwargs) → None[source]

Set zoom, primary marker, and markers ‘a’ - ‘z’.

size(width: int, height: int) → None[source]

Set GTKWave window size.

pos(x: int = -1, y: int = -1) → None[source]

Set GTKWave window position.

treeopen(tree: str) → None[source]

Start with tree open in Signal Search Tree (SST).

GTKWave specifies tree paths with a trailing ‘.’. The trailing ‘.’ will automatically be added if it is omitted in the tree parameter.

Parameters:tree (str) – scope/path/tree to be opened in GTKWave’s SST frame.
signals_width(width: int) → None[source]

Set width of Signals frame.

sst_expanded(is_expanded: bool) → None[source]

Set whether Signal Search Tree (SST) frame is expanded.

pattern_trace(is_enabled: bool) → None[source]

Enable/disable pattern trace.

group(name: str, closed: bool = False, highlight: bool = False) → Generator[None, None, None][source]

Contextmanager helper for begin_group() and end_group().

This context manager starts a new group of signal traces and ends the group when leaving the with block. E.g.:

>>> import io
>>> gtkw = GTKWSave(io.StringIO())
>>> with gtkw.group('mygroup'):
...     gtkw.trace('a.b.x')
...     gtkw.trace('a.b.y')
...     gtkw.trace('a.b.z')
Parameters:
  • name (str) – the name/label of the trace group.
  • closed (bool) – group should be closed at GTKWave startup.
  • highlight (bool) – group should be highlighted at GTKWave startup.
begin_group(name: str, closed: bool = False, highlight: bool = False) → None[source]

Begin a new signal trace group.

Consider using group() instead of begin_group() and end_group().

Parameters:
  • name (str) – the name/label of the trace group.
  • closed (bool) – group should be closed at GTKWave startup.
  • highlight (bool) – group should be highlighted at GTKWave startup.
end_group(name: str, closed: bool = False, highlight: bool = False) → None[source]

End a signal trace group.

This call must match with a prior call to begin_group(). Consider using :meth:`group() instead of begin_group() and end_group().

Parameters:
  • name (str) – the name/label of the trace group.
  • closed (bool) – group should be closed at GTKWave startup.
  • highlight (bool) – group should be highlighted at GTKWave startup.
blank(label: str = '', analog_extend: bool = False, highlight: bool = False) → None[source]

Add blank or label to trace signals list.

Parameters:
  • label (str) – Optional label for the blank.
  • analog_extend (bool) – extend the height of an immediately preceding analog trace signal.
  • highlight (bool) – blank should be highlighted at GTKWave startup.
trace(name: str, alias: Optional[str] = None, color: Union[vcd.gtkw.GTKWColor, str, int, None] = None, datafmt: str = 'hex', highlight: bool = False, rjustify: bool = True, extraflags: Union[vcd.gtkw.GTKWFlag, Sequence[str], None] = <GTKWFlag.0: 0>, translate_filter_file: Optional[str] = None, translate_filter_proc: Optional[str] = None) → None[source]

Add signal trace to save file.

Parameters:
  • name (str) – fully-qualified name of signal to trace.
  • alias (str) – optional alias to display instead of the name.
  • color (GTKWColor) – optional color to use for the signal’s trace.
  • datafmt (str) – the format used for data display. Must be one of ‘hex’, ‘dec’, ‘bin’, ‘oct’, ‘ascii’, ‘real’, or ‘signed’.
  • highlight (bool) – trace should be highlighted at GTKWave startup.
  • rjustify (bool) – trace name/alias should be right-justified.
  • extraflags (GTKWFlag) – extra flags to apply to the trace.
  • translate_filter_file (str) – path to translate filter file.
  • translate_filter_proc (str) – path to translate filter executable.

Note

GTKWave versions <= 3.3.64 require vector signal names to have a bit range suffix. For example, an 8-bit vector variable “module.myint” would be known by GTKWave as “module.myint[7:0]”.

GTKWave versions after 3.3.64 do not use bit-range suffixes.

trace_bits(name: str, alias: Optional[str] = None, color: Union[str, int, None] = None, datafmt: str = 'hex', highlight: bool = False, rjustify: bool = True, extraflags: Union[vcd.gtkw.GTKWFlag, Sequence[str], None] = <GTKWFlag.0: 0>, translate_filter_file: Optional[str] = None, translate_filter_proc: Optional[str] = None) → Generator[None, None, None][source]

Contextmanager for tracing bits of a vector signal.

This allows each individual bit of a vector signal to have its own trace (and trace configuration).

>>> import io
>>> gtkw = GTKWSave(io.StringIO())
>>> name = 'mod.myint'
>>> with gtkw.trace_bits(name):
...     gtkw.trace_bit(0, name)
...     gtkw.trace_bit(1, name)
...     gtkw.trace_bit(2, name)
...     gtkw.trace_bit(3, name, 'special', color=GTKWColor.yellow)
Parameters:
  • name (str) – fully-qualified name of the vector variable to trace.
  • alias (str) – optional alias to display instead of name.
  • color (int) – optional trace color.
  • datafmt (str) – format for data display.
  • highlight (bool) – trace should be highlighted at GTKWave startup.
  • rjustify (bool) – trace name/alias should be right-justified.
  • extraflags (GTKWFlag) – extra flags to apply to the trace.
  • translate_filter_file (str) – path to translate filter file.
  • translate_filter_proc (str) – path to translate filter executable.
trace_bit(index: int, name: str, alias: Optional[str] = None, color: Union[vcd.gtkw.GTKWColor, str, int, None] = None) → None[source]

Trace individual bit of vector signal.

This is meant for use in conjunction with trace_bits().

Parameters:
  • index (int) – index of bit
  • name (str) – name of parent vector signal.
  • alias (str) – optional alias to display for bit.
  • color (int) – optional color for bit’s trace.
class vcd.gtkw.GTKWFlag[source]

These are the valid GTKWave trace flags.

highlight = 1

Highlight the trace item

hex = 2

Hexadecimal data value representation

dec = 4

Decimal data value representation

bin = 8

Binary data value representation

oct = 16

Octal data value representation

rjustify = 32

Right-justify signal name/alias

invert = 64
reverse = 128
exclude = 256
blank = 512

Used for blank, label, and/or analog height

signed = 1024

Signed (2’s compliment) data representation

ascii = 2048

ASCII character representation

collapsed = 4096

Used for closed groups

ftranslated = 8192

Trace translated with filter file

ptranslated = 16384

Trace translated with filter process

analog_step = 32768

Show trace as discrete analog steps

analog_interpolated = 65536

Show trace as analog with interpolation

analog_blank_stretch = 131072

Used to extend height of analog data

real = 262144

Real (floating point) data value representation

analog_fullscale = 524288

Analog data scaled using full simulation time

zerofill = 1048576
onefill = 2097152
closed = 4194304
grp_begin = 8388608

Begin a group of signals

grp_end = 16777216

End a group of signals

bingray = 33554432
graybin = 67108864
real2bits = 134217728
ttranslated = 268435456
popcnt = 536870912

Show the population count, i.e. the number of set bits

fpdecshift = 1073741824
class vcd.gtkw.GTKWColor[source]

The colors used by GTKWave.

The cycle color is special and indicates the GTKWave should cycle through this list of colors, starting from the last selected color.

cycle = -1

Cycle between colors

normal = 0

Default color

red = 1
orange = 2
yellow = 3
green = 4
blue = 5
indigo = 6
violet = 7
vcd.gtkw.make_translation_filter(translations: Sequence[Tuple[Any, ...]], datafmt: str = 'hex', size: Optional[int] = None) → str[source]

Create translation filter.

The returned translation filter string that can be written to a translation filter file usable by GTKWave.

Parameters:
  • translations – Sequence of 2-tuples (value, alias) or 3-tuples (value, alias, color).
  • datafmt (str) – Format to apply to the translation values. This datafmt must match the datafmt used with GTKWSave.trace(), otherwise these translations will not be matched by GTKWave.
Returns:

Translation filter string suitable for writing to a translation filter file.

vcd.gtkw.decode_flags(flags: Union[str, int]) → List[str][source]

Decode hexadecimal flags from GTKWave save file into flag names.

This is useful for understanding what, for example “@802022” means when inspecting a GTKWave save file.

Parameters:flags – Hexadecimal flags from GTKWave save file; either as an integer or string with hexadecimal characters.
Returns:List of flag names
vcd.gtkw.spawn_gtkwave_interactive(dump_path: str, save_path: str, quiet: bool = False) → None[source]

Spawn gtkwave process in interactive mode.

A process pipeline is constructed such that the contents of the VCD dump file at dump_path are displayed interactively as the dump file is being written (i.e. with VCDWriter.

The process pipeline built is approximately equivalent to:

$ tail -f dump_path | shmidcat | gtkwave -vI save_path

The tail, shmidcat, and gtkwave executables must be found in $PATH.

Warning

This function does not work on Windows.

Note

A child python process of the caller will remain running until the GTKWave window is closed. This process ensures that the various other child processes are properly reaped.

Parameters:
  • dump_path (str) – path to VCD dump file. The dump file must exist, but be empty.
  • save_path (str) – path to GTKWave save file. The save file will be read immediately by GTKWave and thus must be completely written.
  • quiet (bool) – quiet GTKWave’s output by closing its stdout and stderr file descriptors.