HDL Simulation with IVerilog

^{Home / Tutorial Index / HDL Simulation with IVerilog}

Introduction

Simulation of designs is an important part of the development cycle. This tutorial introduces the reader to simulation with Icarus Verilog and displaying simulation results with gtkwave. This design flow may be used with the oh fpga design (see https://github.com/parallella/oh/blob/master/verilog/verilog_faq.md).

Assuming you have already become familar with the tutorials available in the Open Hardware for Chips and FPGAs project at https://github.com/parallella/oh/tree/master/verilog, this tutorial provides some additional help with getting started. I wrote this having spent some weeks trying to keep up with the latest changes in the oh project.

One major problem I found was that as the oh code developed, I needed to keep my simulation environment, separate and consistent between releases of the oh code. Creating a branch in the oh repository and merging the latest changes into that branch makes it more difficult to go back to an earlier version of the oh code and testing to see if the behaviour being observed with the latest simulation scripts was also in the older version. So I put my simulation scripts into a separate repository outside the oh project see the ohLocal folder.

A benefit of separating the design verification and the hdl implementation development is that scripts developed to display signals with gtkwave can then be shared more easily with other projects. These scripts are stored in the local/bin folder. A disadvantage of separating the two is that if the hdl design signal names change then the scripts can become out of date, sometimes without it being very obvious until the user attempts to understand the operation of the module that has been changed and finds that the simulation output is not being displayed in the newer version.

Preparation

Install the simulator (http://iverilog.icarus.com/) and the waveform viewer (http://gtkwave.sourceforge.net/). Assuming you are using a Ubuntu machine:

$ sudo apt-get install iverilog gtkwave

Design flow

Here is a very brief overview of the essential commands needed to run a simulation of the oh design. I will go into more detail in later sections of each of these steps. But first navigate to the parallella/parallella-fpga/ohLocal folder and have a go at running the HDL compiler and simulator:

$ cd parallella/parallella-fpga/ohLocal
$ ./axislavedo.sh ../oh/elink/dv/tests/test_hello.emf

If this runs without problems display the waveforms

$ gtkwave waveform.vcd -S ../local/bin/addaxielink0dvsignals.tcl &

Analyse the waveforms and if necessary update the design or the test vectors and re-run these steps to re-run the simulation.

Scripts for building and running the hdl code

The oh design verification architecture has a framework (https://github.com/parallella/oh/tree/master/common/dv) that provides stimulus to a DUT (for example dut_axi_elink.v). The DUT contains the production HDL code that being tested.

I have taken a copy of this file and modified it for my own extended testing of for example the mailbox (dut_mands_axi_elink.v). This DUT has an axi_elink module (elink0) connected via the elink bus (rxo/txo, rxi/txi) to a second axi_elink module (elink1) that writes and reads data from memory. The second axi_elink can be configured directly from the stimulus so that writes from the Epiphany core to the mailbox in elink0 can be simulated. The Arm CPU read of the mailbox in elink0 may also be simulated.

I found it convenient to introduce a timeout so that I could reduce the length of the simulation, and this is implemented in my local copy of the dv_ctrl.v and dv_top.v oh scripts.

I replace the oh build and run scripts with a single more generic shell script that will build and run one or more of the DUT simulation files (see doit.sh).

It is a relatively small task to keep the local versions of these files (dv_ctrl_local.v, dv_top_local.v, libs.cmd and dut_mands_axi_elink.v) updated.

Working with GTKWave

The more important addition it to provide a set of generic tcl scripts that will assist with adding signals to the gtkwave display once the simulation run has been completed.

Gtkwave allows you to add signals from the simulation results by hand and then saving the configuration for use on a later simulation run. In the picture below the dv_top tree is expanded and the clk wire is selected and the Append button is pressed to add the clk signal to the waveform display:

Scripts to display waveforms

All the operations that are done via the user interface of Gtkwave can also be performed via tcl scripts. The scripts that I have added provides a way of loading groups of signals from various places in the design in a consistent way. So for example the oh transaction (a 104 bit wide vector) can be displayed in portions that are significant (read / write, address, data, core id etc).

Using the tcl scripts that I provide, allows you to view various parts of the design in a consistent way and is flexible because when the design is changed and signal names are modified and a new simulation run is completed the original waveform display is immediately available and editing a few tcl scripts allows the signal names that have changed to be included in the updated display.

Helper scripts

At the most basic level the addhelpers.tcl script provides tcl procedures to:

addVector: add specific elements from a large vector to a named group
addSignals: add variable number of signals
addModuleSignals: add a variable number of signals from a module
addGroup: add variable number of signals from a module to a named group
SetFocus: set focus on a specific group, in preparation for moving, closing etc
moveSetFocus: move the previously selected group
closeGroup: close or collapse the group to display just the name
closeGroupDeleteSignal: close the group and delete the named signal
collapseGroup: collapse a named group

Using the Helper scripts

Typically when adding a new wire to the display the user requires that the wire is added in a particular location after a named entry or group. This anchor signal is provided by the user of the procedure and then after the anchor signal may be deleted. For example in the addfifo.tcl script the sys_clk signal is used to anchor all the required signal groups and then at the end sys_clk is cut because this is already on the waveform display and is not needed in many places.

There are other examples of the use of the basic helper scripts in other procedures, but the best way to understand is to try and use them. Create a simple script in the ohLocal folder and read in the file in GTKWave with {File; Read Tcl Script File}

#!/usr/bin/tclsh
#

# toggle the hierarchy to ensure that the correct signal is selected
gtkwave::/Edit/Toggle_Trace_Hier

source ../local/bin/addhelpers.tcl
set elink elink0
set module "dv_top.dut.$elink"
set signal "sys_clk"
addGroup mygroup $module $signal txrr_access txrr_packet txrr_wait

# Expand the group so that you can see the added signals
gtkwave::/Edit/Toggle_Group_Open|Close

# un-toggle the hierarchy after using the helpers
gtkwave::/Edit/Toggle_Trace_Hier

# Zoom to the place on the screen of interest
gtkwave::setWindowStartTime 17.9us
gtkwave::setZoomRangeTimes 17.9us 18us

Displaying signals from more complex modules

The following is a list groups of signals that have already been created:

addAxiElink: adds key signals from an axi_elink, see addaxielinkslavedvsignals.tcl for an example of how to use this procedure
addElink: adds key signals from an elink
addRegRdWr: adds key signals from the core registers from and elink
addExfer_Io: adds signals from the io core module
addEtx_Protocol: adds signals from the protocol core module
addErx_Protocol: adds signals from the protocol core module
addMMU: adds signals from the mmu core module
addEtx_Arbiter: adds signals from the arbiter core module
addErx_Arbiter: adds signals from the arbiter core module
addEcfg: adds signals from the cfg core module
addmailbox: adds signals from the mailbox core module
addEmem: adds signals from the memory module
addTransaction: adds signals from a transaction, see addelink.tcl for an example of how to use this procedure
addfifo: adds key signals from a fifo, see addfifo.tcl for an example of how to use this procedure

Feedback is always welcome