Waveform Viewers

When running simulations on your computer, you'll generate waveform files which let you view the values of every signal over time; they're an invaluable tool for quickly debugging and maintaining yoursanity! You'll need to install some software to be able to look at the files. For that, you have a few (three) options:

1. GTKWave: This is an oldy, but goody. This was out in some form even when I was in undergrad in the mid 2000's.

Detailed install instructions can be found here, and shouldn't need any significant changes, but we've found:

• If you're on Windows and you already installed GTKWave at the same time you installed iVerilog, therenn's no need to install it again.
• macOS people will probably have the easiest time installing from homebrew with brew install --cask gtkwave. You might need to go the General tab under your Security and Privacy settings and manually allow GTKWave to run.
  • For some reason GTKWave doesn't like being called from the command line. Assuming it actually installed, you can probably get away with launching it from your Launchpad, and then opening .vcd file from there.

brew uninstall gtkwave
brew untap randomplum/gtkwave
brew install --HEAD randomplum/gtkwave/gtkwave

• Debian/Ubuntu folks, if you did everything for iVerilog already, you likely can just apt install gtkwave.

2. Surfer: This is a new tool under development for viewing waveforms! It just feels so much more modern than GTKWave. There's a web version, which does great with small waveform files. The web version of this is not as performant, though.¹ It would be to your benefit to install it locally; many platforms have prebuilt binaries to make it easy, but you may also need to build it from source; click around on the website for the installation process that'll work for you. Mac folks on x86 processors, see the instructions at the bottom of this page for how to build from source (thanks, Yoland!)

3. Oboe: This is a really new tool produced by an MIT startup. One big selling point is that it is entirely web-based so it allows you to upload and share waveforms to help with remote debugging/assistance. I've used it a bit and it seems pretty solid, but also this is a new tool, so things may come up with it it. The creators have provided a Google doc about how to go about getting set up. Google Doc with setup instructions here

Try out any of these, or all three! Try downloading this sample file and opening it in one of them, to ensure that you can view a waveform! When you start running your testbenches in cocotb, you'll start generating waveform files that can serve you well.

Additional Mac x86 Surfer Instructions:

If you are on Windows, Linux (x86, Debian-like), or macOS ARM (i.e. M1/M2/M3), you can download the pre-compiled binaries from the Surfer Project's Website without compiling it yourself.

If you are running on any other platform, most notably macOS but on an Intel Processor (x86), you must build Surfer from source:

1. Install Homebrew (if you don't already have it)

   You can check if you have Homebrew by running brew -v, otherwise, install it by running:

   /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

2. Install Rust and Rustup curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

3. Install OpenSSL

   brew install openssl

4. Install Surfer

   cargo install --git https://gitlab.com/surfer-project/surfer surfer

   This may take a while to build depending on your computer. It can take up to 15 minutes to compile the binary.

Once completed, run surfer <your_vcd_file>.vcd from the command line to open your waveform. You can test it with the sample waveform we have provided.