December 28, 2024

GTKWave and iVerilog

GTKWave is a tool designed explicitly for analysis of Verilog simulation models. It is not interactive, but works "post-mortem" with dump files.

Installing it

I am running Fedora 41 and I find gtkwave in the packages, so I just do: 
su
dnf install gtkwave
It pulls in several other packages: 
Installing:
 gtkwave                 x86_64  3.3.121-1.fc41
Installing dependencies:
 Judy                    x86_64  1.0.5-37.fc41
 amtk                    x86_64  5.6.1-7.fc41
 libgedit-gtksourceview  x86_64  299.0.5-2.fc41
 libpeas1-loader-python3 x86_64  1.36.0-7.fc41
 tepl                    x86_64  6.8.0-3.fc41
Installing weak dependencies:
 gedit                   x86_64  2:46.2-5.fc41
This takes only 2 minutes and it seems to "just work".

Some examples

Putting the cart before the horse sort of, but here are two examples of my first productive use of gtkwave. I was working up a PWM module to allow me to control the brightness of an LED. I just "tried it" on the FPGA and it did not work. Then I set up a testbench using what I describe below and I could immediately see the wrong waveform, even under simulation. After some head scratching, I was able to figure out the problem, fix my Verilog and get these results. The second is just a zoomed in view (also cropped to allow it to be seen better) of the first.

Basic use with iverilog

You add this to your test bench: 
initial
begin
   $dumpfile("test.vcd");
   $dumpvars(0,test);
end
Then run your simulation via: 
vvp foo.vvp -fst 
gtkwave dump.fst
The -fst option is not necessary, but is said to be faster than the default -vcd. I don't use it, but there it is for the record. What I do is the add the verilog lines as shown, then: 
iverilog -o wave  counter2_tb.v counter2.v
vvp wave
gtkwave test.vcd

Using gtkwave

After doing the above, GTKWave starts up, but nothing is displayed in the graphics pane. We now face another learning curve.

When I ran it, it produced "test.vcd" (none of this fst business for me) and I see the word "test" in the upper left pane. Now what? We roll up our sleeves and begin reading that 159 page manual. My notes follow.

VCD stands for "value change dump" (I wonder what vvp stands for). VCD is an industry standard (IEEE-1364). For now we ignore other formats, though we are aware that they exist and that they may offer higher performance.

When I run it I see SST on the left (signal search tree). A narrow vertical band to the right of that is labeled "signals", and to the right of that is a big black pane marked "waves". Our mission is to get some of our signal displayed in the "waves" area.

The game starts with the word "test" in the SST subwindow. This is the name of the top level module in my test bench.

I click on "test" and some signal names appear in the subwindow below.
I expand "test" and out pops "c1". This is the instantiated name of the one and only module in this particular demo. If I had more modules, they would also pop out. When I click on "c1" I get signals for it in the subwindow below.
In other words "c1" corresponds to this: 

counter c1 (value, clk, reset);

I can select a signal by clicking on it, then clicking the "Append" button below. This causes it to be added to the "Signals" strip and to the "Waves" display. You can keep selecting and appending signals to get all that you want. Alternately, you can just drag and drop signals to the "Signals" strip.

I see at the top that I have time from 0 to 575 seconds available, but only the first 2 seconds are getting displayed. Using the "-" button causes the display to zoom out showing me more time. We have +, -, "zoom fit" as well as buttons to go to the start or end. There are no buttons to move left or right, but there is a scroll bar at the bottom of the waves subwindow for that!

The buttons that look like left and right are actually find previous edge and find next edge. Arrow keys don't work, nor does the mouse.

Save file

When you have a complex design and spend signficant time selecting signals, you will be annoyed to have to repeat this each time you start gtkwave. To make this nicer, you should use File -> Write save file. I chose the name "easy" and ended up with "easy.gtkw" on disk. Then startup gtkwave like so: 
gtkwave test.vcd easy.gtkw

More things

You can right click on signals and change display properties like color or data format (hex or whatever)

In the "guide" line above he talks about a "translate filter file" that you can set up to translate numerical values to register names, opcodes to full instructions and amazing things that would be handy for a complex design like a microcontroller. He is my hero because he talks about using a Makefile to work with iVerilog, somewhat like I do. He works up a MIPS assembler simulator, which is far beyond anything I need at this time, but it is good to know that such things can be done.

Feedback? Questions? Drop me a line!

Tom's Computer Info / tom@mmto.org