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 here.

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 https://github.com/steveicarus/iverilog/issues/323.

Waveforms

To get waveforms in VCD format some Verilog code must be added to the top component as shown in the example below:

module button_deb(
    input  clk,
    input  rst,
    input  button_in,
    output button_valid);

//... Verilog module code here

// the "macro" to dump signals
`ifdef COCOTB_SIM
initial begin
  $dumpfile ("button_deb.vcd");
  $dumpvars (0, button_deb);
  #1;
end
`endif
endmodule

Issues for this simulator

Verilator

Warning

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. Some features of cocotb may not work correctly or at all.

Currently cocotb only supports Verilator 4.106 (no earlier or later version). See also the corresponding cocotb issue #2300 and upstream issue.

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 here.

One major limitation compared to standard Verilog simulators is that it does not support delayed assignments when accessed from cocotb.

To run cocotb with Verilator, you need verilator in your PATH.

New 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, the native format of GTKWave. FST traces are much smaller and more efficient to write, but require the use of GTKWave.

To enable FST tracing, add --trace-fst to EXTRA_ARGS as shown below.

EXTRA_ARGS += --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.

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 here.

Noteworthy is that despite GHDL being a VHDL simulator, it implements the VPI interface.

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.

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.

Issues for this simulator