All releases are available from the GitHub Releases Page.
cocotb 1.5.0 (2021-03-11)¶
Support for building with Microsoft Visual C++ has been added. See Installation for more details. (#1798)
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.fork()will now raise a descriptive
TypeErrorif a coroutine function is passed into them. (#2006)
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)
pytestis installed, its assertion-rewriting framework will be used to produce more informative tracebacks from the
The handle to
TOPLEVEL, typically seen as the first argument to a cocotb test function, is now available globally as
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)
cocotb.regression.TestFactory.add_option()now supports groups of options when a full Cartesian product is not desired (#2175)
Added asyncio-style queues,
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)
Tests skipped by default (created with skip=True) can again be run manually by setting the
In Icarus Verilog, generate blocks are now accessible directly via lookup without having to iterate over parent handle. (#2079, #2143)
# 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)
The Mixed-signal (analog/digital) example has been added, showing how to use HDL helper modules in cocotb testbenches that exercise two mixed-signal (i.e. analog and digital) designs. (#1051)
New example Matrix Multiplier. (#1502)
A Reference Card showing the most used features of cocotb has been added. (#2321)
A chapter Extending existing build flows has been added. (#2340)
Deprecations and Removals¶
The contents of
cocotb.generatorshave been deprecated. (#2047)
The outdated “Sorter” example has been removed from the documentation. (#2049)
cocotb.testis deprecated. Pass a specific
Exceptionor a tuple of Exceptions instead. (#2117)
The system task overloads for
$fatalin Verilog and mixed language testbenches have been removed. (#2133)
TestErrorhas been deprecated, use Built-in Exceptions. (#2177)
The undocumented class
cocotb.xunit_reporter.Filehas been removed. (#2200)
COCOTB_HOOKS. See the documentation for
cocotb.hookfor suggestions on alternatives. (#2201)
unpack()and the use of
ctypes.Structurein signal assignments. (#2203)
The outdated “ping” example has been removed from the documentation and repository. (#2232)
Using the undocumented custom format
dictobject in signal assignments has been deprecated. (#2240)
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)
Monitor, and all their subclasses to use the
awaitsyntax instead of the
The package build process is now fully PEP 517 compliant. (#2091)
Improved support and performance for Verilator (version 4.106 or later now required). (#2105)
Changed how libraries are specified in
GPI_EXTRAto allow specifying libraries with paths, and names that don’t start with “lib”. (#2341)
Cocotb 1.4.0 (2020-07-08)¶
Lockcan now be used in
async withstatements. (#1031)
Add support for distinguishing between
vpiReg) type when using the VPI interface. (#1107)
Support for dropping into
pdbupon failure, via the new
COCOTB_PDB_ON_EXCEPTIONenvironment variable (#1180)
Simulators run through a Tcl script (Aldec Riviera Pro and Mentor simulators) now support a new
RUN_ARGSMakefile variable, which is passed to the first invocation of the tool during runtime. (#1244)
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())
The cocotb log configuration is now less intrusive, and only configures the root logger instance,
logging.getLogger(), as part of
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()
The colored output can now be disabled by the
NO_COLORenvironment variable. (#1309)
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
The name of the entry point symbol for libraries in
GPI_EXTRAcan now be customized. The delimiter between each library in the list has changed from
New methods for setting the value of a
NonHierarchyIndexableObject(HDL arrays). (#1507)
# 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)
Support for using
awaitinside an embedded IPython terminal, using
is_set(), so users may check if an
Eventhas fired. (#1723)
cocotb.simulator.is_running()function was added so a user of cocotb could determine if they are running within a simulator. (#1843)
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)
Getting and setting the value of a
NonHierarchyIndexableObjectnow iterates through the correct range of the simulation object, so arrays that do not start/end at index 0 are supported. (#1507)
XGMIImonitor no longer crashes on Python 3, and now assembles packets as
XGMIIdriver has expected
bytessince cocotb 1.2.0. (#1545)
signal <= value_of_wrong_typeno longer breaks the scheduler, and throws an error immediately. (#1661)
Scheduling behavior is now consistent before and after the first
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)
If a makefile uses cocotb’s
make helpnow lists the supported targets and variables. (#1318)
A new section Rotating Log Files has been added. (#1400)
The documentation at http://docs.cocotb.org/ has been restructured, making it easier to find relevant information. (#1482)
Deprecations and Removals¶
cocotb.utils.reject_remaining_kwargs()is deprecated, as it is no longer needed now that we only support Python 3.5 and newer. (#1339)
The value of
cocotb.handle.StringObjects is now of type
bytes, instead of
strwith an implied ASCII encoding scheme. (#1381)
ReturnValueis now deprecated. Use a
returnstatement instead; this works in all supported versions of Python. (#1489)
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)
bytesobjects should be passed instead. (#1519)
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)
Tests are now evaluated in order of their appearance in the
MODULEenvironment variable, their stage, and the order of invocation of the
cocotb.testdecorator within a module. (#1380)
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
cocotb.handle.NonHierarchyIndexableObject.valueis now a list in left-to-right range order of the underlying simulation object. Previously the list was always ordered low-to-high. (#1507)
Various binary representations have changed type from
bytes. These include:
cocotb.binary.BinaryValue.buff, which as a consequence means
cocotb.binary.BinaryValue.assign()no longer accepts malformed
strs (which were treated as binary).
The objects produced by
cocotb.generators.byte, which means that single bytes are represented by
intinstead of 1-character
The packets produced by the
Code working with these objects may find it needs to switch from creating
b"this". This change is a consequence of the move to Python 3. (#1514)
There’s no longer any need to set the
PYTHON_BINmakefile variable, the Python executable automatically matches the one cocotb was installed into. (#1574)
SIMsetting for Aldec Riviera-PRO has changed from
Certain methods on the
cocotb.simulatorPython module now throw a
RuntimeErrorwhen no simulator is present, making it safe to use
cocotbwithout a simulator present. (#1843)
Invalid values of the environment variable
COCOTB_LOG_LEVELare no longer ignored. They now raise an exception with instructions how to fix the problem. (#1898)
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.test(), for adding test timeouts. (#1119)
cocotb.triggers.with_timeout(), for a shorthand for waiting for a trigger with a timeout. (#1119)
cocotb.test()now accepts a specific exception type. (#1116)
New environment variable
COCOTB_RESULTS_FILE, to allow configuration of the xUnit XML output filename. (#1053)
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.
cocotb.function()now work more reliably and with fewer race conditions.
assertwill be considered a test failure. Previously, it was considered a test error.
loads()now also work correctly in Python 3.7 onwards.
cocotb.triggers.Timercan now be used with
decimal.Decimalinstances, allowing constructs like
Timer(Decimal('1e-9'), units='sec')as an alternate spelling for
Timer(100, units='us'). (#1114)
Many (editorial) documentation improvements.
cocotb.result.create_errorare deprecated in favor of using Python exceptions directly.
TestErrorcan still be used if the same exception type is desired. (#1109)
AvalonSTPktsWithChanneltype is deprecated. Use the
colourattribute of log objects like
some_coro.logis deprecated. Use
cocotb is now packaged for Fedora Linux and available as python-cocotb. (Fedora bug #1747574) (thanks Ben Rosser)
Released on 24 July 2019
cocotb is now built as Python package and installable through pip. (#517, #799, #800, #803, #805)
asyncfunctions and generators was added (Python 3 only). Please have a look at Coroutines 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.