Skip to content
Switch branches/tags
Go to file
Cannot retrieve contributors at this time

Welcome to cocotb's documentation!

What is cocotb?

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

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

cocotb requires a simulator to simulate the :term:`HDL` design and has been used with a variety of simulators on Linux, Windows and macOS. Please check the :ref:`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 :term:`RTL` code. The Design Under Test (:term:`DUT`) is instantiated as the toplevel in the simulator without any wrapper code. cocotb drives stimulus onto the inputs to the :term:`DUT` (or further down the hierarchy) and monitors the outputs directly from Python. Note that cocotb can not instantiate :term:`HDL` blocks - your DUT must be complete.

A test is simply a Python function. At any given time either the simulator is advancing time or the Python code is executing. The :keyword:`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.

.. toctree::
   :maxdepth: 1


.. toctree::
   :maxdepth: 1
   :caption: Tutorials
   :name: tutorials


.. toctree::
   :maxdepth: 1
   :caption: How-to Guides
   :name: howto_guides


.. todo::
   - Add WaveDrom, IPython sections
   - How to deal with existing Verification IP?
   - Point to

.. toctree::
   :maxdepth: 1
   :caption: Key topics
   :name: key_topics


.. todo::
   - Move section "How does cocotb work?" from Introduction to here
   - Add some info from :doc:`coroutines`
   - Add GPI section
   - Explain ``ReadOnly``, ``ReadWrite``, ... phases
   - Add pitfall from to troubleshooting

.. toctree::
   :maxdepth: 1
   :caption: Reference
   :name: reference

   Python Code Library Reference <library_reference>
   GPI Library Reference <library_reference_c>

.. toctree::
   :maxdepth: 1
   :caption: Development & Community
   :name: development_community


.. todo::
   - Add "Join us online" and "Contributing"
   - In Contributing, add explanation on how to provide a PR, how to test existing PRs, etc.
   - merge `further_resources` into Contributing

.. toctree::
   :maxdepth: 1
   :caption: Index
   :name: index

   Classes, Methods, Variables etc. <genindex>
   Python Modules <py-modindex>