Build options and Environment Variables¶
Makefiles are provided for a variety of simulators in
The common Makefile
cocotb/share/makefiles/Makefile.sim includes the appropriate simulator Makefile based on the contents of the
Makefiles defines the targets
sim, the default target is
Both rules create a results file with the name taken from
COCOTB_RESULTS_FILE, defaulting to
This file is a xUnit-compatible output file suitable for use with e.g. Jenkins.
sim targets unconditionally re-runs the simulator whereas the
regression target only re-builds if any dependencies have changed.
In addition, the target
clean can be used to remove build and simulation artifacts.
help lists these available targets and the variables described below.
The following sections document environment variables and makefile variables according to their owner/consumer.
Of the environment variables, only
MODULE is mandatory to be set
(typically done in a makefile or run script), all others are optional.
Use this to indicate the instance in the hierarchy to use as the DUT. If this isn’t defined then the first root instance is used.
The DUT is available in cocotb tests as a Python object at
cocotb.top; and is also passed to all cocotb tests as the first and only parameter.
Seed the Python random module to recreate a previous test stimulus. At the beginning of every test a message is displayed with the seed used for that execution:
INFO cocotb.gpi __init__.py:89 in _initialise_testbench Seeding Python random module with 1377424946
To recreate the same stimuli use the following:
Use this to override the default behavior of annotating cocotb output with ANSI color codes if the output is a terminal (
forces output to be ANSI-colored regardless of the type of
stdoutor the presence of
suppresses the ANSI color output in the log messages
All command-line software which outputs text with ANSI color added should check for the presence of a
NO_COLORenvironment variable that, when present (regardless of its value), prevents the addition of ANSI color.
If defined, log lines displayed in the terminal will be shorter. It will print only time, message type (
ERROR, …) and the log message itself.
In order to give yourself time to attach a debugger to the simulator process before it starts to run, you can set the environment variable
COCOTB_ATTACHto a pause time value in seconds. If set, cocotb will print the process ID (PID) to attach to and wait the specified time before actually letting the simulator run.
Enable performance analysis of the Python portion of cocotb. When set, a file
test_profile.pstatwill be written which contains statistics about the cumulative time spent in the functions.
From this, a callgraph diagram can be generated with gprof2dot and
graphviz. See the
profileMake target in the
endian_swapperexample on how to set this up.
The default logging level to use. This is set to
INFOunless overridden. Valid values are
Defines how to resolve bits with a value of
Wwhen being converted to integer. Valid settings are:
randomly resolve to a
HTTP port to use for debugging Python’s memory usage. When set to e.g.
8088, data will be presented at http://localhost:8088.
This needs the
dowserPython modules installed.
The absolute path to the Python library associated with the current Python installation; i.e.
python.dllon Windows. This is determined with
cocotb-config --libpythonin cocotb’s makefiles.
The name of the Python module(s) to search for test functions - if your tests are in a file called
MODULEwould be set to
test_mydesign. Multiple modules can be specified using a comma-separated list. All tests will be run from each specified module in order of the module’s appearance in this list.
The is the only environment variable that is required for cocotb, all others are optional.
The name of the test function(s) to run. If this variable is not defined cocotb discovers and executes all functions decorated with the
cocotb.testdecorator in the supplied
Multiple test functions can be specified using a comma-separated list.
The file name where xUnit XML tests results are stored. If not provided, the default is
New in version 1.3.
Enable to report Python coverage data. For some simulators, this will also report HDL coverage.
This needs the
coveragePython module to be installed.
A comma-separated list of modules that should be executed before the first test. You can also use the
cocotb.hookdecorator to mark a function to be run before test code.
Deprecated since version 1.5:
cocotb.hookis deprecated, and in the future this variable will be ignored.
If defined, cocotb will drop into the Python debugger (
pdb) if a test fails with an exception. See also the Python subsection of Attaching a Debugger.
A comma-separated list of extra libraries that are dynamically loaded at runtime. A function from each of these libraries will be called as an entry point prior to elaboration, allowing these libraries to register system functions and callbacks. Note that HDL objects cannot be accessed at this time. An entry point function must be named following a
:separator, which follows an existing simulator convention.
GPI_EXTRA=libnameA.so:entryA,libnameB.so:entryBwill first load
libnameA.sowith entry point
entryA, then load
libnameB.sowith entry point
Changed in version 1.4.0: Support for the custom entry point via
:was added. Previously
:was used as a separator between libraries instead of
Changed in version 1.5.0: Library name must be fully specified. This allows using relative or absolute paths in library names, and loading from libraries that aren’t prefixed with “lib”. Paths should not contain commas.
Makefile-based Test Scripts¶
The following variables are makefile variables, not environment variables.
Set this to 1 to enable the GUI mode in the simulator (if supported).
Selects which simulator Makefile to use. Attempts to include a simulator specific makefile from
Set this to 1 to enable wave traces dump for the Aldec Riviera-PRO and Mentor Graphics Questa simulators. To get wave traces in Icarus Verilog see Waveforms.
Used to inform the makefile scripts which HDL language the top-level design element is written in. Currently it supports the values
verilogfor Verilog or SystemVerilog tops, and
vhdlfor VHDL tops. This is used by simulators that support more than one interface (VPI, VHPI, or FLI) to select the appropriate interface to start cocotb.
The variable is also made available to cocotb tests conveniently as
Selects a simulator interface to use when
vhdlsources are tested. This includes the initial GPI interface loaded, and
GPI_EXTRAlibrary loaded in mixed language simulations. Valid values are
fli; however not all values are supported by all simulators.
A list of the Verilog source files to include. Paths can be absolute or relative; if relative, they are interpreted as relative to the Makefile’s location.
A list of the VHDL source files to include. Paths can be absolute or relative; if relative, they are interpreted as relative to the Makefile’s location.
A list of the VHDL source files to include in the VHDL library lib (currently for the GHDL simulator only).
Any arguments or flags to pass to the compile stage of the simulation.
Any arguments or flags to pass to the execution of the compiled simulation.
Any argument to be passed to the “first” invocation of a simulator that runs via a TCL script. One motivating usage is to pass -noautoldlibpath to Questa to prevent it from loading the out-of-date libraries it ships with. Used by Aldec Riviera-PRO and Mentor Graphics Questa simulator.
Passed to both the compile and execute phases of simulators with two rules, or passed to the single compile and run command for simulators which don’t have a distinct compilation stage.
“Plusargs” are options that are starting with a plus (
+) sign. They are passed to the simulator and are also available within cocotb as
cocotb.plusargs. In the simulator, they can be read by the Verilog/SystemVerilog system functions
The special plusargs
+seed, if present, are evaluated to set the random seed value if
RANDOM_SEEDis not set. If both
The default time unit that should be assumed for simulation when not specified by modules in the design. If this isn’t specified then it is assumed to be
1ns. Allowed values are 1, 10, and 100. Allowed units are
New in version 1.3.
The default time precision that should be assumed for simulation when not specified by modules in the design. If this isn’t specified then it is assumed to be
1ps. Allowed values are 1, 10, and 100. Allowed units are
New in version 1.3.
Use to add additional dependencies to the compilation target; useful for defining additional rules to run pre-compilation or if the compilation phase depends on files other than the RTL sources listed in
Use to add additional dependencies to the simulation target.
Use to define a scratch directory for use by the simulator. The path is relative to the Makefile location. If not provided, the default scratch directory is
The name of a simulator script that is run as part of the simulation, e.g. for setting up wave traces. You can usually write out such a file from the simulator’s GUI. This is currently supported for the Mentor Questa, Mentor ModelSim and Aldec Riviera simulators.
Library Build Process¶
You can pass additional options to the library build process
(which is usually happening as part of the installation with
pip) using the
for C and C++ compilation and linking:
The following variables are used for cocotb internals. They may change at any time, and users should not rely on them.
Path to the directory containing the cocotb Python package in the
Path to the directory containing the cocotb Makefiles and simulator libraries in the subdirectories
Enable code coverage collection for cocotb internals. When set, a file
.coverage.cocotbwill be written which contains statistics about the code coverage. This is mainly useful for cocotb’s own Continuous Integration setup.