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:
ColocatedNodeHammer run / collect primitives sharing one placement.
The members are
@staticmethod @ChiaFunction(resources={"hammer": 1});__init__re-binds each into a per-instance pinned form sonode.<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
collectrequires 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
PlacementGroupto schedule onto. If given,require_colocatedis 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-vlsiaction 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
-pin order (later files override earlier ones).config_contents – filename -> YAML/JSON text, written into
obj_dir/configs/on the worker and appended as-pafterconfigs. This is how a flow ships configs (or a previous action’soutput) 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
skippedinstead 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 ascollect().
- static read_chunk(obj_dir: str, rel: str, offset: int, length: int) bytes[source]
Read
lengthbytes atoffsetfromobj_dir/relon the worker. The transfer primitive behindcollect_fs(); returnsb""at or past EOF.relis 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 todest_diron 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 pinnedlist_matches()/read_chunk()members. It therefore needs a placement group so both members hit the one worker that owns obj_dir — construct the node withrequire_colocated=Trueor passplacement_group=....Files keep their path relative to obj_dir: a match at
obj_dir/syn-rundir/reports/x.rptlands atdest_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 ascollect().dest_dir – Destination directory on the calling machine; created as needed.
max_bytes_per_file – When set, files over this size are recorded in
skippedand 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 tocacti_.
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:
objectA single CACTI-characterized SRAM and its generated collateral.
- 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:
objectResult of
characterize_top_mems_conf_with_cacti().The
sram_libs/sram_namesviews are derived fromsramsso the existing dict-based consumers keep working, whilesramsexposes 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 atcacti_<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-diskOpenRAMCache.The collateral is returned untouched: the native
.lib(one per corner),.lefand.vare what downstream synthesis consumes. TheOpenRAMResultalso 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 (seechia.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:
RuntimeErrorOpenRAM 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:
objectKnobs 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_tempandstore_gdsare 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
.libeach). Passed to OpenRAM asuse_specified_cornersso 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.
Falsemeans 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", … orFalsefor none. If the router fails for a geometry (it does for some sky130 shapes) the run is retried withFalseand 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
Nonelets 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 thanmax_widthis 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.Noneapplies 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 = valuelines appended to the config (values are rendered withrepr), 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:
objectOne 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:
objectOne generated macro: untouched OpenRAM collateral plus a scalar summary.
The scalar fields deliberately share names with
CACTIResultso reports and tables written for the CACTI flow work unchanged.
- chia.vlsi.sram_openram.openram_runner.validate_spec_for_openram(spec: SRAMSpec) None[source]
Raise
OpenRAMErrorfor 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 atconfig.max_depthand width atconfig.max_width(a multiple of the mask granularity). Returnsspecitself 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).bodyis the deterministic part (everything that defines the macro) and is what the cache key hashes;full_configappends the run-specificoutput_pathline.
- 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_diris the directory holdingsram_compiler.py,compiler/andtechnology/. Resolution order:$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 theVERSIONfile.the
openrampackage importable underpython(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/busdeclarations and the set of pins, plusmemory()’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 colsand aspare_wenpin) 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 ofold_libintonew_lib.A
netlist_onlyOpenRAM run has no layout, so its Liberty saysarea : 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 cachedarealine (seetransplant_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_versionintoto_versionentries (seerecharacterize_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:
objectThin 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.
filesmaps basename -> content.
- 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:
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 genericchia.chipyard.macrocompiler.generate_macrocompiler_lib(), so MacroCompiler remaps.top.mems.vexactly as it does for CACTI.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/*_wmodeto OpenRAM’s active-lowcsb/web, zero-extension of the address/data buses (sky130 single-port macros carry a spare row and a spare column, so the macro’sADDR_WIDTH/DATA_WIDTHcan 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.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.vis 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;
resultsmaps 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:
characterize_top_mems_conf_with_openram()parses.top.mems.confout ofgenerated_src_filesand characterizes every SRAM at or above the synflop threshold;characterize_srams_with_openram()does the same for pre-parsed specs;both return an
OpenRAMCharacterizationwhosesram_libs/sram_namesviews feed the existing Hammer node and DB code unchanged.
Differences from the CACTI flow that callers should know:
Identical geometries share one macro (canonical name), so
sram_libshas one entry per macro, not per SRAM.sramsis 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). Passadapter_files + macro_stub_fileswhere the CACTI flow passesgenerate_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_openramtasks onopenramworkers whenparallel=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:
objectOne 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:
objectResult 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_specsand 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_openramper macro via.chia_remote(requires a running Ray cluster withopenramworkers); 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.confingenerated_src_filesand characterize its SRAMs (seecharacterize_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
openramslot). Dispatch several of these, one per spec subset, to use more workers. Returnsmacro 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.