dft: document constraints and max_imbalance

Expose -max_imbalance via DFT_MAX_IMBALANCE and document scan-order constraints file directives (groups/strict order/before/chain endpoints). Also update prerequisite OpenROAD pin commit hash.

Author: PrecisEDAnon

doc-DFT-howto.md

@@ -10,7 +10,7 @@ What you get:
 
 ## Prerequisites
 
-- `tools/OpenROAD` is pinned to `PrecisEDAnon/OpenROAD` (`OpenROAD-clean-DFT`) at `2fadc72cd524c1eec3c5c5c7a1eeede739b0a805`.
+- `tools/OpenROAD` is pinned to `PrecisEDAnon/OpenROAD` (`OpenROAD-clean-DFT`) at `9d5965b568187743cdae7fd03b8889dfc79a0080`.
 - Build tools (if needed): `./build_openroad.sh --local`
   - ORFS defaults `OPENROAD_EXE` to `tools/install/OpenROAD/bin/openroad`.
 
@@ -44,6 +44,7 @@ Pick one of these:
 - Exact chain count: `DFT_CHAIN_COUNT=<N>`
 - Cap bits per chain: `DFT_MAX_CHAIN_LENGTH=<bits>` (alias: `DFT_MAX_LENGTH`)
 - Cap chains (upper bound): `DFT_MAX_CHAINS=<N>`
+- Balance constraint (default 30%): `DFT_MAX_IMBALANCE=<percent>` (alias: `DFT_MAX_IMBALANCE_PERCENT`)
 
 Examples:
 
@@ -136,6 +137,33 @@ Format:
 - One chain per line: `chain_name inst0 inst1 inst2 ...`
 - Single-chain shorthand is allowed: `inst0 inst1 inst2 ...`
 
+### 3h) OpenROAD scan-order constraints file (groups / ordering / chain endpoints)
+
+This is separate from `DFT_SCAN_ORDER_FILE`. It *constrains* OpenROAD’s internal solver instead of specifying the entire solution.
+
+- Enable: `DFT_SCAN_SOLVER=openroad DFT_SCAN_ORDER_CONSTRAINTS_FILE=/path/to/constraints.txt`
+
+Supported directives (comments start with `#`; names refer to scan-flop instance names after `scan_replace`):
+
+- Chain naming and optional endpoint coordinates (integer DBU):
+  - `chain <name> [begin <x> <y>] [end <x> <y>]`
+  - Equivalent forms: `chain_begin <name> <x> <y>` / `chain_end <name> <x> <y>`
+- Grouping (members must stay together in exactly one chain; groups can be hierarchical):
+  - `group <name> [priority] <inst_or_group...>`
+- Strict order (no interpolation; creates fixed adjacency edges):
+  - `path <name> [priority] <inst0 inst1 inst2 ...>`
+  - Aliases: `strict_group` / `strict`
+- Fixed adjacency:
+  - `fixed_edge <from_inst> <to_inst>`
+- Partial order (“before”):
+  - `before <inst_or_group_a> <inst_or_group_b>`
+- Hard assignment of instances/groups to a named chain:
+  - `assign <chain_name> <inst_or_group...>`
+
+Notes:
+- Chain endpoint coordinates affect the ordering objective by adding begin→first and last→end costs for that chain.
+- The tool enforces polarity as a hard constraint using a “falling then rising” structure within each chain; constraints that force rising-before-falling within a chain are rejected.
+
 ## 4) Reuse Existing Scan Ports / Custom Naming
 
 OpenROAD DFT endpoints are configured via name patterns:

flow/scripts/dft_scan_post_floorplan.tcl

@@ -73,6 +73,10 @@ if { $max_length == "" } {
 	set timing_hold_weight [dft_get_env DFT_TIMING_HOLD_WEIGHT ""]
 	set timing_critical_slack [dft_get_env DFT_TIMING_CRITICAL_SLACK ""]
 	set scan_order_constraints_file [dft_get_env DFT_SCAN_ORDER_CONSTRAINTS_FILE ""]
+	set max_imbalance [dft_get_env DFT_MAX_IMBALANCE ""]
+	if { $max_imbalance == "" } {
+	  set max_imbalance [dft_get_env DFT_MAX_IMBALANCE_PERCENT ""]
+	}
 
 	set insert_lockup [dft_get_env DFT_INSERT_LOCKUP ""]
 	set lockup_cell_rising [dft_get_env DFT_LOCKUP_CELL_RISING ""]
@@ -112,6 +116,9 @@ set dft_args [list \
 	if { $vertical_weight != "" } {
 	  lappend dft_args -vertical_weight $vertical_weight
 	}
+	if { $max_imbalance != "" } {
+	  lappend dft_args -max_imbalance $max_imbalance
+	}
 	if { $timing_setup_weight != "" } {
 	  lappend dft_args -timing_setup_weight $timing_setup_weight
 	}

flow/scripts/dft_scan_pre_global_route.tcl

@@ -1207,6 +1207,10 @@ proc dft_build_dft_config_args {{clock_mixing_override ""}} {
   set scanopt_rounds [dft_get_env DFT_SCANOPT_ROUNDS ""]
   set scanopt_seed [dft_get_env DFT_SCANOPT_SEED ""]
   set vertical_weight [dft_get_env DFT_VERTICAL_WEIGHT ""]
+  set max_imbalance [dft_get_env DFT_MAX_IMBALANCE ""]
+  if { $max_imbalance == "" } {
+    set max_imbalance [dft_get_env DFT_MAX_IMBALANCE_PERCENT ""]
+  }
   set timing_setup_weight [dft_get_env DFT_TIMING_SETUP_WEIGHT ""]
   set timing_hold_weight [dft_get_env DFT_TIMING_HOLD_WEIGHT ""]
   set timing_critical_slack [dft_get_env DFT_TIMING_CRITICAL_SLACK ""]
@@ -1247,6 +1251,9 @@ proc dft_build_dft_config_args {{clock_mixing_override ""}} {
   if { $vertical_weight != "" } {
     lappend dft_args -vertical_weight $vertical_weight
   }
+  if { $max_imbalance != "" } {
+    lappend dft_args -max_imbalance $max_imbalance
+  }
   if { $timing_setup_weight != "" } {
     lappend dft_args -timing_setup_weight $timing_setup_weight
   }