Cocotb 1.5.0 is out!

by Philipp Wagner on March 11, 2021

The cocotb project is proud to announce the release of its new version 1.5.0. cocotb is a COroutine based COsimulation TestBench environment for verifying VHDL/Verilog RTL using Python.

Cocotb can be installed and updated from PyPi through pip:

pip install --upgrade cocotb

For full installation instructions refer to the documentation at https://docs.cocotb.org/en/v1.5.0/install.html.

This release concluces a nine month development period, slightly longer than the last releases. A major focus of this release was stability and ease of use (again), with some nice new features thrown in.

Read on for some of the highlights in this release.

Assertion rewriting

assert statements are the most convenient way to check that the simulation is doing what it is expected to do, and code like this can be found in almost all cocotb testbenches:

# test_fifo.py
assert dut.dout.value.integer == expected_output

When this condition does not hold, cocotb will mark the test as failed and report the error.

In cocotb 1.4 the error report looks like that:

Test Failed: test_fifo_manual (result was AssertionError)
Traceback (most recent call last):
  File "/.../test_fifo.py", line 65, in test_fifo_manual
    assert dut.dout.value.integer == expected_output
AssertionError

Now compare that with cocotb 1.5:

Test Failed: test_fifo_manual (result was AssertionError)
Traceback (most recent call last):
  File "/.../test_fifo.py", line 65, in test_fifo_manual
    assert dut.dout.value.integer == expected_output
AssertionError: assert 101 == 100
+  where 101 = 01100101.integer
+    where 01100101 = ModifiableObject(fifo.dout).value
+      where ModifiableObject(fifo.dout) = HierarchyObject(fifo).dout

Now both the actual value read from the simulation (101) and the expected value (100) are shown, making debugging complex testbenches much more convenient.

There are two things you need to know about this new feature, which is called assertion rewriting:

  • Pytest must be installed. (You can check by typing pytest into a terminal.) Pytest can be easily installed with pip install pytest.
  • Assertion rewriting works best if you use assert dut.my_signal.value == something instead of just assert dut.my_signal == something.

Abstractions are hard work: build system and simulator support

Much of the power of cocotb comes from abstracting away the subtle differences between simulators, operating systems, compilers, and Python versions so that our users can focus on getting actual verification work done. Keeping this abstraction working for the wide range of possible combinations is hard work, and as usual we have made further refinements in this area.

For example, in this release we added support for building our compiled extension libraries with Microsoft Visual Studio C++, and fixed many small papercut issues related to various platforms.

Currently cocotb supports 11 simulators, here are some notable news items on that front:

  • Very early experimental support for Questa's VHPI interface has been added. (Continue using the default FLI interface unless you're in alpha testing mood!)
  • Support for the open source Verilator simulator has been much improved (it is still experimental). At the time of writing, only Verilator 4.106 is supported until a small Verilator issue #2778 is fixed.

Bus agents are now in cocotb-bus

Since very early on cocotb shipped with a limited set of bus agents and monitors, as well as a scoreboard class. While some of our users are routinely using these classes, others have written their custom replacements to better meet their needs.

To best suit both user groups and to kickstart the development of more advanced bus adapters, we have factored out the Bus and Scoreboard classes, as well as the cocotb.drivers and cocotb.monitors modules into a separate Python package named cocotb-bus.

For now, the old names will continue to exist, but their use will cause a DeprecationWarning, and will be removed in the future.

We invite all users interested in this area to have a look at the cocotb-bus repository on GitHub and get involved there. Let's shape the "perfect" bus verification IP together!

Deprecations

To make the migration to a future version of cocotb as easy as possible for our users we added deprecation warnings to our code base for some features where better alternatives exist.

If you see a deprecation warning after updating to cocotb 1.5 have a look at it and try to address it within the next half year or so. The warnings should give you enough information to address the problem quickly.

As usual: better documentation

cocotb prides itself with an ever-growing set of high-quality documentation. This time around we added two new examples, including a mixed-signal one. If you have a hard time remembering some cocotb features the documentation now contains a handy reference card.

And finally, for users who like to integrate cocotb into their own custom build and simulation flows (instead of using the provided makefiles) we now have a whole page dedicated to simulator-specific ways of running simulations with cocotb. (We still recommend starting with the makefiles and using them as reference for custom integrations.)

Looking forward: cocotb 2.0

After this 1.5 release we'll take the opportunity to say goodbye to some quirks in cocotb. We will be looking at the way signal values are represented in cocotb (the BinaryValue class) and solve some long-standing issues there. We also plan to look at some of cocotb's scheduling behavior and try to align it more with what users of recent approaches such as asyncio have come to expect. Surgery of this kind isn't possible in a fully backwards-compatible way, and that's why we'll release the next version as cocotb 2.0. Of course, breaking user testbenches is something we've never done lightly, and the next release will be no exception. We'll of course keep you all updated as soon as we figure out ourselves where the journey will take us!



A much more detailed description of all changes in this first 1.5 release can be found in the release notes at https://docs.cocotb.org/en/v1.5.0/release_notes.html.

Cocotb is a community project under the umbrella of the FOSSi Foundation. Thanks to all sponsors of the FOSSi Foundation the cocotb project can make use of a continuous integration system which runs proprietary simulators in a compliant way. We are also thankful to Aldec for providing a license of Riviera-PRO, ensuring that Riviera-PRO and cocotb continue to be well integrated.

Please reach out to Philipp at philipp@fossi-foundation.org if you or your company want to support cocotb, either financially to help pay for costs such as running our continuous integration setup, or with in-kind donations, such as simulator licenses.

To close this rather long release announcement, here are some statistics:

  • 319 files changed, 15016 insertions(+), 7546 deletions(-)
  • 312 commits
  • 19 code contributors
  • 1 new maintainer: Marlon James (@marlonjames on GitHub)

These numbers are impressive and showcase the power of the free and open source collaboration model. To be able to sustain this amount of change and the high-quality review process behind it we are happy to have an active group of maintainers caring for cocotb and its users. Thank you, and thanks to the whole cocotb community for coming together to create this unique piece of software.

And now, go and enjoy the best release of cocotb so far!

If you have questions or issues with this release head over to the issue tracker at https://github.com/cocotb/cocotb/issues with your question.