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 ## Basic trace display
  27
  28 First, we need a VCD file. Try:
  29
  30     python -m nmutil.test.example_gtkwave
  31
  32 Among other files, it will generate ``test_shifter.vcd``.
  33
  34 Lets write a simple GTKW document. First, import the function:
  35
  36     from nmutil.gtkw import write_gtkw
  37
  38 Create a list of the traces you want to see. Some hints:
  39
  40 1. Put all trace names in quotes.
  41 2. Use the same names as you would see in the trace pane of GTKWave
  42 3. If a trace is multi-bit, use array notation 'name[max:min]'
  43
  44 For example:
  45
  46     traces = [
  47         'clk',
  48         # prev port
  49         'op__sdir', 'p_data_i[7:0]', 'p_shift_i[7:0]', 'p_valid_i', 'p_ready_o',
  50         # internal signals
  51         'fsm_state', 'count[3:0]', 'shift_reg[7:0]',
  52         # next port
  53         'n_data_o[7:0]', 'n_valid_o', 'n_ready_i'
  54     ]
  55
  56 Now, create the document:
  57
  58     write_gtkw("simple.gtkw", "test_shifter.vcd", traces, module='top.shf')
  59
  60 Remarks:
  61
  62 1. ``simple.gtkw`` is the name of our GTKWave document
  63 2. ``test_shifter.vcd`` is the VCD file
  64 3. ``traces`` is a list of trace names
  65 4. ``top.shf`` is the hierarchy path of the module
  66
  67 Now try:
  68
  69     gtkwave simple.gtkw
  70
  71 Notice:
  72
  73 1. No need to press the "zoom to fit" button. The default zoom level is
  74 adequate for a 1 MHz clock.
  75 2. If you made a mistake, there will be no warning. The trace will
  76 simply not appear
  77 3. The reload button will only reload the VCD file, not the GTKW document. If you regenerate the document, you need to close and open a
  78 new tab, or exit GTKWave and run again: ``gtkwave simple.gtkw``
  79 4. If you feel tired of seeing the GTKWave splash window every time,
  80 do: ``echo splash_disable 1 >> ~/.gtkwaverc``
  81 5. If you modify the document manually, better to save it with another
  82 name
  83
  84 ## Adding color
  85
  86 Go back to the trace list and replace the ``'op__sdir'`` string with:
  87
  88     ('op__sdir', {'color': 'orange'})
  89
  90 Recreate the document (you can change the file name):
  91
  92     write_gtkw("color.gtkw", "test_shifter.vcd", traces, module='top.shf')
  93
  94 If you now run ``gtkwave color.gtkw``, you will see that ``op__sdir``
  95 has the new color.
  96
  97 # New signals at simulation time
  98
  99 At simulation time, you can declare a new signal, and use it inside
 100 the test case, as any other signal. By including it in the "traces"
 101 parameter of Simulator.write_vcd, it is included in the trace dump
 102 file.
 103
 104 Useful for adding "printf" style debugging for GTKWave.
 105
 106 # String traces
 107
 108 When declaring a Signal, you can pass a custom decoder that
 109 translates the Signal logic level to a string. nMigen uses this
 110 internally to display Enum traces, but it is available for general
 111 use.
 112
 113 Some applications are:
 114
 115 1. Display a string when a signal is at high level, otherwise show a
 116    single horizontal line. Useful to draw attention to a time interval.
 117 2. Display the stages of a unit test
 118 3. Display arbitrary debug statements along the timeline.