Documentation/gtkwave_tutorial.mdwn

   1 [[!img 2020-08-15_12-04.png size="800x" ]]
   2
   3 This tutorial is about generating better GTKWave documents (*.gtkw)
   4 from Python. The goal is to ease analysis of traces generated by
   5 unit-tests, and at the same time to better understand the inner working
   6 of modules, for which we are writing such tests.
   7
   8 # Stylish GTKWave Documents
   9
  10 In this tutorial, you will learn how to:
  11
  12 1. Use individual trace colors.
  13    For instance, use different color styles for input, output, debug and
  14    internal traces.
  15 2. Use numeric bases besides the default hex.
  16 3. Create collapsible trace groups
  17    Useful to hide and show, at once, groups of debug, internal and
  18    sub-module traces.
  19    Select the opening or closing brace, then use the T key.
  20 4. Add comments in the signal names pane
  21 5. Change the displayed name of a trace
  22 6. Use a sane default for initial zoom level
  23 7. Place markers on interesting places
  24 8. Put the generating file name as a comment in the file
  25
  26 # New signals at simulation time
  27
  28 At simulation time, you can declare a new signal, and use it inside
  29 the test case, as any other signal. By including it in the "traces"
  30 parameter of Simulator.write_vcd, it is included in the trace dump
  31 file.
  32
  33 Useful for adding "printf" style debugging for GTKWave.
  34
  35 # String traces
  36
  37 When declaring a Signal, you can pass a custom decoder that
  38 translates the Signal logic level to a string. nMigen uses this
  39 internally to display Enum traces, but it is available for general
  40 use.
  41
  42 Some applications are:
  43
  44 1. Display a string when a signal is at high level, otherwise show a
  45    single horizontal line. Useful to draw attention to a time interval.
  46 2. Display the stages of a unit test
  47 3. Display arbitrary debug statements along the timeline.