From 68afbcb75f2fa3e57ae32f4174e09cd4569cc6a6 Mon Sep 17 00:00:00 2001
From: dgaddy <dgaddy@ucsc.edu>
Date: Fri, 3 Jul 2026 00:41:05 -0700
Subject: [PATCH] floonoc sky130hd: fix PSM-0069 by reducing io.tcl edge_margin
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Bottom-edge IO pins on met2 at edge_margin=5.0μm had their
spacing-expanded obstruction (obs_yMax=5381nm) overlapping the row-0
VSS via area (y_min=5200nm). pdngen's Grid::makeVias silently dropped
all row-0 met1×met4 via candidates as kObstructed — no PDN-0110 fires
for obstruction removal — so the VSS stripe terminated short of row 0,
leaving every cell in that row with VGND disconnected (PSM-0069).

Fix: reduce edge_margin from 5.0→4.37μm (nearest valid met2 y-track
below the 4.82μm threshold); obs_yMax drops to 4751nm, clearing the
via area. _final passes with [INFO PSM-0040] All shapes on net VSS
are connected.

Documents root cause in CLAUDE.md known-bugs table and DECISIONS.md;
updates debug-design skill with a PSM-0069 recognizer.
---
 .claude/skills/debug-design/SKILL.md |  4 ++++
 CLAUDE.md                            |  5 +++--
 designs/sky130hd/floonoc/io.tcl      |  8 ++++++--
 designs/src/floonoc/DECISIONS.md     | 10 +++++-----
 4 files changed, 18 insertions(+), 9 deletions(-)

diff --git a/.claude/skills/debug-design/SKILL.md b/.claude/skills/debug-design/SKILL.md
index ab4a2203..584c9a93 100644
--- a/.claude/skills/debug-design/SKILL.md
+++ b/.claude/skills/debug-design/SKILL.md
@@ -131,6 +131,7 @@ tail -200 logs/<platform>/<design>/base/2_*.log
 
 2. **PDN failures**: Power grid cannot be constructed.
    - Check if `pdn.tcl` exists and metal layer names match the platform (M1-M7 for asap7, met1-met5 for sky130hd)
+   - If `2_4_floorplan_pdn.log` is clean but PSM-0069 fires at Stage 6, see **G (PSM errors)** — via obstruction leaves no trace in the PDN log
 
 3. **IO placement failures**: Too many pins for the die perimeter — increase die area or create a manual `io.tcl`.
 
@@ -229,6 +230,9 @@ head -50 reports/<platform>/<design>/base/6_finish_drc.rpt 2>/dev/null
 # Or manually parse 6_report.json
 ```
 
+**PSM errors** (power connectivity, `6_*.log`):
+- **PSM-0069** — check if all PSM-0039 warnings cluster in a single boundary row. If so, vias to that row were likely silently dropped by pin obstruction (no PDN-0110 fires for obstruction removal). See CLAUDE.md bugs table for root cause and fix.
+
 ---
 
 ## Step 4: Generate Layout Images
diff --git a/CLAUDE.md b/CLAUDE.md
index 23fac27b..111a8cb3 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -82,11 +82,11 @@ Per-design close history, knobs, QoR, and known issues live in **`designs/src/<d
 **The authoritative "which pairs finish" list is the `webpage` worktree's `results.html`** (one QoR row per finishing pair), not this index — the lists below had drifted stale (they understated coverage; e.g. eyeriss/floonoc/litepci/snitch_cluster/ternip/partition_p all finish). As of the 2026-06 toolchain upgrade the suite has **59 finishing (platform, design) pairs**.
 
 Reaching `_final` on the **2026-06 upgraded tools** (bazel-orfs `553c1c3`), validated clean (QoR within ~5 % of the pre-upgrade `results.html` baseline):
-- lfsr, minimax, sha3, ternip (all 3 platforms); coralnpu, liteeth, gemmini, litedram (all 3); NyuziProcessor (asap7/nangate45); floonoc (asap7/nangate45); eyeriss (all 3); litepci (asap7/nangate45); **all NVDLA partitions a/m/o/p (asap7/sky130hd), a/c/m/o/p (nangate45), partition_c (asap7)**; vortex-asap7.
+- lfsr, minimax, sha3, ternip (all 3 platforms); coralnpu, liteeth, gemmini, litedram (all 3); NyuziProcessor (asap7/nangate45); floonoc (all 3 platforms); eyeriss (all 3); litepci (asap7/nangate45); **all NVDLA partitions a/m/o/p (asap7/sky130hd), a/c/m/o/p (nangate45), partition_c (asap7)**; vortex-asap7.
 
 Reaching `_final` but with a **flagged QoR regression** the upgrade introduced (not flow-knob recoverable without RTL/SDC — see each DECISIONS.md): vortex-nangate45/sky130hd (yosys-0.64 FF-fallback cell growth +25–28 %), cnn-nangate45 (new-RTLMP macro placement, Fmax −49 %), coralnpu-sky130hd / vortex-sky130hd (marginal setup), litepci-nangate45 (pre-existing unconstrained forwarded clock).
 
-In progress / not yet re-validated on the upgraded tools at last checkpoint: cnn-asap7/sky130hd, bp_uno (all 3), snitch_cluster (asap7/nangate45), litepci-sky130hd (GRT-congestion retune), floonoc-sky130hd (reaches `6_final` but PSM-0069 VSS power-grid check fails the report). sky130hd NVDLA partition_c still does not finish (GP plateau).
+In progress / not yet re-validated on the upgraded tools at last checkpoint: cnn-asap7/sky130hd, bp_uno (all 3), snitch_cluster (asap7/nangate45), litepci-sky130hd (GRT-congestion retune). sky130hd NVDLA partition_c still does not finish (GP plateau).
 
 Use `tools/fetch_cache.sh` to pull cached `_final` results from the remote cache; designs in the local-only / not-finishing lists above aren't on it.
 
@@ -149,6 +149,7 @@ Designs in this repo carry workarounds for upstream tool bugs. Update this table
 | **`repair_timing` non-convergence** — repair loop spends iterations on the same RTL-bounded endpoint without making progress. Not a bug per se, but a flow pathology when the clock target is too tight for the design | asap7 `snitch_cluster`, asap7 `litedram` | `SKIP_INCREMENTAL_REPAIR = 1` to skip post-GRT `repair_timing` | `39ca8670` | None |
 | **ODB-0445** in post-GRT `repair_timing` — `[CRITICAL ODB-0445] No undo_updateField support for type dbTechNonDefaultRule`. The resizer's `Journal::undo` can't unroll changes to `dbTechNonDefaultRule` made during repair; crash trips during the slack-spiral retry on a single endpoint. Surfaces in dense placements that need NDR-using moves | asap7 `NyuziProcessor` (post util 55→65 PPA push) | `SKIP_INCREMENTAL_REPAIR = 1` — same workaround family as `repair_timing` non-convergence; detailed-route hold-repair still runs | (this PR) | None (no upstream issue filed yet) |
 | **LiteX GENSDRPHY `input sdram_dq`** — `litedram/gen.py` declares the bidirectional SDR DQ bus as a plain `input` port (Lattice-platform convention; the tristate buffer lives at the IOB), but the same module instantiates 16 `TRELLIS_IO` cells that internally drive the port via OE-gated logic. yosys' `check -assert -mapped` sees the conflict and aborts synth on all 3 platforms | asap7/nangate45/sky130hd `litedram` | Patch `litedram_core.v` to make `sdram_dq` an `inout` port (`patch/litedram_core.patch`). Combined with `SYNTH_HIERARCHICAL = 1` so abc keeps each `TRELLIS_IO` as a hierarchy boundary | (this PR) | None (LiteX `gen.py:870` carries a `# FIXME: Allow other Vendors.` note) |
+| **PSM-0069 power/ground net not reaching boundary row** — `Grid::makeVias` silently drops via candidates connecting a power/ground stripe to the boundary cell row when signal IO pins on an intermediate layer have their spacing-expanded obstruction overlapping that row's via area; the stripe terminates short of the boundary row, leaving all its cells with disconnected power/ground. No PDN-0110 fires for obstruction removal (PDN-0110 is for via geometry failures only); manifests as a PSM-0039 flood on boundary-row instances and PSM-0069 at `_final`. | sky130hd `floonoc` | Reduce `edge_margin` in `io.tcl` until the IO-pin obstruction clears the boundary-row via area; threshold: `edge_margin < core_yMin − row_height/2 − met_spacing`. See DECISIONS.md for platform-specific values. | `bbc7fd0` | None filed upstream |
 | ~~**CTS-0122** false skip~~ **RESOLVED 2026-06** — `dbNet::getFirstOutput()` skipped the driver of clock nets sourced by a `clock: true` macro output. Fixed upstream ([#10549], `cd4f5041`); the OpenROAD `299f3015` pin is past it, so the local `patches/openroad-cts-0122-fix.patch` was **dropped**. litepci-asap7 went from WNS −883 ps (broken clock tree) to +944 ps. | sky130hd/nangate45/asap7 `litepci` | (removed — fix in pin) | (this PR) | [OpenROAD#10549](https://github.com/The-OpenROAD-Project/OpenROAD/pull/10549) (merged `cd4f5041`) |
 
 ### Useful ORFS env vars for these workarounds
diff --git a/designs/sky130hd/floonoc/io.tcl b/designs/sky130hd/floonoc/io.tcl
index 65143987..efc3c2f0 100644
--- a/designs/sky130hd/floonoc/io.tcl
+++ b/designs/sky130hd/floonoc/io.tcl
@@ -21,7 +21,7 @@
 # pin shape is fully contained — earlier attempts with -force_to_die_boundary
 # triggered GRT-0209 "pin completely outside die" on bigger-pin platforms.
 
-# ── asap7 layer config (from platforms/asap7/config.mk + make_tracks.tcl) ──
+# ── sky130hd layer config (from platforms/sky130hd/config.mk + make_tracks.tcl) ──
 set hor_layer  met3    ;# IO_PLACER_H — pins on left/right edges
 set ver_layer  met2    ;# IO_PLACER_V — pins on top/bottom edges
 set hor_offset 0.34  ;# met3 y_offset
@@ -29,7 +29,11 @@ set hor_pitch  0.68  ;# met3 y_pitch
 set ver_offset 0.23  ;# met2 x_offset
 set ver_pitch  0.46  ;# met2 x_pitch
 
-set edge_margin 5.0      ;# distance from die edge (well > pin width / 2)
+set edge_margin 4.37     ;# distance from die edge; must keep met2 obstruction top
+                         ;# below row-0 VSS via area (y=5200 nm). At 5.0 um the
+                         ;# met2 spacing-expanded obstruction reaches y=5381 nm,
+                         ;# blocking every met1-met4 via at row 0. At 4.37 um it
+                         ;# reaches y=4751 nm, clearing the via area.
 set end_margin  5.0      ;# distance from corner along the edge
 
 proc bus_pins {name high {low 0}} {
diff --git a/designs/src/floonoc/DECISIONS.md b/designs/src/floonoc/DECISIONS.md
index 8dc3ff10..bdb59505 100644
--- a/designs/src/floonoc/DECISIONS.md
+++ b/designs/src/floonoc/DECISIONS.md
@@ -44,18 +44,18 @@ Network-on-chip with std-cell-only logic; the only physical-design knobs are clo
 
 ## sky130hd
 
-**Status**: reaches `_final` on bazel-orfs 553c1c3 (was "not finishing" on the old tools)
-**Last updated**: 2026-06-04 (toolchain upgrade)
+**Status**: finishing
+**Last updated**: 2026-06-26 (commit `bbc7fd0`)
 
 ### Configuration
 - `TNS_END_PERCENT = 100`
-- `io.tcl` present
+- `io.tcl` present — `edge_margin = 4.37 µm` (see Decisions for why)
 - Clock: `20.0 ns` (Fmax target ~50 MHz)
 
 ### Decisions
 - **2026-04-29 `ec7be591`**: gave the same treatment as the working platforms (io.tcl + 20 ns clock) but synthesis still doesn't reach `_final` on sky130hd.  Stops at `1_synth` per `tools/summary.sh` "Incomplete builds" output.
 - **2026-06-04 toolchain upgrade (bazel-orfs 553c1c3 / OpenROAD 299f3015 / yosys 0.64)**: big step forward — the old-tools synth stall is gone and the flow runs all the way to `6_final.odb`. **But the final report fails PSM-0069**: `Check connectivity failed on VSS` — many TAP/FILLER/stdcell `VGND` pins are left unconnected by the default sky130hd PDN under the new tools (PSM-0039 warnings precede it). So it produces a routed DB but not a clean signoff. **Flagged** — needs a PDN fix (followpin/strap coverage of VSS, likely a `pdn.tcl`) to close PSM; out of scope for the flow-knob upgrade. asap7 + nangate45 floonoc pass clean.
+- **2026-06-26 `bbc7fd0`**: PSM-0069 root cause found and fixed. The 1598 bottom-edge IO pins on met2 at `edge_margin=5.0 µm` had their spacing-expanded obstruction (obs_yMax=5381 nm) overlapping the row-0 VSS via area (y_min=5200 nm); `pdngen` silently dropped all row-0 met1×met4 via candidates with no PDN-0110 warning. Fix: reduced `edge_margin` to **4.37 µm** (nearest valid met2 y-track below the 4.82 µm threshold); obs_yMax drops to 4751 nm, clearing the via area. `_final` passes with `[INFO PSM-0040] All shapes on net VSS are connected.` See CLAUDE.md bugs table for the threshold formula.
 
 ### Known issues / open questions
-- Synthesis itself is failing on sky130hd; need to inspect the yosys log to determine whether it's a memory-inference issue, a slang-frontend incompatibility, or something else.
-- Worth checking the yosys-slang log against the gallery of known failures before deeper debug.
+- None.