chipflow.rtl.blackbox

Blackbox macro wrapper.

load_blackbox_wrapper reads a *.blackbox.json produced by macrostrip (or any conformant tool) and returns an RTLWrapper subclass that:

  • synthesizes an ExternalWrapConfig from the JSON’s pin list,

  • uses the companion Verilog stub so Yosys sees the macro’s port signature during synthesis,

  • registers the macro with the platform at elaborate time so the submit step can bundle its LEF / Liberty / frame-view GDS into the upload.

The macro is declared in chipflow.toml:

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

and instantiated from Python by logical name:

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

Classes

BlackboxWrapper

RTLWrapper subclass that also registers the macro with the platform.

Functions

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

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

Module Contents

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