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

RTLWrapper

Dynamic Amaranth Component that wraps an external RTL module.

Functions

load_wrapper_from_toml(toml_path[, generate_dest])

Load an RTLWrapper from a TOML configuration file.

Package Contents

class chipflow.rtl.RTLWrapper(config, verilog_files=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)

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)

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)

Returns:

Configured RTLWrapper component

Raises:

ChipFlowError – If configuration is invalid or generation fails

Return type:

RTLWrapper