Icarus Verilog + GTKWave Guide

with support for MIPS architecture implementation

BY IOANNIS KONSTADELIAS <ikonstadel@gmail.com>
Introduction
Here is a guide for those who want to develop and test hardware on Linu OS! The positives of
wor"ing#developing on Linu is that $ou don%t have to wor" on &indows and thus in 'ost (ases
$ou (an have ever$thing for free! The 'ost i'portant thing is that $ou have ever$thing open sour(e!
Noone restri(ts $ou fro' using so'ething that alread$ eists) in the wa$ $ou want! That%s the 'ain
reason I prefer solutions in Linu li"e that than ea'ples li"e *odelSi'! The$ are o") +ut the$
resti(t 'e!
This guide isn%t supposed to in(lude ever$ little detail of either I(arus ,erilog or -TK&ave) +ut the
things $ou have to do to use so'e etra fun(tionalit$ that pro+a+l$ $ou haven%t in 'ind to use or
$ou (ouldn%t "now how to do it +e(ause of la(" of support on the Internet! The 'ain goal of this
guide is to show $ou how to view in -TK&ave the values of the signals of $our progra' in a 'ore
hu'an wa$! In a wa$ that will help $ou a lot with de+ugging! In a wa$ su(h the i'age +elow.
Let%s get it started/
Icarus Verilog
About
I(arus ,erilog is a free ,erilog si'ulation and s$nthesis tool! It (o'piles sour(e (ode written in
,erilog 0IEEE123456 into so'e target for'at! It also generates netlists for the s$nthesis part! It%s +$
far the +est free tool and 'an$ people wor" on that 'a"ing it 'ore and 'ore (o'plete da$ +$ da$!
&ell) +e(ause I use 7+untu 0and spe(ifi(all$ 23!28) whi(h doesn%t 'ean an$thing for the whole
guide6) I%ll show $ou ever$thing with (o''ands for that OS!
Installation
Open a ter'inal and t$pe 0or (op$1paste6 the +elow (o''ands!
9irstl$) add a new ppa.
$ sudo add-apt-repository ppa:team-electronics/ppa
Then) update the lo(al repositor$ (a(he.
$ sudo apt-get update
9inall$) install 0update6 the I(arus ,erilog pa("age
$ sudo apt-get install iverilog
Usage
Let%s sa$ $ou have the sour(e files one.v and two.v to (o'pile! A :ui(" wa$ to (o'pile the' is
;ust +$ t$ping
$ iverilog one.v two.v
In that wa$) a.out is (reated and that%s our +inar$.
$ ls
$ a.out one.v two.v
Now we (an ee(ute a.out with vvp (o''and.
$ vvp a.out
If $ou want to spe(if$ another na'e for the +inar$) $ou (an use the -o option ;ust li"e in g((.
$ iverilog -o my_out.out one.v two.v
$ ls
$ one.v two.v my_out.v
&ell) all these are o") +ut if $ou want to write on +ig) or (o'ple verilog (ode) $ou should also use
during the (o'pilation the -Wall option.
$ iverilog -Wall -o my_out.out one.v two.v
-Wall option wor"s in the sa'e logi( as in g((! It ena+les 'ore warnings during the (o'pilation)
that (an help $ou find that little thing that destro$s the fun(tionalit$ of $our hardware! And $es)
warnings in our (ase (an affe(t the fun(tionalit$ of our design 'ore often than progra''ing in <!
So -Wall is a 'ust! You should also (onsider on -Winfloop! You (an i'agine its usage!
&ell) that%s all fro' 'e a+out I(arus ,erilog! If $ou want to learn 'ore a+out it) $ou should visit it%s
offi(ial we+site at http.##iverilog!i(arus!(o'# and for further How Tos and support its offi(ial wi"i at
http.##iverilog!wi"ia!(o'#wi"i#*ain=>age! I also re(o''end $ou to su+s(ri+e to the 'ailing list
https.##lists!sour(eforge!net#lists#listinfo#iverilog1devel!
GTKWave
About
-TK&ave is a full$ featured -TK? wave viewer for 7ni) &in3@) and *a( OSA whi(h reads
LAT) LAT@) ,BT) 9ST) and -H& files as well as standard ,erilog ,<D#E,<D files and allows
their viewing! Its offi(ial we+site is at http.##gt"wave!sour(eforge!net#!
-TK&ave is the +est free wave viewer and is the re(o''ended viewer +$ I(arus ,erilog
developer!
Installation
Open a ter'inal and t$pe 0or (op$1paste6 the +elow (o''ands!
9irstl$) update the lo(al repositor$ (a(he.
$ sudo apt-get update
9inall$) install 0update6 the -TK&ave pa("age
$ sudo apt-get install gtkwave
Usage
It%s usage it%s reall$ eas$! In order to open -TK&ave $ou (an either t$pe gt"wave in ter'inal) or +$
(li("ing on its i(on.
As $ou (an i'agine) there%s nothing $ou (an do +$ si'pl$ opening it alone! In order to see so'e
wavefor') $ou 'ust open through -TK&ave so'e saved du'pfiles! In our (ase we will use !v(d
files) whi(h are produ(ed for our I(arus ,erilog tool!
Creation of .vcd files
In our verilog (ode in an initial +lo(" we should in(lude these two lines.
module Test;
...
initial begin
$dumpfile("my_dumpfile.vcd");
$dumpvars(0, my_module_name);
end
...
endmodule
NOT! In (ase $ou have defined arra$s in our design! E!g!.
module Mem (bla, bla, bla, );
...
reg [M:0] data [N:0];

endmodule
its i'portant that $ou in(lude also these lines in $our initial +lo(" 0for ever$ arra$ $ou
defined6) in order to +e a+le to see the arra$ signals in -TK&ave.
module Test;
integer i;
...
initial begin
$dumpfile("my_dumpfile.vcd");
$dumpvars(0, my_module_name);
for(i = 0; i < M; i = i + 1)
$dumpvars(1, full.path.to.array.data[i]);
end
...
endmodule
It%s pro+a+le that the last a(tion will result a &arning t$pe li"e that +elow during the (o'pilation!
You don%t need to worr$.
VCD warning: array word cpu_tb.cpu0.cpu_dp.data_mem.data[39] will
conflict with an escaped identifier.
Opening VCD files with GTKWave
You (an open o ,<D file either fro' ter'inal or +$ the -7I! In this guide I%ll use as 'u(h as I (an
the ter'inal wa$! It%s 'ore (at(h$ and for sure it%ll save as useful ti'e) espe(iall$ when we test a
hardware design! So here we go.
$ gtkwave my_dumpfile.vcd
As $ou (an see) there aren%t an$ waves in the &ave window! That%s +e(ause the user has to (hoose
whi(h signals want to see! In order to (hoose the signal $ou want to see) $ou should go in the left
window with the SST na'e! Here $ou (an see $our hardware hierar(h$! B$ (li("ing the ? of ever$
instan(e) $ou (an see the signals that are related with that instan(e! Then $ou (an dragCdrop the')
or (op$Cpaste the' in the Signals window! ,oilD/ Here are the wavefor's!
NOT! "hen I close and re#open $T%"a&e with the same '() file* the signals that I ha&e chosen
+efore are lost. Should I alwa,s spend all this time +, onl, inserting signals to +e shown-
The answer is Eof (ourse not/F! After $ou have de(ided on the signals $ou want to +e shown $ou
(an (li(" File Write Save File As and save a file with a !gt"w ending! Let%s sa$ for this ea'ple
(onfig!gt"w! 9ro' now and then $ou (an open it with $our !v(d file and get instantl$ to the point)
whi(h is de+ugging G6 .
$ gtkwave my_dumpfile.vcd config.gtkw
A etter view on things
Now $ou are a+le to see the values of the signals in a faster wa$! But how a+out the interpretationH
The values of the signals are in heade(i'al for'at and all waves are (olored green! Yes/ You (an
(hange these properties!
You (an (hange the' +$ right1(li("ing on the signals and (hoosing Data For!at or Color For!at!
You are free to eperi'ent with these options! &hen $ou have the desired opti(al result $ou (an
save $our (onfiguration +$ going File Write Save File!
All (r$stal (lear until now!!!
Ta"e GTKWave # #o$r side
&hen $ou right1(li(" on a signal and espe(iall$ in the Data For!at option $ou (an see the (hoi(e
Translate Filter File! &e%ll sti(" with that option for the rest of this guide! It%s a ver$ powerful
option) +ut it goes +$ the 'ost ti'es as there%s not there!
&ith that option $ou (an translate the values of the signals in a 'ore hu'an wa$! You (an do this
+$ writing a !tt translation filter! It isn%t as (o'ple as it sounds! Let%s see an ea'ple.
You write a *I>S pro(essor in ,erilog! You have a Iegister 9ile with the register of this
ar(hite(ture! You don%t want to see the na'es of the' as he nu'+ers) even as de(i'al! So $ou (an
si'pl$ write a !tt file li"e this.
00 $0 - $zero
01 $1 - $at
02 $2 - $v0
...
The first (olu'n represents the heade(i'al values that a signal that represents registers (an have!
The se(ond 'ore (o'ple (olu'n is what we want to see instead of the first (olu'n! And that%s it/!
Now we onl$ have to go to the signal we want to (hange) right1(li(" on it) (hoose Data For!at
Translate Filter File %nale and Select! Then $ou have to +rowse to the filter $ou wrote)
(hoose it and hit OK! ,oilD/ 0*a"e sure that the data for'at is in he +efore $ou (hoose the filter6!
Now $ou (an save again $our (onfiguration! You%re read$ to go/
In that wa$ $ou (an filter whatever $ou want! 9ro' registers% na'es and op(odes to full
instru(tions/ 9ull instru(tionsHHH
Supposing that we tal" a+out a *I>S i'ple'entation) we initialiJe the Instru(tion *e'or$ arra$
with the verilog (o''and $readmemb() fro' a file! This file 'ust +e of su(h for'at.
@0 000000_01000_00100_01001_00000_100000 // add $t1, $t0, $a0
@4 101011_01011_01001_0000000000000101 // sw $t1, 5($t3)
@8 100011_01011_10010_0000000000000101 // lw $s2, 5($t3)
@c 000000_01000_10011_01001_00000_101010 // slt $t1, $t0, $s3
@10 000100_01001_10010_1111111111111011 // beq $t1, $s2, -5
where the first (olu'n is the address in he of the (o''and 0in *I>S ever$ address ta"es 3@ +its6
and the se(ond (olu'n is the +inar$ representation of the *I>S asse'+l$ instru(tion! You (an
in(lude so'e <?? st$le (o''ents if $ou li"e to!
This spe(ial (o''and is used li"e that in an initial +lo(".
$readmemb("program.mbin", full.path.to.data);
Before we (ontinue with '$ favorite part) let%s 'a"e our life a lot easier!
&a"efile' O$r est friend
Let%s (reate a si'ple 'a"e file with what we saw up to here! The s(enario is that we have a design
in ,erilog and we want to run it and see the wavefor's instantl$) without tou(hing the 'ouse at all.
CC = iverilog
FLAGS = -Wall -Winfloop
library_input: one.v two.v testbench.v
$(CC) $(FLAGS) -o test one.v two.v testbench.v
vvp test
gtkwave my_dumpfile.vcd config.gtkw
The 'a"efile should +e in the sa'e dire(tor$ with the other !v) !v(d and !gt"w files in our ea'ple!
You si'pl$ ee(ute this "ind of s(ript +$ ;ust t$ping 'a"e in the ter'inal!
$ make
Now) when $ou want to run $our verilog (ode $ou (an ;ust t$pe make and ever$thing (o'es up for
$ou!
(o pain (o gain
Now (o'es the last +ut the +est part! How (an $ou represent the instru(tions in -TK&ave fro' the
'o'ent $ou have to (hange the' fro' test to testH It%s ti'e (onsu'ing! It%s also ti'e (onsu'ing to
(onvert an instru(tion to its +inar$ representation in order to test the pro(essor! There are so'e
online (onverters) +ut the$ restri(t $ou in the wa$ that $ou (annot insert a whole progra' and get its
+inar$! 9urther'ore) its +oring to fill the file with addresses 0K8) K5) L6! There are ti'es $ou
want to run a +ig progra') and $ou spend the M ti'e in (onverting it in a for'at that
$readmemb() (an read it!
9or this reason there%s no solution +ut to develop $our own parser! You%ll spend a few hours to finish
it) +ut the results will save $ou a lot 'ore hours in the testing of $our (ode! 9or 'e I developed a
*I>S asse'+l$ to *I>S +inar$ parser! I na'ed it *AS*BIN and wor"s li"e this. It ta"es as first
argu'ent the !'as' asse'+l$ file 0input6) and as a se(ond argu'ent the !'+in +inar$ file 0output6.
$ ./masmbin input.masm output.mbin
In this stage) it (an ta"e @ options.
-c
Shows in .mbin file in comments the parsed instruction
-f filter.txt
Outputs a .txt filter file for GTKWave
So as $ou see) this parser does another ;o+ with the right option. It (reates the filter that we wanted
to represent the values of signals in -TK&ave as higher level instru(tions!
Now we%re going to put ever$thing together and have a ni(e *I>S asse'+l$ si'ulator!
Let%s start fro' the (onventions $ou should ta"e.
In Nread'e'+06) the file 'ust +e the sa'e 0for our ea'ple) program.m+in6
The filter for our instru(tions in -TK&ave should have a sta+le na'e 0for our ea'ple)
translate.instruction.t/t6
O") now lets write our final 'a"efile.
CC = iverilog
FLAGS = -Wall -Winfloop
library_input: one.v two.v testbench.v
$(CC) $(FLAGS) -o test one.v two.v testbench.v
./masmbin -c -f translate_instruction.txt program.masm
program.mbin
vvp test
gtkwave my_dumpfile.vcd config.gtkw
Now) ever$thing is in pla(e! You (an edit the progra'!'as' file as $ou want) save it) and ee(ute
'a"e! Ever$thing will (o'e up auto'ati(all$!
If $ou want to download the new version of *AS*BIN $ou (an do so at
https'))dl.dropo*$sercontent.co!)$)+,-,./0.)&12S3as!3to3in3parser3v/.-.tar.g4!
9or the previous version refer to the githu+ repositor$.
https.##githu+!(o'#gon233@#*I>S1as'1to1+in1parser