[Libre-soc-dev] Improving GTKWave debugging

Cesar Strauss cestrauss at gmail.com
Sat Aug 15 11:27:10 BST 2020


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.

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

A more complete description follows:


commit de64658d0a482f1d6df3c84b4087864ff65ccfef
Author: Cesar Strauss <cestrauss at 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

    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


commit d3a72bb0688cf343dddc069ef50ba60b9736e8d9
Author: Cesar Strauss <cestrauss at 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

    Useful for adding "printf" style debugging for GTKWave.


commit 1d4fa2db3d660510ebeceb650188c6fcf3127fd4 (HEAD -> master,
origin/master, origin/HEAD)
Author: Cesar Strauss <cestrauss at 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

    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.



More information about the Libre-soc-dev mailing list