Hello World #

Once cocotb, icarus, and gtkwave are installed, you’re ready to get started. To use cocotb you will need three things:

1. HDL to verify
2. a cocotb testbench
3. a Makefile to build and run your testbench + HDL.

This minimal example is very dumb, but provides a framework for the smallest set of files necessary in order to get started running cocotb. This introduction assumes you have some working knowledge of icarus verilog and how iverilog command and vvp commands work in icarus. If you do not have any background with icarus check out the icarus and gtkwave quickstart

Github Link #

Simple Example #

HDL Source #

hello.v

module hello;
initial begin;
    $display("hello learncocotb.com");
end
endmodule

Cocotb Testbench #

testbench.py

# Simple tests for an counter module
import cocotb
from cocotb.triggers import RisingEdge

@cocotb.test()
async def hello_world(dut):
    pass 

Makefile #

Makefile

# simulator
SIM ?= icarus

#language
TOPLEVEL_LANG ?= verilog

# source files
VERILOG_SOURCES = hello.v

# use VHDL_SOURCES for VHDL files

# TOPLEVEL is the name of the toplevel module in your Verilog or VHDL file
TOPLEVEL = hello

# MODULE is the basename of the Python test file
MODULE = testbench

# include cocotb's make rules to take care of the simulator setup
include $(shell cocotb-config --makefiles)/Makefile.sim

Running the example #

(.venv)% make
b-repo/.venv/bin/python
     -.--ns INFO     gpi                                ../gpi/GpiCommon.cpp:101  in gpi_print_registered_impl       VPI registered
     0.00ns INFO     cocotb                             Running on Icarus Verilog version 11.0 (stable)
     0.00ns INFO     cocotb                             Running tests with cocotb v1.7.2 from /Users/ShaneP/Desktop/learncocotb-repo/.venv/lib/python3.10/site-packages/cocotb
     0.00ns INFO     cocotb                             Seeding Python random module with 1676559720
     0.00ns INFO     cocotb.regression                  pytest not found, install it to enable better AssertionError messages
     0.00ns INFO     cocotb.regression                  Found test testbench.hello_world
     0.00ns INFO     cocotb.regression                  running hello_world (1/1)
hello learncocotb.com
     0.00ns INFO     cocotb.regression                  hello_world passed
     0.00ns INFO     cocotb.regression                              
     
        **************************************************************************************
        ** TEST                          STATUS  SIM TIME (ns)  REAL TIME (s)  RATIO (ns/s) **
        **************************************************************************************
        ** testbench.hello_world          PASS           0.00           0.00          3.28  **
        **************************************************************************************
        ** TESTS=1 PASS=1 FAIL=0 SKIP=0                  0.00           0.00          0.23  **
        **************************************************************************************

What Just Happened?

How did we go from make to suddenly running icarus and then cocotb? The sequence of events was as follows:

1. make compiles and executes the HDL (iverilog and vvp are ran during the make sequence)
2. the simulator connects to cocotb during the make process
3. the simulator advances time and cocotb schedules things to occur, values to be set, etc.
4. Test completes

The output of make shows that our test, hello_world, ran to completion and reported a pass (because nothing was checked in our testbench). The "hello learncocotb.com" string was also displayed on the output.

For ease of viewing we can also redirect the output of vvp to a logfile.

Adding Logifle #

We can redirect the stdout of vvp using the -l switch for adding a logfile. If we take a look at Makefile.icarus - a makefile ran when we run our top level make - we can see that there are environment variables that can be added to the vvp execution:

$(SIM_CMD_PREFIX) $(ICARUS_BIN_DIR)/vvp -M $(shell cocotb-config --lib-dir) -m $(shell cocotb-config --lib-name vpi icarus) $(SIM_ARGS) $(EXTRA_ARGS) $(SIM_BUILD)/sim.vvp $(PLUSARGS)

We can add our logfile to either SIM_ARGS or EXTRA_ARGS. Let’s add a logfile to our top level make via SIM_ARGS. SIM_ARGS can either be defined in our makefile or added at the command line at runtime. For now we will add it to the command line.

make SIM_ARGS=-lhello_stdout

When the above command is executed the stdout from the simulation will be redirected to a file called hello_stdout which will be created next to your testbench.py is. That file will now contain our $display string.

A list of all make build options and environment variables available to users are outlined in the cocotb docs