chip_ignite/docs/LVS_WAIVER.md

# LVS Pin-Match Waiver — `user_project_wrapper`

**Status**: 208 LVS pin-match errors on `user_project_wrapper` are accepted as cosmetic.
**Submission**: ChipFoundry shuttle CI2605, May 2026.

## Summary

When `cf harden user_project_wrapper` runs LVS via Magic SPICE-extraction + netgen comparison, it reports 208 "no matching pin" errors and the final status `Top level cell failed pin matching`. **These errors are extraction-layer artifacts, not electrical defects.** Netgen itself reports — on the same run, in the same `netgen-lvs.log` — `Cell pin lists for user_project_wrapper and user_project_wrapper altered to match` and `Device classes user_project_wrapper and user_project_wrapper are equivalent`. The two netlists are functionally identical; only port labels are missing on the layout-side extraction.

## Root cause

The wrapper has 206 outputs tied to constants:
- `la_data_out[127:0]` ← `128'b0`
- `io_out[37:0]` ← `38'b0`
- `io_oeb[37:0]` ← `38'b1` (all inputs)
- `user_irq[2:1]` ← `2'b0`

Magic's SPICE extraction follows each constant-driven net back to the global power/ground rails. All 128 `la_data_out` bits resolve to the same extracted GND net; all 38 `io_oeb` bits to the same VDD net. Magic places one port label on the merged net (or none), so 205+ of the original output ports lose their labels in the extracted SPICE. Netgen then sees the verilog netlist declaring 206 individual ports and the extracted netlist with only a handful — hence the pin-match mismatch.

The same root cause produces the additional report of `vssd2 in netlist only` (PDN power-net naming asymmetry between netlist and layout — fixed in the May 7 PDN swap, commit `8cc8414`) and `io_oeb[9] in layout only` / `user_irq[2] in layout only` (Magic arbitrarily keeps one label per merged net).

## Why this is not a real defect

1. **Netgen confirms electrical equivalence.** From the LVS report's own final summary:
   > `Cell pin lists for user_project_wrapper and user_project_wrapper altered to match.`
   > `Device classes user_project_wrapper and user_project_wrapper are equivalent.`
   The mismatched pins all belong to nets that, after Magic's extraction, are the same global power/ground nets in both netlists. The connectivity is correct.
2. **Magic DRC: 0 violations.** GDS layout is manufacturable.
3. **Gate-level simulation passes.** All 5 cocotb tests on the Caravel-integrated gate-level netlist (`cf verify <test> --sim gl`) return `GPIO[7:0] = 0xAB` (the firmware's success code):
   - `ldpc_basic`, `ldpc_noisy`, `ldpc_max_iter`, `ldpc_back_to_back`, `ldpc_demo` — all PASS (originally verified May 1, 2026 on `cf_wrapper_v5`)
   - **Re-verified May 13, 2026 on HEAD (`8cc8414`, the PDN-fix wrapper)**: `ldpc_basic` PASSED at `854225.00ns`, GPIO[7:0]=`0xAB`, 0 criticals / 0 errors / 0 warnings, 34169 cycles consumed (of 37586 recommended timeout), 2h 19min wall-clock. The PDN swap between `cf_wrapper_v5` and HEAD only changes which physical rails connect to `mprj` (`vccd1/vssd1` instead of `vccd2/vssd2`); both rails sit at 1.8 V in simulation, so the other 4 tests' May 1 results apply unchanged to HEAD.
4. **`mpw_precheck`: 17 of 19 checks PASS** (`cf precheck` on `cf_wrapper_v5`, May 1, 2026). The two failures are:
   - **KLayout FEOL**: a `SIGSEGV` (signal 11) crash inside the KLayout DRC tool, not a real DRC violation.
   - **LVS**: the cosmetic pin-match issue described in this waiver.

   All structural, consistency, GPIO, XOR, Magic DRC, KLayout BEOL/Offgrid/Metal-Density/Pin-Labels/ZeroArea, Spike, OEB, License, Documentation, and Makefile checks pass.

## Why per-pin tieoff cells do not help (verified by experiment, May 8 2026)

On May 7–11, 2026, seven follow-up `cf harden user_project_wrapper` runs (`cf_wrapper_v6` through `v11`) attempted to eliminate the 208 errors. The most thorough — v8 — replaced the bulk `assign la_data_out = 128'b0; …` tieoffs with **206 individually-instantiated `sky130_fd_sc_hd__conb_1` cells**, each with its own logical output net driving a single wrapper output pin, hand-placed via `MANUAL_GLOBAL_PLACEMENTS` next to its target pin:

```verilog
sky130_fd_sc_hd__conb_1 tie_la_data_out_0 (.LO(la_data_out[0]));
sky130_fd_sc_hd__conb_1 tie_la_data_out_1 (.LO(la_data_out[1]));
…
sky130_fd_sc_hd__conb_1 tie_io_oeb_37 (.HI(io_oeb[37]));
```

**Result: the same 208 LVS errors.** Magic's extraction propagates each `conb_1` output back through its `.LO` / `.HI` port to the global VGND/VPWR rail at the extracted-SPICE level, collapsing all 206 distinct logical nets into the same two power nets. Adding per-pin standard cells changes the synthesized netlist but does not change Magic's extraction behavior.

The v9 and v10 attempts (more placement tweaks and looser routing-DRC tolerance) regressed the layout to 1780 and 1362 routing DRC errors respectively. v11 was interrupted. None succeeded.

The full archive of these experiments is preserved at `experiments/2026-05-12-archive-v6-v11/` with a per-file README explaining what was tried and why it failed. The lessons are also documented in the project repository's `docs/hardening-results.md` ("Wrapper Hardening Attempts (May 7-11, 2026)").

## Comparable precedent

The Caravel reference design `user_proj_example` uses the same bulk constant-tieoff idiom (`assign la_data_out = 128'b0; assign io_out = …; assign io_oeb = …; assign user_irq[2:1] = 2'b0;`) and exhibits the same LVS pin-match pattern when hardened with `SYNTH_ELABORATE_ONLY=true`. This is a known limitation of the Magic + netgen flow on wrappers with bulk-tied unused outputs, not a defect specific to this design.

## What would fix it (deferred — too risky for this submission)

The only methodologically clean fix is to drive the 206 wrapper-output bits from inside the macro `ldpc_decoder_top` as dummy zero outputs, so each wrapper output connects to a distinct extracted macro pin. This requires a full macro re-harden. Yosys synthesis of this macro is non-deterministic (documented in `docs/hardening-results.md`), and the current macro netlist (`balanced_popcount` synthesis, Run 6) is the only run proven to meet TT-corner timing at 50 MHz with clean DRC. Re-hardening the macro to add dummy outputs risks losing that timing closure. The trade-off — 4–6 hours of re-harden + regression risk vs. a cosmetic LVS issue with no electrical consequence — is not worth taking under the contest's tapeout deadline.

## Conclusion

The 208 LVS pin-match errors are extraction-layer bookkeeping, not electrical defects. The device classes are equivalent, gate-level simulation passes, the GDS is DRC-clean, and 17 of 19 precheck checks pass. The design is electrically correct and manufacturable.

We respectfully request the LVS pin-match failure be accepted as a waived cosmetic issue.

---

**References**
- `docs/hardening-results.md` — full hardening history, including v6–v11 attempts and root-cause analysis
- `experiments/2026-05-12-archive-v6-v11/README.md` — archived v6–v11 experiment files and per-file analysis
- `signoff/user_project_wrapper/openlane-signoff/netgen-lvs.log` — netgen's own "Device classes equivalent" / "Cell pin lists altered to match" lines
- `signoff/user_project_wrapper/openlane-signoff/lvs.rpt` — full LVS report
- Commit `8cc8414` (May 7, 2026) — PDN net-assignment fix that resolved the prior `vssd1/vssd2` symmetry issue
- Commit `74ad20a` (May 1, 2026, `cf_wrapper_v5`) — golden wrapper hardening