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()
, andblank()
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.-
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.gtkwIf the [dumpfile] is not present in the save file, both the dump and save files must be specified to gtkwave:
$ gtkwave my.vcd my.gtkwParameters: - 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.
-
zoom_markers
(zoom: float = 0.0, marker: int = -1, **kwargs) → None[source]¶ Set zoom, primary marker, and markers ‘a’ - ‘z’.
-
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.
-
sst_expanded
(is_expanded: bool) → None[source]¶ Set whether Signal Search Tree (SST) frame is expanded.
-
group
(name: str, closed: bool = False, highlight: bool = False) → Generator[None, None, None][source]¶ Contextmanager helper for
begin_group()
andend_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 ofbegin_group()
andend_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 ofbegin_group()
andend_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
, andgtkwave
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.