Wrapping External RTL

chipflow.rtl.wrapper turns a TOML description of an external Verilog or SystemVerilog module into an Amaranth Component ready to drop into a design. The TOML specifies the source files, clocks and resets, bus/pin interfaces, optional preprocessing (sv2v, yosys-slang, SpinalHDL), and — as of this release — Verilog module parameter overrides.

This page is an API-level pointer. For the full usage guide, worked examples, and the TOML reference, see the ChipFlow training material:

Quick reference

Load a wrapper from a TOML file and instantiate it inside a design:

from chipflow.rtl.wrapper import load_wrapper_from_toml

class MyDesign(wiring.Component):
    def elaborate(self, platform):
        m = Module()
        m.submodules.timer = load_wrapper_from_toml("wb_timer.toml")
        return m

Supply Verilog parameter overrides from TOML, from Python, or both (the Python kwarg wins on collisions; unmentioned parameters fall back to the TOML table):

# wb_timer.toml
name = "wb_timer"

[parameters]
DATA_WIDTH = 32
ADDR_WIDTH = 4

# caller overrides DATA_WIDTH; ADDR_WIDTH=4 still applies
w = load_wrapper_from_toml("wb_timer.toml", parameters={"DATA_WIDTH": 64})

The merged parameters are emitted as p_<NAME>=<value> kwargs on the Instance() at elaboration, and are also fed into generator template substitution (so SpinalHDL / sv2v / yosys-slang see the final values when producing Verilog).

Wrapping an NDA hard macro

For third-party / NDA hard macros shipped as a LEF + Liberty + Verilog stub, use chipflow.rtl.blackbox.load_blackbox_wrapper(). The macro is declared in chipflow.toml by logical name, pointing at a *.blackbox.json produced by macrostrip:

# chipflow.toml
[chipflow.silicon.macros.sram_64x64]
blackbox = "vendor/ihp/sram_64x64.blackbox.json"

from chipflow.rtl import load_blackbox_wrapper

sram = load_blackbox_wrapper(
    "sram_64x64",
    clocks={"sys": "CLK"},
    resets={"sys": "RST_N"},
)
m.submodules.sram = sram

Signal pins become signature members (In(width) / Out(width)); power, ground, clock, and reset pins are handled out-of-band. At submit time the platform bundles the macro’s companion files (LEF, Liberty, frame-view GDS, Verilog stub, blackbox JSON) into a macros.tar.gz alongside the RTLIL, so the ChipFlow backend can feed them to ORFS without the real macro layout ever leaving customer premises.

Non-NDA macros

The same mechanism works for macros you’re free to ship in full — no NDA, no stripping. Point macrostrip blackbox at the real GDS (rather than running macrostrip frame first):

macrostrip blackbox \
  --lef macro.lef --top MY_MACRO \
  --frame-gds macro.real.gds \
  --liberty macro.lib \
  --verilog-stub macro.v \
  -o macro.blackbox.json

Declare and instantiate it exactly as above. The blackbox JSON schema field is named frame_gds for historical reasons, but chipflow-lib treats it as “the GDS to include” — frame-view or real, the submission path is identical. Skip macrostrip swap on return: there’s nothing to substitute back.

API