chipflow.rtl.wrapper

RTL wrapper for external Verilog/SystemVerilog/SpinalHDL modules.

This module provides a TOML-based configuration system for wrapping external RTL modules as Amaranth wiring.Component classes. It supports:

  • Automatic Signature generation from TOML port definitions

  • SpinalHDL code generation

  • SystemVerilog to Verilog conversion via sv2v or yosys-slang

  • Clock and reset signal mapping

  • Port and pin interface mapping to RTL signals

  • CXXRTL simulation via chipflow.sim integration

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.

Module Contents

class chipflow.rtl.wrapper.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.wrapper.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