feat!: openroad enhancements, variable renames (#608)

Exposes a number of new OpenROAD flags and features as configuration variables.

Also performs some variable names that are considered API breaks.

See Changelog.md for a total list of changes.

Co-authored-by: Kareem Farid <kareefardi@users.noreply.github.com>

Changelog.md

@@ -18,33 +18,100 @@
 
 ## Steps
 
-* `Yosys.*`
-  * Added `SYNTH_CORNER`
+* `Odb.AddPDNObstructions`, `Odb.AddRoutingObstructions`
+
+  * `PDN_OBSTRUCTIONS` and `ROUTING_OBSTRUCTIONS` are now lists of tuples
+    instead of variable-length Tcl-style lists (AKA: strings).
+
+* `OpenROAD.*`
+
+  * Added `log_cmd` from OpenROAD-flow-scripts -- neat idea for consistency
+  * New convenience methods to append flags to calls based on environment
+    variables
+  * **Internal**: Steps now sensitive to `_OPENROAD_GUI` environment variable --
+    coupled with `--only`, it runs a step in OpenROAD then doesn't quit so you
+    may inspect the result.
+    * This is not part of the OpenLane stable API and may be broken at any
+      moment.
 
 * `OpenROAD.CTS`
+
   * Added flags `CTS_OBSTRUCTION_AWARE` and `CTS_BALANCE_LEVELS`
   * Added `CTS_SINK_BUFFER_MAX_CAP_DERATE_PCT`
   * Added `CTS_DELAY_BUFFER_DERATE_PCT`
 
+* `OpenROAD.CutRows`
+
+  * Added `FP_PRUNE_THRESHOLD` to prune rows not meeting the threshold after
+    cutting.
+
 * `OpenROAD.DetailedRouting`
-  * Added `DRT_SAVE_SNAPSHOTS` which enables saving snapshots of the layout each detalied routing iteration.
+
+  * Added `DRT_SAVE_SNAPSHOTS` which enables saving snapshots of the layout each
+    detalied routing iteration.
   * Added `DRT_SAVE_DRC_REPORT_ITERS`
 
-
+* `OpenROAD.GlobalPlacement`
+
+  * Added optional variable `PL_ROUTABILITY_MAX_DENSITY_PCT`
+
+* `OpenROAD.RepairDesignPostGPL`
+
+  * Added optional variable `DESIGN_REPAIR_MAX_UTIL_PCT`
+
+* `OpenROAD.ResizerTimingPostCTS`
+
+  * Renamed `PL_RESIZER_GATE_CLONING` to `PL_RESIZER_SETUP_GATE_CLONING`
+
+  * Fixed `PL_RESIZER_SETUP_GATE_CLONING` incorrectly applied to hold fixing
+
+  * Added the following optional variables
+
+    * `PL_RESIZER_SETUP_BUFFERING`
+    * `PL_RESIZER_SETUP_BUFFER_REMOVAL`
+    * `PL_RESIZER_SETUP_REPAIR_TNS_PCT`
+    * `PL_RESIZER_SETUP_MAX_UTIL_PCT`
+    * `PL_RESIZER_HOLD_REPAIR_TNS_PCT`
+    * `PL_RESIZER_HOLD_MAX_UTIL_PCT`
+
+* `OpenROAD.RepairDesignPostGRT`
+
+  * Renamed `GRT_RESIZER_GATE_CLONING` to `GRT_RESIZER_SETUP_GATE_CLONING`
+
+  * Fixed `GRT_RESIZER_SETUP_GATE_CLONING` incorrectly applied to hold fixing
+
+  * Added the following optional variables
+
+    * `GRT_RESIZER_SETUP_BUFFERING`
+    * `GRT_RESIZER_SETUP_BUFFER_REMOVAL`
+    * `GRT_RESIZER_SETUP_REPAIR_TNS_PCT`
+    * `GRT_RESIZER_SETUP_MAX_UTIL_PCT`
+    * `GRT_RESIZER_HOLD_REPAIR_TNS_PCT`
+    * `GRT_RESIZER_HOLD_MAX_UTIL_PCT`
+
+* Created `OpenROAD.UnplaceAll`
+
+  * Removes the placement status of all instances.
+
+* `Yosys.*Synthesis`
+
+  * Added `SYNTH_CORNER`: a step-specific override for `DEFAULT_CORNER`.
+
 ## Tool Updates
 
 * Updated nix-eda
-   * Updated nixpkgs to nixos-24.11 (@ `3c53b4b`)
-   * Updated KLayout to `0.29.9`
-   * Updated Magic to `8.3.503`
-   * Updated Netgen to `1.5.287`
+  * Updated nixpkgs to nixos-24.11 (@ `3c53b4b`)
+  * Updated KLayout to `0.29.9`
+  * Updated Magic to `8.3.503`
+  * Updated Netgen to `1.5.287`
 * Updated ioplace-parser to`0.4.0`
 * Updated OpenROAD to `1d61007`
   * Updated OpenSTA to `aa598a2`
 
 ## Misc. Enhancements/Bugfixes
 
 * `openlane.state`
+
   * `DesignFormat`
     * Now a dataclass encapsulating the information about the DesignFormat
       directly.
@@ -60,8 +127,28 @@
     * States initialized with keys that have values that are `None` now remove
       said keys.
 
+* `openlane.config`
+
+  * Moved a number of global variables:
+    * `WIRE_LENGTH_THRESHOLD` moved from global variables to
+      `Checker.WireLength`
+    * `GPIO_PAD_*` removed- no step currently uses them
+    * `FP_TRACKS_INFO`, `FP_TAPCELL_DIST` moved to relevant steps
+    * `FILL_CELL` and `DECAP_CELL` renamed to `FILL_CELLS` and `DECAP_CELLS` as
+      they are both lists
+    * `EXTRA_GDS_FILES` and `FALLBACK_SDC_FILE` renamed to `EXTRA_GDS` and
+      `FALLBACK_SDC`: information can be obtained from their typing
+  * Changed some `decimal.Decimal` initializations to use integers or strings
+    instead of floats.
+
 ## API Breaks
 
+* `Odb.AddRoutingObstructions`, `Odb.AddPDNObstructions`
+
+  * Typing for representation of obstructions has been changed. Designs with a
+    meta version of 2 or higher must update their variables from strings to
+    tuples.
+
 * `openlane.steps`
 
   * `TclStep` now uses the IDs uppercased for `CURRENT_` and `SAVE_`.
@@ -79,19 +166,27 @@
     to `full_name`. The enumeration's name has been added to `alts`, while
     `.name` is now an alias for `.id`.
 
+* `openlane.config`
+
+  * `WIRE_LENGTH_THRESHOLD`, `GPIO_PAD_*`, `FP_TRACKS_INFO`, `FP_TAPCELL_DIST`
+    are no longer global variables.
+
+  * `FILL_CELL`, `DECAP_CELL`, `EXTRA_GDS_FILES`, `FALLBACK_SDC_FILE` were all
+    renamed, see Misc. Enhancements/Bugfixes.
+
 # 2.3.2
 
 ## Steps
 
 * `Yosys.*`
-  * Fixed blackbox Verilog and lib models causing a crash if they are
-    gzipped and/or have the extension `.gz`.
-    
+  * Fixed blackbox Verilog and lib models causing a crash if they are gzipped
+    and/or have the extension `.gz`.
+
 ## Tool Updates
 
 * Relaxed requirement on `httpx` to include `0.28.X`, which has no removals
   compared to `0.27.0`.
-  
+
 ## Documentation
 
 * Clarified support for gzipped files in the Classic flow.

openlane/config/flow.py

@@ -53,44 +53,12 @@ def _prefix_to_wildcard(prefixes_raw: Union[str, Sequence[str]]):
         "The ground pin for the cells.",
         pdk=True,
     ),
-    Variable(
-        "WIRE_LENGTH_THRESHOLD",
-        Optional[Decimal],
-        "A value above which wire lengths generate warnings.",
-        units="µm",
-        pdk=True,
-    ),
     Variable(
         "TECH_LEFS",
         Dict[str, Path],
         "Map of corner patterns to to technology LEF files. A corner not matched here will not be supported by OpenRCX in the default flow.",
         pdk=True,
     ),
-    Variable(
-        "GPIO_PADS_LEF",
-        Optional[List[Path]],
-        "Path(s) to GPIO pad LEF file(s).",
-        pdk=True,
-    ),
-    Variable(
-        "GPIO_PADS_LEF_CORE_SIDE",
-        Optional[List[Path]],
-        "Path(s) to GPIO pad LEF file(s) as used for routing (?).",
-        pdk=True,
-    ),
-    Variable(
-        "GPIO_PADS_VERILOG",
-        Optional[List[Path]],
-        "Path(s) to GPIO pad Verilog models.",
-        pdk=True,
-    ),
-    Variable(
-        "GPIO_PAD_CELLS",
-        Optional[List[str]],
-        "A list of pad cell name prefixes.",
-        deprecated_names=[("GPIO_PADS_PREFIX", _prefix_to_wildcard)],
-        pdk=True,
-    ),
     Variable(
         "PRIMARY_GDSII_STREAMOUT_TOOL",
         str,
@@ -136,20 +104,6 @@ def _prefix_to_wildcard(prefixes_raw: Union[str, Sequence[str]]):
         pdk=True,
     ),
     # Floorplanning
-    Variable(
-        "FP_TRACKS_INFO",
-        Path,
-        "A path to the a classic OpenROAD `.tracks` file. Used by the floorplanner to generate tracks.",
-        deprecated_names=["TRACKS_INFO_FILE"],
-        pdk=True,
-    ),
-    Variable(
-        "FP_TAPCELL_DIST",
-        Decimal,
-        "The distance between tap cell columns.",
-        units="µm",
-        pdk=True,
-    ),
     Variable(
         "FP_IO_HLAYER",
         str,
@@ -190,16 +144,18 @@ def _prefix_to_wildcard(prefixes_raw: Union[str, Sequence[str]]):
         pdk=True,
     ),
     Variable(
-        "FILL_CELL",
+        "FILL_CELLS",
         List[str],
         "A list of cell names or wildcards of fill cells to be used in fill insertion.",
         pdk=True,
+        deprecated_names=["FILL_CELL"],
     ),
     Variable(
-        "DECAP_CELL",
+        "DECAP_CELLS",
         List[str],
         "A list of cell names or wildcards of decap cells to be used in fill insertion.",
         pdk=True,
+        deprecated_names=["DECAP_CELL"],
     ),
     Variable(
         "LIB",
@@ -358,7 +314,7 @@ def _prefix_to_wildcard(prefixes_raw: Union[str, Sequence[str]]):
     Variable(
         "ENDCAP_CELL",
         str,
-        "Defines so-called 'end-cap' cells- decap cells placed at either sides of a design.",
+        "Defines the so-called 'end-cap' cell- class of decap cells placed at either sides of a design.",
         pdk=True,
         deprecated_names=["FP_ENDCAP_CELL"],
     ),
@@ -474,17 +430,46 @@ def _prefix_to_wildcard(prefixes_raw: Union[str, Sequence[str]]):
         "Specifies LIB files of pre-hardened macros used in the current design, used during timing analyses (and during parasitics-based STA as a fallback). These are loaded indiscriminately for all timing corners.",
     ),
     Variable(
-        "EXTRA_GDS_FILES",
+        "EXTRA_GDS",
         Optional[List[Path]],
         "Specifies GDS files of pre-hardened macros used in the current design, used during tape-out.",
+        deprecated_names=["EXTRA_GDS_FILES"],
     ),
     Variable(
-        "FALLBACK_SDC_FILE",
+        "FALLBACK_SDC",
         Path,
         "A fallback SDC file for when a step-specific SDC file is not defined.",
-        deprecated_names=["BASE_SDC_FILE", "SDC_FILE"],
+        deprecated_names=["FALLBACK_SDC_FILE", "BASE_SDC_FILE", "SDC_FILE"],
         default=Path(os.path.join(get_script_dir(), "base.sdc")),
     ),
 ]
 
+__for_whenever_we_implement_padring = [
+    Variable(
+        "GPIO_PADS_LEF",
+        Optional[List[Path]],
+        "Path(s) to GPIO pad LEF file(s).",
+        pdk=True,
+    ),
+    Variable(
+        "GPIO_PADS_LEF_CORE_SIDE",
+        Optional[List[Path]],
+        "Path(s) to GPIO pad LEF file(s) as used for routing (?).",
+        pdk=True,
+    ),
+    Variable(
+        "GPIO_PADS_VERILOG",
+        Optional[List[Path]],
+        "Path(s) to GPIO pad Verilog models.",
+        pdk=True,
+    ),
+    Variable(
+        "GPIO_PAD_CELLS",
+        Optional[List[str]],
+        "A list of pad cell name prefixes.",
+        deprecated_names=[("GPIO_PADS_PREFIX", _prefix_to_wildcard)],
+        pdk=True,
+    ),
+]
+
 flow_common_variables = pdk_variables + scl_variables + option_variables

openlane/config/preprocessor.py

@@ -180,7 +180,7 @@ def evaluate(expression: str, symbols: Mapping[str, Any]) -> Decimal:
                     eval_stack.pop()
                     eval_stack.pop()
 
-                    result = Decimal(0.0)
+                    result = Decimal("0")
                     if token.value == "**":
                         result = number1**number2
                     elif token.value == "*":

openlane/scripts/magic/common/read.tcl

@@ -55,8 +55,8 @@ proc read_extra_gds {} {
     set old_readonly [gds readonly]
     gds rescale false
     gds readonly true
-    if {  [info exist ::env(EXTRA_GDS_FILES)] } {
-        set gds_files_in $::env(EXTRA_GDS_FILES)
+    if {  [info exist ::env(EXTRA_GDS)] } {
+        set gds_files_in $::env(EXTRA_GDS)
         foreach gds_file $gds_files_in {
             puts "> gds read $gds_file"
             gds read $gds_file

openlane/scripts/magic/gds/extras_mag.tcl

@@ -25,8 +25,8 @@ if { $::env(MAGIC_GDS_POLYGON_SUBCELLS) } {
 	gds polygon subcells true
 }
 
-if {  [info exist ::env(EXTRA_GDS_FILES)] } {
-	set gds_files_in $::env(EXTRA_GDS_FILES)
+if { [info exist ::env(EXTRA_GDS)] } {
+	set gds_files_in $::env(EXTRA_GDS)
 	foreach gds_file $gds_files_in {
 		gds read $gds_file
 

openlane/scripts/openroad/common/dpl.tcl

@@ -15,7 +15,7 @@ source $::env(SCRIPTS_DIR)/openroad/common/dpl_cell_pad.tcl
 
 remove_fillers
 
-detailed_placement\
+log_cmd detailed_placement\
     -max_displacement [subst { $::env(PL_MAX_DISPLACEMENT_X) $::env(PL_MAX_DISPLACEMENT_Y) }]
 
 if { [info exists ::env(PL_OPTIMIZE_MIRRORING)] && $::env(PL_OPTIMIZE_MIRRORING) } {

openlane/scripts/openroad/common/grt.tcl

@@ -26,7 +26,7 @@ lappend arg_list -verbose
 if { $::env(GRT_ALLOW_CONGESTION) == 1 } {
     lappend arg_list -allow_congestion
 }
-puts $arg_list
-global_route {*}$arg_list
 
-write_guide $::env(STEP_DIR)/after_grt.guide
+log_cmd global_route {*}$arg_list
+
+write_guide $::env(STEP_DIR)/after_grt.guide