Getting Started with cocotb

This guide shows how to create a basic test for flow/storage hardware components (such as pipes, FIFOs, etc.) using the cocotb framework. Cocotb allows you to write testbenches in Python, which are then used to verify VHDL/Verilog designs.

The examples in this guide use the MVB FIFOX component test located at comp/mvb_tools/storage/fifox/cocotb/cocotb_test.py as a reference.

Quick Start

For beginners, the easiest way to get started is:

Create a ``cocotb`` folder in the directory of the component you want to test
Copy template files from an existing test (e.g., comp/mvb_tools/storage/fifox/cocotb/)
Modify the files for your component: - Update the TOPLEVEL in the Makefile to match your component name - Adjust signal names and bus parameters in the testbench - Update the model function to compute expected outputs for your component
Run the test using the Makefile

Note

For automatic generation of a test template, use the generate_test_template script in ndk-fpga/build/scripts/cocotb. This creates a basic test structure that you can customize.

Test Structure

A cocotb test consists of two main parts:

1. Testbench Class - Reusable setup code that encapsulates all test infrastructure:

Drivers - Objects that write stimulus data to the DUT (Device Under Test) input interfaces

Monitors - Objects that read output data from the DUT and convert it to transactions

Scoreboard - Compares actual outputs (from monitors) against expected outputs

Expected outputs - List of transactions that the DUT should produce

Optional objects - Probes for throughput measurement, bit drivers for backpressure testing

Reset sequence - Hardware reset initialization

The testbench class is typically reusable across multiple tests and can be copied/adapted for similar components.

2. Test Function - The actual test with:

@cocotb.test() decorator (required) - Marks the function as a cocotb test

async function definition (required) - Enables coroutine-based simulation

Test logic - Stimulus generation, DUT interaction, and verification

Example test file structure:

# SPDX-License-Identifier: BSD-3-Clause
# Copyright (C) 2025 CESNET z. s. p. o.
# Author(s): Ondřej Schwarz <ondrejschwarz@cesnet.cz>
#            Daniel Kondys <kondys@cesnet.cz>


# importing required modules
import cocotb
from cocotb.clock import Clock
from cocotb.triggers import RisingEdge, ClockCycles
from cocotbext.ofm.mvb.drivers import MVBDriver
from cocotbext.ofm.mvb.monitors import MVBMonitor
from cocotbext.ofm.ver.backpressure import BackpressureGenerator, BackpressureConfig
from cocotbext.ofm.ver.generators import random_integers
from cocotb_bus.drivers import BitDriver
from cocotb_bus.scoreboard import Scoreboard
from cocotbext.ofm.utils.throughput_probe import ThroughputProbe, ThroughputProbeMvbInterface
from cocotbext.ofm.base.generators import ItemRateLimiter
from cocotbext.ofm.mvb.transaction import MvbTrClassic


# definition of the class encapsulating components of the test
class testbench():
    # dut = device tree of the tested component
    def __init__(self, dut, debug=False):
        self.dut = dut

        # setting up the input driver and connecting it to signals beginning with "RX"
        self.stream_in = MVBDriver(dut, "RX", dut.CLK)

        # setting up the output monitor and connecting it to signals beginning with "TX"
        self.stream_out = MVBMonitor(dut, "TX", dut.CLK, tr_type=MvbTrClassic)

        # setting up driver of the DST_RDY so it randomly fluctuates between 0 and 1
        self.backpressure = BitDriver(dut.TX_DST_RDY, dut.CLK)

        # setting up the probe measuring throughput
        self.throughput_probe = ThroughputProbe(ThroughputProbeMvbInterface(self.stream_out), throughput_units="items")
        self.throughput_probe.set_log_period(10)
        self.throughput_probe.add_log_interval(0, None)

        # counter of sent transactions
        self.pkts_sent = 0

        # list of the transactions that are expected to be received
        self.expected_output = []

        # setting up a scoreboard which compares received transactions with the expected transactions
        self.scoreboard = Scoreboard(dut)

        # linking a monitor with its expected output
        self.scoreboard.add_interface(self.stream_out, self.expected_output)

        # setting up the logging level
        if debug:
            self.stream_in.log.setLevel(cocotb.logging.DEBUG)
            self.stream_out.log.setLevel(cocotb.logging.DEBUG)

    # method for adding transactions to the expected output
    def model(self, transaction):
        """Model the DUT based on the input transaction"""
        self.expected_output.append(transaction)
        self.pkts_sent += 1

    # method preforming a hardware reset
    async def reset(self):
        self.dut.RESET.value = 1
        await ClockCycles(self.dut.CLK, 10)
        self.dut.RESET.value = 0
        await RisingEdge(self.dut.CLK)


# defining a test - functions with "@cocotb.test()" decorator will be automatically found and run
@cocotb.test()
async def run_test(dut, pkt_count=10000):
    # start a clock generator
    cocotb.start_soon(Clock(dut.CLK, 5, units="ns").start())

    # initialization of the test bench
    tb = testbench(dut, debug=False)

    # change MVB driver's IdleGenerator to ItemRateLimiter
    # note: the RateLimiter's rate is affected by backpressure (DST_RDY).
    # Even though it takes into account cycles with DST_RDY=0, the desired rate might not be achievable.
    idle_gen_conf = dict(random_idles=True, max_idles=5, zero_idles_chance=50)
    tb.stream_in.set_idle_generator(ItemRateLimiter(rate_percentage=30, **idle_gen_conf))

    # running simulated reset
    await tb.reset()

    # starting the BitDriver (randomized DST_RDY)
    tb.backpressure.start(BackpressureGenerator(BackpressureConfig(1, 5, 0.5)))

    # dynamically getting the width of the data signal that will be set (useful if the width of the signal may change)
    data_width = tb.stream_in.item_widths["data"]

    # generating MVB items as random integers between the minimum and maximum unsigned value of the item
    for transaction in random_integers(0, 2**data_width-1, pkt_count):

        # logging the generated transaction
        cocotb.log.debug(f"generated transaction: {hex(transaction)}")

        # initializing MVB transaction object
        mvb_tr = MvbTrClassic()

        # setting data of MVB transaction to the generated integer
        mvb_tr.data = transaction

        # appending the transaction to tb.expected_output
        tb.model(mvb_tr)

        # passing the transaction to the driver which then writes it to the bus
        tb.stream_in.append(mvb_tr)

    last_num = 0

    # checking if all the expected packets have been received
    while (tb.stream_out.item_cnt < pkt_count):

        # logging number of received packets after every 1000 packets
        if (tb.stream_out.item_cnt // 1000) > last_num:
            last_num = tb.stream_out.item_cnt // 1000
            cocotb.log.info(f"Number of transactions processed: {tb.stream_out.item_cnt}/{pkt_count}")

        # if not all packets have been received yet, waiting 100 cycles so the simulation doesn't stop prematurely
        await ClockCycles(dut.CLK, 100)

    # logging values measured by throughput probe
    tb.throughput_probe.log_max_throughput()
    tb.throughput_probe.log_average_throughput()

    # displaying result of the test
    raise tb.scoreboard.result

Test Flow

A typical test follows these steps:

Start clock - Initialize the clock generator using cocotb.start_soon(Clock(...).start()). The clock drives the synchronous logic of the DUT.
Initialize testbench - Create the testbench object, which sets up all drivers, monitors, and the scoreboard.
Reset - Run the hardware reset sequence (typically 8-16 clock cycles with RESET high). This ensures the DUT starts in a known state.
Configure stimulus - Set up idle generators (to create realistic gaps in data) and backpressure drivers (to test DUT behavior when output is blocked).
Generate and send data - Create random transactions using helper functions like random_transactions or custom generators. Send them to the DUT via the driver’s append() method.
Model expected output - For each sent transaction, compute what the DUT should output and add it to the expected_output list. This is typically done in a model() method.
Wait for completion - Use a waiting loop to ensure all transactions are processed before checking results. Without this, the scoreboard might evaluate prematurely.
Check results - Raise tb.scoreboard.result to display pass/fail. The scoreboard automatically compares each received transaction against the expected output.

Required Files

To run a cocotb test, you need these files in your cocotb/ folder:

pyproject.toml - Python dependencies

This file declares the Python packages required for the test (cocotb, cocotbext-ndk, etc.). The build system uses it to create a virtual environment with all dependencies.

[project]
name = "cocotb-hash-table-simple-test"
version = "0.1.0"
dependencies = [
    "cocotbext-ofm @ ${NDK_FPGA_COCOTBEXT_OFM_URL}",
    "setuptools",
]

[build-system]
requires = ["pdm-backend"]
build-backend = "pdm.backend"

cocotb_test_sig.fdo - Simulator waveform signals

This script defines which signals will be visible in the simulator’s waveform viewer. Use it to debug failing tests by inspecting signal timing.

# coctb_test_sig.fdo : Include file with signals
# Copyright (C) 2024 CESNET z. s. p. o.
# Author(s): Jakub Cabal <cabal@cesnet.cz>
#
# SPDX-License-Identifier: BSD-3-Clause

view wave
delete wave *

add_wave -group {ALL} -noupdate -hex /mvb_fifox/*

config wave -signalnamewidth 1

Makefile - Build and run configuration

The Makefile specifies the simulator to use (Modelsim, Vivado, etc.), the top-level entity, and cocotb configuration. It handles building the simulation and running the test.

# Makefile: Makefile to compile module
# Copyright (C) 2024 CESNET z. s. p. o.
# Author(s): Ondřej Schwarz <Ondrej.Schwarz@cesnet.cz>
#
# SPDX-License-Identifier: BSD-3-Clause

TOP_LEVEL_ENT=mvb_fifox
TARGET=cocotb

.PHONY: all
all: comp

include ../../../../../build/Makefile

Note

Adjust component-specific values (TOPLEVEL, generics, parameters) and relative paths in all files to match your component.

Running the Test

Create Python virtual environment:
```
make cocotb-venv
```
This creates a virtual environment (typically in venv-<hash>/) with all dependencies from pyproject.toml.
Activate the environment:
```
source venv-xxx/bin/activate
```
Replace venv-xxx with the actual virtual environment folder name.
Run the test:
```
make
```
This builds the simulation (if needed) and runs the cocotb test. Results are printed to the terminal, and waveforms are saved for debugging.

To run the test in console-only mode (without launching the GUI waveform viewer), use:
```
make SIM_FLAGS=-c
```
This is useful for automated testing or when running tests on remote servers.

Tip

Use export COCOTB_LOG_LEVEL=DEBUG before running to enable debug logging for troubleshooting. See the Debug Logging section for more details.

Tip

If a test fails, examine the waveform file to understand the timing and identify the issue. The signals defined in cocotb_test_sig.fdo will be visible.

In case of having trouble with the automation, the test can also be run manually by following the subsequent steps.

Create Python virtual environment:

To manually create the virtual environment, issue:
```
python<version> -m venv venv-xxx
```
Use python3.11 as this is the mainline NDK-FPGA Python version.
Activate the environment:
```
source venv-xxx/bin/activate
```

Fetch the depedencies:

source <ndk-fpga>/env.sh && pip install .

Run the test:

Run the test as described above.