VLSI

API reference for chia.vlsi. These pages are generated from the docstrings in the source, so they stay in sync with the code.

Hammer

chia.vlsi.hammer — Hammer-vlsi nodes.

HammerNode.run() wraps one hammer-vlsi CLI call. Hammer’s CLI is uniform across actions (syn, par, drc, lvs, sim, power, and the -to- bridge actions): configs in via repeated -p, an --obj_dir for build output, an -o output config that feeds the next action, and the action name. One node therefore covers the whole flow, with the action as a parameter.

obj_dir is PATH-BASED: it lives on the worker that ran the action, so chained actions (syn -> syn-to-par -> par) and report fetches (HammerNode.collect()) must land on the SAME worker. HammerNode enforces that via a placement group (see chia.base.colocated .ColocatedNode for the given / reserved / no-PG construction modes). HammerNode.<fn>.chia_remote(...) (the class attribute) is the raw, unpinned form for callers that handle placement themselves.

This module knows nothing about technologies, tools, or sites — all of that arrives via the project’s configs.

class chia.vlsi.hammer.HammerResult(success: bool, returncode: int, action: str, obj_dir: str, stdout: str, stderr: str, output: dict = <factory>, listing: dict[str, int]=<factory>)[source]

Bases: object

class chia.vlsi.hammer.HammerCollectResult(obj_dir: str, files: dict[str, str], skipped: dict[str, int], listing: dict[str, int])[source]

Bases: object

class chia.vlsi.hammer.HammerMatchResult(obj_dir: str, matches: list[tuple[str, int]], skipped: dict[str, int])[source]

Bases: object

class chia.vlsi.hammer.HammerCollectFsResult(obj_dir: str, dest_dir: str, copied: dict[str, int], skipped: dict[str, int])[source]

Bases: object

class chia.vlsi.hammer.HammerNode(placement_group=None, require_colocated: bool = True, *, bundle_index: int = 0, reserve_bundle: dict | None = None, pg_strategy: str = 'STRICT_PACK', wait_for_pg: bool = True, pg_ready_timeout_s: float | None = None)[source]

Bases: ColocatedNode

Hammer run / collect primitives sharing one placement.

The members are @staticmethod @ChiaFunction(resources={"hammer": 1}); __init__ re-binds each into a per-instance pinned form so node.<fn>.chia_remote(...) lands on this node’s bundle:

with HammerNode() as node:    # reserves a {"CPU": 1, "hammer": 1} PG
    syn = get(node.run.chia_remote(
        "syn", configs=[...], obj_dir="/scratch/build/run1"))
    rpts = get(node.collect.chia_remote(
        syn.obj_dir, ["syn-rundir/reports/**"]))
    par = get(node.run.chia_remote("syn-to-par", ...))  # same worker

collect requires the default bundle’s hammer slot, so a collect dispatched while a run executes on this bundle waits for it in the default case — it cannot read half-written reports.

Set up placement and bind the member functions.

Parameters:
  • placement_group – an existing Ray PlacementGroup to schedule onto. If given, require_colocated is moot (placement is already fixed) and this node will not remove the PG on close.

  • require_colocated – when no PG is given, reserve one so all members co-locate. When False, leave placement to the caller.

  • bundle_index – which bundle of the (given or reserved) PG to pin to.

  • reserve_bundle – resource shape of a self-reserved bundle (default _DEFAULT_BUNDLE). A bundle too small for some members is allowed — those members just can’t dispatch through this node (a construction-time warning lists them).

  • pg_strategy – placement strategy for a self-reserved PG.

  • wait_for_pg – block on pg.ready() for a self-reserved PG so the node is usable immediately.

  • pg_ready_timeout_s – optional timeout for that wait.

static run(action: str, configs: list[str] | None = None, config_contents: dict[str, str] | None = None, obj_dir: str = 'build', extra_args: list[str] | None = None, hammer_bin: str = 'hammer-vlsi', timeout_seconds: int = 86400) → HammerResult[source]

Run one hammer-vlsi action on a worker.

Parameters:
  • action – Any action hammer-vlsi accepts: “syn”, “par”, “syn-to-par”, …

  • configs – Paths to config YAML/JSON files that exist on the worker (baked into the image or mounted), passed as -p in order (later files override earlier ones).

  • config_contents – filename -> YAML/JSON text, written into obj_dir/configs/ on the worker and appended as -p after configs. This is how a flow ships configs (or a previous action’s output) by value to a remote worker.

  • obj_dir – Hammer build directory on the worker.

  • extra_args – Extra CLI args, inserted before the action.

  • hammer_bin – The hammer executable, or a custom CLIDriver script.

  • timeout_seconds – Wall-clock limit for the subprocess.

static collect(obj_dir: str, patterns: list[str], max_bytes_per_file: int | None = None) → HammerCollectResult[source]

Fetch text files from a previous action’s obj_dir on this worker.

Dispatch via the pinned instance member (node.collect.chia_remote) so it lands on the worker that owns obj_dir — an unpinned call may not.

Parameters:
  • obj_dir – The build directory a previous action ran in.

  • patterns – Globs relative to obj_dir (** is recursive), e.g. ["syn-rundir/reports/**", "syn-rundir/*.log"]. Files matched by multiple patterns appear once.

  • max_bytes_per_file – When set, files over this size are recorded in skipped instead of shipped through the object store — protects against a glob accidentally matching a netlist. None (and 0, the falsy edge) means no cap: everything matched is shipped.

static list_matches(obj_dir: str, patterns: list[str], max_bytes_per_file: int | None = None) → HammerMatchResult[source]

Resolve patterns against obj_dir on the worker and return the manifest of matching files (relpath + size) without reading contents.

The planning half of collect_fs(): it tells the caller what to stream and how big each file is. Same glob/dedup/cap rules as collect().

static read_chunk(obj_dir: str, rel: str, offset: int, length: int) → bytes[source]

Read length bytes at offset from obj_dir/rel on the worker. The transfer primitive behind collect_fs(); returns b"" at or past EOF. rel is confined to obj_dir.

collect_fs(obj_dir: str, patterns: list[str], dest_dir: str, max_bytes_per_file: int | None = None, chunk_bytes: int = 16777216) → HammerCollectFsResult[source]

Stream matching files from a previous action’s obj_dir onto the filesystem of THIS (the calling) process, a chunk at a time.

Unlike collect(), which returns every file’s contents in one object-store payload, this writes each file to dest_dir on the caller’s local disk incrementally — peak memory is ~``chunk_bytes``, not the size of the whole collection. Use it to pull large report trees / gate-level netlists back from the worker to a machine that does NOT share a filesystem with it.

This is a caller-side orchestrator, not a @ChiaFunction: it runs wherever you call it and writes to that machine’s disk, pulling bytes from the obj_dir worker via the node’s pinned list_matches() / read_chunk() members. It therefore needs a placement group so both members hit the one worker that owns obj_dir — construct the node with require_colocated=True or pass placement_group=....

Files keep their path relative to obj_dir: a match at obj_dir/syn-rundir/reports/x.rpt lands at dest_dir/syn-rundir/reports/x.rpt.

Parameters:
  • obj_dir – The build directory a previous action ran in (on the worker).

  • patterns – Globs relative to obj_dir (** recursive); same matching/dedup/cap rules as collect().

  • dest_dir – Destination directory on the calling machine; created as needed.

  • max_bytes_per_file – When set, files over this size are recorded in skipped and not streamed. None (and 0) means no cap.

  • chunk_bytes – Bytes per worker read — the memory bound per file.

SRAM characterization (CACTI)

CACTI Runner

Methods to run CACTI 7, and return characterization results.

class chia.vlsi.sram_cacti.cacti_runner.CACTIResult(access_time_ns: float, cycle_time_ns: float, read_energy_nj: float, leakage_power_mw: float, height_mm: float, width_mm: float, area_um2: float, full_out: str)[source]

Bases: object

chia.vlsi.sram_cacti.cacti_runner.run_cacti(spec: SRAMSpec, technology_um: float = 0.13, cacti_path: str = 'cacti') → CACTIResult | None[source]

Run CACTI for a single SRAM spec and return parsed results.

Returns None if CACTI fails.

chia.vlsi.sram_cacti.cacti_runner.analytical_area_estimate(spec: SRAMSpec, cell_area_per_bit_um2: float = 1.0) → CACTIResult[source]

Fallback area estimate when CACTI fails.

Uses a simple model: area = depth * width * cell_area_per_bit. Timing is estimated from simple RC scaling.

CACTI Macrocompiler

CACTI-specific adapter over the generic Chipyard MacroCompiler glue.

The generic MacroCompiler support — MDF library generation and the tapeout.jar remap step — lives in chia.chipyard.macrocompiler. This module just wraps it with the cacti_ cell-name prefix used by the CACTI characterization flow.

chia.vlsi.sram_cacti.cacti_macrocompiler.generate_cacti_macrocompiler_lib(sram_specs: list[SRAMSpec], cell_prefix: str = 'cacti_') → str[source]

Generate the MacroCompiler MDF library for CACTI-characterized SRAMs.

Thin wrapper over generate_macrocompiler_lib() that defaults the cell-name prefix to cacti_.

SRAM Characterize

Top-level orchestration: characterize SRAMs with CACTI and generate Liberty files.

Parses .top.mems.conf from generated_src, runs CACTI for large SRAMs, generates Liberty files, and optionally runs MacroCompiler to remap synflop _ext modules to CACTI-characterized library macros.

class chia.vlsi.sram_cacti.sram_characterize.CharacterizedSRAM(name: str, spec: SRAMSpec, result: CACTIResult, lib_contents: dict[str, str], lef_content: str)[source]

Bases: object

A single CACTI-characterized SRAM and its generated collateral.

to_lib_dict() → dict[source]

Legacy dict shape.

class chia.vlsi.sram_cacti.sram_characterize.CactiCharacterization(generated_src_files: list[tuple[str, str]], srams: list[~chia.vlsi.sram_cacti.sram_characterize.CharacterizedSRAM] = <factory>)[source]

Bases: object

Result of characterize_top_mems_conf_with_cacti().

The sram_libs / sram_names views are derived from srams so the existing dict-based consumers keep working, while srams exposes the full per-SRAM CACTI result.

chia.vlsi.sram_cacti.sram_characterize.characterize_top_mems_conf_with_cacti(generated_src_files: list[tuple[str, str]], cacti_path: str, synflop_threshold_bytes: int = 256, technology_um: float = 0.13, cell_prefix: str = 'cacti_', corners: Sequence[LibertyCorner] = (LibertyCorner(name='ff', temperature=-40, voltage=1.95, pvt_name='PVT_1P95V_-40C', lib_suffix='ff_n40C_1v95'), LibertyCorner(name='ss', temperature=100, voltage=1.6, pvt_name='PVT_1P6V_100C', lib_suffix='ss_100C_1v60'), LibertyCorner(name='tt', temperature=25, voltage=1.8, pvt_name='PVT_1P8V_25C', lib_suffix='tt_025C_1v80'))) → CactiCharacterization[source]

Firtool specific characterize SRAMs with CACTI and generate Liberty files.

Finds .top.mems.conf in generated_src_files, runs CACTI for each large SRAM, generates .lib files, and replaces .top.mems.v to remove synflop definitions for SRAMs that become library cells.

Small SRAMs (< synflop_threshold_bytes) keep their synflop implementations and are synthesized as flip-flop arrays by Genus.

Parameters:
  • generated_src_files – List of (filename, contents) from the build.

  • cacti_path – Path to the CACTI binary.

  • synflop_threshold_bytes – SRAMs smaller than this stay as synflops.

  • technology_um – Technology node in microns (default 0.130 for Sky130).

  • cell_prefix – Prefix on the Liberty/LEF cell name. Default cacti_ disambiguates from chipyard’s .top.mems.v synflop wrapper for the MacroCompiler remap step. Pass “” when the caller’s Verilog refers to the bare _ext module directly (e.g. firtool –repl-seq-mem), so Genus can link the extmodule reference to the Liberty cell without an intervening rewrite.

  • corners – Liberty corners to characterize each SRAM at. Defaults to SKY130_CORNERS (ff/ss/tt). Each corner produces one entry in the per-SRAM lib_contents dict, keyed by its lib_suffix.

Returns:

  • generated_src_files: the (unmodified) input files

  • srams: a CharacterizedSRAM per large SRAM (name, spec, CACTI result, per-corner Liberty contents, and LEF content)

It also exposes .sram_libs (legacy list-of-dicts) and .sram_names views.

Return type:

A CactiCharacterization with

chia.vlsi.sram_cacti.sram_characterize.characterize_srams_with_cacti(sram_specs: list[SRAMSpec], generated_src_files: list[tuple[str, str]], cacti_path: str, synflop_threshold_bytes: int = 256, technology_um: float = 0.13, cell_prefix: str = 'cacti_', corners: Sequence[LibertyCorner] = (LibertyCorner(name='ff', temperature=-40, voltage=1.95, pvt_name='PVT_1P95V_-40C', lib_suffix='ff_n40C_1v95'), LibertyCorner(name='ss', temperature=100, voltage=1.6, pvt_name='PVT_1P6V_100C', lib_suffix='ss_100C_1v60'), LibertyCorner(name='tt', temperature=25, voltage=1.8, pvt_name='PVT_1P8V_25C', lib_suffix='tt_025C_1v80'))) → CactiCharacterization[source]

Characterize SRAM specs with CACTI and generate Liberty/LEF.

Splits sram_specs into tiny SRAMs (kept as synflops, below synflop_threshold_bytes) and large SRAMs (CACTI-characterized), runs CACTI for the large ones, and returns a CactiCharacterization. generated_src_files is passed through into the result unchanged.

See characterize_top_mems_conf_with_cacti for the variant that first parses the specs out of a .top.mems.conf in generated_src_files.

Liberty Gen

Generate minimal Liberty (.lib) files for SRAM macros from CACTI results.

Produces Liberty files with area, timing arcs, and pin definitions that match the Chisel-generated _ext module port names. Uses scalar delay model (no NLDM tables) — sufficient for synthesis area estimation and basic timing.

class chia.vlsi.sram_cacti.liberty_gen.LibertyCorner(name: str, temperature: int, voltage: float, pvt_name: str, lib_suffix: str)[source]

Bases: object

chia.vlsi.sram_cacti.liberty_gen.generate_liberty(spec: SRAMSpec, result: CACTIResult, corner: LibertyCorner | None = None, cell_prefix: str = 'cacti_') → str[source]

Generate a Liberty .lib file for an SRAM macro at a specific corner.

The cell name and pin names match the Chisel-generated _ext module so Genus can use this as a drop-in library cell.

If corner is None, defaults to typical (tt_025C_1v80).

cell_prefix defaults to cacti_ so the Liberty cell name doesn’t collide with the synflop wrapper named <spec.name> in chipyard’s .top.mems.v (MacroCompiler then rewrites synflop refs to point at cacti_<name>). Pass “” when the upstream Verilog references <spec.name> directly as an extmodule (e.g. firtool –repl-seq-mem) so the Liberty cell name lines up.

LEF Gen

Generate minimal LEF (.lef) files for SRAM macros from CACTI results.

Produces LEF files with macro dimensions, pin shapes, and obstruction layers matching the CACTI-characterized SRAM area. Pin names match the Liberty cell and Verilog blackbox stubs (cacti_<name>).

LEF is geometry-only (no timing) so ONE file is generated per SRAM, not per corner like Liberty.

Uses CLASS BLOCK BLACKBOX per LEF 5.7 spec – designed for blocks that contain a SIZE statement estimating total area with approximate pin locations.

chia.vlsi.sram_cacti.lef_gen.generate_lef(spec: SRAMSpec, result: CACTIResult, pin_layer: str = 'met4', obs_layers: list[str] | None = None, cell_prefix: str = 'cacti_') → str[source]

Generate a minimal LEF file for an SRAM macro.

Parameters:
  • spec – SRAM specification (pin names, depth, width, ports).

  • result – CACTI characterization result (physical dimensions).

  • pin_layer – Metal layer name for pin geometry (default “met4” for Sky130).

  • obs_layers – Metal layers for obstruction block. Defaults to [“met1”, “met2”, “met3”] for Sky130.

  • cell_prefix – Prefix on the LEF MACRO name (must match Liberty cell name). See generate_liberty for the disambiguation rationale.

Returns:

Complete LEF file content as a string.

SRAM macros (OpenRAM)

Drop-in alternative to the CACTI characterization: real sky130 macros from the OpenRAM compiler (native Liberty/LEF/Verilog), cached per worker node.

OpenRAM Runner

Run the OpenRAM SRAM compiler for one SRAM geometry and collect its collateral.

  • OpenRAM generates a macro (layout, LEF, Liberty per corner, Verilog model) and takes minutes to hours per macro, so run_openram() is a @ChiaFunction(resources={"openram": 1}) meant to be dispatched once per distinct geometry, in parallel, and every result goes through the on-disk OpenRAMCache.

  • The collateral is returned untouched: the native .lib (one per corner), .lef and .v are what downstream synthesis consumes. The OpenRAMResult also exposes the CACTI-shaped scalar summary (area, access time, leakage, …) parsed from them for reporting.

  • Macros are named canonically from their geometry (openram_sky130_1rw_2048x64_m8), not after the Chipyard SRAM, so identical geometries share one macro and one cache entry; a per-SRAM Verilog adapter (see chia.vlsi.sram_openram.openram_macrocompiler) bridges the Chipyard port names to the macro.

OpenRAM is driven through a Python config file, exactly as its command line does (python sram_compiler.py config.py), under the interpreter that has the openram package (CHIA_OPENRAM_PYTHON in the chia-openram image).

exception chia.vlsi.sram_openram.openram_runner.OpenRAMError[source]

Bases: RuntimeError

OpenRAM could not produce a macro for a spec (never silently fallen back).

class chia.vlsi.sram_openram.openram_runner.OpenRAMConfig(tech_name: str = 'sky130', corners: tuple[~chia.vlsi.sram_cacti.liberty_gen.LibertyCorner, ...]=(LibertyCorner(name='ff', temperature=-40, voltage=1.95, pvt_name='PVT_1P95V_-40C', lib_suffix='ff_n40C_1v95'), LibertyCorner(name='ss', temperature=100, voltage=1.6, pvt_name='PVT_1P6V_100C', lib_suffix='ss_100C_1v60'), LibertyCorner(name='tt', temperature=25, voltage=1.8, pvt_name='PVT_1P8V_25C', lib_suffix='tt_025C_1v80')), analytical_delay: bool = True, check_lvsdrc: bool = False, route_supplies: str | bool = 'ring', perimeter_pins: bool = True, num_banks: int = 1, words_per_row: int | None = None, local_array_size: int = 0, num_threads: int = 1, uniquify: bool = True, max_depth: int | None = 2048, max_width: int | None = None, max_tile_bits: int | None = None, round_depth_pow2: bool = True, extra_options: dict[str, ~typing.Any]=<factory>, config_template: str | None = None, timeout_seconds: int = 21600, openram_python: str | None = None, keep_temp: bool = False, store_gds: bool = False)[source]

Bases: object

Knobs for an OpenRAM run. Everything here has a working default for sky130; the SRAM geometry itself comes from the SRAMSpec.

Only timeout_seconds, openram_python, keep_temp and store_gds are excluded from the cache key — every other field changes the macro and therefore the key.

corners: tuple[LibertyCorner, ...] = (LibertyCorner(name='ff', temperature=-40, voltage=1.95, pvt_name='PVT_1P95V_-40C', lib_suffix='ff_n40C_1v95'), LibertyCorner(name='ss', temperature=100, voltage=1.6, pvt_name='PVT_1P6V_100C', lib_suffix='ss_100C_1v60'), LibertyCorner(name='tt', temperature=25, voltage=1.8, pvt_name='PVT_1P8V_25C', lib_suffix='tt_025C_1v80'))

Liberty corners to characterize (one native .lib each). Passed to OpenRAM as use_specified_corners so the PVT triples match the chia corner set exactly (default: sky130 ff/ss/tt as in the CACTI flow).

analytical_delay: bool = True

Analytical (Elmore) timing — seconds. False means SPICE characterization: hours per macro and needs ngspice in the image.

check_lvsdrc: bool = False

DRC/LVS on the final layout; needs magic+netgen, not in the image.

route_supplies: str | bool = 'ring'

"ring" (default), "left", … or False for none. If the router fails for a geometry (it does for some sky130 shapes) the run is retried with False and the result says so.

Type:

OpenRAM power routing

perimeter_pins: bool = True

Route the signal pins out to the macro perimeter. OpenRAM’s escape router crashes on some sky130 shapes (e.g. masked two-port arrays); the run is then retried with False (pins stay on the internal shapes, which is irrelevant for synthesis) and the result says so.

words_per_row: int | None = None

None lets OpenRAM pick the column mux; 1/2/4/8/16 forces it.

max_depth: int | None = 2048

Largest macro OpenRAM is asked to build. A Chipyard SRAM deeper than max_depth (OpenRAM/sky130 refuses more than 512 rows x 8-way mux, and BOOM’s 8192-word L2 bank hits that) or wider than max_width is mapped onto several copies of a smaller TILE macro; MacroCompiler composes the full memory from the tiles (that is its normal job for vendor macro libraries). None = no cap.

max_tile_bits: int | None = None

an SRAM whose depth*width (after power-of-two depth rounding) is at or below this many bits is built as ONE macro even if it exceeds max_width; only bigger SRAMs are clipped to the caps. None applies the caps to every SRAM. Lets the caps describe the tile for the few huge arrays without splitting every medium one.

Type:

Tiling budget

round_depth_pow2: bool = True

Round a non-power-of-two depth UP to the next power of two (BOOM has 40-word predictor tables; OpenRAM’s analytical characterizer fails to find its probe nets on such arrays, and real compilers only offer power-of-two depths anyway). MacroCompiler leaves the extra rows unused.

extra_options: dict[str, Any]

Verbatim name = value lines appended to the config (values are rendered with repr), for any OpenRAM option not modelled above.

config_template: str | None = None

Raw text of an OpenRAM config file (it is Python) inserted before the generated lines, so the spec-derived geometry/ports/output lines always win.

timeout_seconds: int = 21600

Per-macro wall-clock limit. OpenRAM’s router needs ~1 h for 1-4 KB sky130 macros and 3+ h for 2048x256; the cache makes this a one-off.

class chia.vlsi.sram_openram.openram_runner.MacroPort(index: int, kind: str, clk: str, csb: str, web: str | None, wmask: str | None, spare_wen: str | None, addr: str, din: str | None, dout: str | None)[source]

Bases: object

One OpenRAM macro port as declared in its Verilog model.

class chia.vlsi.sram_openram.openram_runner.OpenRAMResult(macro_name: str, access_time_ns: float, cycle_time_ns: float, read_energy_nj: float, leakage_power_mw: float, height_mm: float, width_mm: float, area_um2: float, full_out: str, setup_time_ns: float, hold_time_ns: float, lib_contents: dict[str, str], lef_content: str, verilog_content: str, config_py: str, data_width: int, addr_width: int, num_wmasks: int, ports: list[~chia.vlsi.sram_openram.openram_runner.MacroPort], power_pins: tuple[str, str], openram_version: str, cache_key: str, from_cache: bool, elapsed_s: float, supply_routed: bool, perimeter_pins: bool = True, notes: list[str] = <factory>)[source]

Bases: object

One generated macro: untouched OpenRAM collateral plus a scalar summary.

The scalar fields deliberately share names with CACTIResult so reports and tables written for the CACTI flow work unchanged.

to_lib_dict() → dict[source]

Legacy dict shape used by the Hammer node (cacti_sram_libs).

chia.vlsi.sram_openram.openram_runner.validate_spec_for_openram(spec: SRAMSpec) → None[source]

Raise OpenRAMError for geometries OpenRAM cannot build.

sky130 has hand-made 1-port (6T) and 2-port (8T) bitcells; anything with three or more ports would silently fall back to OpenRAM’s parameterized bitcell, which is not what anyone wants from a sky130 macro, so it is an error here (no CACTI/analytical fallback either, by design).

chia.vlsi.sram_openram.openram_runner.tile_spec_for(spec: SRAMSpec, config: OpenRAMConfig) → SRAMSpec[source]

The geometry OpenRAM actually builds for spec: the same ports and mask granularity, depth capped at config.max_depth and width at config.max_width (a multiple of the mask granularity). Returns spec itself when no cap applies. MacroCompiler tiles the SRAM from copies of this macro (via the adapter of the same name).

chia.vlsi.sram_openram.openram_runner.macro_name_for(spec: SRAMSpec, config: OpenRAMConfig, cell_prefix: str = 'openram_') → str[source]

Canonical macro name from geometry: <prefix><tech>_<family>_<depth>x<width>[_m<gran>].

chia.vlsi.sram_openram.openram_runner.render_openram_config(spec: SRAMSpec, config: OpenRAMConfig, macro_name: str, spare_rows: int, spare_cols: int, route_supplies: str | bool, output_path: str | None = None, perimeter_pins: bool | None = None) → tuple[str, str][source]

Return (body, full_config).

body is the deterministic part (everything that defines the macro) and is what the cache key hashes; full_config appends the run-specific output_path line.

chia.vlsi.sram_openram.openram_runner.openram_package_info(python: str) → tuple[str, str][source]

(package_dir, version) of the OpenRAM installation to drive.

package_dir is the directory holding sram_compiler.py, compiler/ and technology/. Resolution order:

  1. $OPENRAM_HOME (its parent dir) — how the chia-openram image installs OpenRAM, as a source checkout; the version is $CHIA_OPENRAM_VERSION (set by the image: <VERSION file>+g<commit>) or the VERSION file.

  2. the openram package importable under python (a pip install).

chia.vlsi.sram_openram.openram_runner.lib_interface(lib_text: str) → dict[source]

The macro’s port interface AS THE LIBERTY DECLARES IT: bus widths from the type/bus declarations and the set of pins, plus memory()’s address/word width.

This is what synthesis binds to (Genus resolves the instance to the library cell), and it differs from OpenRAM’s Verilog model: the model carries the spare column (DATA_WIDTH = word_size + spare cols and a spare_wen pin) that the Liberty does not expose.

chia.vlsi.sram_openram.openram_runner.summarize_native_lib(lib_text: str, lef_text: str) → dict[source]

CACTI-shaped scalars out of OpenRAM’s native nominal-corner Liberty + LEF.

chia.vlsi.sram_openram.openram_runner.parse_macro_verilog(v_text: str) → dict[source]

Extract the module name, parameters, power pins and per-port signal names from OpenRAM’s Verilog model.

chia.vlsi.sram_openram.openram_runner.run_openram(spec: SRAMSpec, config: OpenRAMConfig | None = None, cache_dir: str | None = None, cache_policy: str = 'use', cell_prefix: str = 'openram_') → OpenRAMResult[source]

Generate (or fetch from cache) the OpenRAM macro for one SRAM spec.

Parameters:
  • spec – Chipyard SRAM spec (from parse_mems_conf).

  • config – OpenRAM knobs; defaults to OpenRAMConfig().

  • cache_dir – result cache directory on this node; defaults to $CHIA_OPENRAM_CACHE_DIR (set in the chia-openram image). "" disables caching.

  • cache_policy – "use" (read+write), "refresh" (ignore existing, rewrite), "readonly" (read, never write).

  • cell_prefix – prefix of the canonical macro name.

Raises:

OpenRAMError – unsupported geometry, OpenRAM failure or timeout. There is deliberately no fallback model.

chia.vlsi.sram_openram.openram_runner.transplant_lib_area(new_lib: str, old_lib: str) → str[source]

Copy the cell area : line of old_lib into new_lib.

A netlist_only OpenRAM run has no layout, so its Liberty says area : 0; the timing tables are the same as a layout run’s. Taking the area line from the layout run’s Liberty makes the re-characterized lib equal to what a full run would have produced.

chia.vlsi.sram_openram.openram_runner.recharacterize_cache_entry(cache: OpenRAMCache, old_key: str, to_version: str, timeout_seconds: int = 3600, python: str | None = None) → tuple[str, dict][source]

Regenerate ONLY the Liberty files of a cached macro under a new OpenRAM version (e.g. after a patch that changes the analytical timing model), reusing the cached layout collateral (LEF/Verilog/SPICE/area).

OpenRAM is re-run on the entry’s own config with netlist_only = True: minutes instead of hours, because the layout and routing (what makes big macros slow) are skipped, while the netlist and the analytical characterization are identical to a full run. The new libs get the cached area line (see transplant_lib_area()). The result is stored as a NEW entry keyed by (config body, to_version); the old entry is kept.

Returns (new_key, report); report["tt_identical"] says whether the nominal-corner lib came out byte-identical to the cached one, which it must when the patch only touches other corners (a built-in self-check).

chia.vlsi.sram_openram.openram_runner.recharacterize_openram_cache(cache_dir: str, from_version: str, to_version: str, timeout_seconds: int = 3600, macros: Sequence[str] | None = None) → list[dict][source]

Re-characterize every entry generated under from_version into to_version entries (see recharacterize_cache_entry()).

OpenRAM Cache

Content-addressed, on-disk cache of OpenRAM results.

OpenRAM takes minutes to hours per macro, and the same SRAM geometries recur across every branch of a design-space loop, so run_openram consults this cache before launching the compiler and stores every successful run in it.

Layout on disk (cache_dir lives on the worker node; it is persistent only if the cluster yaml bind-mounts a host directory there):

<cache_dir>/
    <key>/
        meta.json          # key inputs, macro name, timings, openram version
        result.json        # the serialized OpenRAMResult (minus big blobs)
        <macro>.v          # OpenRAM collateral, verbatim
        <macro>.lef
        <macro>.py
        <macro>_<corner>.lib   (one per corner)
        <macro>.html / <macro>.log  (optional)
        <macro>.gds        (only with store_gds)

The key is the SHA-256 of the deterministic part of the rendered OpenRAM config (technology, geometry, ports, write size, corners, every option that changes the macro) plus the OpenRAM version. Paths, temp dirs and timeouts are excluded, so entries are portable: a cache populated on one node, or exported with export_openram_cache(), is valid anywhere the same OpenRAM version runs.

chia.vlsi.sram_openram.openram_cache.default_cache_dir() → str | None[source]

The cache directory the worker image advertises (CHIA_OPENRAM_CACHE_DIR), or None.

chia.vlsi.sram_openram.openram_cache.cache_key(config_body: str, openram_version: str) → str[source]

SHA-256 over the deterministic config body and the OpenRAM version.

class chia.vlsi.sram_openram.openram_cache.OpenRAMCache(cache_dir: str)[source]

Bases: object

Thin wrapper over the on-disk layout above. Safe for concurrent writers (entries are built in a temp dir and atomically renamed into place).

load(key: str) → dict | None[source]

Return the stored result dict (with file contents inlined) or None.

store(key: str, result: dict, files: dict[str, str | bytes], meta: dict) → str[source]

Write an entry atomically. files maps basename -> content.

inventory() → list[dict][source]

One meta dict per entry (macro name, geometry, version, timings).

export_tar(keys: list[str] | None = None) → bytes[source]

Tar+gz the selected entries (default: all) into memory.

import_tar(blob: bytes, overwrite: bool = False) → list[str][source]

Unpack a tarball made by export_tar(); returns imported keys.

OpenRAM Macrocompiler glue

MacroCompiler glue and Verilog adapters for OpenRAM macros.

Downstream of characterization the OpenRAM flow needs three pieces of Verilog/JSON collateral per Chipyard SRAM, all generated here:

  1. MDF library for MacroCompiler (generate_openram_macrocompiler_lib()): one entry per Chipyard SRAM named <cell_prefix><sram name> with the Chipyard port names (RW0_clk/RW0_en/…). This is the generic chia.chipyard.macrocompiler.generate_macrocompiler_lib(), so MacroCompiler remaps .top.mems.v exactly as it does for CACTI.

  2. Adapter module (generate_openram_adapters()): the module MacroCompiler instantiates, <cell_prefix><sram name>, is a thin Verilog wrapper that instantiates the canonical OpenRAM macro and bridges the two interfaces: active-high *_en/*_wmode to OpenRAM’s active-low csb/web, zero-extension of the address/data buses (sky130 single-port macros carry a spare row and a spare column, so the macro’s ADDR_WIDTH/DATA_WIDTH can exceed the SRAM’s), the spare-column write enable tied off, and a constant all-ones write mask when the macro is masked but the Chipyard port is not.

  3. Blackbox stub for the macro itself (generate_openram_macro_stubs()): an empty module with the macro’s exact port list, so Genus elaborates the adapter and binds the instance to the Liberty cell of the same name (the same mechanism the CACTI flow uses; OpenRAM’s behavioural .v is NOT given to synthesis).

The Liberty and LEF are OpenRAM’s own files, untouched.

chia.vlsi.sram_openram.openram_macrocompiler.generate_openram_macrocompiler_lib(sram_specs: list[SRAMSpec], cell_prefix: str = 'openram_') → str[source]

MDF JSON for MacroCompiler: one <cell_prefix><name> entry per spec (the adapter module name), Chipyard port naming.

chia.vlsi.sram_openram.openram_macrocompiler.generate_openram_adapter(spec: SRAMSpec, result: OpenRAMResult, cell_prefix: str = 'openram_') → tuple[str, str][source]

Return (filename, verilog) of the adapter <cell_prefix><spec.name>.

chia.vlsi.sram_openram.openram_macrocompiler.generate_openram_adapters(specs: list[SRAMSpec], results: dict[str, OpenRAMResult], cell_prefix: str = 'openram_') → list[tuple[str, str]][source]

Adapters for every spec; results maps spec name -> its macro result.

chia.vlsi.sram_openram.openram_macrocompiler.generate_openram_macro_stub(result: OpenRAMResult) → tuple[str, str][source]

Empty blackbox module with the macro’s exact ports (power pins omitted, as OpenRAM’s own model does without USE_POWER_PINS).

chia.vlsi.sram_openram.openram_macrocompiler.generate_openram_macro_stubs(results: dict[str, OpenRAMResult] | list[OpenRAMResult]) → list[tuple[str, str]][source]

One stub per distinct macro.

SRAM Characterize (OpenRAM)

Top-level orchestration: generate OpenRAM macros for a design’s SRAMs.

Drop-in counterpart of chia.vlsi.sram_cacti.sram_characterize:

Differences from the CACTI flow that callers should know:

  • Identical geometries share one macro (canonical name), so sram_libs has one entry per macro, not per SRAM. srams is still per SRAM.

  • The per-SRAM module MacroCompiler maps to (openram_<name>) is a Verilog adapter around the macro (adapter_files), and the macro itself needs a blackbox stub (macro_stub_files). Pass adapter_files + macro_stub_files where the CACTI flow passes generate_macro_stubs(...).

  • Unsupported SRAMs (3+ ports, read- or write-only) and OpenRAM failures raise OpenRAMError; there is no analytical/CACTI fallback.

  • Macros run in parallel as run_openram tasks on openram workers when parallel=True (the default), consulting the per-node result cache.

class chia.vlsi.sram_openram.sram_characterize.CharacterizedSRAM(name: str, spec: SRAMSpec, tile_spec: SRAMSpec, result: OpenRAMResult, lib_contents: dict[str, str], lef_content: str, macro_name: str, adapter_verilog: str)[source]

Bases: object

One Chipyard SRAM mapped onto an OpenRAM macro (same shape as the CACTI dataclass, plus the macro name and adapter).

class chia.vlsi.sram_openram.sram_characterize.OpenRAMCharacterization(generated_src_files: list[tuple[str, str]], srams: list[~chia.vlsi.sram_openram.sram_characterize.CharacterizedSRAM] = <factory>, macros: dict[str, ~chia.vlsi.sram_openram.openram_runner.OpenRAMResult] = <factory>, adapter_files: list[tuple[str, str]] = <factory>, macro_stub_files: list[tuple[str, str]] = <factory>)[source]

Bases: object

Result of characterize_srams_with_openram().

property sram_libs: list[dict]

One Hammer-shaped lib dict per distinct macro.

property tile_specs: list[SRAMSpec]

what the MacroCompiler MDF must describe (the adapter <prefix><name> has this geometry; MacroCompiler composes the full SRAM from copies of it).

Type:

Per-SRAM specs with the TILE geometry

property stub_files: list[tuple[str, str]]

adapters + macro stubs.

Type:

Everything synthesis needs besides the remapped mems.v

chia.vlsi.sram_openram.sram_characterize.characterize_srams_with_openram(sram_specs: list[SRAMSpec], generated_src_files: list[tuple[str, str]], config: OpenRAMConfig | None = None, cache_dir: str | None = None, cache_policy: str = 'use', synflop_threshold_bytes: int = 256, cell_prefix: str = 'openram_', parallel: bool = True, dispatch_options: dict | None = None) → OpenRAMCharacterization[source]

Generate OpenRAM macros for sram_specs and the Verilog glue to use them.

Parameters:
  • sram_specs – parsed Chipyard SRAM specs.

  • generated_src_files – passed through unchanged into the result.

  • config – OpenRAM knobs (see OpenRAMConfig).

  • cache_dir – per-node result cache; None = the image default ($CHIA_OPENRAM_CACHE_DIR), "" = no cache.

  • cache_policy – "use" | "refresh" | "readonly".

  • synflop_threshold_bytes – SRAMs smaller than this stay synflops.

  • cell_prefix – prefix of both the adapter modules (<prefix><sram>, what MacroCompiler maps to) and the canonical macro names.

  • parallel – dispatch run_openram per macro via .chia_remote (requires a running Ray cluster with openram workers); False runs them serially in this process.

  • dispatch_options – extra .options(...) for the dispatched tasks, e.g. {"scheduling_strategy": "DEFAULT"} when calling from inside a placement group.

Raises:

OpenRAMError – on any unsupported SRAM or OpenRAM failure (no fallback).

chia.vlsi.sram_openram.sram_characterize.characterize_top_mems_conf_with_openram(generated_src_files: list[tuple[str, str]], config: OpenRAMConfig | None = None, cache_dir: str | None = None, cache_policy: str = 'use', synflop_threshold_bytes: int = 256, cell_prefix: str = 'openram_', parallel: bool = True, dispatch_options: dict | None = None) → OpenRAMCharacterization[source]

Find .top.mems.conf in generated_src_files and characterize its SRAMs (see characterize_srams_with_openram()). No conf -> empty result.

chia.vlsi.sram_openram.sram_characterize.prefill_openram_cache(sram_specs_or_mems_conf: list[SRAMSpec] | str, config: OpenRAMConfig | None = None, cache_dir: str | None = None, synflop_threshold_bytes: int = 256, cell_prefix: str = 'openram_') → dict[str, dict][source]

Populate this node’s cache for every distinct macro the specs need.

Runs the macros serially on this worker (it already holds one openram slot). Dispatch several of these, one per spec subset, to use more workers. Returns macro name -> {key, from_cache, elapsed_s, area_um2}.

chia.vlsi.sram_openram.sram_characterize.openram_cache_inventory(cache_dir: str | None = None) → list[dict][source]

Metadata of every entry in this node’s cache.

chia.vlsi.sram_openram.sram_characterize.export_openram_cache(cache_dir: str | None = None, keys: list[str] | None = None) → bytes[source]

Tar+gz of this node’s cache (or the given keys), e.g. to persist it on the head.

chia.vlsi.sram_openram.sram_characterize.import_openram_cache(blob: bytes, cache_dir: str | None = None, overwrite: bool = False) → list[str][source]

Unpack a tarball from export_openram_cache() into this node’s cache.