LVS Triage
LVS proves that the drawn layout corresponds to the schematic / netlist. Mismatches are common in early iterations. This skill reads LVS reports (Calibre, Netgen, Pegasus) and proposes focused fixes.
When to use
- After routing / layout finalization
- After any manual layout edit
- Before tapeout sign-off
- When integrating analog macros into a digital floorplan
Inputs
- LVS report file (Calibre
.rep, Netgencomp.out, etc.) - Schematic netlist (
.cdl/.sp/.v) - Extracted layout netlist
- Device model list (PDK-specific)
Workflow
- Parse report into categories:
- Unmatched instances
- Unmatched nets (shorts, opens)
- Device parameter mismatches (W/L, M, NF)
- Property mismatches (labels, dummies)
- Top-3 root-cause check:
- Missing label on a net (most common)
- Missing via between metal layers
- Wrong device variant picked from PDK
- For each mismatch propose the exact layer + coordinate to edit
- Batch waivers: some analog dummies intentionally don't appear in schematic — document waiver
- Re-run plan: minimal LVS subset to re-verify
Output format
lvs/lvs_triage.md:- Mismatch summary (count by category)
- Top 20 mismatches with fix
- Waiver list with justification
- Re-run script
Technical basis
LVS methodology references: Mentor Calibre user guide, open-source Netgen (http://opencircuitdesign.com/netgen/). Signoff tools: Calibre LVS, Cadence Pegasus, Synopsys IC Validator.
Structural-LEC "unproven cells" are a substitute-tool gap — cover with device-level LVS (captured v0.1.98)
eda_lvs mode=yosys_equiv is structural LEC (yosys equiv_simple+equiv_induct): it proves
Boolean equivalence with a SAT engine. That engine lacks a model for some standard-cell
primitives, so those cells come back "unproven" / sat_model_unsupported_cells — this is a
LIMITATION OF THE SUBSTITUTE TOOL, not a netlist mismatch, and no yosys flag closes it for
all cells (-undef, deeper equiv_induct -seq N, dfflibmap/async2sync only widen it).
To actually cover the unproven cells, switch to device-level LVS (the sky130/gf180 sign-off path — netgen has no SAT-model concept, it matches transistors):
eda_extraction(magic ext2spice, pdk=sky130, output_format=spice) — GDS → flat layout SPICE.- Use the selected foundry Netgen setup and native global-net commands. Include the actual standard-cell SPICE models on the schematic side and keep layout extraction and schematic hierarchy comparable.
- netgen
lvs <layout.spice> <schematic>with the foundry setup + the supplement, AND the std-cell SPICE library loaded into the SCHEMATIC circuit so each gate expands to transistors (else the schematic cells are empty placeholders → a false device-granularity mismatch). This reaches device-class-exact (e.g. HDLC: 20937 = 20937 devices, all 4 classes equivalent — the 230 yosys-unproven cells became 0 device-level-unproven; cf. benchmark_clean sha256 device-exact 12148 = 12148).
Expected honest residual when the schematic side is a logic-only Verilog netlist: the tie
cells (sky130 conb_1 = two poly resistors to VPWR/VGND) show their power-side terminals as
disconnected, because a post-PnR Verilog gate netlist has NO power connectivity (grep VPWR = 0).
This is a Category-D Verilog-vs-extracted power-modeling artifact (sha256 documented the same),
NOT a real mismatch — every logic net + all devices match. Closing it fully needs a power-aware
SPICE schematic side. Caveat: eda_lvs mode=netgen's matched flag is currently an unreliable
regex (see ORGANIC-20260531-eda-lvs-netgen-false-positive-and-no-stdcell-lib) — verify against the
real netgen verdict lines ("Circuits match"/"failed pin matching"/device-class equivalence), not
the boolean.
Read the native Netgen/KLayout LVS comparison for the actual selected layout and schematic. Inspect unmatched devices, nets and pins and retain the original PDK comparison rules.
Top-level pin matching needs PORTS on the layout .subckt — two routes (captured v0.1.114)
After device-level netgen reaches device-count-exact + classes-equivalent (e.g. HDLC
16393=16393, 0 disconnected nodes), the last residual is often
Final result: Top level cell failed pin matching — because the Magic GDS flat extraction emits
a portless .subckt <top> (empty port list), so netgen's name-matching partition has nothing
to anchor (flat layout nets ≠ schematic nets, disjoint naming). Two general programs close this:
Route A — canonical cause-fix (PREFER):
programs/magic_port_extract_emit.py. Emits the Magicport makeallextraction TCL + the shell preamble. Two prerequisites, both proven on HDLC: (1)export PDK=<pdk>andPDK_ROOTin the SHELL before magic launches (the system.magicrcreads$env(PDK)at startup — an in-scriptset env(PDK)is too late; theeda_run_tcl engine=magicwrapper currently does NOT export it → see ORGANIC-20260531-magic-extraction-no-toplevel-ports; drive viadocker exec vibeic-edawith the export preamble). (2)port makeallonly promotes labels on the PDK port-purpose layer (sky130MET3PIN= GDS 70/16); an OpenROAD GDS-streamout step that put pin text on a drawing layer (sky130 10/1) yields nothing — relabel 10/1→70/16 (klayout) first. Result on HDLC: a real port-labeled flat.subckt hdlc_core_flat clk fcs_ok …with 20937 devices, and the netgen verdict advances past the pin-match-seed stage. (To reach "Circuits match uniquely" the moved label must also be geometrically snapped to the met3 routing shape so it ties to the net.)Route B — tool-independent fallback:
programs/lvs_def_port_seed.py. Parses ANY DEFPINSsection → ordered(pin, net, direction), and emits both a netgen port-seed TCL and an ordered port list to inject into the portless.subckt <top>line. Runs NOW, no Magic dependency. Honest limit (proven on HDLC): name-seeding ALONE does NOT converge a flat extraction whose internal nets carry Magic auto-names (a_NNNN#) — the injected ports become disconnected pins (HDLC: 47 disconnected pins). Route B is a partition HINT / audit artifact; when the layout body has no matching net names, Route A (real label promotion tied to geometry) is genuinely required — say so rather than reporting a false PASS.
Both are deterministic + pytest-pinned (programs/tests/test_magic_port_extract_emit.py,
programs/tests/test_lvs_def_port_seed.py).
When a field design-side recipe SUCCEEDS but runner automation FAILS: DIFF the two runs' INPUTS first (captured #512)
When you are field-verifying a plugin's automation of a recipe the field agent ALREADY proved by hand — the runner's automated run FAILs at some step while the field's manual run SUCCEEDED at that same step — do NOT re-triage the failure from scratch. Chasing the failure text (e.g. a netgen "Netlists do not match" / "failed pin matching") leads to round after round of symptom fixes.
Instead, DIFF what the successful field run fed vs what the runner fed at that step: which netlist, which env var, which extraction path, which artifact version. That single differing INPUT is almost always the plugin's blind spot — the runner's automation silently selected a different (wrong) input that the field, running by hand, implicitly avoided.
Worked evidence (the same GDSII-LVS feature, twice):
- #508 — the env var was
exported in the magic-extraction shell, but the tool that consumes it (netgen) runs in a SEPARATE shell (_docker_exec= freshbash -lcper call, env does not persist). Input delta = shell scope. - #509 — the LVS schematic side used the PRE-PnR synth netlist (spare=0,
clkbuf=0) while the field used the POST-PnR netlist (spare=18, clkbuf=89).
Input delta = netlist choice. Signoff now selects the paired DEF and
nlviews from the final LibreLane State through_prestream_native.signoff_inputs.
Neither root cause is visible in the failure text; both surface INSTANTLY from a field-input-vs-runner-input diff — short-circuiting N rounds of surface fixes. General rule: every field→core handoff where the field has manually proven the recipe — the runner's automation has likely picked a different input than the field did; diff the inputs first.
Switching a design-side artifact to runner-auto regeneration leaves a stale provenance entry — verify provenance completeness before declaring the upgrade done (captured #516)
When you promote a step output from a design-side manually-installed
artifact to runner-auto regeneration — i.e. you move the design-side
artifact aside so the runner freshly selects its own input (the right move to
avoid the #512 input-masking blind spot) — the design-side provenance.jsonl
entry it leaves behind goes stale in two distinct ways, and you must
reconcile BOTH before you can honestly call the design-side→runner-auto switch
"done":
- (a) generated_by is stale even when the bytes are identical. If the
runner reproduces the same recipe, the runner output is byte-identical and
the entry's content hash still matches — but the entry's
generated_byfield is now wrong (it claims design-side; the file on disk is the runner's). A byte-identical hash is actually the proof that runner-auto == the design-side recipe, but it does NOT make the provenance attribution correct. (繁中:generated_by過時 — 雜湊雖對,歸屬已錯。) - (b) other declared outputs of the entry can go missing. A provenance
entry frequently declares MORE than one output (e.g. the report and the
tool's stdout log). If you move those aside and the runner only regenerates
SOME of them under the same names, the entry's other declared outputs are now
absent → a
PROVENANCE_OUTPUT_FILE_MISSING/ completeness failure.
Doctrine: before declaring the switch complete, run the provenance output-hash completeness check, and then either restore the moved-aside declared outputs (regenerate them under their declared names) or supersede the stale entry (write a fresh runner-authored entry so the runner entry is authoritative). Pick restore-vs-supersede by intent, not by reflex.
Worked evidence (spm LVS upgrade): moved aside lvs.rpt +
lvs_netgen_stdout.log; the runner regenerated lvs.rpt (byte-identical hash —
runner-auto result == design-side recipe) but did NOT regenerate the stdout log
under that name → the stale entry's declared log was missing → P0 provenance
FAIL; restoring the log fixed it.
why_not_bucket_a: deciding whether a given stale entry should be superseded (runner now owns it) or have its outputs restored depends on whether the runner wrote its own replacement entry AND whether a byte-identical output is semantically the runner's — a provenance-intent judgement, not a fixed rule. The deterministic residual (the completeness check that catches a missing declared output) already exists and fires correctly; this section is the judgement layer over it. So when you switch a design-side artifact to runner-auto, treat the provenance reconciliation as a required closing step, not an afterthought.
Captured rule — Extract a sealed chip stream as vendor GDS
When the final Magic.SpiceExtraction of a sealed SKY130 chip fails with
"Encountered one or more fatal errors while running Magic." and Netgen LVS/PERC
then have no SPICE, read the extraction log before touching LVS. If every
Error while reading cell ... Unknown layer/datatype names a PDK seal-ring cell
(sr_polygon*, nikon_sealring_shape, sealring_slots, seal_ring_corner)
on foundry marker/mask layers (81/51, 81/52, 61/20, 22/22, NN/0 masks), the
defect is the read mode, not the layout: the PDK generator documents those
layers as outside the user-facing tech and meant for vendor-GDS use, and
LibreLane's own Magic.DRC reads the same finished stream with
gds noduplicates true; gds readonly true. Read it the same way in the chip's
extraction rc (flow_chip_inputs.py, extraction-only block); do not lower
MAGIC_CAPTURE_ERRORS, filter the log, drop markers from the stream or edit the
seal ring. Prove it with an A/B on the real sealed stream: SPICE and every
.ext must be identical between the reads, only the read errors disappear.
Measured (cpu_queue sha256-sealed-extraction-vendor-i0476-cl, image 0.4.76,
sealed Subservient v1.40.67 chip): ordinary read 37 errors -> step FAIL;
vendor read 0 errors, SPICE byte-identical (53006 lines, 51196 X), 107/107 .ext
identical, illegal overlap measured 27, Netgen LVS 0 errors (2464 = 2464
devices, circuits match uniquely). A read error on any non-PDK cell is still a
real defect: KLayout DRC/XOR read every layer and stay the check for it.
Handoff
- Re-run DRC after LVS fix →
/drc-fix - Layout edits → documented in
/eco-planlog - Schematic change → back to
/rtl-repairor/analog-layout