orfs: plumb polarity_mode + docs

Author: PrecisEDAnon

doc-DFT-howto.md

@@ -27,6 +27,7 @@ This auto-wires the two ORFS DFT hook scripts:
 Note:
 - If your design contains mixed clock domains and/or negedge flops, ORFS defaults `DFT_LOCKUP_POLICY=auto` and may fall back to `DFT_CLOCK_MIXING=no_mix`, which can increase the number of scan chains/ports.
   - To keep `clock_mix`, set `DFT_LOCKUP_POLICY=off` and configure lockup insertion (at minimum: `DFT_LOCKUP_CELL_RISING` + `DFT_LOCKUP_CLOCK_PIN_RISING`, and likewise `*_FALLING` if negedge scan flops exist).
+- Polarity defaults to `DFT_POLARITY_MODE=mid` (mixed polarity allowed; falling-edge flops are stitched before rising-edge flops within each chain). To forbid mixing polarities within a chain, set `DFT_POLARITY_MODE=strict` (may require additional chains when both polarities exist).
 
 ## Optional: Routing-aware ordering (trial route, then stitch)
 

docs/user/FlowVariables.md

@@ -49,6 +49,7 @@ proc dft_set_scan_enable_case_analysis {scan_enable_name} {
 #   - DFT_MAX_CHAINS (explicit cap), and/or
 #   - DFT_MAX_CHAIN_LENGTH (aka DFT_MAX_LENGTH) to bound chain length in bits.
 set clock_mixing [dft_get_env DFT_CLOCK_MIXING "no_mix"]
+set polarity_mode [dft_get_env DFT_POLARITY_MODE "mid"]
 set scan_enable_pattern [dft_get_env DFT_SCAN_ENABLE_NAME_PATTERN "scan_enable_{}"]
 set scan_in_pattern [dft_get_env DFT_SCAN_IN_NAME_PATTERN "scan_in_{}"]
 set scan_out_pattern [dft_get_env DFT_SCAN_OUT_NAME_PATTERN "scan_out_{}"]
@@ -89,6 +90,7 @@ set max_chains [dft_get_env DFT_MAX_CHAINS ""]
 
 set dft_args [list \
   -clock_mixing $clock_mixing \
+  -polarity_mode $polarity_mode \
 	-scan_enable_name_pattern $scan_enable_pattern \
 	-scan_in_name_pattern $scan_in_pattern \
 	-scan_out_name_pattern $scan_out_pattern \

flow/scripts/dft_scan_post_floorplan.tcl

@@ -1309,6 +1309,7 @@ proc dft_build_dft_config_args {{clock_mixing_override ""}} {
   if { $clock_mixing_override != "" } {
     set clock_mixing $clock_mixing_override
   }
+  set polarity_mode [dft_get_env DFT_POLARITY_MODE "mid"]
 
   set scan_enable_pattern [dft_get_env DFT_SCAN_ENABLE_NAME_PATTERN "scan_enable_{}"]
   set scan_in_pattern [dft_get_env DFT_SCAN_IN_NAME_PATTERN "scan_in_{}"]
@@ -1349,6 +1350,7 @@ proc dft_build_dft_config_args {{clock_mixing_override ""}} {
 
   set dft_args [list \
     -clock_mixing $clock_mixing \
+    -polarity_mode $polarity_mode \
     -scan_enable_name_pattern $scan_enable_pattern \
     -scan_in_name_pattern $scan_in_pattern \
     -scan_out_name_pattern $scan_out_pattern \

flow/scripts/dft_scan_pre_global_route.tcl

@@ -1004,6 +1004,17 @@ DFT_CLOCK_MIXING:
   stages:
     - floorplan
     - grt
+DFT_POLARITY_MODE:
+  description: >
+    How scan architect handles rising-edge and falling-edge scan flops within
+    a scan chain. Pass-through to `set_dft_config -polarity_mode` (`mid` or
+    `strict`). `mid` allows mixed polarity per chain by stitching falling-edge
+    flops before rising-edge flops. `strict` forbids mixing polarities within
+    a chain, requiring separate chains when both polarities are present.
+  default: mid
+  stages:
+    - floorplan
+    - grt
 DFT_CHAIN_COUNT:
   description: >
     Exact number of scan chains to generate (pass-through to

flow/scripts/variables.yaml

@@ -101,6 +101,7 @@ def run_openroad_execute_dft_plan(
     chain_count: int,
     max_imbalance: float,
     clock_mixing: str,
+    polarity_mode: str,
     scan_order_metric: Optional[str],
     scan_order_solver: str,
     scanopt_rounds: Optional[int],
@@ -190,6 +191,7 @@ def run_openroad_execute_dft_plan(
         f"-chain_count {chain_count}",
         f"-max_imbalance {max_imbalance}",
         f"-clock_mixing {clock_mixing}",
+        f"-polarity_mode {polarity_mode}",
         f"-scan_order_solver {scan_order_solver}",
         "-scan_enable_name_pattern scan_enable_{}",
         "-scan_in_name_pattern scan_in_{}",
@@ -427,6 +429,11 @@ def main(argv: Optional[List[str]] = None) -> int:
         help="Comma-separated list (percent).",
     )
     ap.add_argument("--clock-mixing", default="no_mix")
+    ap.add_argument(
+        "--polarity-mode",
+        default="mid",
+        help="Polarity handling policy: mid (default) or strict.",
+    )
     ap.add_argument("--scan-order-metric", default=None)
     ap.add_argument("--scan-order-solver", default="SCANOPT")
     ap.add_argument("--scanopt-rounds", type=int, default=500000)
@@ -486,7 +493,8 @@ def main(argv: Optional[List[str]] = None) -> int:
             metric = args.scan_order_metric or "DEFAULT"
             print(
                 f"=== execute_dft_plan: {tag} "
-                f"(solver={args.scan_order_solver}, metric={metric}, clock_mixing={args.clock_mixing}) ==="
+                f"(solver={args.scan_order_solver}, metric={metric}, "
+                f"clock_mixing={args.clock_mixing}, polarity_mode={args.polarity_mode}) ==="
             )
             out_def = out_prefix.with_name(f"{out_prefix.name}_{tag}.def")
             out_v = out_prefix.with_name(f"{out_prefix.name}_{tag}.v")
@@ -508,6 +516,7 @@ def main(argv: Optional[List[str]] = None) -> int:
                     chain_count=k,
                     max_imbalance=imb,
                     clock_mixing=args.clock_mixing,
+                    polarity_mode=args.polarity_mode,
                     scan_order_metric=args.scan_order_metric,
                     scan_order_solver=args.scan_order_solver,
                     scanopt_rounds=args.scanopt_rounds,