Simulator Support#
This page lists the simulators that cocotb can be used with and documents specifics, limitations, workarounds etc.
In general, cocotb can be used with any simulator supporting the industry-standard VPI, VHPI or FLI interfaces. However, in practice simulators exhibit small differences in behavior that cocotb mostly takes care of.
If a simulator you would like to use with cocotb is not listed on this page open an issue at the cocotb GitHub issue tracker.
Icarus Verilog#
In order to use this simulator, set SIM
to icarus
:
make SIM=icarus
Note
A working installation of Icarus Verilog is required. You can find installation instructions in the Icarus Verilog Installation Guide.
Accessing bits in a vector#
Accessing bits of a vector directly was not possible until (including) version 10.3:
dut.stream_in_data[2].value = 1
See also steveicarus/iverilog#323.
Waveforms#
Icarus Verilog can produce waveform traces in the FST format. FST traces are much smaller and more efficient to write than VCD. They can be viewed with GTKWave or with Surfer.
To enable FST tracing, set WAVES
to 1
.
make SIM=icarus WAVES=1
Issues for this simulator#
Verilator#
Warning
cocotb supports Verilator 5.026+.
Verilator is in the process of adding more functionality to its VPI interface, which is used by cocotb to access the design. Therefore, Verilator support in cocotb is currently experimental, and some features of cocotb may not work correctly or at all. If you encounter an issue using Verilator with cocotb, please try the newest release and check existing issues before opening a new one.
In order to use this simulator, set SIM
to verilator
:
make SIM=verilator
Note
A working installation of Verilator is required. You can find installation instructions in the Verilator documentation.
Note
Delayed assignments require the use of Verilator’s timing argument.
To run cocotb with Verilator, you need verilator
in your PATH.
Added in version 1.3.
Changed in version 1.5: Improved cocotb support and greatly improved performance when using a higher time precision.
Coverage#
To enable HDL code coverage, add Verilator’s coverage option(s) to the EXTRA_ARGS
make variable, for example:
EXTRA_ARGS += --coverage
This will result in coverage data being written to coverage.dat
.
Waveforms#
To get waveforms in VCD format, add Verilator’s trace option(s) to the
EXTRA_ARGS
make variable, for example in a Makefile:
EXTRA_ARGS += --trace --trace-structs
To set the same options on the command line, use EXTRA_ARGS="--trace --trace-structs" make ...
.
A VCD file named dump.vcd
will be generated in the current directory.
Verilator can produce waveform traces in the FST format. FST traces are much smaller and more efficient to write. They can be viewed with GTKWave or with Surfer.
To enable FST tracing, add --trace-fst
to EXTRA_ARGS
as shown below.
EXTRA_ARGS += --trace --trace-fst --trace-structs
The resulting file will be dump.fst
and can be opened by gtkwave dump.fst
.
Issues for this simulator#
Synopsys VCS#
In order to use this simulator, set SIM
to vcs
:
make SIM=vcs
cocotb currently only supports VPI for Synopsys VCS, not VHPI.
Issues for this simulator#
Aldec Riviera-PRO#
In order to use this simulator, set SIM
to riviera
:
make SIM=riviera
Note
On Windows, do not install the C++ compiler, i.e. unselect it during the installation process of Riviera-PRO.
(A workaround is to remove or rename the mingw
directory located in the Riviera-PRO installation directory.)
Deprecated since version 1.4: Support for Riviera-PRO was previously available with SIM=aldec
.
The LICENSE_QUEUE
environment variable can be used for this simulator –
this setting will be mirrored in the TCL license_queue
variable to control runtime license checkouts.
Issues for this simulator#
Aldec Active-HDL#
In order to use this simulator, set SIM
to activehdl
:
make SIM=activehdl
Warning
cocotb does not work with some versions of Active-HDL (see #1494).
Known affected versions:
Aldec Active-HDL 10.4a
Aldec Active-HDL 10.5a
Issues for this simulator#
Mentor/Siemens EDA Questa#
In order to use this simulator, set SIM
to questa
:
make SIM=questa
Starting with Questa 2022.3 and cocotb 1.7 users with VHDL toplevels can choose between two communication interfaces between Questa and cocotb: the proprietary FLI and VHPI.
For backwards-compatibility cocotb defaults to FLI.
Users can choose VHPI instead by setting the VHDL_GPI_INTERFACE
environment variable to vhpi
before running cocotb.
For more information, see Mentor/Siemens EDA ModelSim.
Issues for this simulator#
Mentor/Siemens EDA ModelSim#
In order to use this simulator, set SIM
to modelsim
:
make SIM=modelsim
Any ModelSim PE or ModelSim PE derivatives (like the ModelSim Microsemi, Intel, Lattice Editions) do not support the VHDL FLI feature.
If you try to use them with FLI, you will see a vsim-FLI-3155
error:
** Error (suppressible): (vsim-FLI-3155) The FLI is not enabled in this version of ModelSim.
ModelSim DE and SE (and Questa, of course) support the FLI.
In order to start ModelSim or Questa with the graphical interface and for the simulator to remain active after the tests have completed, set GUI=1
.
If you have previously launched a test without this setting, you might have to delete the SIM_BUILD
directory (sim_build
by default) to get the correct behavior.
Issues for this simulator#
Cadence Incisive#
In order to use this simulator, set SIM
to ius
:
make SIM=ius
For more information, see Cadence Xcelium.
Issues for this simulator#
Cadence Xcelium#
In order to use this simulator, set SIM
to xcelium
:
make SIM=xcelium
The simulator automatically loads VPI even when only VHPI is requested.
Testing designs with VHDL toplevels is only supported with Xcelium 23.09.004 and newer.
Issues for this simulator#
GHDL#
Warning
GHDL support in cocotb is experimental. Some features of cocotb may not work correctly or at all. At least GHDL 2.0 is required.
In order to use this simulator, set SIM
to ghdl
:
make SIM=ghdl
Note
A working installation of GHDL is required. You can find installation instructions in the GHDL documentation.
Noteworthy is that despite GHDL being a VHDL simulator, it implements the VPI interface. This prevents cocotb from accessing some VHDL-specific constructs, like 9-value signals.
To specify a VHDL architecture to simulate, set the ARCH
make variable to the architecture name.
Issues for this simulator#
Waveforms#
To get waveforms in VCD format, set the SIM_ARGS
option to --vcd=anyname.vcd
,
for example in a Makefile:
SIM_ARGS+=--vcd=anyname.vcd
The option can be set on the command line, as shown in the following example.
SIM_ARGS=--vcd=anyname.vcd make SIM=ghdl
A VCD file named anyname.vcd
will be generated in the current directory.
SIM_ARGS
can also be used to pass command line arguments related to other waveform formats supported by GHDL.
NVC#
Note
NVC version 1.11.0 or later is required.
In order to use this simulator, set SIM
to nvc
:
make SIM=nvc
Issues for this simulator#
Coverage#
To enable code coverage, add --cover
to SIM_ARGS
, for example
in a Makefile:
SIM_ARGS += --cover
Specifying types of coverage is also supported. For example, to collect statement and branch coverage:
SIM_ARGS += --cover=statement,branch
The covdb
files will be placed in the RTL_LIBRARY
subdirectory of SIM_BUILD
.
For instructions on how to specify coverage types and produce a report, refer to NVC’s code coverage documentation.
Waveforms#
To get waveforms in FST format, set the SIM_ARGS
option to --wave=anyname.fst
, for example in a Makefile:
SIM_ARGS += --wave=anyname.fst
SIM_ARGS
can also be used to set the waveform output to VCD by adding --format=vcd
.
Tachyon DA CVC#
In order to use Tachyon DA’s CVC simulator,
set SIM
to cvc
:
make SIM=cvc
Note that cocotb’s makefile is using CVC’s interpreted mode.