(no commit message)

diff --git a/Documentation/Documentation/gtkwave_tutorial.mdwn b/Documentation/Documentation/gtkwave_tutorial.mdwn
new file mode 100644 (file)
index 0000000..b3dd497
--- /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 <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.