Skip to content

SPEC.md

Latest commit

 

History

History
187 lines (154 loc) · 8.81 KB

SPEC.md

File metadata and controls

187 lines (154 loc) · 8.81 KB

Frame-View GDS Specification

Version: 0.1 (draft)

This document defines the contents of a frame-view GDS for a hard macro — the reduced-information GDS that can substitute for the real macro GDS in a chip-level physical flow (P&R, DRC, antenna, density, LVS) without exposing proprietary layout.

A conformant frame view is interchangeable across tools: any backend accepting this spec will accept frame views produced by the reference macrostrip implementation or by any other tool that writes a conformant GDS.

Goals

  • Boundary-equivalent to the real macro. Anything a chip-level tool can see at the macro boundary (pin shapes, power rails, outline) must be byte-identical between the frame view and the real macro.
  • Safe to share. Nothing proprietary — no internal cells, no internal routing, no identifiable fingerprints.
  • Tool-agnostic. Standard GDSII only. No tool-specific annotations.

Non-goals

  • Accurate internal density, parasitic extraction, or internal DRC. Those are the responsibility of the real macro and are evaluated by the macro owner before shipping the LEF/Liberty.

Required contents

A frame-view GDS for macro cell MACRO MUST contain:

  1. One top cell named exactly MACRO, matching the LEF MACRO MACRO declaration and the Verilog black-box stub module name.
  2. All signal/clock pin shapes, on the layers and at the coordinates declared by the LEF PIN ... PORT ... LAYER ... RECT/POLYGON statements. Shapes MUST be geometrically identical to the real macro on each LEF-declared layer.
  3. All power/ground pin shapes and boundary-crossing rails, on the layers declared by PIN ... USE POWER/GROUND. Shapes MUST be geometrically identical to the real macro wherever they cross the PR boundary or lie on a pin layer.
  4. Per-pin text labels with the LEF pin name as the text string, placed on at least one of the pin's declared shape layers. Chip-level LVS and name-based routing match pin geometry to pin nets via these labels; without them the frame is geometrically correct but nameless. Trailing global-net characters (e.g., LEF's !) are preserved in the label string; consumers that can't handle them are responsible for escaping.
  5. A version marker cell named $MACROSTRIP_V1 containing a single text label on layer (63, 63) with the string macrostrip-frame-view v1. Backends use this marker to detect the spec version on submission.

Optional contents

A frame view MAY contain:

  • PR boundary polygon on a PDK-specific prBoundary (or equivalent) layer, matching the LEF SIZE ... BY ... dimensions. Useful for flows whose DRC decks or placement tools query an explicit outline layer. Many PDKs (e.g., IHP SG13G2) define such a layer; others (e.g., GF180MCU) don't. When generators emit this polygon, they SHOULD use the layer the target flow expects.
  • Density fill (metal cheesing pattern) on metal layers, to preserve chip-level density DRC. If included, the fill pattern MUST NOT reveal internal structure — a uniform grid of identical tiles (or a vendor-sanctioned pattern) is acceptable. The reference implementation reads an OpenROAD-compatible density-fill JSON (the same schema that ORFS platform directories use, e.g. orfs/flow/platforms/ihp-sg13g2/fill.json): per LEF layer, a list of rectangle sizes (largest first), space_to_fill, space_to_non_fill, and space_to_outline. Fill is emitted as hierarchical array instances of density-fill sub-cells (see §Forbidden exception), sized and spaced per the JSON and clipped to macro_area − (pins ∪ OBS). Multi-size entries are applied largest first, chaining the unfilled remainder to the next size.
  • Well / nwell / deep-nwell shapes crossing the boundary, if the PDK's chip-level DRC requires well continuity. The conventional form is a single rectangle covering the full macro footprint (equal to LEF SIZE), since any finer well structure would leak internal layout.
  • Obstruction (LEF OBS) shapes, which provide routing blockages on specified layers above the macro.

Forbidden contents

A frame view MUST NOT contain:

  • Any cell other than MACRO, $MACROSTRIP_V1, and density-fill sub-cells whose names start with $MACROSTRIP_FILL_ (one per (layer, size) combination emitted by density fill; see §Optional contents).
  • Any shape inside the PR boundary that is not (a) a pin, (b) a boundary- crossing rail, (c) an OBS shape, (d) optional density fill, or (e) well/ nwell shapes.
  • Standard-cell instances, logic gates, flip-flops, memories, or any recognizable circuit structure.
  • Internal interconnect routing.
  • Layer-purpose pairs not used by the real macro at the boundary.
  • Cell names, text labels, or property values that could identify or fingerprint the real design beyond the macro's publicly advertised name.

Validation

A backend consuming a frame view SHOULD verify:

  1. The version marker cell is present and readable.
  2. The top cell name matches the LEF MACRO name.
  3. All LEF-declared pins have matching GDS shapes on the declared layers.
  4. All LEF-declared pins have a text label with the pin's name on at least one of the pin's declared layers.
  5. If the frame includes a PR-boundary polygon, it matches LEF SIZE. Backends SHOULD NOT require the polygon's presence — flows for PDKs without a PR-boundary convention legitimately omit it.
  6. No cells other than the top cell, the version marker, and density-fill sub-cells whose names start with $MACROSTRIP_FILL_ are present.

The reference macrostrip validate command performs these checks.

Swap operation

The reverse operation — substituting a frame view with the real macro in a finished chip GDS — is a cell-definition replacement keyed only on cell name:

  • The real macro's top cell MUST be named identically to the frame view's (MACRO); that name is the swap's identity contract.
  • Replacing the cell's contents in place preserves its cell_index, so every instance reference from parent cells remains valid without re-instancing.

The swap operation MUST:

  • Refuse to swap if the real macro GDS contains a $MACROSTRIP_V1 marker (the real input is itself a frame view — a likely user error).
  • Refuse to swap if no cell named MACRO exists in either the chip or the real macro GDS.
  • Preserve all placements, orientations, and transforms of the macro instance in the chip cell hierarchy.

The swap operation intentionally does NOT compare pin or boundary geometry between the frame and the real macro. Cell-name identity is the contract; if the user supplies a real macro with the wrong size or pin layout under a matching cell name, chip-level LVS and DRC will catch it downstream. Many PDKs have no canonical PR-boundary layer, so requiring a geometric match would turn legitimate swaps into errors for no gain.

Companion blackbox JSON

Alongside a frame-view GDS, macrostrip may emit a <macro>.blackbox.json describing the macro in a tool-agnostic form so downstream tooling can consume pin metadata without re-parsing LEF. The JSON is a build-time handoff — it is not part of the tapeout deliverable and does not participate in the swap operation.

Schema (JSON object):

  • version: string literal "1" for this spec revision.
  • name: string. Macro top-cell name.
  • boundary: { "width": number, "height": number } in micrometers.
  • pins: array, one entry per logical pin (bus bits grouped into a single entry):
    • name: string. Base name without bus index; LEF trailing ! is preserved (e.g. "VDD!").
    • direction: "in" | "out" | "inout". "inout" is the default when LEF omits DIRECTION.
    • width: positive integer. Scalar pins have width 1.
    • msb, lsb: integers. For scalars, both are 0. For buses, these are the highest and lowest indices found in LEF; a contiguous bus has width == msb - lsb + 1.
    • role: "signal" | "clock" | "power" | "ground" | "reset". Mapped from LEF USE: POWER→power, GROUND→ground, CLOCK→clock, SIGNAL→signal. "reset" is reserved for future heuristic or manual annotation; macrostrip never emits it today.
  • files (optional): object of companion file paths relative to the JSON file's directory. All entries are optional:
    • lef, liberty, verilog_stub, frame_gds.

Consumers MAY reject JSON whose version field they don't recognize.

Open questions (v0.1)

  • How much density-fill detail is acceptable before it becomes a fingerprint? Likely PDK-specific; revisit after real-world use.
  • Do we need a manifest file alongside the GDS (YAML/JSON) with a hash of the real macro's boundary shapes, to let the backend cross-check swap compatibility without seeing the real macro?
  • Version bump policy: any change to required/forbidden contents bumps the major version.