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 itertools

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.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((1, i % 5) for i in itertools.count())

    # 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.