From c7c06c56d92a6c186e92a87a9bff674b71b8def7 Mon Sep 17 00:00:00 2001 From: lkcl Date: Sat, 15 Aug 2020 12:03:37 +0100 Subject: [PATCH] --- .../Documentation/gtkwave_tutorial.mdwn | 94 +++++++++++++++++++ 1 file changed, 94 insertions(+) create mode 100644 Documentation/Documentation/gtkwave_tutorial.mdwn diff --git a/Documentation/Documentation/gtkwave_tutorial.mdwn b/Documentation/Documentation/gtkwave_tutorial.mdwn new file mode 100644 index 000000000..b3dd49733 --- /dev/null +++ b/Documentation/Documentation/gtkwave_tutorial.mdwn @@ -0,0 +1,94 @@ +# GTKWave improvements + +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 +work. + +A more complete description follows: + +https://git.libre-soc.org/?p=soc.git;a=commitdiff;h=de64658d0a482f1d6df3c84b4087864ff65ccfef + +commit de64658d0a482f1d6df3c84b4087864ff65ccfef +Author: Cesar Strauss +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 +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 +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. -- 2.30.2