DFT: add ORFS hooks and scan utilities

Author: aghose

doc-DFT-howto.md

@@ -0,0 +1,40 @@
+# DFT / Scan — Quickstart (Before vs After)
+
+This is a short “how to run” guide. For implementation details, limitations, and scan-order benchmarks, see `doc-DFT.md`.
+
+## Before (Baseline: no DFT)
+
+Run the flow normally:
+
+- `make -C flow DESIGN_CONFIG=./designs/nangate45/ibex/config.mk FLOW_VARIANT=baseline_no_dft finish`
+
+## After (DFT Enabled: scan flops + stitched chain)
+
+Enable the two DFT hook scripts:
+
+- `POST_FLOORPLAN_TCL=$(pwd)/flow/scripts/dft_scan_post_floorplan.tcl`
+  - runs `scan_replace` (functional flops → scan flops)
+  - creates scan ports: `scan_enable_0`, `scan_in_0`, `scan_out_0`
+  - sets `set_case_analysis 0 [get_ports scan_enable_0]` (functional-mode timing)
+- `PRE_GLOBAL_ROUTE_TCL=$(pwd)/flow/scripts/dft_scan_pre_global_route.tcl`
+  - runs `execute_dft_plan` (stitches the scan chain using placement)
+
+Example:
+
+- `make -C flow DESIGN_CONFIG=./designs/nangate45/ibex/config.mk FLOW_VARIANT=with_dft POST_FLOORPLAN_TCL=$(pwd)/flow/scripts/dft_scan_post_floorplan.tcl PRE_GLOBAL_ROUTE_TCL=$(pwd)/flow/scripts/dft_scan_pre_global_route.tcl finish`
+
+## Sanity Checks
+
+- Report the plan (from OpenROAD, after `scan_replace`):
+  - `report_dft_plan -verbose`
+- Validate chain integrity from a finished netlist:
+  - `python3 flow/util/scan_chain_validate.py --verilog flow/results/<platform>/<design>/<variant>/6_final.v`
+- Or validate from an ODB (runs `scan_replace` + `execute_dft_plan` in-memory and writes a temp netlist):
+  - `python3 flow/util/scan_chain_validate.py --odb flow/results/<platform>/<design>/<variant>/3_5_place_dp.odb --openroad $OPENROAD_EXE --liberty <lib> --sdc flow/results/<platform>/<design>/<variant>/3_place.sdc --ensure-ports --scan-replace --execute-dft-plan`
+
+## Compare “Before vs After” QoR
+
+- Routed wirelength / timing: compare `flow/results/<...>/metrics.json` and the OpenROAD/OpenSTA reports between `baseline_no_dft` and `with_dft`.
+- Scan-chain wire metric on a fixed placement (also runs an NN heuristic for comparison):
+  - `python3 flow/util/scan_chain_cost.py --scan-replace --nearest-neighbor --openroad $OPENROAD_EXE --liberty <lib> --odb flow/results/<...>/3_5_place_dp.odb --sdc flow/results/<...>/3_place.sdc`
+

doc-DFT.md

@@ -0,0 +1,235 @@
+# DFT / Scan in ORFS (OpenROAD-flow-scripts) — What We Changed + How To Reproduce
+
+Quickstart: `doc-DFT-howto.md`
+
+This document summarizes the DFT/scan-chain work done in this repo, with **OpenROAD commit `7bc521f36a` treated as the baseline** and a **vanilla OpenSTA** requirement (no `src/sta` parser changes needed).
+
+## Goal / Scope
+
+- Make OpenROAD’s DFT scan insertion usable in ORFS:
+  - `scan_replace` converts functional flops → scan flops.
+  - `execute_dft_plan` stitches scan chains using placement (wirelength-aware).
+- Ensure it works with **vanilla OpenSTA** (no OpenSTA parser patches required).
+- Provide a practical way to compare:
+  - **7bc521 “baseline DFT”** (broken / mostly no-op) vs
+  - **fixed DFT** (actually produces scan flops + stitched chains),
+  - using QoR proxies and a scan-chain “TSP-like” cost metric.
+
+## Baselines, Branches, and Key Commits
+
+### OpenROAD submodule (`tools/OpenROAD`)
+
+- Baseline reference branch: `orfs-baseline-7bc521`
+  - pinned at `7bc521f36a`
+- Fixed DFT/scan branch (vanilla OpenSTA): `orfs-dft-scan`
+  - `5649f22868`
+- Older variant (kept for history): `orfs-dft-scan-with-opensta`
+  - `5d3e1e243c`
+
+### OpenSTA submodule (`tools/OpenROAD/src/sta`)
+
+- Vanilla OpenSTA used by baseline and final solution:
+  - `d7cb9be1`
+- A prior OpenSTA parser patch was made (not required for the final approach) and preserved:
+  - branch `orfs-sta-scan-nextstate-6d62008a` at commit `6d62008a`
+
+### ORFS top-level (this repo)
+
+- ORFS commit `84cc6b71d`:
+  - bumps `tools/OpenROAD` gitlink to `5649f22868`
+  - adds DFT hook scripts under `flow/scripts/`
+
+## What Was Fixed in OpenROAD DFT
+
+### 1) Make scan-cell recognition work with vanilla OpenSTA
+
+Problem:
+- Libraries (e.g., Nangate45) tag scan pins via Liberty `nextstate_type` like `scan_in`, `scan_enable`.
+- Vanilla OpenSTA does **not** reliably surface those pins as `test_scan_*` scan-signal types.
+- Result: OpenROAD DFT often can’t identify scan pins → scan cells not recognized → chains not built.
+
+Fix (final approach):
+- In `tools/OpenROAD/src/dbSta/src/dbSta.cc`, added **fallback inference** by common pin names:
+  - enable: `SE`, `SCE`, `SCAN_EN`, `SCAN_ENABLE`, `SCANENABLE`
+  - in: `SI`, `SCD`, `SCAN_IN`, `SCANIN`
+  - out: `SO`, `SCO`, `SCAN_OUT`, `SCANOUT`
+- This allows DFT to identify scan pins without requiring any `tools/OpenROAD/src/sta` changes.
+
+### 2) Fix scan stitching correctness
+
+Problem:
+- Baseline stitching logic had an iteration/pop bug in `ScanStitch.cpp` that could skip/omit links.
+
+Fix:
+- Rewrote the scan-cell linking loop to deterministically connect:
+  - `scan_in_driver -> first.SI`
+  - `cell[i-1].SO -> cell[i].SI` for all i
+  - `last.SO -> scan_out_load`
+
+### 3) Remove reliance on `sta::TestCell` and improve scan-out handling
+
+Changes in the earlier “with-opensta” variant that were retained/improved:
+- Stop depending on `sta::TestCell` objects.
+- Use `getLibertyScanIn/Enable/Out()` helpers instead.
+- Add scan-out fallback to `Q` if scan-out pin metadata isn’t tagged.
+
+### 4) Add/enable regression coverage
+
+- Added a DFT regression `scan_architect_no_mix_nangate45` and wired it into OpenROAD’s CMake test setup.
+- Verified DFT tests pass in the fixed OpenROAD build (`ctest -R '^dft\.'`).
+
+## ORFS Integration (How DFT Is Hooked Into the Flow)
+
+Two ORFS hook scripts were added:
+
+- `flow/scripts/dft_scan_post_floorplan.tcl`
+  - Intended to be set via `POST_FLOORPLAN_TCL=...`
+  - Runs:
+    - `set_dft_config -max_chains 1 -clock_mixing clock_mix`
+    - `scan_replace`
+    - creates ports: `scan_enable_0`, `scan_in_0`, `scan_out_0`
+    - `set_case_analysis 0 [get_ports scan_enable_0]` (functional-mode assumption)
+
+- `flow/scripts/dft_scan_pre_global_route.tcl`
+  - Intended to be set via `PRE_GLOBAL_ROUTE_TCL=...`
+  - Runs:
+    - `set_dft_config ...` (must match)
+    - `set_case_analysis 0 ...`
+    - `execute_dft_plan` (stitch chains)
+
+Notes:
+- This wiring is **opt-in**: you enable it by setting `POST_FLOORPLAN_TCL` and `PRE_GLOBAL_ROUTE_TCL` when you run `make -C flow ...`.
+- The scripts currently hardcode `-max_chains 1` to keep scan-port count stable for comparisons (this is intentionally worst-case for scan wiring impact).
+
+## Reproduction: Baseline vs Fixed DFT (QoR Proxy Comparison)
+
+### Design used
+
+- `nangate45/ibex` (`flow/designs/nangate45/ibex/config.mk`)
+
+### OpenROAD executables used
+
+- Fixed OpenROAD (DFT works): `tools/OpenROAD/build_gate7bc521/bin/openroad` (reports `v2.0-26262-g5649f22868`)
+- Baseline OpenROAD 7bc521 (DFT mostly broken): `tools/OpenROAD_7bc521/build_gate7bc521/bin/openroad`
+  - built from a detached worktree at `7bc521f36a` (version string prints `HEAD-HASH-NOTFOUND` due to git-describe failure in that worktree)
+
+### Flow commands
+
+- Baseline (no DFT):
+  - `make -C flow DESIGN_CONFIG=./designs/nangate45/ibex/config.mk FLOW_VARIANT=qor_scan_base_20260104 OPENROAD_EXE=$(pwd)/tools/OpenROAD/build_gate7bc521/bin/openroad finish`
+- Fixed DFT enabled:
+  - `make -C flow DESIGN_CONFIG=./designs/nangate45/ibex/config.mk FLOW_VARIANT=qor_scan_dft_20260104 OPENROAD_EXE=$(pwd)/tools/OpenROAD/build_gate7bc521/bin/openroad POST_FLOORPLAN_TCL=$(pwd)/flow/scripts/dft_scan_post_floorplan.tcl PRE_GLOBAL_ROUTE_TCL=$(pwd)/flow/scripts/dft_scan_pre_global_route.tcl finish`
+- Baseline OpenROAD 7bc521 “DFT enabled” (shows it’s broken/no-op):
+  - `make -C flow DESIGN_CONFIG=./designs/nangate45/ibex/config.mk FLOW_VARIANT=qor_scan_dft_or7bc521_20260104 OPENROAD_EXE=$(pwd)/tools/OpenROAD_7bc521/build_gate7bc521/bin/openroad POST_FLOORPLAN_TCL=$(pwd)/flow/scripts/dft_scan_post_floorplan.tcl PRE_GLOBAL_ROUTE_TCL=$(pwd)/flow/scripts/dft_scan_pre_global_route.tcl finish`
+
+### QoR snapshot (finish metrics)
+
+From `flow/logs/nangate45/ibex/<variant>/6_report.json` and `5_2_route.json`:
+
+- no DFT (`qor_scan_base_20260104`):
+  - instance area `29091.6`
+  - sequential area `10065.2`
+  - total power `0.0960477`
+  - setup WS `-0.0211463`
+  - detailed-route WL `256015`
+- “DFT enabled” but OpenROAD 7bc521 broken (`qor_scan_dft_or7bc521_20260104`):
+  - instance area `29106`
+  - sequential area `10065.2`
+  - total power `0.0961684`
+  - setup WS `-0.0240458`
+  - detailed-route WL `256612`
+  - `report_dft_plan` shows **0 chains** (scan cells not recognized)
+- fixed DFT (`qor_scan_dft_20260104`):
+  - instance area `31790.5` (+~9.3%)
+  - sequential area `12702.3` (+~26.2%)
+  - total power `0.0995975` (+~3.7%)
+  - setup WS `-0.029858`
+  - detailed-route WL `278902` (+~8.9%)
+  - `report_dft_plan` shows **1 chain / 1931 scan cells**
+
+Interpretation:
+- Comparing DFT vs no-DFT: PPA generally degrades due to bigger flops + new scan nets.
+- The valid “DFT QoR” story is DFT-vs-DFT (reduce overhead vs naive chain ordering / too-few chains), not DFT vs no-DFT.
+
+## “Traveling Salesman”-Style Metric (Scan Chain Cost)
+
+To quantify “how good” a scan chain ordering is, we added:
+
+- `flow/util/scan_chain_cost.py`
+
+What it computes:
+- Parses OpenROAD `report_dft_plan -verbose` to get the scan-cell order per chain.
+- Extracts placed instance locations (DEF `PLACED` coordinates) by writing a DEF (`write_def`) and parsing the `COMPONENTS` section.
+- Computes:
+  - chain path length = sum Manhattan distance between consecutive scan cells in that order
+  - a naive baseline = same cost for lexicographic instance order (`sorted(inst_names)`)
+
+Note:
+- The metric intentionally uses DEF `PLACED` coordinates (OpenDB `dbInst::getLocation()`), since `dbInst::getOrigin()` is orientation-dependent (e.g. MX/MY) and can skew comparisons/optimization.
+
+### Example usage
+
+- On a DFT-run placed DB:
+  - `python3 flow/util/scan_chain_cost.py --openroad tools/OpenROAD/build_gate7bc521/bin/openroad --liberty flow/platforms/nangate45/lib/NangateOpenCellLibrary_typical.lib --odb flow/results/nangate45/ibex/qor_scan_dft_20260104/3_5_place_dp.odb --sdc flow/results/nangate45/ibex/qor_scan_dft_20260104/3_place.sdc`
+- With a simple “TSP-ish” nearest-neighbor baseline:
+  - `python3 flow/util/scan_chain_cost.py --nearest-neighbor --openroad tools/OpenROAD/build_gate7bc521/bin/openroad --liberty flow/platforms/nangate45/lib/NangateOpenCellLibrary_typical.lib --odb flow/results/nangate45/ibex/qor_scan_dft_20260104/3_5_place_dp.odb --sdc flow/results/nangate45/ibex/qor_scan_dft_20260104/3_place.sdc`
+- On a no-DFT placed DB (compute hypothetical scan cost by doing `scan_replace` in-memory, without re-placement):
+  - `python3 flow/util/scan_chain_cost.py --openroad tools/OpenROAD/build_gate7bc521/bin/openroad --liberty flow/platforms/nangate45/lib/NangateOpenCellLibrary_typical.lib --odb flow/results/nangate45/ibex/qor_scan_base_20260104/3_5_place_dp.odb --sdc flow/results/nangate45/ibex/qor_scan_base_20260104/3_place.sdc --scan-replace`
+
+### Observed results (ibex, 1 chain)
+
+- DFT placed: `manhattan_um=11990.000`, naive lexicographic `90306.230` (ratio `7.532x`)
+- no-DFT placed + hypothetical scan: `manhattan_um=11982.700`, naive `93778.840` (ratio `7.826x`)
+
+Why DFT vs no-DFT chain cost is similar here:
+- The scan chain cost is dominated by **where flops are placed** in the design.
+- For `ibex` at this utilization, scan insertion didn’t significantly perturb placement, so the chain path length barely changes.
+
+What *does* show up clearly:
+- The new scan/control nets. Example (fixed DFT, routed DB):
+  - `report_wire_length -net {scan_enable_0} -detailed_route` → `8033.45um`
+
+### Optimizer benchmark (OpenROAD opt vs nearest-neighbor)
+
+On the 9-design suite (`aes/ibex/jpeg × nangate45/asap7/sky130hd`), using `flow/util/scan_chain_cost.py --scan-replace --nearest-neighbor` on placed ODBs (so scan flops are inserted in-memory, then the chain is planned/ordered from the placement database):
+
+| platform | design | cells | OpenROAD opt (um) | NN (um) | opt/NN |
+| --- | --- | ---: | ---: | ---: | ---: |
+| nangate45 | aes | 562 | 3571.680 | 4178.080 | 0.855 |
+| nangate45 | ibex | 1931 | 9197.880 | 10545.640 | 0.872 |
+| nangate45 | jpeg | 4390 | 17903.670 | 20815.750 | 0.860 |
+| asap7 | aes | 562 | 1053.810 | 1222.344 | 0.862 |
+| asap7 | ibex | 273 | 428.652 | 514.404 | 0.833 |
+| asap7 | jpeg | 4325 | 5045.058 | 5709.204 | 0.884 |
+| sky130hd | aes | 562 | 11050.640 | 13137.940 | 0.841 |
+| sky130hd | ibex | 1931 | 21754.680 | 24411.360 | 0.891 |
+| sky130hd | jpeg | 4390 | 50973.380 | 57692.340 | 0.884 |
+
+Avg `opt/NN` = `0.865` (~`13.5%` shorter than NN).
+
+Reproduce (single design):
+- `python3 flow/util/scan_chain_cost.py --scan-replace --nearest-neighbor --openroad tools/OpenROAD/build_gate7bc521/bin/openroad --liberty flow/platforms/nangate45/lib/NangateOpenCellLibrary_typical.lib --odb flow/results/nangate45/ibex/cmp9_or0db856_rp100_20251229_022425/3_5_place_dp.odb --sdc flow/results/nangate45/ibex/cmp9_or0db856_rp100_20251229_022425/3_place.sdc`
+
+Notes:
+- ASAP7 needs multiple libs; pass them all, e.g. `--liberty flow/platforms/asap7/lib/NLDM/*_TT_*`.
+
+## Current Limitations / Known Gaps
+
+- `scan_opt` is implemented in OpenROAD DFT and re-stitches scan chains using the latest placement
+  (without re-running `scan_replace`). The scan-chain optimizer uses NN + farthest-insertion + bounded 2-opt (with an rtree fallback for huge chains).
+- The ORFS hook scripts currently hardcode `-max_chains 1`. A next step is to sweep `-max_chains` and quantify overhead reduction (DFT-vs-DFT).
+- Clock-domain correctness constraints (lockups, strict no-mix, etc.) are not yet wired through ORFS configuration beyond `-clock_mixing`.
+
+## Scan-Chain Integrity Validation (Does it Actually Shift?)
+
+QoR deltas and plan reports are necessary but not sufficient; we also want a basic structural check that the scan path is one continuous chain from `scan_in_0` to `scan_out_0`.
+
+- `flow/util/scan_chain_validate.py` validates scan stitching from a gate-level netlist (or from an ODB by writing a temporary netlist via OpenROAD).
+- It treats `assign` + inserted `BUF*/CLKBUF*` as transparent, so post-P&R buffering doesn’t cause false failures.
+
+Example usage:
+
+- Validate a finished netlist:
+  - `python3 flow/util/scan_chain_validate.py --verilog flow/results/nangate45/ibex/qor_scan_dft_20260104/6_final.v`
+- Validate from an ODB (writes a temp netlist first):
+  - `python3 flow/util/scan_chain_validate.py --odb flow/results/nangate45/ibex/qor_scan_dft_20260104/6_final.odb --openroad tools/OpenROAD/build_gate7bc521/bin/openroad --liberty flow/platforms/nangate45/lib/NangateOpenCellLibrary_typical.lib --sdc flow/results/nangate45/ibex/qor_scan_dft_20260104/6_final.sdc --ensure-ports`

flow/scripts/dft_scan_post_floorplan.tcl

@@ -0,0 +1,44 @@
+# DFT scan insertion hook for ORFS.
+#
+# Intended use: set `POST_FLOORPLAN_TCL` to this file.
+#
+# This runs after floorplan, before saving `2_1_floorplan.odb`, so subsequent
+# stages (place/cts/route) see scan flops and scan ports.
+
+puts "DFT: scan_replace + create scan ports"
+
+# Keep the number of scan ports stable for QoR comparisons.
+# With clock mixing enabled, all scan cells share one hash domain, so -max_chains
+# applies globally.
+set_dft_config -max_chains 1 -clock_mixing clock_mix
+
+# Replace functional flops with scan-capable flops.
+scan_replace
+
+proc dft_ensure_scan_port {port_name io_type} {
+  set block [ord::get_db_block]
+
+  set bterm [$block findBTerm $port_name]
+  if { $bterm != "NULL" } {
+    return
+  }
+
+  set net [$block findNet $port_name]
+  if { $net == "NULL" } {
+    set net [odb::dbNet_create $block $port_name]
+    $net setSigType SCAN
+  }
+
+  set bterm [odb::dbBTerm_create $net $port_name]
+  $bterm setSigType SCAN
+  $bterm setIoType $io_type
+}
+
+# One-chain scan I/O + shared enable.
+dft_ensure_scan_port "scan_enable_0" INPUT
+dft_ensure_scan_port "scan_in_0" INPUT
+dft_ensure_scan_port "scan_out_0" OUTPUT
+
+# Functional-mode assumption for STA/power (disable scan path).
+set_case_analysis 0 [get_ports scan_enable_0]
+

flow/scripts/dft_scan_pre_global_route.tcl

@@ -0,0 +1,17 @@
+# DFT scan insertion hook for ORFS.
+#
+# Intended use: set `PRE_GLOBAL_ROUTE_TCL` to this file.
+#
+# This runs after CTS, before global routing, so scan-chain connections are
+# included in routing.
+
+puts "DFT: execute_dft_plan (stitch scan chains)"
+
+# Must match `flow/scripts/dft_scan_post_floorplan.tcl`.
+set_dft_config -max_chains 1 -clock_mixing clock_mix
+
+# Ensure functional-mode STA/power assumptions in this stage too.
+set_case_analysis 0 [get_ports scan_enable_0]
+
+execute_dft_plan
+