1 [[!img 2020-08-15_12-04.png size="800x" ]]
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.
8 # Stylish GTKWave Documents
10 In this tutorial, you will learn how to:
12 1. Use individual trace colors.
13 For instance, use different color styles for input, output, debug and
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
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
26 ## Basic trace display
28 First, we need a VCD file. Try:
30 python -m nmutil.test.example_gtkwave
32 Among other files, it will generate ``test_shifter.vcd``.
34 Lets write a simple GTKW document. First, import the function:
36 from nmutil.gtkw import write_gtkw
38 Create a list of the traces you want to see. Some hints:
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]'
49 'op__sdir', 'p_data_i[7:0]', 'p_shift_i[7:0]', 'p_valid_i', 'p_ready_o',
51 'fsm_state', 'count[3:0]', 'shift_reg[7:0]',
53 'n_data_o[7:0]', 'n_valid_o', 'n_ready_i'
56 Now, create the document:
58 write_gtkw("simple.gtkw", "test_shifter.vcd", traces, module='top.shf')
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
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
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
86 Go back to the trace list and replace the ``'op__sdir'`` string with:
88 ('op__sdir', {'color': 'orange'})
90 Recreate the document (you can change the file name):
92 write_gtkw("color.gtkw", "test_shifter.vcd", traces, module='top.shf')
94 If you now run ``gtkwave color.gtkw``, you will see that ``op__sdir``
97 ## Writing GTKWave documents, with style
99 Let's say we want all input traces be orange, and all output traces be
100 yellow. To change them one by one, as we did with ``op__sdir``, would be
101 very tedious and verbose. Also, hardcoding the color name will make it
102 difficult to change it later.
104 To solve this, lets create a style specification:
107 'in': {'color': 'orange'},
108 'out': {'color': 'yellow'}
113 ('op__sdir', {'color': 'orange'})
119 then (notice how we add ``style``):
121 write_gtkw("style1.gtkw", "test_shifter.vcd", traces, style, module='top.shf')
123 If you now run ``gtkwave style1.gtkw``, you will see that ``op__sdir``
124 still has the new color.
126 Let's add more color:
132 ('p_data_i[7:0]', 'in'),
133 ('p_shift_i[7:0]', 'in'),
135 ('p_ready_o', 'out'),
141 ('n_data_o[7:0]', 'out'),
142 ('n_valid_o', 'out'),
148 write_gtkw("style2.gtkw", "test_shifter.vcd", traces, style, module='top.shf')
150 If you now run ``gtkwave style2.gtkw``, you will see that input, output and internal signals have different color.
152 # New signals at simulation time
154 At simulation time, you can declare a new signal, and use it inside
155 the test case, as any other signal. By including it in the "traces"
156 parameter of Simulator.write_vcd, it is included in the trace dump
159 Useful for adding "printf" style debugging for GTKWave.
163 When declaring a Signal, you can pass a custom decoder that
164 translates the Signal logic level to a string. nMigen uses this
165 internally to display Enum traces, but it is available for general
168 Some applications are:
170 1. Display a string when a signal is at high level, otherwise show a
171 single horizontal line. Useful to draw attention to a time interval.
172 2. Display the stages of a unit test
173 3. Display arbitrary debug statements along the timeline.