Build Options and Environment Variables

Build Options and Environment Variables#

Make System#

Makefiles are provided for a variety of simulators in src/cocotb/share/makefiles/simulators. The common Makefile src/cocotb/share/makefiles/Makefile.sim includes the appropriate simulator Makefile based on the contents of the SIM variable.

Make Targets#

Makefiles defines the targets regression and sim, the default target is sim.

Both rules create a results file with the name taken from COCOTB_RESULTS_FILE, defaulting to results.xml. This file is a xUnit-compatible output file suitable for use with e.g. Jenkins. The 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. The target help lists these available targets and the variables described below.

Make Phases#

Typically the makefiles provided with cocotb for various simulators use a separate compile and run target. This allows for a rapid re-running of a simulator if none of the RTL source files have changed and therefore the simulator does not need to recompile the RTL.

Variables#

The following sections document environment variables and makefile variables according to their owner/consumer.

Of the environment variables, only COCOTB_TEST_MODULES is mandatory to be set (typically done in a makefile or run script), all others are optional.

Cocotb#

COCOTB_TOPLEVEL#

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. Leading and trailing whitespace are automatically discarded.

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.

Changed in version 1.6: Strip leading and trailing whitespace

Changed in version 2.0: TOPLEVEL is renamed to COCOTB_TOPLEVEL.

Deprecated since version 2.0: TOPLEVEL is a deprecated alias and will be removed.

COCOTB_RANDOM_SEED#

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:

make COCOTB_RANDOM_SEED=1377424946

See also: COCOTB_PLUSARGS

Changed in version 2.0: RANDOM_SEED is renamed to COCOTB_RANDOM_SEED.

Deprecated since version 2.0: RANDOM_SEED is a deprecated alias and will be removed.

COCOTB_ANSI_OUTPUT#

Use this to override the default behavior of annotating cocotb output with ANSI color codes if the output is a terminal (isatty()).

COCOTB_ANSI_OUTPUT=1: forces output to be ANSI-colored regardless of the type of stdout or the presence of NO_COLOR
COCOTB_ANSI_OUTPUT=0: suppresses the ANSI color output in the log messages

NO_COLOR#: From http://no-color.org,

All command-line software which outputs text with ANSI color added should check for the presence of a NO_COLOR environment variable that, when present (regardless of its value), prevents the addition of ANSI color.

COCOTB_REDUCED_LOG_FMT#: Defaults to 1. Logs will include simulation time, message type (INFO, WARNING, ERROR, …), logger name, and the log message itself. If the value is set to 0, the filename and line number where a log function was called will be added between the logger name and the log message.

COCOTB_ATTACH#: 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_ATTACH to 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.

COCOTB_ENABLE_PROFILING#

Enable performance analysis of the Python portion of cocotb. When set, a file test_profile.pstat will 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.

COCOTB_LOG_LEVEL#: The default log level of all "cocotb" Python loggers. Valid values are TRACE, DEBUG, INFO, WARNING, ERROR, CRITICAL. The default is unset, which means that the log level is inherited from the root logger. This behaves similarly to INFO.

Changed in version 2.0: The root "gpi" logger level is no longer set when this environment variable is used. Use GPI_LOG_LEVEL instead.

GPI_LOG_LEVEL#: The default log level of all "gpi" (the low-level simulator interface) loggers, including both Python and the native GPI logger. Valid values are TRACE, DEBUG, INFO, WARNING, ERROR, CRITICAL. The default is unset, which means that the log level is inherited from the root logger. This behaves similarly to INFO.

Added in version 2.0.

COCOTB_RESOLVE_X#

Defines how to resolve bits with a value of X, Z, U, W, or - when being converted to integer. Valid settings are:

VALUE_ERROR: Raise a ValueError exception.
ZEROS: Resolve to 0.
ONES: Resolve to 1.
RANDOM: Randomly resolve to a 0 or a 1.

Set to VALUE_ERROR by default.

Warning

This exists for backwards-compatability reasons. Using any value besides VALUE_ERROR is not recommended.

LIBPYTHON_LOC#: The absolute path to the Python library associated with the current Python installation; i.e. libpython.so or python.dll on Windows. This is determined with cocotb-config --libpython in cocotb’s makefiles.

COCOTB_TRUST_INERTIAL_WRITES#

Defining this variable enables a mode which allows cocotb to trust that VPI/VHPI/FLI inertial writes are applied properly according to the respective standards. This mode can lead to noticeable performance improvements, and also includes some behavioral difference that are considered by the cocotb maintainers to be “better”. Not all simulators handle inertial writes properly, so use with caution.

This is achieved by not scheduling writes to occur at the beginning of the ReadWrite mode, but instead trusting that the simulator’s inertial write mechanism is correct. This allows cocotb to avoid a VPI callback into Python to apply writes.

Note

This flag is enabled by default for GHDL and NVC simulators. More simulators may enable this flag by default in the future as they are gradually updated to properly apply inertial writes according to the respective standard.

Note

To test if your simulator behaves correctly with your simulator and version, first clone the cocotb github repo and run:

cd tests/test_cases/test_inertial_writes
make simulator_test SIM=<your simulator here> TOPLEVEL_LANG=<vhdl or verilog>

If the tests pass, your simulator and version apply inertial writes as expected and you can turn on COCOTB_TRUST_INERTIAL_WRITES.

Regression Manager#

COCOTB_TEST_MODULES#

The name of the Python module(s) to search for test functions - if your tests are in a file called test_mydesign.py, COCOTB_TEST_MODULES would 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.

Changed in version 2.0: MODULE is renamed to COCOTB_TEST_MODULES.

Deprecated since version 2.0: MODULE is a deprecated alias and will be removed.

COCOTB_TESTCASE#: A comma-separated list of tests to run. Does an exact match on the test name.

Changed in version 2.0: TESTCASE is renamed to COCOTB_TESTCASE.

Deprecated since version 2.0: TESTCASE is a deprecated alias and will be removed.

Deprecated since version 2.0: Use COCOTB_TEST_FILTER instead.

If matching only the exact test name is desired, use the regular expression anchor character $. For example, my_test$ will match my_test, but not my_test_2.

To run multiple tests, use regular expression alternations. For example, my_test|my_other_test.

Changed in version 2.0: Previously, if more than one test matched a test name in the TESTCASE list, only the first test that matched that test name in the COCOTB_TEST_MODULES list was run. Now, all tests that match the test name across all COCOTB_TEST_MODULESs are run.

Warning

Only one of COCOTB_TESTCASE or COCOTB_TEST_FILTER should be used.

COCOTB_TEST_FILTER#: A regular expression matching names of test function(s) to run. If this variable is not defined cocotb discovers and executes all functions decorated with the cocotb.test decorator in the supplied COCOTB_TEST_MODULES list.

Added in version 2.0.

Warning

Only one of COCOTB_TESTCASE or COCOTB_TEST_FILTER should be used.

COCOTB_RESULTS_FILE#: The file name where xUnit XML tests results are stored. If not provided, the default is results.xml.

Added in version 1.3.

COCOTB_USER_COVERAGE#

Enable to collect Python coverage data for user code. For some simulators, this will also report HDL coverage. If COCOTB_COVERAGE_RCFILE is not set, branch coverage is collected and files in the cocotb package directory are excluded.

This needs the coverage Python module to be installed.

Changed in version 2.0: COVERAGE is renamed to COCOTB_USER_COVERAGE.

Deprecated since version 2.0: COVERAGE is a deprecated alias and will be removed.

COCOTB_COVERAGE_RCFILE#

Location of a configuration file for coverage collection of Python user code using the the coverage module. See https://coverage.readthedocs.io/en/latest/config.html for documentation of this file.

If this environment variable is set, cocotb will not apply its own default coverage collection settings, like enabling branch coverage and excluding files in the cocotb package directory.

Added in version 1.7.

Changed in version 2.0: COVERAGE_RCFILE is renamed to COCOTB_COVERAGE_RCFILE.

Deprecated since version 2.0: COVERAGE_RCFILE is a deprecated alias and will be removed.

COCOTB_PDB_ON_EXCEPTION#: 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.

Scheduler#

COCOTB_SCHEDULER_DEBUG#: Enable additional log output of the coroutine scheduler.

GPI#

GPI_EXTRA#

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.

For example:

GPI_EXTRA=libnameA.so:entryA,libnameB.so:entryB will first load libnameA.so with entry point entryA , then load libnameB.so with entry point entryB.

Changed in version 1.4: Support for the custom entry point via : was added. Previously : was used as a separator between libraries instead of ,.

Changed in version 1.5: 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.

PyGPI#

PYGPI_PYTHON_BIN#: The Python binary in the Python environment to use with cocotb. This is set to the result of cocotb-config --python-bin in the Makefiles and Python Runner. You will likely only need to set this variable manually if you are using a Python environment other than the currently activated environment, or if you are using a custom flow.

PYGPI_USERS#

The Python module and callable that starts up the Python cosimulation environment. User overloads can be used to enter alternative Python frameworks or to hook existing cocotb functionality. The variable is formatted as path.to.entry.module:entry_point.function,other_module:other_func. The string before the colon is the Python module to import and the string following the colon is the object to call as the entry function. Multiple entry points can be specified by separating them with a comma.

The entry function must be a callable matching this form:

entry_function(argv: List[str]) -> None

Changed in version 1.8: level argument to _sim_event is no longer passed, it is assumed to be SIM_FAIL (2).

Changed in version 2.0: The entry-module-level functions _sim_event, _log_from_c, and _filter_from_c are no longer required.

Changed in version 2.0: Multiple entry points can be specified by separating them with a comma.

Changed in version 2.0: Renamed from PYGPI_ENTRY_POINT.

Makefile-based Test Scripts#

The following variables are makefile variables, not environment variables.

GUI#: Set this to 1 to enable the GUI mode in the simulator (if supported).

SIM#: Selects which simulator Makefile to use. Attempts to include a simulator specific makefile from src/cocotb/share/makefiles/simulators/makefile.$(SIM)

WAVES#: Set this to 1 to enable wave traces dump for the Aldec Riviera-PRO, Mentor Graphics Questa, and Icarus Verilog simulators. To get wave traces in Verilator see Waveforms.

TOPLEVEL_LANG#: Used to inform the makefile scripts which HDL language the top-level design element is written in. Currently it supports the values verilog for Verilog or SystemVerilog tops, and vhdl for 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.

VHDL_GPI_INTERFACE#

Explicitly sets the simulator interface to use when TOPLEVEL_LANG is vhdl. This includes the initial GPI interface loaded, and GPI_EXTRA library loaded in mixed language simulations. Valid values are vpi, vhpi, or fli. Not all simulators support all values; refer to the Simulator Support section for details.

Setting this variable is rarely needed as cocotb chooses a suitable default value depending on the simulator used.

VERILOG_SOURCES#: A list of the Verilog source files to include. Paths can be absolute or relative; if relative, they are interpreted as relative to the location where make was invoked.

VERILOG_INCLUDE_DIRS#: A list of the Verilog directories to search for include files. Paths can be absolute or relative; if relative, they are interpreted as relative to the location where make was invoked.

VHDL_SOURCES#: A list of the VHDL source files to include. Paths can be absolute or relative; if relative, they are interpreted as relative to the location where make was invoked.

VHDL_SOURCES_<lib>#: A list of the VHDL source files to include in the VHDL library lib (currently for GHDL/ModelSim/Questa/Xcelium/Incisive/Riviera-PRO only).

VHDL_LIB_ORDER#: A space-separated list defining the order in which VHDL libraries should be compiled (needed for ModelSim/Questa/Xcelium/Incisive, GHDL determines the order automatically).

COMPILE_ARGS#: Any arguments or flags to pass to the compile (analysis) stage of the simulation.

SIM_ARGS#: Any arguments or flags to pass to the execution of the compiled simulation.

RUN_ARGS#: 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.

EXTRA_ARGS#: 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.

COCOTB_PLUSARGS#: “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 $test$plusargs and $value$plusargs.

The special plusargs +ntb_random_seed and +seed, if present, are evaluated to set the random seed value if COCOTB_RANDOM_SEED is not set. If both +ntb_random_seed and +seed are set, +ntb_random_seed is used.

Changed in version 2.0: PLUSARGS is renamed to COCOTB_PLUSARGS.

Deprecated since version 2.0: PLUSARGS is a deprecated alias and will be removed.

SIM_CMD_PREFIX#

Prefix for simulation command invocations.

This can be used to add environment variables or other commands before the invocations of simulation commands. For example, SIM_CMD_PREFIX := LD_PRELOAD="foo.so bar.so" can be used to force a particular library to load. Or, SIM_CMD_PREFIX := gdb --args to run the simulation with the GDB debugger.

Added in version 1.6.

SIM_CMD_SUFFIX#

Suffix for simulation command invocations. Typically used to redirect simulator stdout and stderr:

# Prints simulator stdout and stderr to the terminal
# as well as capture it all in a log file "sim.log".
SIM_CMD_SUFFIX := 2>&1 | tee sim.log

Added in version 2.0.

COCOTB_HDL_TIMEUNIT#: 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 s, ms, us, ns, ps, fs.

Added in version 1.3.

COCOTB_HDL_TIMEPRECISION#: 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 s, ms, us, ns, ps, fs.

Added in version 1.3.

CUSTOM_COMPILE_DEPS#: 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 VERILOG_SOURCES or VHDL_SOURCES.

CUSTOM_SIM_DEPS#: Use to add additional dependencies to the simulation target.

SIM_BUILD#: Use to define a scratch directory for use by the simulator. The path is relative to the location where make was invoked. If not provided, the default scratch directory is sim_build.

SCRIPT_FILE#: 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.

TOPLEVEL_LIBRARY#: The name of the library that contains the COCOTB_TOPLEVEL module/entity. Only supported by the Aldec Riviera-PRO, Aldec Active-HDL, and Siemens EDA Questa 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 conventional variables for C and C++ compilation and linking: CFLAGS, CPPFLAGS, and LDFLAGS.