Makefiles are provided for a variety of simulators in cocotb/share/makefiles/simulators. The common Makefile cocotb/share/makefiles/Makefile.sim includes the appropriate simulator Makefile based on the contents of the :makeSIM variable.
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.
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.
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.
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.
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 <quickstart_creating_a_test>.
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 1377424946To recreate the same stimuli use the following:
make RANDOM_SEED=1377424946See also: :makePLUSARGS
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=1forces output to be ANSI-colored regardless of the type of
stdoutor the presence ofNO_COLORCOCOTB_ANSI_OUTPUT=0suppresses 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_COLORenvironment variable that, when present (regardless of its value), prevents the addition of ANSI color.
COCOTB_REDUCED_LOG_FMT
If defined, log lines displayed in the terminal will be shorter. It will print only time, message type (INFO, WARNING, ERROR, ...) and the log message itself.
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. See the profile Make target in the endian_swapper example on how to set this up.
COCOTB_LOG_LEVEL
The default logging level to use. This is set to INFO unless overridden. Valid values are DEBUG, INFO, WARNING, ERROR, CRITICAL.
COCOTB_RESOLVE_X
Defines how to resolve bits with a value of X, Z, U or W when being converted to integer. Valid settings are:
VALUE_ERRORraise a
ValueErrorexceptionZEROSresolve to
0ONESresolve to
1RANDOMrandomly resolve to a
0or a1
Set to VALUE_ERROR by default.
MEMCHECK
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 cherrypy and dowser Python modules installed.
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.
MODULE
The name of the Python module(s) to search for test functions -if your tests are in a file called test_mydesign.py, MODULE 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.
TESTCASE
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.test decorator in the supplied MODULE list.
Multiple test functions can be specified using a comma-separated list.
COCOTB_RESULTS_FILE
The file name where xUnit XML tests results are stored. If not provided, the default is results.xml.
1.3
COVERAGE
Enable to report Python coverage data. For some simulators, this will also report HDL coverage.
This needs the coverage Python module to be installed.
COCOTB_HOOKS
A comma-separated list of modules that should be executed before the first test. You can also use the cocotb.hook decorator to mark a function to be run before test code.
1.5 cocotb.hook is deprecated, and in the future this variable will be ignored.
COCOTB_PDB_ON_EXCEPTION
If defined, cocotb will drop into the Python debugger (pdb) if a test fails with an exception. See also the troubleshooting-attaching-debugger-python subsection of troubleshooting-attaching-debugger.
COCOTB_SCHEDULER_DEBUG
Enable additional log output of the coroutine scheduler.
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:entryBwill first loadlibnameA.sowith entry pointentryA, then loadlibnameB.sowith entry pointentryB.
1.4.0 Support for the custom entry point via : was added. Previously : was used as a separator between libraries instead of ,.
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.
The following variables are makefile variables, not environment variables.
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.
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.
The following variables are used for cocotb internals. They may change at any time, and users should not rely on them.
COCOTB_PY_DIR
Path to the directory containing the cocotb Python package in the cocotb subdirectory.
COCOTB_SHARE_DIR
Path to the directory containing the cocotb Makefiles and simulator libraries in the subdirectories lib, include, and makefiles.
COCOTB_LIBRARY_COVERAGE
Enable code coverage collection for cocotb internals. When set, a file .coverage.cocotb will be written which contains statistics about the code coverage. This is mainly useful for cocotb's own Continuous Integration setup.