rules_cocotb

Bazel rules that run cocotb Python testbenches against Verilog/SystemVerilog and VHDL modules using open-source HDL simulators (Verilator, Icarus Verilog, GHDL).

Overview

A cocotb_test is a Bazel test target that pairs:

• a Verilog or VHDL *_library target (from rules_verilog or rules_vhdl) as the module under test,
• one or more Python cocotb test sources, and
• a cocotb_toolchain that picks the simulator.

The top-level rules are documented under Rules; the per-simulator integrations live under Simulators.

End-to-end example

The walkthrough below builds a tiny 8-bit adder, drives it from a Python cocotb testbench, and runs the test with Verilator.

MODULE.bazel

bazel_dep(name = "rules_verilog", version = "1.1.1")
bazel_dep(name = "rules_cocotb", version = "{version}")

rules_cocotb registers a default toolchain (//cocotb/toolchain:toolchain) wired to Verilator (default), Icarus Verilog, and GHDL. No further register_toolchains call is required to use the bundled simulators.

adder.sv

module adder (
    input  [7:0] x,
    input  [7:0] y,
    input        carry_in,
    output       carry_output_bit,
    output [7:0] sum
);
    logic [8:0] result;
    assign result           = x + y + carry_in;
    assign sum              = result[7:0];
    assign carry_output_bit = result[8];
endmodule

adder_test.py

import cocotb
from cocotb.handle import HierarchyObject
from cocotb.triggers import Timer


@cocotb.test()
async def test_adder(dut: HierarchyObject) -> None:
    """Drive a handful of vectors through the 8-bit adder."""
    vectors = [
        # (x, y, carry_in, expected_sum, expected_carry_out)
        (0x00, 0x00, 0, 0x00, 0),
        (0xFF, 0x01, 0, 0x00, 1),
        (0x55, 0xAA, 1, 0x00, 1),
    ]
    for x, y, cin, exp_sum, exp_cout in vectors:
        dut.x.value = x
        dut.y.value = y
        dut.carry_in.value = cin
        await Timer(1, units="ns")
        sum_val = int(dut.sum.value)
        cout_val = int(dut.carry_output_bit.value)
        assert sum_val == exp_sum and cout_val == exp_cout, (
            f"adder mismatch for x={x:#04x} y={y:#04x} cin={cin}"
        )

BUILD.bazel

load("@rules_verilog//verilog:defs.bzl", "verilog_library")
load("@rules_cocotb//cocotb:cocotb_test.bzl", "cocotb_test")

verilog_library(
    name = "adder",
    srcs = ["adder.sv"],
)

cocotb_test(
    name = "adder_test",
    srcs = ["adder_test.py"],
    module = ":adder",
    sim = "verilator",
)

Run it

$ bazel test //path/to:adder_test
//path/to:adder_test                                                     PASSED

To rerun under Icarus instead, change sim = "verilator" to sim = "icarus". To swap to a VHDL toplevel, replace verilog_library with vhdl_library from rules_vhdl and pick sim = "ghdl".

Going further

• The cocotb_test reference covers the full attribute set (params, sim_opts, env, etc.).
• The cocotb_toolchain reference shows how to define a custom toolchain — for selecting a different default simulator, narrowing the set of simulators, or wiring in a bring-your-own-install cocotb_*_sim.
• The cocotb_stubgen reference covers generating typed Python stubs from an HDL library, so a testbench's dut parameter type-checks instead of being an untyped HierarchyObject.
• The Simulators section lists every built-in simulator integration and per-simulator status.

Rules

• cocotb_test
• cocotb_toolchain
• cocotb_stubgen

cocotb_test

Rules

• cocotb_test

cocotb_test

load("@rules_cocotb//cocotb:cocotb_test.bzl", "cocotb_test")

cocotb_test(name, deps, srcs, data, env, module, params, precompiled_libs, sim, sim_opts)

Run a test using cocotb on a given Verilog/VHDL module.

ATTRIBUTES

cocotb_toolchain

Rules

• cocotb_toolchain

cocotb_toolchain

load("@rules_cocotb//cocotb:cocotb_toolchain.bzl", "cocotb_toolchain")

cocotb_toolchain(name, cocotb, default_sim, env, simulators, vhdl_libraries)

Define a toolchain for cocotb_* rules.

The toolchain bundles a cocotb Python library with a set of HDL simulators that cocotb_test targets can select between via their sim attribute. Register an instance with the standard toolchain(...) wrapper to make it discoverable.

Registering simulators

Each entry in simulators is a cocotb_*_sim target keyed by the string name that cocotb_test(sim = ...) will use to select it. Names are user-chosen — common conventions are "verilator", "icarus", "ghdl". Each name must be unique within the dict.

load("@rules_cocotb//cocotb:cocotb_ghdl_sim.bzl", "cocotb_ghdl_sim")
load("@rules_cocotb//cocotb:cocotb_icarus_sim.bzl", "cocotb_icarus_sim")
load("@rules_cocotb//cocotb:cocotb_toolchain.bzl", "cocotb_toolchain")
load("@rules_cocotb//cocotb:cocotb_verilator_sim.bzl", "cocotb_verilator_sim")

# Instantiate the sim rules you want to ship.
cocotb_verilator_sim(
    name = "cocotb_verilator",
    # ... (see //cocotb/toolchain:BUILD.bazel for the full attr set)
)

cocotb_ghdl_sim(
    name = "cocotb_ghdl",
    ghdl = "@ghdl",
    vhdl_libs = ["@ghdl//:vhdl_libs_v08"],
)

cocotb_icarus_sim(
    name = "cocotb_icarus",
    iverilog = "@iverilog//:iverilog",
    vvp = "@iverilog//:vvp",
    ivl_files = {
        "@iverilog//:ivl": "ivl",
        # ... (see //cocotb/toolchain:BUILD.bazel for the full map)
    },
)

cocotb_toolchain(
    name = "my_cocotb_toolchain",
    cocotb = "//path/to:cocotb_py_library",
    default_sim = "verilator",
    simulators = {
        ":cocotb_ghdl": "ghdl",
        ":cocotb_icarus": "icarus",
        ":cocotb_verilator": "verilator",
    },
)

toolchain(
    name = "my_toolchain",
    toolchain = ":my_cocotb_toolchain",
    toolchain_type = "@rules_cocotb//cocotb:toolchain_type",
)

Add register_toolchains("//path/to:my_toolchain") to MODULE.bazel ahead of //cocotb/toolchain to override the default. default_sim chooses which simulator runs when a cocotb_test omits its own sim attribute; it's optional, but if set must name one of the keys in simulators.

Supplying VHDL standard libraries

vhdl_libraries is optional and empty by default, and is the only part of this toolchain that cocotb_stubgen reads. It reads it optionally: stub generation is static analysis of HDL sources and runs no simulator, so a project that only wants typed DUT handles need not register a cocotb_toolchain at all.

The generator shipped today works from the parse tree alone — it maps each port's terminal type mark (std_logic, unsigned, integer, ...) onto a cocotb handle class, which covers designs whose ports are declared in terms of the standard types directly — and so ignores these sources. The attr reserves the interface for full elaboration, which would additionally resolve project-local aliases and subtypes through to their base types; until that lands, setting it only adds the files to each stubgen action's inputs:

vhdl_library(
    name = "std",
    srcs = glob(["std/*.vhdl"]),
)

vhdl_library(
    name = "ieee",
    srcs = glob(["ieee2008/*.vhdl"]),
    deps = [":std"],
)

cocotb_toolchain(
    name = "my_cocotb_toolchain",
    cocotb = "//path/to:cocotb_py_library",
    simulators = {":cocotb_ghdl": "ghdl"},
    vhdl_libraries = [":ieee"],
)

Each entry is a vhdl_library; the VHDL library name comes from its library attr, which defaults to the target name. Libraries reached through deps count too, so listing :ieee above is enough to pull in :std. Several targets may share a library name.

Only ieee and std are accepted, and the set must be complete: a partial set is rejected rather than honored, because unresolved types degrade to Any silently instead of erroring.

Note that @ghdl//:vhdl_libs_v08 is not usable here: it is a compiled GHDL library artifact for cocotb_ghdl_sim(vhdl_libs = ...), whereas this attr wants VHDL sources for the parser.

Per-simulator API and wiring details live in the Simulators section.

ATTRIBUTES

cocotb_stubgen

Rules

• cocotb_stubgen

cocotb_stubgen

load("@rules_cocotb//cocotb:cocotb_stubgen.bzl", "cocotb_stubgen")

cocotb_stubgen(name, module)

Generate typed cocotb DUT stubs for an HDL library.

Point module at a vhdl_library or verilog_library and the rule produces a PyInfo target you add to any Python rule's deps (most commonly cocotb_test.deps) to make the DUT's ports and signals type-check.

Example — a VHDL DUT tests/foo/dut.vhd:

vhdl_library(
    name = "dut",
    srcs = ["dut.vhd"],
)

cocotb_stubgen(
    name = "dut_stubs",
    module = ":dut",
)

cocotb_test(
    name = "dut_test",
    srcs = ["dut_test.py"],
    module = ":dut",
    deps = [":dut_stubs"],
    sim = "ghdl",
)

One class is emitted per entity / module found in each HDL source, each subclassing cocotb.handle.HierarchyObject so it can stand in as the DUT parameter's type directly. The import path mirrors the HDL source's own package and basename — tests/foo/dut.vhd yields a Dut class importable as:

from tests.foo.dut import Dut

async def test(dut: Dut) -> None:
    dut.clk.value = 0

VHDL ports / generics / architecture signals are typed against cocotb's handle hierarchy (LogicObject, LogicArrayObject, IntegerObject, ...). Verilog ports, parameters and nets fall back to typing.Any — Verilog declarations are effectively untyped once logic / wire / reg are flattened. Instantiations in either language type as the instantiated entity's own stub class.

Verilog is parsed without preprocessing, so ports supplied by a macro (module m(`MY_PORTS);) are omitted rather than guessed at.

The generator is the one rules_cocotb ships and is not swappable. No cocotb_toolchain is required either — stub generation is static analysis and runs no simulator. Registering one contributes only its optional vhdl_libraries, which the generator shipped today ignores; see cocotb_toolchain.

ATTRIBUTES

Simulators

A simulator integration is a Bazel rule that wires a specific HDL simulator into the cocotb test harness. cocotb_test doesn't talk to simulators directly — it picks one of the simulators registered in the active cocotb_toolchain by name (via its sim attribute), and the toolchain dispatches compile + run through the matching cocotb_*_sim target.

Each cocotb_*_sim rule produces a CocotbSimInfo provider that the shared cocotb_test rule consumes. New simulator integrations can be added by writing a rule that returns the same provider and registering it in a cocotb_toolchain.simulators dict.

Built-in integrations

The default toolchain (//cocotb/toolchain:toolchain) registers only the CI-verified row — Verilator (default), Icarus Verilog, and GHDL. For any other simulator, define your own cocotb_toolchain that wires the relevant cocotb_*_sim to your install and register it ahead of the default.

The "CI-verified" column is what rules_cocotb's own //tests/... exercises. The other rules are wired correctly against cocotb's runner classes, but rules_cocotb can't ship the binaries (commercial license or no BCR module yet), so we can't validate them ourselves — please file issues if you hit problems wiring one up.

Other simulators

Tachyon DA CVC has no cocotb_tools.runner class as of the cocotb version pinned by this module, so there's no cocotb_cvc_sim rule. If/when cocotb adds runner support upstream we can add the wiring.

Per-simulator status, known limitations, and any downstream-wiring patterns are inline on each simulator's reference page.

cocotb_ghdl_sim

Rules

• cocotb_ghdl_sim

cocotb_ghdl_sim

load("@rules_cocotb//cocotb:cocotb_ghdl_sim.bzl", "cocotb_ghdl_sim")

cocotb_ghdl_sim(name, env, ghdl, ghdl_coverage, ghdl_prefix, vhdl_libs)

A simulator configuration for running GHDL simulations in cocotb tests.

Status

Working against the BCR ghdl module from version 6.0.0.bcr.1 onward, which links the ghdl binary with -Wl,--export-dynamic and the upstream src/grt/grt.ver version script so cocotb's libcocotbvpi_ghdl.so can resolve unprefixed vpi_* symbols at dlopen time. Earlier ghdl@6.0.0 is missing those linker flags and fails at sim time with undefined symbol: vpi_register_cb.

The backend is selectable with --@ghdl//:backend={mcode, llvm-jit} (default mcode on x86_64, llvm-jit elsewhere).

Notes

GHDL only supports VHDL (VhdlInfo); pair it with a vhdl_library target as the module. The integration is build-at-test-time: cocotb's runner runs ghdl -a/-m in a writable build_dir via Runner.build(). Pre-compiling at Bazel time isn't viable because the JIT backends bake absolute sandbox paths into the .cf files.

The vhdl_libs attribute should point at the pre-compiled IEEE/std libraries from the BCR ghdl module — most projects want ["@ghdl//:vhdl_libs_v08"].

ATTRIBUTES

cocotb_icarus_sim

Rules

• cocotb_icarus_sim

cocotb_icarus_sim

load("@rules_cocotb//cocotb:cocotb_icarus_sim.bzl", "cocotb_icarus_sim")

cocotb_icarus_sim(name, env, iverilog, ivl_base, ivl_files, vvp)

A simulator configuration for running Icarus Verilog binaries in cocotb tests.

Status

Fully functional. Sourced from the BCR iverilog module (bazel_dep(name = "iverilog", version = "13.0.bcr.1")). The default toolchain wires iverilog, vvp, and the IVL backend components. Exercised end-to-end by the in-tree adder_icarus_test.

Notes

The iverilog driver locates its backend components (ivl, vvp.tgt, system.vpi, etc.) via the IVL_BASE environment variable. For the BCR iverilog module, the components are exposed as individual labels; this rule's ivl_files attribute maps each label to its expected filename and assembles them into a directory for IVL_BASE.

Icarus only supports Verilog/SystemVerilog (VerilogInfo); pair it with a verilog_library target as the module.

ATTRIBUTES

cocotb_verilator_sim

Rules

• cocotb_verilator_sim

cocotb_verilator_sim

load("@rules_cocotb//cocotb:cocotb_verilator_sim.bzl", "cocotb_verilator_sim")

cocotb_verilator_sim(name, deps, cocotb, copts, copy_tree, env, process_wrapper, verilator,
                     verilator_coverage)

A simulator configuration for compiling Verilator binaries to be run in cocotb tests.

Status

Fully functional. Sourced from the verilator and rules_verilator BCR modules; the default toolchain wires @verilator//:verilator_executable together with cocotb's share/lib/verilator/verilator.cpp entrypoint. Used by the in-tree adder_test smoke test, which passes end-to-end.

Notes

Verilator only supports Verilog/SystemVerilog (VerilogInfo); pair it with a verilog_library target as the module. The sim_opts attribute on cocotb_test is forwarded to the underlying verilator invocation — e.g. sim_opts = ["--trace-fst"] enables FST waveform capture.

The BCR verilator binary needs the rules_verilator process wrapper to set up its include / lib paths, and cocotb's verilator.cpp front-end plus its VPI shared libraries to link against. The rule locates those inside the cocotb pip wheel automatically — point cocotb at any py_library wrapping @cocotb_pip_deps//cocotb and the rule extracts what it needs internally.

ATTRIBUTES

cocotb_nvc_sim

Rules

• cocotb_nvc_sim

cocotb_nvc_sim

load("@rules_cocotb//cocotb:cocotb_nvc_sim.bzl", "cocotb_nvc_sim")

cocotb_nvc_sim(name, env, nvc, nvc_libpath, vhdl_libs)

A simulator configuration for running NVC (open-source VHDL simulator) in cocotb tests.

Status

Working against the BCR nvc module from version 1.21.0 onward, which links the nvc binary with -Wl,--dynamic-list=src/symbols.txt so cocotb's libcocotbvpi_nvc.so plugin can resolve unprefixed vpi_* / vhpi_* symbols at dlopen time.

Notes

NVC only supports VHDL (VhdlInfo); pair it with a vhdl_library target as the module. The integration is build-at-test-time: cocotb's runner runs nvc -a / -e / -r in a writable build_dir via Runner.build() / Runner.test().

vhdl_libs accepts a list of per-library TreeArtifact targets — typically ["@nvc//:vhdl_libs"], the BCR nvc module's filegroup of per-library directories laid out exactly like a system install under <prefix>/lib/nvc/<library>/. The rule's implementation stages those TreeArtifacts side-by-side under a single root and points NVC_LIBPATH at it so nvc finds every shipped library (STD, IEEE, NVC, plus the SYNOPSYS / VITAL extras inside IEEE) at simulation time.

ATTRIBUTES

cocotb_questa_sim

Rules

• cocotb_questa_sim

cocotb_questa_sim

load("@rules_cocotb//cocotb:cocotb_questa_sim.bzl", "cocotb_questa_sim")

cocotb_questa_sim(name, env, vcom, vlib, vlog, vsim)

A simulator configuration for running Mentor/Siemens EDA Questa (and the older ModelSim — cocotb uses the same questa runner for both) simulations in cocotb tests.

Status

Infrastructure only. Questa/ModelSim is commercial, with no BCR module and no redistributable binary; rules_cocotb cannot validate this rule in CI. Wire it up downstream by pointing the binary attrs at your own install (e.g. via new_local_repository over $MODEL_TECH or the equivalent Questa install directory) and registering a cocotb_toolchain that routes sim = "questa" through this rule. Cocotb's runner handles the actual build/sim via Runner.build / Runner.test.

Notes

Questa accepts both Verilog/SystemVerilog (VerilogInfo) and VHDL (VhdlInfo) modules. The rule defers the vlib / vlog / vcom invocations to cocotb's runner at test time rather than running them during the Bazel build, so the simulator only needs to be present on the test execution environment.

ATTRIBUTES

cocotb_xcelium_sim

Rules

• cocotb_xcelium_sim

cocotb_xcelium_sim

load("@rules_cocotb//cocotb:cocotb_xcelium_sim.bzl", "cocotb_xcelium_sim")

cocotb_xcelium_sim(name, env, xrun)

A simulator configuration for running Cadence Xcelium (and the older Incisive — cocotb uses the same xcelium runner for both) simulations in cocotb tests.

Status

Infrastructure only. Xcelium/Incisive is commercial, with no BCR module and no redistributable binary; rules_cocotb cannot validate this rule in CI. Wire it up downstream by pointing xrun at your own install and registering a cocotb_toolchain that routes sim = "xcelium" through this rule. Cocotb's runner handles the actual build/sim via Runner.build / Runner.test.

Notes

Xcelium accepts both Verilog/SystemVerilog (VerilogInfo) and VHDL (VhdlInfo) modules. The xrun driver dispatches to the appropriate compiler internally, so only the one binary attr is needed.

ATTRIBUTES

cocotb_vcs_sim

Rules

• cocotb_vcs_sim

cocotb_vcs_sim

load("@rules_cocotb//cocotb:cocotb_vcs_sim.bzl", "cocotb_vcs_sim")

cocotb_vcs_sim(name, env, vcs)

A simulator configuration for running Synopsys VCS simulations in cocotb tests.

Status

Infrastructure only. VCS is commercial, with no BCR module and no redistributable binary; rules_cocotb cannot validate this rule in CI. Wire it up downstream by pointing vcs at your own install and registering a cocotb_toolchain that routes sim = "vcs" through this rule. Cocotb's runner handles the actual build/sim (cocotb's VCS runner produces a simv binary and executes it for the run).

Notes

VCS accepts Verilog/SystemVerilog (VerilogInfo) modules. The cocotb runner internally manages vcs's build flow and the simv output binary, so only the vcs compiler binary is needed as a rule attribute.

ATTRIBUTES

cocotb_dsim_sim

Rules

• cocotb_dsim_sim

cocotb_dsim_sim

load("@rules_cocotb//cocotb:cocotb_dsim_sim.bzl", "cocotb_dsim_sim")

cocotb_dsim_sim(name, dsim, env)

A simulator configuration for running Siemens DSim (formerly Metrics DSim) simulations in cocotb tests.

Status

Infrastructure only. DSim is commercial, with no BCR module and no redistributable binary; rules_cocotb cannot validate this rule in CI. Wire it up downstream by pointing dsim at your own install and registering a cocotb_toolchain that routes sim = "dsim" through this rule. Cocotb's runner handles the actual build/sim via Runner.build / Runner.test.

Notes

DSim accepts both Verilog/SystemVerilog (VerilogInfo) and VHDL (VhdlInfo) modules. The dsim driver handles compile and run phases internally, so only the one binary attr is needed.

ATTRIBUTES

cocotb_riviera_sim

Rules

• cocotb_riviera_sim

cocotb_riviera_sim

load("@rules_cocotb//cocotb:cocotb_riviera_sim.bzl", "cocotb_riviera_sim")

cocotb_riviera_sim(name, coverage_args, coverage_data_glob, coverage_tool, env, vsimsa)

A simulator configuration for running Aldec Riviera-PRO simulations in cocotb tests.

Status

Infrastructure only. Riviera-PRO is commercial, with no BCR module and no redistributable binary; rules_cocotb cannot validate this rule in CI. Wire it up downstream by pointing the binary attrs at your own install and registering a cocotb_toolchain that routes sim = "riviera" through this rule. Cocotb's runner handles the actual build/sim via Runner.build / Runner.test.

Downstream wiring

Expose vsimsa to Bazel and register a custom cocotb_toolchain. vsimsa is the only binary cocotb's Riviera runner invokes; the rest of the Aldec install (alib/alog/acom/asim engines, libraries, license config) is loaded internally by vsimsa through $RIVIERA_HOME. Pull those into the action sandbox by attaching them as data on the vsimsa target — anything reachable through its runfiles will be staged alongside the binary.

Typically this means a local repository (e.g. new_local_repository or a custom repository rule pointed at $RIVIERA_HOME) whose BUILD.bazel wraps vsimsa as a native_binary (or sh_binary) target with the rest of the install as its data deps, then:

load("@rules_cocotb//cocotb:cocotb_riviera_sim.bzl", "cocotb_riviera_sim")
load("@rules_cocotb//cocotb:cocotb_toolchain.bzl", "cocotb_toolchain")

cocotb_riviera_sim(
    name = "cocotb_riviera",
    vsimsa = "@riviera//:vsimsa",
)

cocotb_toolchain(
    name = "my_cocotb_toolchain",
    cocotb = "//path/to:cocotb_py_library",
    simulators = {":cocotb_riviera": "riviera"},
)

Then register_toolchains("//path/to:my_cocotb_toolchain") in MODULE.bazel (ahead of the default //cocotb/toolchain registration) and cocotb_test(sim = "riviera", ...) will resolve through it.

Riviera-PRO accepts both Verilog/SystemVerilog (VerilogInfo) and VHDL (VhdlInfo) modules.

ATTRIBUTES

cocotb_activehdl_sim

Rules

• cocotb_activehdl_sim

cocotb_activehdl_sim

load("@rules_cocotb//cocotb:cocotb_activehdl_sim.bzl", "cocotb_activehdl_sim")

cocotb_activehdl_sim(name, env, vcom, vlib, vlog, vsimsa)

A simulator configuration for running Aldec Active-HDL simulations in cocotb tests.

Status

Infrastructure only. Active-HDL is commercial, with no BCR module and no redistributable binary; rules_cocotb cannot validate this rule in CI. Wire it up downstream by pointing the binary attrs at your own install and registering a cocotb_toolchain that routes sim = "activehdl" through this rule. Cocotb's runner handles the actual build/sim via Runner.build / Runner.test.

Downstream wiring

The pattern matches cocotb_riviera_sim — wrap the installed vlib, vlog, vcom, and vsimsa binaries via a local repository, then:

load("@rules_cocotb//cocotb:cocotb_activehdl_sim.bzl", "cocotb_activehdl_sim")
load("@rules_cocotb//cocotb:cocotb_toolchain.bzl", "cocotb_toolchain")

cocotb_activehdl_sim(
    name = "cocotb_activehdl",
    vlib = "@activehdl//:vlib",
    vlog = "@activehdl//:vlog",
    vcom = "@activehdl//:vcom",
    vsimsa = "@activehdl//:vsimsa",
)

cocotb_toolchain(
    name = "my_cocotb_toolchain",
    cocotb = "//path/to:cocotb_py_library",
    simulators = {":cocotb_activehdl": "activehdl"},
)

Register the toolchain in MODULE.bazel ahead of //cocotb/toolchain and use cocotb_test(sim = "activehdl", ...).

Active-HDL accepts both Verilog/SystemVerilog (VerilogInfo) and VHDL (VhdlInfo) modules.

ATTRIBUTES