rules_cocotb

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