cocotb testbenches (Verilator + VPI)

Explains how rtl_buddy integrates cocotb — a coroutine-based Python verification framework — to drive Verilator-compiled RTL via VPI, covering YAML configuration, pass/fail detection, and prerequisites.

Prerequisites

cocotb must be installed in the active Python environment:

uv add cocotb
# or: pip install cocotb

The runner calls cocotb-config at compile time. If it is missing, rtl_buddy raises a FatalRtlBuddyError with an actionable message rather than a raw traceback.

YAML shape

Add toplevel: and a cocotb: block to a testbench entry in tests.yaml. toplevel: is required when cocotb: is present — omitting it is a fatal config error caught at load time.

testbenches:
  - name: "tb_my_design"
    filelist:
      - "my_design.sv"
    toplevel: my_design          # required: DUT top-level module name
    cocotb:
      module: test_my_design     # Python module with @cocotb.test() coroutines

  - name: "tb_multi"
    filelist:
      - "my_design.sv"
    toplevel: my_design
    cocotb:
      module:                    # list form: all modules are loaded
        - test_smoke
        - test_corner_cases

tests:
  - name: "test_my_design"
    desc: "cocotb test"
    reglvl: 0
    model: "my_design"
    model_path: "../../design/block/models.yaml"
    testbench: "tb_my_design"

Pass/fail detection

cocotb writes a JUnit XML results file (cocotb_results.xml) instead of PASS/FAIL stdout lines. rtl_buddy parses this file automatically — do not add $display("PASS …") in cocotb tests. The desc field reports the first three failure messages with a (+N more) suffix when there are more.

Testbench field reference

Field	Type	Required	Description
toplevel	string	Yes (cocotb only)	Top-level DUT module name → COCOTB_TOPLEVEL
cocotb.module	string or list	Yes	Python test module(s) → COCOTB_TEST_MODULES

See rtl-buddy docs show reference/yaml for the full tests.yaml schema.