eecs270.org

Local Simulation Tool Installation Guide

In the past, we have recommended using ModelSim through CAEN VNC for testing Verilog. While this is still a valid option, we recommend and provide support for local simulation through an open source toolchain.

• Icarus Verilog (iverilog) - compiles and runs Verilog testbenches. Dumps output waveforms to .vcd files.
• GTKWave - standalone GUI for viewing waveforms.
• VaporView - VS Code extension for viewing waveforms inside the editor.

Installation

Windows

For Windows, we recommend using WSL to install the tools. Install WSL as described by the eecs280 setup guide. While you can run these tools natively on Windows, the setup is more complex. Additionally, having WSL Linux gives you a lot more flexibility for running other tools and scripts in the future.

In your WSL Ubuntu shell:

sudo apt update
sudo apt install iverilog gtkwave

GTKWave on WSL needs WSLg for GUI support. WSLg is enabled by default on Windows 11 and on recent Windows 10 builds. If gtkwave does not open a window, run wsl --update in PowerShell.

macOS

Install Homebrew if you do not already have it, then:

brew install icarus-verilog
brew install --cask gtkwave

If macOS Gatekeeper blocks GTKWave on first launch, right-click the app and choose Open.

VaporView (requires VS Code)

1. Open VS Code.
2. Go to the Extensions panel.
3. Search for VaporView and click Install.

Basic Usage

The examples below use Project 0 (Majority), but the same pattern works for every project.

1. Dump waveforms from your testbench

Add the following to the initial block of your testbench so that simulation produces a .vcd file:

initial begin
    $dumpfile("wave.vcd");
    $dumpvars(0, TestBench0);   // 0 = all nested levels; TestBench0 = top module
    // ...your test stimulus...
end

2. Compile and simulate with iverilog

From the directory containing your Verilog sources:

iverilog -o sim TestBench0.v Majority.v   # compile testbench + design into 'sim'
vvp sim                                   # run sim, producing wave.vcd

• iverilog compiles your Verilog files into a simulator executable.
• vvp sim runs the simulation, which writes the waveform dump wave.vcd.

3a. View waveforms in GTKWave

gtkwave wave.vcd

• Click a module in the top-left pane, then drag signals from the bottom-left pane into the waveform view.
• Because the testbench chose to dump all variables, you can see internal signals that are not exposed by LabsLand testing. This is critical for debugging.
• Use File → Write Save File (Ctrl+S) to save your signal selection as wave.gtkw; reopen later with gtkwave wave.gtkw.

3b. View waveforms in VaporView

• Open your project folder in VS Code.
• Click wave.vcd in the Explorer.
• Use the VaporView side panel to add signals to the waveform view.
• As with gtkwave, you can view internal signals that are not exposed by LabsLand testing.

Example: Project 0 Workflow

# Compile testbench + design
iverilog -o sim TestBench0.v Majority.v

# Run simulation (produces wave.vcd)
vvp sim

# Inspect waveforms
gtkwave wave.vcd      # standalone GUI
# or
code wave.vcd         # VaporView in VS Code

Iterate: edit your Verilog, re-run the three commands, refresh the waveform viewer.

Further Resources

• Icarus Verilog documentation
• GTKWave manual

Notes

• While waveform-based testing is extremely useful, always make sure to also test on LabsLand. Physical hardware can reveal issues that do not appear in simulation.
• iverilog is very powerful and supports all base Verilog features, but it may fail on certain SystemVerilog constructs. This will not affect this class, but if you explore hardware design in the future, you may run into issues.
• If you prefer to use a different simulator or waveform viewer, please inform the course staff so that we can try to provide support and documentation for it.