chipflow.rtl

RTL integration for ChipFlow.

This module provides infrastructure for integrating external RTL (Verilog, SystemVerilog, SpinalHDL, etc.) into Amaranth designs via TOML configuration.

Example usage:

from chipflow.rtl import RTLWrapper, load_wrapper_from_toml

# Load a timer peripheral from TOML configuration
timer = load_wrapper_from_toml("wb_timer.toml", generate_dest="build/gen")

# Add to SoC
wb_decoder.add(timer.bus, name="timer", addr=TIMER_BASE)
m.submodules.timer = timer

# Build a standalone CXXRTL simulator for testing
sim = timer.build_simulator("build/sim")
sim.set("i_clk", 1)
sim.step()

Submodules

Classes

BlackboxWrapper

RTLWrapper subclass that also registers the macro with the platform.

RTLWrapper

Dynamic Amaranth Component that wraps an external RTL module.

Functions

load_blackbox_wrapper(logical_name, *[, clocks, resets])

Load a hard macro by logical name declared in chipflow.toml.

load_wrapper_from_toml(toml_path[, generate_dest, ...])

Load an RTLWrapper from a TOML configuration file.

Package Contents

class chipflow.rtl.BlackboxWrapper(config, verilog_files, logical_name)

Bases: chipflow.rtl.wrapper.RTLWrapper

RTLWrapper subclass that also registers the macro with the platform.

Shares all wrapper behaviour with RTLWrapper; the only difference is that elaborate() informs the platform about the macro’s physical artifacts (LEF / Liberty / frame-view GDS) so the submit step can bundle them.

Parameters:

  • config (chipflow.rtl.wrapper.ExternalWrapConfig)

  • verilog_files (list[pathlib.Path])

  • logical_name (str)

elaborate(platform)

Generate the Amaranth module with Verilog instance.

Creates an Instance() of the wrapped Verilog module with all port mappings configured from the TOML specification.

chipflow.rtl.load_blackbox_wrapper(logical_name, *, clocks=None, resets=None)

Load a hard macro by logical name declared in chipflow.toml.

Parameters:

  • logical_name (str) – Key under [chipflow.silicon.macros].

  • clocks (Optional[Dict[str, str]]) – Amaranth clock-domain → macro pin name. e.g. {"sys": "CLK"} wires the sys domain’s clock to the macro’s LEF pin CLK.

  • resets (Optional[Dict[str, str]]) – Amaranth clock-domain → macro reset pin name (active-low convention, matching RTLWrapper).

Returns:

A BlackboxWrapper (a wiring.Component) whose signature mirrors the macro’s signal pins. Power/ground pins are omitted; clock/reset pins are omitted from the signature and wired at elaborate time.

Raises:

ChipFlowError – if the macro isn’t declared in chipflow.toml, its blackbox JSON is missing/malformed, or a referenced clock/reset pin isn’t in the macro’s pin list.

Return type:

BlackboxWrapper

class chipflow.rtl.RTLWrapper(config, verilog_files=None, parameters=None)

Bases: amaranth.lib.wiring.Component

Dynamic Amaranth Component that wraps an external RTL module.

This component is generated from TOML configuration and creates the appropriate Signature and elaborate() implementation to instantiate the RTL module.

When a driver configuration is provided, the component uses SoftwareDriverSignature to enable automatic driver generation and register struct creation.

Auto-mapping works by parsing the Verilog files to find actual port names, then matching patterns to identify which signals correspond to interface members.

Parameters:

  • config (ExternalWrapConfig)

  • verilog_files (List[pathlib.Path] | None)

  • parameters (Dict[str, pydantic.JsonValue] | None)

elaborate(platform)

Generate the Amaranth module with Verilog instance.

Creates an Instance() of the wrapped Verilog module with all port mappings configured from the TOML specification.

get_source_files()

Get the list of Verilog/SystemVerilog source files.

Returns:

List of paths to source files for this wrapper.

Return type:

List[pathlib.Path]

get_top_module()

Get the top module name.

Returns:

Name of the top-level Verilog module.

Return type:

str

get_signal_map()

Get the mapping from Amaranth port paths to Verilog signal names.

Returns:

Dictionary mapping port names to signal path → Verilog name mappings. Example: {‘bus’: {‘cyc’: ‘i_wb_cyc’, ‘stb’: ‘i_wb_stb’, …}}

Return type:

Dict[str, Dict[str, str]]

build_simulator(output_dir, *, optimization='-O2', debug_info=True)

Build a CXXRTL simulator for this wrapper.

This compiles the Verilog/SystemVerilog sources into a CXXRTL shared library and returns a simulator instance ready for use.

Parameters:

  • output_dir (pathlib.Path | str) – Directory for build artifacts (library, object files, etc.)

  • optimization (str) – C++ optimization level (default: -O2)

  • debug_info (bool) – Include CXXRTL debug info for signal access (default: True)

Returns:

CxxrtlSimulator instance configured for this wrapper.

Raises:

Example:

wrapper = load_wrapper_from_toml("wb_timer.toml")
sim = wrapper.build_simulator("build/sim")

# Reset
sim.set("i_rst_n", 0)
sim.set("i_clk", 0)
sim.step()
sim.set("i_clk", 1)
sim.step()
sim.set("i_rst_n", 1)

# Access signals using Verilog names
sim.set("i_wb_cyc", 1)
sim.step()
value = sim.get("o_wb_dat")

sim.close()
chipflow.rtl.load_wrapper_from_toml(toml_path, generate_dest=None, parameters=None)

Load an RTLWrapper from a TOML configuration file.

Parameters:

  • toml_path (pathlib.Path | str) – Path to the TOML configuration file

  • generate_dest (pathlib.Path | None) – Destination directory for generated Verilog (if using SpinalHDL)

  • parameters (Dict[str, pydantic.JsonValue] | None) – Verilog module parameter overrides. Merged on top of the TOML’s parameters table and applied both to code generation (so generators see the final values when templating their command-line) and to the Instance() of the wrapped module at elaboration.

Returns:

Configured RTLWrapper component

Raises:

ChipFlowError – If configuration is invalid or generation fails

Return type:

RTLWrapper