# GTKWave improvements

* (Originally at <http://lists.libre-soc.org/pipermail/libre-soc-dev/2020-August/000146.html>)
* [alu_fsm.py source](https://git.libre-soc.org/?p=soc.git;a=blob;f=src/soc/experiment/alu_fsm.py;h=9668535aedc8e507212906baf679dc37484b8e8d;hb=1d4fa2db3d660510ebeceb650188c6fcf3127fd4#l209)

Lately, I've been investigating about generating better GTKWave "save"
files (\*.gtkw), from Python. The goal is to ease analysis of traces
generated by unit-tests, and at the same time to better understand the
inner working of modules, for which we are writing such tests.

I am using src/soc/experiment/alu_fsm.py as a test bed for demonstration.

To see the current work, run:

1) python3 src/soc/experiment/alu_fsm.py
2) gtkwave test_shifter.gtkw

Besides color, another interesting feature is collapsible group of
traces. Try selecting the opening brace of the "debug" and "internal"
groups, and double-click or press T.

Another bonus is string traces, which allows "printf" style debugging in
the trace pane.

[[!img 2020-08-15_12-04.png size="800x" ]]

A current limitation is having to deal with signal names instead of
Signals themselves. Also, direct use of vcd.gtkw is a bit verbose. I
intend to work a bit on this, next.

Possibly, I'll propose and contribute back improvements to the nMigen
sim.pysim.Simulator.write_vcd method, which was my inspiration for this
work.

A more complete description follows:

https://git.libre-soc.org/?p=soc.git;a=commitdiff;h=de64658d0a482f1d6df3c84b4087864ff65ccfef

commit de64658d0a482f1d6df3c84b4087864ff65ccfef
Author: Cesar Strauss <cestrauss@gmail.com>
Date:   Thu Aug 13 19:40:35 2020 -0300

    Demonstrates creating stylish GTKWave "save" files from python

    This is inspired on the use of the vcd.gtkw module in nMigen, used
    internally to create "save" files of selected Signals, for
    "Simulator.write_vcd".

    However, the vcd.gtkw module exposes a great deal of extra
    possibilities, like:

    1) Individual trace colors.
    For instance, use different color styles for input, output, debug
    and internal traces.
    2) Numeric bases besides the default hex.
    3) Collapsible trace groups
    Useful to hide and show, at once, groups of debug, internal and
    sub-module traces.
    Select the opening or closing brace, then use the T key.
    4) Comments in the signal names pane
    5) Change the displayed name of a trace
    6) Sane default for initial zoom level
    7) Place markers on interesting places
    8) Put the generating file name as a comment in the file

https://git.libre-soc.org/?p=soc.git;a=commitdiff;h=d3a72bb0688cf343dddc069ef50ba60b9736e8d9

commit d3a72bb0688cf343dddc069ef50ba60b9736e8d9
Author: Cesar Strauss <cestrauss@gmail.com>
Date:   Fri Aug 14 08:06:49 2020 -0300

    Demonstrates adding extra debug signals traces to the dump file

    At simulation time, you can declare a new signal, and use it inside
    the test case, as any other signal. By including it in the "traces"
    parameter of Simulator.write_vcd, it is included in the trace dump
    file.

    Useful for adding "printf" style debugging for GTKWave.

https://git.libre-soc.org/?p=soc.git;a=commitdiff;h=1d4fa2db3d660510ebeceb650188c6fcf3127fd4

commit 1d4fa2db3d660510ebeceb650188c6fcf3127fd4 (HEAD -> master,
origin/master, origin/HEAD)
Author: Cesar Strauss <cestrauss@gmail.com>
Date:   Fri Aug 14 08:25:36 2020 -0300

    Demonstrates string traces

    When declaring a Signal, you can pass a custom decoder that
    translates the Signal logic level to a string. nMigen uses this
    internally to display Enum traces, but it is available for general
    use.

    Some applications are:
    1) Display a string when a signal is at high level, otherwise show a
    single horizontal line. Useful to draw attention to a time interval.
    2) Display the stages of a unit test
    3) Display arbitrary debug statements along the timeline.