PDK enablement: declarative cell metadata (pin tables + classifications) instead of per-PDK Rust modules

[robtaylor]

Summary

PDK enablement today is per-PDK code + vendored Verilog. Every new cell family — third-party IP memories, hard macros, foundry IP — means re-vendoring Verilog into jacquard/vendor/, extending build.rs's scanner, editing prefix-matchers (is_<pdk>_cell, extract_cell_type), and adding entries to half a dozen hand-curated matches!() lists (is_filler_cell, is_io_pad_cell, is_sequential_cell, is_multi_output_cell, …). That doesn't scale across the ecosystem, and it makes downstream sim runs gated on Jacquard PRs even when the IP could be supported with a small data file.

Concretely: after #64 cleared antennas / corner pads / fillers, the next blocker on jacquard sim against a real gf180mcu-project-template post-P&R chip_top is third-party gf180mcu_ocd_ip_sram__sram1024x8m8wm1 — Tim Edwards' OCD 3.3V port of the GF180MCU SRAM IP. The cell is not in Jacquard's vendor/, not matched by is_gf180mcu_cell (only walks fd_sc_* / fd_io_* / ws_*), and has no pin table. Real ports (CLK, CEN, GWEN, WEN[7:0], A[9:0], D[7:0], Q[7:0], optionally inout VDD/VSS) — not filler-stubbable.

Where the friction sits

For each new cell family Jacquard currently needs:

1. Pin direction table — build.rs::generate_<pdk>_pin_table scans jacquard/vendor/<pdk>/**/*.v, parses input / output, bakes a static table at compile time. (Misses inout, which GF180MCU: power-pin + wired-filler shortcuts for real post-P&R netlists #64 had to short-circuit for power pins.)
2. Cell-family detection — is_<pdk>_cell hard-coded prefix matchers (e.g. gf180mcu_fd_sc_mcu7t5v0__, gf180mcu_ws_io__).
3. Classifications — is_filler_cell / is_io_pad_cell / is_sequential_cell / is_multi_output_cell / is_delay_cell, each a curated matches!() list per PDK.
4. AIG-level special cases — gf180mcu_postprocess in aig.rs, IO-pad behavioural rules, multi-output decomposition for addf/addh, etc.

Items 1–3 are mostly mechanical data restating what's already in the cell's Verilog port list + a small "kind" tag. Item 4 is genuine semantics extraction and the harder part (but rare — most new entries to a PDK are IP not new gate families).

What a declarative model could look like

Two-tier; the tiers are cleanly separable and can land independently.

Tier 1 — runtime pin tables (eliminates items 1 + 2)

Drop a --cell-library <path>.v (or cell_library = [...] in a config / [tool.jacquard] table) that points at one or more Verilog files. sverilogparse (already a dep) parses them at startup and populates the LeafPinProvider for every module ... endmodule block found. Handles input / output and inout correctly; replaces the build.rs scanner for std cells and removes the need to vendor third-party IP Verilog into Jacquard at all. Downstream projects pass their existing IP blackbox.v files directly.

Behaviour today (per-PDK module + build.rs) could remain as a built-in default; user-supplied libraries augment / override it. No compile-time work for new families.

Tier 2 — declarative cell metadata (eliminates item 3, partially item 4)

YAML or JSON co-located with each cell library, describing the things port lists can't tell you:

# gf180mcu_ocd_ip_sram.cells.yaml
gf180mcu_ocd_ip_sram__sram1024x8m8wm1:
  kind: ram_block
  depth: 1024
  width: 8
  ports:
    clk: CLK
    chip_enable: CEN          # active-low
    chip_enable_polarity: low
    write_enable: GWEN        # active-low
    write_enable_polarity: low
    byte_enable: WEN          # [7:0], active-low, per-byte
    byte_enable_polarity: low
    addr: A                   # [9:0]
    data_in: D                # [7:0]
    data_out: Q               # [7:0]
  power_pins: [VDD, VSS]      # inout, under USE_POWER_PINS

Other recognised kinds mirror today's classifiers: filler, endcap, tap, io_pad_input, io_pad_output, io_pad_bidir, power_pad, corner_pad, analog_passthrough, clock_gate, dff, latch, sram, rom, delay, multi_output. The built-in SKY130 / GF180MCU classifications could become shipped YAML files — defaults the binary loads from a known path, but anything user-supplied takes precedence.

For kind: ram_block specifically: the port mapping is enough for Jacquard's existing DriverType::RAMBlock slot to pick up the macro without any code change. This is the case for OCD SRAM and would be the case for fd_ip_sram siblings.

What stays per-PDK code

Std-cell AIG decomposition (pdk_decomp.rs reading .functional.v and converting primitive gates → AND-inverter) is genuine semantics work. New std-cell libraries would still need decomp rules. But new IP (memories, analog passthroughs, hardened blocks, foundry-supplied macros) — the common case driving Phase 7-style "we need just one more cell" PRs — would be 100% data-only after this lands.

Migration shape (rough)

1. Tier-1 first: introduce --cell-library runtime parsing alongside the existing static tables. Existing tests keep passing; user-supplied libraries augment.
2. Convert one PDK's filler/io-pad/sequential classifications to YAML, prove parity in tests, leave the other as code. gf180mcu is the obvious candidate since GF180MCU: power-pin + wired-filler shortcuts for real post-P&R netlists #64 just touched it.
3. Convert the other PDK once parity is proven.
4. Deprecate the build.rs scanner; the per-PDK Rust modules shrink to AIG-decomposition rules + library default-paths.
5. New PDK / new IP: ship a manifest, no code.

Impact on docs/adding-a-pdk.md

The recipe today is "vendor + write a module + extend several lists." After this lands it becomes "ship a .cells.yaml alongside the library, point --cell-library at it, done — unless you need new std-cell decomposition rules." Existing docs/plans/gf180mcu-enablement.md § Follow-on cleanup items 2 + 3 (sharing decomp infra, moving CellLibrary enum) become natural consequences rather than separate refactors.

Surfaced by

• #64 — power-pin + wired-filler shortcuts. Each shortcut was a per-PDK workaround for what should have been data.
• A real gf180mcu-project-template post-P&R chip_top — blocked on gf180mcu_ocd_ip_sram__sram1024x8m8wm1, an IP that Jacquard can't be expected to vendor.
• docs/plans/gf180mcu-enablement.md § Follow-on cleanup items 1, 2, 3, 4 — all point at the same underlying issue.

Not blocking any active workstream upstream — filing as a design discussion. Happy to take a stab at Tier 1 once there's directional sign-off.

[robtaylor]

Directional sign-off from this side. Quick framing before a spike starts so we agree on what the first slice looks like:

Scope of the spike: Tier 1 + minimal kind tag (one slice).

Tier 1 alone doesn't unblock the OCD SRAM case — --cell-library gives us the pin table, but Jacquard still needs to know the cell is a RAM macro to allocate a DriverType::RAMBlock slot during AIG construction (currently gated on is_gf180mcu_cell's prefix matcher, which only walks fd_* / ws_*). So Tier 1 ships alongside a minimal Tier 2 — just the kind discriminator (std / dff / latch / clock_gate / ram / filler / endcap / tap / io_pad_* / delay / multi_output). That's the same data today's hand-curated matches!() lists encode; moving it into a manifest is mechanical.

Format: TOML. Already pulled in via Cargo/pyproject; consistent with the existing [tool.jacquard.pdks.*] precedent; no YAML coercion footguns on cell names with __. Concretely:

[cells.gf180mcu_ocd_ip_sram__sram1024x8m8wm1]
kind = "ram"

[cells.gf180mcu_fd_io__fillcap_18_h]
kind = "filler"

Deferred to a separate design pass: port-mapping schema (chip_enable: CEN, byte_enable_polarity: low, etc.). That's a small behavioral description language doing more than classification — versioning, validation, and an AIG-construction-side consumer all need thought. Spike Tier 1 + kind, see real adoption, then ADR the port-mapping schema with concrete data instead of guessing.

Migration order matches the issue: built-in sky130.rs / gf180mcu.rs classifiers stay as fallback through the whole transition; build.rs scanner removal happens LAST, only after the manifest pathway is the source of truth for at least one PDK in production.

Happy for you to start the spike — we'll iterate the schema as the real cases land.

[robtaylor]

Framing works for us — agree with the slice scope, TOML choice, and migration order. One thing to nail down before the spike starts so we don't over-promise what "kind = ram" delivers in the first cut:

kind = "ram" without port mapping — what does AIG construction actually do?

aig.rs today has two hardcoded RAM detection paths, both relying on convention-named ports:

• $__RAMGEM_SYNC_ (lines ~775-786): expects PORT_R_CLK / PORT_R_ADDR / PORT_R_RD_DATA[31:0] / PORT_W_CLK / PORT_W_ADDR / PORT_W_WR_EN[31:0] / PORT_W_WR_DATA[31:0]. From Yosys's memlib_yosys.txt mapping.
• CF_SRAM_* prefix (lines ~1006/1080): expects .DO output. ChipFlow's single-port convention.

The OCD SRAM port list (CLK / CEN / GWEN / WEN[7:0] / A[9:0] / D[7:0] / Q[7:0]) doesn't match either. So a manifest entry that just says kind = "ram" can do one of three things:

1. Allocate RAMBlock with zero-initialised port_r_/port_w_ and route the cell's outputs to the 32 X-source slots. Works for opaque-IP sim where downstream code doesn't read SRAM contents (Q[N] outputs propagate X, downstream forces converge correctly — compute_x_sources test at aig.rs:3247-3273 already validates this shape). Doesn't require any port-name inference, but also doesn't model memory behaviour at all.
2. Require a kind = "ram_yosys_ramgem" or kind = "ram_chipflow" flavour for known conventions, reject kind = "ram" alone. Honest about today's state. Less elegant but lets the manifest grow into the port-mapping schema cleanly.
3. Defer RAMBlock allocation entirely on kind = "ram"; treat as opaque black-box with output pins floating until the port-mapping schema lands. Pushes more work to the port-mapping pass, less to the first slice.

(1) is the unblock for downstream use cases that don't exercise SRAM contents — chip_top parses, sim runs, X-prop is well-defined. We'd happily live with (1) as the documented semantics of kind = "ram" in the first slice and let the port-mapping schema later upgrade it to "kind = ram with explicit ports gets real memory modelling, kind = ram without ports is X-source equivalent" — that decision can be made when the schema actually lands instead of guessing now.

If (1) is acceptable as the documented first-slice semantics: zero ambiguity, the spike scope is small, and the migration story is clean. If you'd rather start at (2) or (3), happy with either, but it changes whether the OCD SRAM case actually clears in the first slice or has to wait for the port-mapping pass.

Other notes:

• Agree on TOML. The __ issue in cell names is real — YAML's anchor / merge-key syntax would chew it eventually.
• Migration order with built-ins as fallback matches what's already documented in gf180mcu-enablement.md § Follow-on cleanup item 1 (build.rs pin-table generator could port SKY130 once a third PDK exercises the API surface). Manifest-as-default-data is the natural endpoint of that thread.
• Schema versioning: even the minimal slice probably wants a schema_version = "1.0" field at the top so adding port-mapping later doesn't break manifests written today. Same pattern as --timing-report JSON.

Happy to take the spike (Tier 1 --cell-library parsing + minimal-Tier-2 kind tag, TOML, semantic (1) above for kind = "ram") once you confirm (1) / (2) / (3). Will open a draft PR against main.

[robtaylor]

Vote (1), with the caveat made explicit: shipping kind = "ram" as opaque-RAM semantics needs one new code path in aig.rs — small but new. Current state is two exact-match recognisers (celltype == "\$__RAMGEM_SYNC_" at line 775 / starts_with("CF_SRAM_") at line 1006); on a non-matching SRAM macro today we fall through to standard-cell processing and misbehave. (3) reads as "the OCD SRAM case stays broken in the first slice" — defeats the point of going beyond pure Tier 1. (2) introduces vocabulary (ram_yosys_ramgem / ram_chipflow) that needs explicit sunsetting once the port-mapping schema arrives. (1) leaves the vocabulary stable across the transition: kind = "ram" opens the door to RAMBlock allocation; whether ports are resolvable is a separate question the port-mapping schema answers later.

Implementation shape — slot the new path as a fallback after the existing two recognisers:

1. celltype == "$__RAMGEM_SYNC_"  → RAMBlock with port_r/port_w resolution  (unchanged)
2. starts_with("CF_SRAM_")        → RAMBlock with .DO resolution             (unchanged)
3. NEW: manifest kind == "ram"    → RAMBlock in opaque mode
        (outputs routed to X-source slots, no port resolution attempted)

(1) and (2) keep matching first so existing tests (compute_x_sources at aig.rs:3247-3273, CF_SRAM paths) stay green without churn. The new path activates only for cells that don't match the existing recognisers AND have a manifest entry tagging them as RAM. When the port-mapping schema lands later, that's a parallel branch in (3) — manifest has ports → RAMBlock with explicit port resolution — and the opaque mode becomes the fallback within (3) for under-specified entries.

Schema versioning ✓. Top-level schema_version = "1.0". Additive rule for v1.x: new optional keys / new kind values OK, semantics of existing kind values must not narrow. The opaque-RAM semantics for kind = "ram" is part of v1.x's contract; v2.0 could split it (e.g. kind = "ram" requires ports, kind = "ram_opaque" for fallback) if real adoption shows that's cleaner, but no need to commit now.

Green-lit for the spike. Tier 1 (--cell-library) + minimal Tier 2 (kind discriminator, TOML, schema_version = "1.0"), opaque-RAM semantics for kind = "ram" as documented above, built-in classifiers stay as fallback. Open the draft PR whenever — happy to iterate on shape there rather than pre-litigating here.