Welcome to cocotb’s documentation!

What is cocotb?

cocotb is a COroutine based COsimulation TestBench environment for verifying VHDL and SystemVerilog RTL using Python.

cocotb is completely free, open source (under the BSD License) and hosted on GitHub.

cocotb requires a simulator to simulate the HDL design and has been used with a variety of simulators on Linux, Windows and macOS. Please check the Simulator Support page for specifics.

A (possibly older) version of cocotb can be used live in a web browser on EDA Playground.

How is cocotb different?

cocotb encourages the same philosophy of design re-use and randomized testing as UVM, however is implemented in Python.

With cocotb, VHDL or SystemVerilog are normally only used for the design itself, not the testbench.

cocotb has built-in support for integrating with continuous integration systems, such as Jenkins, GitLab, etc. through standardized, machine-readable test reporting formats.

cocotb was specifically designed to lower the overhead of creating a test.

cocotb automatically discovers tests so that no additional step is required to add a test to a regression.

All verification is done using Python which has various advantages over using SystemVerilog or VHDL for verification:

  • Writing Python is fast - it’s a very productive language.

  • It’s easy to interface to other languages from Python.

  • Python has a huge library of existing code to re-use.

  • Python is interpreted - tests can be edited and re-run without having to recompile the design.

  • Python is popular - far more engineers know Python than SystemVerilog or VHDL.

How does cocotb work?

A typical cocotb testbench requires no additional RTL code. The Design Under Test (DUT) is instantiated as the toplevel in the simulator without any wrapper code. cocotb drives stimulus onto the inputs to the DUT (or further down the hierarchy) and monitors the outputs directly from Python. Note that cocotb can not instantiate HDL blocks - your DUT must be complete.

_images/cocotb_overview.svg

A test is simply a Python function. At any given time either the simulator is advancing time or the Python code is executing. The await keyword is used to indicate when to pass control of execution back to the simulator. A test can spawn multiple coroutines, allowing for independent flows of execution.