All releases are available from the GitHub Releases Page.
cocotb 1.6.0.dev0 (2021-09-23)
ModelSim and Questa now support compilation into a named VHDL library
Xcelium now supports compilation into a named VHDL library
VHDL signals that are zero bits in width now read as the integer
0, instead of raising an exception. (#2294)
Correctly parse plusargs with
=s in the value. (#2483)
Fixed discovery of signals inside SystemVerilog interfaces. (#2683)
The analog_model example has been added, showing how to use Python models for analog circuits together with a digital part. (#2438)
Deprecations and Removals
Setting values on indexed handles using the
handle[i] = valuesyntax is deprecated. Instead use the
handle[i].value = valuesyntax. (#2490)
Setting values on handles using the
dut.handle = valuesyntax is deprecated. Instead use the
handle.value = valuesyntax. (#2490)
Setting values on handles using the
signal <= newvalsyntax is deprecated. Instead, use the
signal.value = newvalsyntax. (#2681)
Assigning out-of-range Python integers to signals would previously truncate the value silently for signal widths <= 32 bits and truncate the value with a warning for signal widths > 32 bits. (#2316)
cocotb now requires Python 3.6+. (#2422)
Selecting tests using
TESTCASEwill now search for the first occurrence of a test of that name in order of modules listed in
MODULEs, and not just the first module in that list. (#2434)
Shorter log lines (configurable with
COCOTB_REDUCED_LOG_FMT) are now the default. For wider log output, similar to previous cocotb releases, set the
COCOTB_REDUCED_LOG_FMTenvironment variable to
Improves formatting on test-related logging outputs. (#2564)
cocotb 1.5.2 (2021-05-03)
cocotb 1.5.1 (2021-03-20)
cocotb 1.5.0 (2021-03-11)
Makefiles now automatically deduce
TOPLEVEL_LANGbased on the value of
VHDL_SOURCES. Makefiles also detect incorrect usage of
TOPLEVEL_LANGfor simulators that only support one language. (#1982)
cocotb.scheduler.start_soonwhich schedules a coroutine to start after the current coroutine yields control. This behavior is distinct from
cocotb.fork()which schedules the given coroutine immediately. (#2023)
cocotb.utils.get_sim_steps(), and the
'step'to mean the simulator time step. This used to be expressed using
None, which is now deprecated. (#2171)
Support for the SystemVerilog type
bithas been added. (#2322)
--lib-name-pathoptions to the
cocotb-configcommand to make cocotb integration into existing flows easier. (#2387)
Support for using Questa’s VHPI has been added. Use
VHDL_GPI_INTERFACEto select between using the FLI or VHPI when dealing with VHDL simulations. Note that VHPI support in Questa is still experimental at this time. (#2408)
Assigning Python integers to signals greater than 32 bits wide will now work correctly for negative values. (#913)
Fix GHDL’s library search path, allowing libraries other than work to be used in simulation. (#2038)
# Example pseudo-region dut.genblk1 #<class 'cocotb.handle.HierarchyArrayObject'>
Fixed an issue with VHPI on Mac OS and Linux where negative integers were returned as large positive values. (#2129)
Deprecations and Removals
The contents of
cocotb.generatorshave been deprecated. (#2047)
The outdated “Sorter” example has been removed from the documentation. (#2049)
The system task overloads for
$fatalin Verilog and mixed language testbenches have been removed. (#2133)
The undocumented class
cocotb.xunit_reporter.Filehas been removed. (#2200)
COCOTB_HOOKS. See the documentation for
cocotb.hookfor suggestions on alternatives. (#2201)
The outdated “ping” example has been removed from the documentation and repository. (#2232)
The access modes of many interfaces in the cocotb core libraries were re-evaluated. Some interfaces that were previously public are now private and vice versa. Accessing the methods through their old name will create a
DeprecationWarning. In the future, the deprecated names will be removed. (#2278)
The bus and testbenching components in cocotb have been officially moved to the cocotb-bus package. This includes
Scoreboard, everything in
cocotb_bus.drivers, and everything in
cocotb_bus.monitors. Documentation will remain in the main cocotb repository for now. Old names will continue to exist, but their use will cause a
DeprecationWarning, and will be removed in the future. (#2289)
Assigning negative Python integers to handles does an implicit two’s compliment conversion. (#913)
Cocotb 1.4.0 (2020-07-08)
Add support for distinguishing between
vpiReg) type when using the VPI interface. (#1107)
Cocotb now supports the following example of forking a non-decorated async coroutine.
async def example(): for i in range(10): await cocotb.triggers.Timer(10, "ns") cocotb.fork(example())
As such, it is now possible to override the default cocotb logging behavior with something like:
# remove the cocotb log handler and formatting root = logging.getLogger() for h in root.handlers[:]: root.remove_handler(h) h.close() # add your own logging.basicConfig()
Cocotb now supports deposit/force/release/freeze actions on simulator handles, exposing functionality similar to the respective Verilog/VHDL assignments.
from cocotb.handle import Deposit, Force, Release, Freeze dut.q <= 1 # A regular value deposit dut.q <= Deposit(1) # The same, higher verbosity dut.q <= Force(1) # Force value of q to 1 dut.q <= Release() # Release q from a Force dut.q <= Freeze() # Freeze the current value of q
Custom logging handlers can now access the simulator time using
logging.LogRecord.created_sim_time, provided the
SimTimeContextFilterfilter added by
default_config()is not removed from the logger instance. (#1411)
Questa now supports
PLUSARGS. This requires that
tcl.hbe present on the system. This is likely included in your installation of Questa, otherwise, specify
# Now supported dut.some_array <= [0xAA, 0xBB, 0xCC] dut.some_array.value = [0xAA, 0xBB, 0xCC] # For simulators that support n-dimensional arrays dut.some_2d_array <= [[0xAA, 0xBB], [0xCC, 0xDD]] dut.some_2d_array.value = [[0xAA, 0xBB], [0xCC, 0xDD]]
Added support for Aldec’s Active-HDL simulator. (#1601)
Makefile.incfrom user makefiles is now a no-op and deprecated. Lines like
include $(shell cocotb-config --makefiles)/Makefile.inccan be removed from user makefiles without loss in functionality. (#1629)
Tests which fail at initialization, for instance due to no
yieldbeing present, are no longer silently ignored (#1253)
Tests that were not run because predecessors threw
cocotb.result.SimFailure, and caused the simulator to exit, are now recorded with an outcome of
cocotb.result.SimFailure. Previously, these tests were ignored. (#1279)
Makefiles now correctly fail if the simulation crashes before a
results.xmlfile can be written. (#1314)
Logging of non-string messages with colored log output is now working. (#1410)
signal <= value_of_wrong_typeno longer breaks the scheduler, and throws an error immediately. (#1661)
for generatestatements using VHPI has been fixed. This bug caused some simulators to crash, and was a regression in version 1.3. (#1882)
XGMIIdriver no longer emits a corrupted word on the first transfer. (#1905)
Deprecations and Removals
The makefile variable
VERILATOR_TRACEthat was not supported for all simulators has been deprecated. Using it prints a deprecation warning and points to the documentation section Simulator Support explaining how to get the same effect by other means. (#1495)
BinaryValue.get_hex_buffproduced nonsense and has been removed. (#1511)
Makefile.pylib, which provided helpers for building C extension modules for Python, has been removed. Users of the
PYTHON_INCLUDEDIRvariables will now have to compute these values themselves. See the
endian_swapperexample for how to do this. (#1632)
Makefile and documentation for the NVC simulator which has never worked have been removed. (#1693)
Cocotb no longer supports Python 2, at least Python 3.5 is now required. Users of Python 2.7 can still use cocotb 1.3, but are heavily encouraged to update. It is recommended to use the latest release of Python 3 for improved performance over older Python 3 versions. (#767)
Mentor Questa, Aldec Riviera-PRO and GHDL are now started in the directory containing the Makefile and also save
results.xmlthere, bringing them in line with the behavior used by other simulators. (#1598) (#1599) (#1063)
All libraries are compiled during installation to the
cocotb/libsdirectory. The interface libraries
libcocotbvhpihave been renamed to have a
simulatormodule has moved to
LD_LIBRARY_PATHenvironment variable no longer needs to be set by the makefiles, as the libraries now discover each other via
The packets produced by the
There’s no longer any need to set the
PYTHON_BINmakefile variable, the Python executable automatically matches the one cocotb was installed into. (#1574)
Released on 08 July 2020
Released on 15 March 2020
Released on 08 January 2020
This will likely be the last release to support Python 2.7.
Initial support for the Verilator simulator (version 4.020 and above). The integration of Verilator into cocotb is not yet as fast or as powerful as it is for other simulators. Please use the latest version of Verilator, and report bugs if you experience problems.
New makefile variables
COCOTB_HDL_TIMEPRECISIONfor setting the default time unit and precision that should be assumed for simulation when not specified by modules in the design. (#1113)
cocotb.__version__constant, which contains the version number of the running cocotb. (#1196)
Notable changes and bug fixes
DeprecationWarnings are now shown in the output by default.
Tracebacks are now preserved correctly for exceptions in Python 2. The tracebacks in all Python versions are now a little shorter.
assertwill be considered a test failure. Previously, it was considered a test error.
Many (editorial) documentation improvements.
AvalonSTPktsWithChanneltype is deprecated. Use the
Released on 24 July 2019
asyncfunctions and generators was added (Python 3 only). Please have a look at Coroutines and Tasks for an example how to use this new feature.
VHDL block statements can be traversed. (#850)
Support for Python 3.7 was added.
Notable changes and bug fixes
The heart of cocotb, its scheduler, is now even more robust. Many small bugs, inconsistencies and unreliable behavior have been ironed out.
Exceptions are now correctly propagated between coroutines, giving users the “natural” behavior they’d expect with exceptions. (#633)
setimmediatevalue()function now works for values larger than 32 bit. (#768)
The documentation was cleaned up, improved and extended in various places, making it more consistent and complete.
Tab completion in newer versions of IPython is fixed. (#825)
Python 2.6 is officially not supported any more. cocotb supports Python 2.7 and Python 3.5+.
The cocotb GitHub project moved from
cocotb/cocotb. Redirects for old URLs are in place.
The bits argument to
BinaryValue, which is now called n_bits.
The logger attribute of log objects like
some_coro.log, which is now just an alias for
cocotb.utils.get_python_integer_typesfunction, which was intended to be private.
Depending on your simulation, cocotb 1.2 might be roughly 20 percent slower than cocotb 1.1. Much of the work in this release cycle went into fixing correctness bugs in the scheduler, sometimes at the cost of performance. We are continuing to investigate this in issue #961. Independent of the cocotb version, we recommend using the latest Python 3 version, which is shown to be significantly faster than previous Python 3 versions, and slightly faster than Python 2.7.
Please have a look at the issue tracker for more outstanding issues and contribution opportunities.
Released on 24 January 2019.
This release is the result of four years of work with too many bug fixes, improvements and refactorings to name them all. Please have a look at the release announcement on the mailing list for further information.
Released on 15 February 2015.
FLI support for ModelSim
Mixed Language, Verilog and VHDL
300% performance improvement with VHPI interface
WaveDrom support for wave diagrams.
Released on 25 February 2014.
Issue #101: Implement Lock primitive to support mutex
Issue #105: Compatibility with Aldec Riviera-Pro
Issue #109: Combine multiple
results.xmlinto a single results file
Issue #111: XGMII drivers and monitors added
Issue #113: Add operators to
Issue #116: Native VHDL support by implementing VHPI layer
Issue #117: Added AXI4-Lite Master BFM
Released on 27 September 2013.
This contains a raft of fixes and feature enhancements.
Released on 19 July 2013.
Release 0.2 supports more simulators and increases robustness over 0.1.
A centralized installation is now supported (see documentation) with supporting libraries build when the simulation is run for the first time.
Released on 9 July 2013.
The first release of cocotb.
Allows installation and running against Icarus, VCS, Aldec simulators.