The Makefiles in cocotb

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.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
  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, 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, 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. #

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… Copyright © 2023