The Makefiles in cocotb #

Makefiles in cocotb with a focus on icarus verilog simulator.

Make Sequence #

The make sequence starts out in your custom make file made for your cocotb testbench. Your make file will include a call to Makefile.sim via include $(shell cocotb-config --makefiles)/Makefile.sim. The order is as follows:

• Makefile (yours) calls Makefile.sim calls Makefile.deprecations calls Makefile.<simulator> calls Makefile.inc

Makefile.sim #

Makefile.sim does the following:

1. sets simulator, defaults to icarus
   • SIM ?= icarus
   • SIM_LOWERCASE := $(shell echo $(SIM) | tr A-Z a-z) (for backwards compatibility / all caps)
2. sets makefile directory (possibly just for windows)
   • COCOTB_MAKEFILES_DIR := $(realpath $(shell cocotb-config --makefiles))
3. calls another makefile
   • include $(COCOTB_MAKEFILES_DIR)/Makefile.deprecations
4. checks if you have the simulator you want to run your sim with
   • HAVE_SIMULATOR = $(shell if [ -f $(COCOTB_MAKEFILES_DIR)/simulators/Makefile.$(SIM_LOWERCASE) ]; then echo 1; else echo 0; fi;)
5. checks machines available simulators
   • AVAILABLE_SIMULATORS = $(patsubst .%,%,$(suffix $(wildcard $(COCOTB_MAKEFILES_DIR)/simulators/Makefile.*)))
6. errors if you dont have the simulator
7. calls another makefile
   • include $(COCOTB_MAKEFILES_DIR)/simulators/Makefile.$(SIM_LOWERCASE)

Makefile.deprecations #

Simple makefile that just makes sure you are not running simulators/simulator functionality that has been deprecated in cocotb

Makefile.$(SIM_LOWERCASE) #

For now I just want to focus on icarus, so I’m going try to understand Makefile.icarus

1. sets top level language
   • TOPLEVEL_LANG ?= verilog
2. calls another makefile
   • Makefile.inc
3. sets the command to be used (basically which simulator to run)
   • CMD_BIN = iverilog
4. finds or takes arguments to locate the iverilog executable
5. sets top level module, and some compilation args
6. defines a compile sequence using iverilog
7. defines a execution sequences using vvp

The main point of this makefile is compilation / execution using the simulator of choice.

In the the execution phase, vvp calls a compiled library via the -m flag to vvp: (-m $(shell cocotb-config --lib-name vpi icarus))

The cocotb-config command links to a file called:

• /.venv/lib/python3.10/site-packages/cocotb/libs/libcocotbvpi_icarus.vpl.

Important note: this library (and all libraries) in the lib folder are built via the cocotb_build_libs.py, which gets executed when pip installing cocotb. These libraries are not in the repo, only on your local machine.

Investigating the source of libcocotbvpi_icaurs.vpl #

If you look at the file cocotb_build_libs.py, it looks like the .vpl is just a compiled shared object with a special extension for icarus verilog. We will dig into this compilation in another section.

Makefile.inc #

This makefile is always included. It sets thing that cocotb needs:

• particular python version
• cocotb support file locations
• figures out where some of the dependencies are
• sets some misc. top level things like top level language, hdl time unit/precision, etc…