Skip to main content

cocotb Testbenches

RTL Buddy runs cocotb tests through VPI on builders whose simulator family is verilator, icarus, xezim, or vcs. cocotb ships no xezim library, so xezim loads the VCS-flavour libcocotbvpi_vcs through --vpi-lib.

Install cocotb​

Install cocotb in the same environment as RTL Buddy:

uv add cocotb

RTL Buddy calls cocotb-config at compile time and reports an installation error if it is missing.

Configure the testbench​

Give the testbench entry a required toplevel: and a cocotb.module string or list:

testbenches:
  - name: tb_my_design
    filelist:
      - my_design.sv
    toplevel: my_design
    cocotb:
      module:
        - test_smoke
        - test_corner_cases

tests:
  - name: cocotb_smoke
    model: my_design
    model_path: ../../design/block/models.yaml
    testbench: tb_my_design
    reglvl: 0

Choose the simulator as for any test:

rb --builder icarus test cocotb_smoke
  • An unsupported simulator family or a missing toplevel: is a fatal configuration error.
  • toplevel: becomes COCOTB_TOPLEVEL and also sets the compile top (Verilator --top-module, VCS -top, Icarus and xezim -s), unless the builder's compile-time options already set one.

See Tests YAML for the schema and Simulation Backends for backend differences.

Interpret results​

cocotb writes cocotb_results.xml, which RTL Buddy parses. The result reports up to the first three failure messages plus a count of the rest. Do not add transcript PASS or FAIL markers to cocotb tests.