Getting Around GTKWave

GTKWave looks like it came from 1998, because it did. It is also free, opens in a second, handles multi-million-cycle files without complaint, runs everywhere, and is on every university workstation. Half an hour with it is enough to be comfortable, and that is what this article is.

Opening

gtkwave simulation.vcd
gtkwave simulation.vcd simulation.gtkw     # with a saved layout

Three regions: the signal tree on the left, mirroring the $scope hierarchy of the file; the signal list below it, the signals you have chosen to look at; and the canvas on the right, time left to right, single bits as traces and buses as bars with the value written inside.

To add a signal, find it in the tree and double-click it, or drag it to the list. Shift-click and Ctrl-click select several. A good start is to expand the design’s top module, select all its ports and add them; that is the interface at a glance, and internal signals come later, only where needed. Start from the outputs and work back: if the outputs are right you are done, and if not, that is when you open the inside.

Time

Fit-to-window is the reset when you are lost. Ctrl and scroll zooms around the mouse, which is how you dive into one region. If the testbench said something failed at 2340 ns, type that into the time box at the top and press Enter to go straight there.

Two cursors

A left click places the primary cursor, and the signal list shows every value at that time. Ctrl and left click places the secondary cursor, and the status bar shows the difference between the two. That difference is most of what you measure:

• the clock period, cursor on one rising edge and the other on the next;
• latency, one on an input change and the other on the resulting output change, divided by the period;
• a pulse width, on a rising and a falling edge of the same signal, for a reset or a chip select;
• setup margin, on the last input change and on the clock edge that samples it.

Five seconds with two cursors confirms or kills a timing hypothesis before you write a formal check for it.

Groups, aliases and radix

Forty signals called things like tb_top.dut.pipeline_stage2.carry_out_reg is complete and useless. Right-click a signal to rename it; the alias lives in the save file and not in the VCD. Select several, right-click, create a group, and name it: “ALU operands”, “memory interface”, “state machine”. Groups collapse to one row when you do not need them.

Right-click a bus and set its data format. Hex almost always; decimal for counts and addresses; binary when individual bits matter; ASCII for bytes that are characters; signed decimal for two’s complement. Set buses to hex the moment you add them.

Add signals in small numbers. Five or six high-level ones to find the region, then the internals of one group. The canvas should tell a story.

The save file

Once the layout is organised, File, Write Save File, and keep the .gtkw next to the testbench:

project/
    tb_counter.v
    counter.v
    Makefile
    counter_sim.vcd        generated
    counter_sim.gtkw       committed

It records the signal list, groups, aliases, radices and zoom, everything but the data. Next run, gtkwave counter_sim.vcd counter_sim.gtkw and the layout is back. Teams commit the save file so that everyone opens the same view and a screenshot in a bug report matches what a colleague sees.

The first look at a new file

1. Fit the whole run. Does it end where you expected?
2. Add the design’s outputs.
3. Add the clock and the reset; the clock confirms the run happened and the reset release shows where real operation began.
4. Set buses to hex.
5. Go to the time the testbench reported.
6. Zoom in there.
7. Add internal signals only where the trouble is.
8. Measure with the cursors.
9. Save the layout, even if the bug is not found yet.

The next article is about what you are looking for once you are there: the shapes that particular bugs make.