rules_systemrdl

Bazel rules for SystemRDL.

Overview

rules_systemrdl integrates PeakRDL with Bazel:

system_rdl_library — compile .rdl sources with configured exporters (e.g. regblock, HTML).
system_rdl_toolchain — configure PeakRDL, exporters, and default exporter arguments.
verilog_system_rdl_library — wrap SystemRDL exporter output as a Verilog library (VerilogInfo).
SystemRdlInfo — provider describing SystemRDL sources and root file.

Rule API details are generated from the Starlark sources in the sections linked from Summary.

Quick start

Add to MODULE.bazel:

bazel_dep(name = "rules_systemrdl", version = "{version}")

register_toolchains(
    # your repository’s registered toolchain target, e.g.
    "//tools/toolchains:system_rdl_toolchain",
)

Load rules from @rules_systemrdl//systemrdl:defs.bzl or from the individual .bzl files documented in this book.

Rules

system_rdl_library

load("@rules_systemrdl//systemrdl:system_rdl_library.bzl", "system_rdl_library")

system_rdl_library(name, deps, srcs, exporter_args, output_name, root)

A SystemRDL library.

Outputs of these rules are generally extracted via a filegroup.

load("@rules_verilog//systemrdl:system_rdl_library.bzl", "system_rdl_library")

system_rdl_library(
    name = "atxmega_spi",
    srcs = ["atxmega_spi.rdl"],
    exporter_args = {
        "regblock": [
            "--cpuif",
            "axi4-lite-flat",
        ],
    },
)

filegroup(
    name = "atxmega_spi.sv",
    srcs = ["atxmega_spi"],
    output_group = "system_rdl_regblock",
)

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
deps	Additional `system_rdl_library` dependencies.	List of labels	optional	`[]`
srcs	Source files which define the entire SystemRDL dag.	List of labels	required
exporter_args	A mapping of exporter names to arguments.	Dictionary: String -> List of strings	optional	`{}`
output_name	Basename used for declared outputs (and validated against the root file's top-level addrmap). Defaults to the target name. Use this when the addrmap name in the SystemRDL source differs from the target name.	String	optional	`""`
root	The top source file of the SystemRDL library.	Label	optional	`None`

system_rdl_output

load("@rules_systemrdl//systemrdl:system_rdl_output.bzl", "system_rdl_output")

system_rdl_output(name, exporter, lib, output_group)

An accessor for system_rdl_library targets.

Outputs can be accessed using a filegroup via output_group but that rule will not error if you specified an invalid output group. Consumers who want to guarantee the outputs are generated from system_rdl_library should use this rule

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
exporter	The exporter to select outputs from. Mutually exclusive with `output_Group`.	String	optional	`""`
lib	The SystemRDL library.	Label	required
output_group	The output group to forward. Mutually exclusive with `exporter`.	String	optional	`""`

system_rdl_toolchain

Rules

system_rdl_toolchain

system_rdl_toolchain

load("@rules_systemrdl//systemrdl:system_rdl_toolchain.bzl", "system_rdl_toolchain")

system_rdl_toolchain(name, exporter_args, exporter_dirs, exporter_files, peakrdl, peakrdl_config)

A SystemRDL toolchain.

Plugins:

Additional exporters are supported via a combination of the peakrdl and peakrdl_config attributes.

load("@rules_venv//python:py_library.bzl", "py_library")
load("@rules_systemrdl//systemrdl:system_rdl_toolchain.bzl", "system_rdl_toolchain")

py_library(
    name = "peakrdl_toml",
    srcs = ["peakrdl_toml.py"],
    deps = [
        "@pip_deps//peakrdl",
        "@pip_deps//tomli",
    ],
)

PLUGINS = [
    ":peakrdl_toml"
]

py_library(
    name = "peakrdl",
    deps = [
        "@pip_deps//peakrdl",
    ] + PLUGINS,
)

system_rdl_toolchain(
    name = "system_rdl_toolchain",
    peakrdl = ":peakrdl",
    peakrdl_config = "peakrdl.toml",
    exporter_files = {
        "regblock": [
            "sv={name}.sv",
            "pkg={name}_pkg.sv",
        ],
        "toml": [
            "toml={name}.toml",
        ],
    },
    exporter_dirs = {
        "html": [
            "dir={name}_html",
        ],
    },
)

toolchain(
    name = "toolchain",
    toolchain = ":system_rdl_toolchain",
    toolchain_type = "@rules_systemrdl//systemrdl:toolchain_type",
    visibility = ["//visibility:public"],
)

peakrdl.toml:

# https://peakrdl.readthedocs.io/en/latest/configuring.html
[peakrdl]
# The import path should be the repo realtive import path of the plugin.
plugins.exporters.toml = "tools.system_rdl.peakrdl_toml:TomlExporter"

Now with the toolchain configured. all system_rdl_library targets built in the same configuration as the registered toolchain will have an additional output group system_rdl_toml that is the output of the custom exporter.

Describing exporter outputs

Each exporter is registered with a list of output descriptors of the form <id>=<pattern>. Exporters that produce regular files go in exporter_files; exporters that produce a directory go in exporter_dirs (an exporter cannot be registered in both).

<id> is a stable identifier used to address this specific output from downstream consumers (e.g. the system_rdl_<exporter>_<id> output group, or the extract attribute on verilog_system_rdl_library / vhdl_system_rdl_library). Ids must be unique within an exporter and match [A-Za-z0-9_]+.
<pattern> is the basename of the output. The literal token {name} is expanded to the target's resolved output name (target name, the output_name attribute, or --rename). Patterns without {name} are fixed-name outputs the exporter always writes under that exact basename (e.g. a shared utility package emitted by peakrdl regblock-vhdl --copy-utils-pkg).

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
exporter_args	A pair of `exporters` keys to a list of default exporter args to apply to all rules.	Dictionary: String -> List of strings	optional	`{}`
exporter_dirs	A mapping of exporter name to a list of output descriptors `<id>=<pattern>` for exporters that produce a directory. See the rule's main documentation for the descriptor format.	Dictionary: String -> List of strings	optional	`{"html": ["dir={name}_html"]}`
exporter_files	A mapping of exporter name to a list of output descriptors `<id>=<pattern>` for exporters that produce regular files. See the rule's main documentation for the descriptor format.	Dictionary: String -> List of strings	optional	`{"regblock": ["sv={name}.sv", "pkg={name}_pkg.sv"]}`
peakrdl	The python library for the `peakrdl` package.	Label	optional	`None`
peakrdl_config	The `peakrdl` config file.	Label	required

verilog_system_rdl_library

Rules

verilog_system_rdl_library

verilog_system_rdl_library

load("@rules_systemrdl//systemrdl:verilog_system_rdl_library.bzl", "verilog_system_rdl_library")

verilog_system_rdl_library(name, deps, exporter, extract, lib)

A rule which extracts a verilog_library from a system_rdl_library.

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
deps	Additional `verilog_library`-providing dependencies.	List of labels	optional	`[]`
exporter	The SystemRDL exporter whose output should be wrapped as a Verilog library.	String	optional	`"regblock"`
extract	Output ids (from the toolchain's `exporter_outputs` descriptors for this exporter) to wrap into the `VerilogInfo`. Defaults to all ids the exporter declares.	List of strings	optional	`[]`
lib	The `system_rdl_library` to extract Verilog from.	Label	required

SystemRdlInfo

Providers

SystemRdlInfo

SystemRdlInfo

load("@rules_systemrdl//systemrdl:system_rdl_info.bzl", "SystemRdlInfo")

SystemRdlInfo(outputs, root, srcs)

Info for SystemRDL targets.

FIELDS

Name	Description
outputs	Dict[str, Depset[File]]: A mapping of exporter names to their outputs.
root	File: The top level source file for a library.
srcs	Depset[File]: All (including transitive) source files.