Overview

This tutorial compiling and simulating a simple design with Icarus Verilog.

This tutorial uses the following software:
Gedit 2.28, Text editor,
Icarus Verilog 0.9.1, Verilog simulation and synthesis tool.
GTKWave 3.2.0, Waveform viewer.
make, to run helper script (optional).

Install the software for this Tutorial

iverilog, gtkwave, make

Setup

See the VHDL tutorial for how to setup Gedit for HDL editing.

Create a new directory for this project in a suitable location and create the following three sub-directories: src, testbenches and simulation, or use the Makefile as shown below.

To make using Icarus Verilog easier use the following make file. Create a new file in Gedit and copy and paste the following code. Save the file as Makefile in the project directory. To create the requires project sub-directories type the following command in the terminal.

make new
 
VERILOGEX = .v # Verilog file extension
 
# testbench path TESTBENCH is passed from the command line
TESTBENCHPATH = testbenches/${TESTBENCH}$(VERILOGEX)
SOURCEPATH = src
 
#iverilog CONFIG
VERILOG_CMD = iverilog
#VERILOG_FLAGS  = 
 
# VVP (iverilog runtime engine)
VVP_CMD = vvp
#VVP_FLAGS = 
 
#Simulation Vars
SIMDIR = simulation
DUMPTYPE = vcd
 
#Viewer
WAVEFORM_VIEWER = gtkwave # Waveform viewer executable
 
 
all: compile run view
 
file_check:
ifeq ($(strip $(FILES)),)
		@echo "FILES not set. Use FILES=value to set it. Put mutltiple files in quotes"
		@exit 2
endif                                                                                             
 
testbench_check:
ifeq ($(strip $(TESTBENCH)),)
		@echo "TESTBENCH not set. Use TESTBENCH=value to set it."
		@exit 2
endif                                                                                             
 
 
check: file_check
	$(VERILOG_CMD) -t null $(FILES)
 
# Setup up project directory
new :
	echo "Setting up project ${PROJECT}"
	mkdir src testbench simulation	
 
 
compile : testbench_check
	mkdir -p simulation                                                                                                             
	$(VERILOG_CMD) -o  $(SIMDIR)/$(TESTBENCH) $(TESTBENCHPATH) $(SOURCEPATH)/*                              
 
 
run : testbench_check
	$(VVP_CMD) $(SIMDIR)/$(TESTBENCH) -$(DUMPTYPE) $(VVP_FLAGS) 
	mv dump.$(DUMPTYPE) $(SIMDIR)/$(TESTBENCH).$(DUMPTYPE)                                                                                                         
 
view : testbench_check                                                                                              
	$(WAVEFORM_VIEWER)  $(SIMDIR)/$(TESTBENCH).$(DUMPTYPE)                                               
 
clean : test_bench_check                                                                                                 
	rm $(SIM_DIR)/$(TESTBENCH)*

Writing Code

Create a new file copy the following code below in to it and save it as counter.v in the src directory. This file describes a simple counter with a up / down selection input.

module up_down_counter    (
out      ,  // Output of the counter
up_down  ,  // up_down control for counter
clk      ,  // clock input
reset       // reset input
);
output [7:0] out;
 
input [7:0] data;
input up_down, clk, reset;
reg [7:0] out;
 
always @(posedge clk)
	if (reset) begin
		out <= 8'b0 ;
	end else if (up_down) begin
		out <= out + 1;
	end else begin
		out <= out - 1;
end
 
endmodule

Create a new file copy the following code in to it and save it as counter_tb.v in the testbench directory. This is a testbench to provide input stimuli for the counter.

module counter_tb;
 
  reg reset = 0;
  reg up_down = 0;
  initial begin
    $dumpvars;
 
	 up_down = 1;
	 reset = 0;
     #10 reset = 1;
     #10 reset = 0;
     #300 $stop;
  end
 
  reg clk = 0;
  always #10 clk = !clk;
 
  always #100 up_down = 0;
 
  wire [7:0] value;
  up_down_counter c1 (value, up_down, clk, reset);
 
endmodule

In a terminal change to the project directory:

cd path/to/project/directory

To test counter the following commands are used, these can be ran using the Makefile as shown below. iverilog compiles the Verilog code counter_tb.v and counter.v and produces an executable in the location given after the -o switch. This executable is ran using vvp which is a simulator, the -vcd switch is used to indicate the resultant waveform should be in vcd format. The result can be viewed using gtkwave.

iverilog -o  simulation/counter_tb testbenches/counter_tb.v src/counter.v
vvp simulation/counter_tb -vcd
gtkwave dump.vcd

This can be done using the makefile given above by typing the following commands.

make compile TESTBENCH=counter_tb
make run TESTBENCH=counter_tb
make view TESTBENCH=counter_tb

After running the above commands GTKWave should open. To view signals from the design select the design from the top left side pane and select a signal from the bottom left side pane and click the Insert button at the bottom left of the GTKWave window to view the signal.

All three of the above make commands can be ran by typing:

make all

The syntax of a Verilog file(s) can be checked and the simulation executable and results file can be deleted with the following commands:

make check FILES="NAME OF FILES"
make clean

Further Information

For further information see:

Icarus Verilog Homepage
GTKWave Homepage

There is also the excellent Icarus Verilog wiki.

For a introduction to Verilog see asic-world.com.