Release Notes¶
All releases are available from the GitHub Releases Page.
cocotb 1.4.0 (2020-07-08)¶
Features¶
Lock
can now be used inasync with
statements. (#1031)Add support for distinguishing between NET (vpiNet) and REG (vpiReg) type when using vpi interface. (#1107)
Support for dropping into
pdb
upon failure, via the newCOCOTB_PDB_ON_EXCEPTION
environment variable (#1180)Simulators run through a TCL script (Aldec Riviera Pro and Mentor simulators) now support a new
RUN_ARGS
Makefile 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())
Issue (#1255)
The cocotb log configuration is now less intrusive, and only configures the root logger instance,
logging.getLogger()
, as part ofcocotb.log.default_config()
(#1266).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()
Support for
vpiRealNet
(#1282)The colored output can now be disabled by the
NO_COLOR
environment 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
Issue (#1403)
Custom logging handlers can now access the simulator time using
logging.LogRecord.created_sim_time
, provided theSimTimeContextFilter
filter added bydefault_config()
is not removed from the logger instance. (#1411)Questa now supports
PLUSARGS
. This requires thattcl.h
be present on the system. This is likely included in your installation of Questa, otherwise, specifyCFLAGS=-I/path/to/tcl/includedir
. (#1424)The name of the entry point symbol for libraries in
GPI_EXTRA
can now be customized. The delimiter between each library in the list has changed from:
to,
. (#1457)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)
Including
Makefile.inc
from user makefiles is now a no-op and deprecated. Lines likeinclude $(shell cocotb-config --makefiles)/Makefile.inc
can be removed from user makefiles without loss in functionality. (#1629)Support for using
await
inside an embedded IPython terminal, usingcocotb.ipython_support
. (#1649)Added
is_set()
, so users may check if anEvent
has fired. (#1723)The
cocotb.simulator.is_running()
function was added so a user of cocotb could determine if they are running within a simulator. (#1843)
Bugfixes¶
Tests which fail at initialization, for instance due to no
yield
being 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 ofcocotb.result.SimFailure
. Previously, these tests were ignored. (#1279)Makefiles now correctly fail if the simulation crashes before a
results.xml
file can be written. (#1314)Logging of non-string messages with colored log output is now working. (#1410)
Getting and setting the value of a
NonHierarchyIndexableObject
now iterates through the correct range of the simulation object, so arrays that do not start/end at index 0 are supported. (#1507)The
XGMII
monitor no longer crashes on Python 3, and now assembles packets asbytes
instead ofstr
. TheXGMII
driver has expectedbytes
since cocotb 1.2.0. (#1545)signal <= value_of_wrong_type
no longer breaks the scheduler, and throws an error immediately. (#1661)Scheduling behavior is now consistent before and after the first
await
of aGPITrigger
. (#1705)Iterating over
for generate
statements using VHPI has been fixed. This bug caused some simulators to crash, and was a regression in version 1.3. (#1882)The
XGMII
driver no longer emits a corrupted word on the first transfer. (#1905)
Improved Documentation¶
If a makefile uses cocotb’s
Makefile.sim
,make help
now 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.StringObject
s is now of typebytes
, instead ofstr
with an implied ASCII encoding scheme. (#1381)ReturnValue
is now deprecated. Use areturn
statement instead; this works in all supported versions of Python. (#1489)The makefile variable
VERILATOR_TRACE
that 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_buff
produced nonsense and has been removed. (#1511)Passing
str
instances tococotb.utils.hexdump()
andcocotb.utils.hexdiffs()
is deprecated.bytes
objects should be passed instead. (#1519)Makefile.pylib
, which provided helpers for building C extension modules for Python, has been removed. Users of thePYTHON_LIBDIR
andPYTHON_INCLUDEDIR
variables will now have to compute these values themselves. See theendian_swapper
example for how to do this. (#1632)Makefile and documentation for the NVC simulator which has never worked have been removed. (#1693)
Changes¶
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.xml
there, 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
MODULE
environment variable, their stage, and the order of invocation of thecocotb.test
decorator within a module. (#1380)All libraries are compiled during installation to the
cocotb/libs
directory. The interface librarieslibcocotbvpi
andlibcocotbvhpi
have been renamed to have a_simulator_name
postfix. Thesimulator
module has moved tococotb.simulator
. TheLD_LIBRARY_PATH
environment variable no longer needs to be set by the makefiles, as the libraries now discover each other viaRPATH
settings. (#1425)cocotb.handle.NonHierarchyIndexableObject.value
is 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
str
tobytes
. These include:cocotb.binary.BinaryValue.buff
, which as a consequence meanscocotb.binary.BinaryValue.assign()
no longer accepts malformed10xz
-stylestr
s (which were treated as binary).The objects produced by
cocotb.generators.byte
, which means that single bytes are represented byint
instead of 1-characterstr
s.The packets produced by the
AvalonSTPkts
.
Code working with these objects may find it needs to switch from creating
str
objects like"this"
tobytes
objects likeb"this"
. This change is a consequence of the move to Python 3. (#1514)There’s no longer any need to set the
PYTHON_BIN
makefile variable, the Python executable automatically matches the one cocotb was installed into. (#1574)The
SIM
setting for Aldec Riviera-PRO has changed fromaldec
toriviera
. (#1691)Certain methods on the
cocotb.simulator
Python module now throw aRuntimeError
when no simulator is present, making it safe to usecocotb
without a simulator present. (#1843)Invalid values of the environment variable
COCOTB_LOG_LEVEL
are no longer ignored. They now raise an exception with instructions how to fix the problem. (#1898)
cocotb 1.3.1¶
Released on 15 March 2020
cocotb 1.3.0¶
Released on 08 January 2020
This will likely be the last release to support Python 2.7.
New features¶
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_TIMEUNIT
andCOCOTB_HDL_TIMEPRECISION
for setting the default time unit and precision that should be assumed for simulation when not specified by modules in the design. (#1113)New
timeout_time
andtimeout_unit
arguments tococotb.test()
, for adding test timeouts. (#1119)cocotb.triggers.with_timeout()
, for a shorthand for waiting for a trigger with a timeout. (#1119)The
expect_error
argument tococotb.test()
now accepts a specific exception type. (#1116)New environment variable
COCOTB_RESULTS_FILE
, to allow configuration of the xunit XML output filename. (#1053)A new
bus_separator
argument tococotb.drivers.BusDriver
. (#1160)A new
start_high
argument tococotb.clock.Clock.start()
. (#1036)A new
cocotb.__version__
constant, which contains the version number of the running cocotb. (#1196)
Notable changes and bug fixes¶
DeprecationWarning
s 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.external()
andcocotb.function()
now work more reliably and with fewer race conditions.A failing
assert
will be considered a test failure. Previously, it was considered a test error.drivers()
andloads()
now also work correctly in Python 3.7 onwards.cocotb.triggers.Timer
can now be used withdecimal.Decimal
instances, allowing constructs likeTimer(Decimal('1e-9'), units='sec')
as an alternate spelling forTimer(100, units='us')
. (#1114)Many (editorial) documentation improvements.
Deprecations¶
cocotb.result.raise_error
andcocotb.result.create_error
are deprecated in favor of using Python exceptions directly.TestError
can still be used if the same exception type is desired. (#1109)The
AvalonSTPktsWithChannel
type is deprecated. Use thereport_channel
argument toAvalonSTPkts
instead.The
colour
attribute of log objects likecocotb.log
orsome_coro.log
is deprecated. Usecocotb.utils.want_color_output()
instead. (#1231)
Other news¶
cocotb is now packaged for Fedora Linux and available as python-cocotb. (Fedora bug #1747574) (thanks Ben Rosser)
cocotb 1.2.0¶
Released on 24 July 2019
New features¶
cocotb is now built as Python package and installable through pip. (#517, #799, #800, #803, #805)
Support for
async
functions 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)
The
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
potentialventures/cocotb
tococotb/cocotb
. Redirects for old URLs are in place.
Deprecations¶
The bits argument to
BinaryValue
, which is now called n_bits.The logger attribute of log objects like
cocotb.log
orsome_coro.log
, which is now just an alias forself
.The
cocotb.utils.get_python_integer_types
function, which was intended to be private.
Known issues¶
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.
cocotb 1.1¶
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.
cocotb 1.0¶
Released on 15 February 2015.
New features¶
FLI support for ModelSim
Mixed Language, Verilog and VHDL
Windows
300% performance improvement with VHPI interface
WaveDrom support for wave diagrams.
cocotb 0.4¶
Released on 25 February 2014.
New features¶
Issue #101: Implement Lock primitive to support mutex
Issue #105: Compatibility with Aldec Riviera-Pro
Issue #109: Combine multiple
results.xml
into a single results fileIssue #111: XGMII drivers and monitors added
Issue #113: Add operators to
BinaryValue
classIssue #116: Native VHDL support by implementing VHPI layer
Issue #117: Added AXI4-Lite Master BFM
Bugs fixed¶
cocotb 0.2¶
Released on 19 July 2013.
New features¶
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.
cocotb 0.1¶
Released on 9 July 2013.
The first release of cocotb.
Allows installation and running against Icarus, VCS, Aldec simulators.