Documentation/gtkwave_tutorial.mdwn

   1 # GTKWave improvements
   2
   3 * (Originally at <http://lists.libre-soc.org/pipermail/libre-soc-dev/2020-August/000146.html>)
   4 * [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)
   5
   6 Lately, I've been investigating about generating better GTKWave "save"
   7 files (\*.gtkw), from Python. The goal is to ease analysis of traces
   8 generated by unit-tests, and at the same time to better understand the
   9 inner working of modules, for which we are writing such tests.
  10
  11 I am using src/soc/experiment/alu_fsm.py as a test bed for demonstration.
  12
  13 To see the current work, run:
  14
  15 1) python3 src/soc/experiment/alu_fsm.py
  16 2) gtkwave test_shifter.gtkw
  17
  18 Besides color, another interesting feature is collapsible group of
  19 traces. Try selecting the opening brace of the "debug" and "internal"
  20 groups, and double-click or press T.
  21
  22 Another bonus is string traces, which allows "printf" style debugging in
  23 the trace pane.
  24
  25 [[!img 2020-08-15_12-04.png size="800x" ]]
  26
  27 A current limitation is having to deal with signal names instead of
  28 Signals themselves. Also, direct use of vcd.gtkw is a bit verbose. I
  29 intend to work a bit on this, next.
  30
  31 Possibly, I'll propose and contribute back improvements to the nMigen
  32 sim.pysim.Simulator.write_vcd method, which was my inspiration for this
  33 work.
  34
  35 A more complete description follows:
  36
  37 https://git.libre-soc.org/?p=soc.git;a=commitdiff;h=de64658d0a482f1d6df3c84b4087864ff65ccfef
  38
  39 commit de64658d0a482f1d6df3c84b4087864ff65ccfef
  40 Author: Cesar Strauss <cestrauss@gmail.com>
  41 Date:   Thu Aug 13 19:40:35 2020 -0300
  42
  43     Demonstrates creating stylish GTKWave "save" files from python
  44
  45     This is inspired on the use of the vcd.gtkw module in nMigen, used
  46     internally to create "save" files of selected Signals, for
  47     "Simulator.write_vcd".
  48
  49     However, the vcd.gtkw module exposes a great deal of extra
  50     possibilities, like:
  51
  52     1) Individual trace colors.
  53     For instance, use different color styles for input, output, debug
  54     and internal traces.
  55     2) Numeric bases besides the default hex.
  56     3) Collapsible trace groups
  57     Useful to hide and show, at once, groups of debug, internal and
  58     sub-module traces.
  59     Select the opening or closing brace, then use the T key.
  60     4) Comments in the signal names pane
  61     5) Change the displayed name of a trace
  62     6) Sane default for initial zoom level
  63     7) Place markers on interesting places
  64     8) Put the generating file name as a comment in the file
  65
  66 https://git.libre-soc.org/?p=soc.git;a=commitdiff;h=d3a72bb0688cf343dddc069ef50ba60b9736e8d9
  67
  68 commit d3a72bb0688cf343dddc069ef50ba60b9736e8d9
  69 Author: Cesar Strauss <cestrauss@gmail.com>
  70 Date:   Fri Aug 14 08:06:49 2020 -0300
  71
  72     Demonstrates adding extra debug signals traces to the dump file
  73
  74     At simulation time, you can declare a new signal, and use it inside
  75     the test case, as any other signal. By including it in the "traces"
  76     parameter of Simulator.write_vcd, it is included in the trace dump
  77     file.
  78
  79     Useful for adding "printf" style debugging for GTKWave.
  80
  81 https://git.libre-soc.org/?p=soc.git;a=commitdiff;h=1d4fa2db3d660510ebeceb650188c6fcf3127fd4
  82
  83 commit 1d4fa2db3d660510ebeceb650188c6fcf3127fd4 (HEAD -> master,
  84 origin/master, origin/HEAD)
  85 Author: Cesar Strauss <cestrauss@gmail.com>
  86 Date:   Fri Aug 14 08:25:36 2020 -0300
  87
  88     Demonstrates string traces
  89
  90     When declaring a Signal, you can pass a custom decoder that
  91     translates the Signal logic level to a string. nMigen uses this
  92     internally to display Enum traces, but it is available for general
  93     use.
  94
  95     Some applications are:
  96     1) Display a string when a signal is at high level, otherwise show a
  97     single horizontal line. Useful to draw attention to a time interval.
  98     2) Display the stages of a unit test
  99     3) Display arbitrary debug statements along the timeline.