Merge pull request The-OpenROAD-Project#3499 from kcaisley/master

Document floorplanning methods and flow variables

Author: maliberty

docs/user/FlowVariables.md

@@ -134,8 +134,10 @@ configuration file.
 | <a name="FASTROUTE_TCL"></a>FASTROUTE_TCL| Specifies a Tcl script with commands to run before FastRoute.| |
 | <a name="FILL_CELLS"></a>FILL_CELLS| Fill cells are used to fill empty sites. If not set or empty, fill cell insertion is skipped.| |
 | <a name="FILL_CONFIG"></a>FILL_CONFIG| JSON rule file for metal fill during chip finishing.| |
-| <a name="FLOORPLAN_DEF"></a>FLOORPLAN_DEF| Use the DEF file to initialize floorplan.| |
+| <a name="FLOORPLAN_DEF"></a>FLOORPLAN_DEF| Use the DEF file to initialize floorplan. Mutually exclusive with FOOTPRINT or DIE_AREA/CORE_AREA or CORE_UTILIZATION.| |
 | <a name="FLOW_VARIANT"></a>FLOW_VARIANT| Flow variant to use, used in the flow variant directory name.| base|
+| <a name="FOOTPRINT"></a>FOOTPRINT| Custom footprint definition file for ICeWall-based floorplan initialization. Mutually exclusive with FLOORPLAN_DEF or DIE_AREA/CORE_AREA or CORE_UTILIZATION.| |
+| <a name="FOOTPRINT_TCL"></a>FOOTPRINT_TCL| Specifies a Tcl script with custom footprint-related commands for floorplan setup.| |
 | <a name="GDS_ALLOW_EMPTY"></a>GDS_ALLOW_EMPTY| Regular expression of module names of macros that have no .gds file| |
 | <a name="GDS_FILES"></a>GDS_FILES| Path to platform GDS files.| |
 | <a name="GENERATE_ARTIFACTS_ON_FAILURE"></a>GENERATE_ARTIFACTS_ON_FAILURE| For instance Bazel needs artifacts (.odb and .rpt files) on a failure to allow the user to save hours on re-running the failed step locally, but when working with a Makefile flow, it is more natural to fail the step and leave the user to manually inspect the logs and artifacts directly via the file system. Set to 1 to change the behavior to generate artifacts upon failure to e.g. do a global route. The exit code will still be non-zero on all other failures that aren't covered by the "useful to inspect the artifacts on failure" use-case. Example: just like detailed routing, a global route that fails with congestion, is not a build failure(as in exit code non-zero), it is a successful(as in zero exit code) global route that produce reports detailing the problem. Detailed route will not proceed, if there is global routing congestion This allows build systems, such as bazel, to create artifacts for global and detailed route, even if the operation had problems, without having know about the semantics between global and detailed route. Considering that global and detailed route can run for a long time and use a lot of memory, this allows inspecting results on a laptop for a build that ran on a server.| 0|
@@ -293,6 +295,8 @@ configuration file.
 - [CORE_UTILIZATION](#CORE_UTILIZATION)
 - [DIE_AREA](#DIE_AREA)
 - [FLOORPLAN_DEF](#FLOORPLAN_DEF)
+- [FOOTPRINT](#FOOTPRINT)
+- [FOOTPRINT_TCL](#FOOTPRINT_TCL)
 - [HOLD_SLACK_MARGIN](#HOLD_SLACK_MARGIN)
 - [IO_CONSTRAINTS](#IO_CONSTRAINTS)
 - [MACRO_BLOCKAGE_HALO](#MACRO_BLOCKAGE_HALO)

flow/scripts/floorplan.tcl

@@ -43,24 +43,26 @@ puts "number instances in verilog is $num_instances"
 set additional_args ""
 append_env_var additional_args ADDITIONAL_SITES -additional_sites 1
 
+# Check which floorplan initialization method is specified (mutually exclusive)
 set use_floorplan_def [env_var_exists_and_non_empty FLOORPLAN_DEF]
 set use_footprint [env_var_exists_and_non_empty FOOTPRINT]
 set use_die_and_core_area \
   [expr { [env_var_exists_and_non_empty DIE_AREA] && [env_var_exists_and_non_empty CORE_AREA] }]
 set use_core_utilization [env_var_exists_and_non_empty CORE_UTILIZATION]
 
+# Enforce mutual exclusion - exactly one method must be specified
 set methods_defined \
   [expr { $use_floorplan_def + $use_footprint + $use_die_and_core_area + $use_core_utilization }]
 if { $methods_defined > 1 } {
   puts "Error: Floorplan initialization methods are mutually exclusive, pick one."
   exit 1
 }
 
+# Method 1: Use existing DEF file with floorplan data
 if { $use_floorplan_def } {
-  # Initialize floorplan by reading in floorplan DEF
   log_cmd read_def -floorplan_initialize $env(FLOORPLAN_DEF)
+  # Method 2: Use ICeWall footprint file (platform-specific extension)
 } elseif { $use_footprint } {
-  # Initialize floorplan using ICeWall FOOTPRINT
   ICeWall load_footprint $env(FOOTPRINT)
 
   initialize_floorplan \
@@ -69,11 +71,13 @@ if { $use_floorplan_def } {
     -site $::env(PLACE_SITE)
 
   ICeWall init_footprint $env(SIG_MAP_FILE)
+  # Method 3: Use explicit die and core area coordinates
 } elseif { $use_die_and_core_area } {
   initialize_floorplan -die_area $::env(DIE_AREA) \
     -core_area $::env(CORE_AREA) \
     -site $::env(PLACE_SITE) \
     {*}$additional_args
+  # Method 4: Calculate core area from utilization, aspect ratio, and margins
 } elseif { $use_core_utilization } {
   initialize_floorplan -utilization $::env(CORE_UTILIZATION) \
     -aspect_ratio $::env(CORE_ASPECT_RATIO) \
@@ -85,6 +89,7 @@ if { $use_floorplan_def } {
   exit 1
 }
 
+# Create routing tracks: MAKE_TRACKS script, platform make_tracks.tcl, or make_tracks command
 if { [env_var_exists_and_non_empty MAKE_TRACKS] } {
   log_cmd source $::env(MAKE_TRACKS)
 } elseif { [file exists $::env(PLATFORM_DIR)/make_tracks.tcl] } {
@@ -93,6 +98,8 @@ if { [env_var_exists_and_non_empty MAKE_TRACKS] } {
   make_tracks
 }
 
+# Configure global routing: FASTROUTE_TCL script or
+# set_global_routing_layer_adjustment/set_routing_layers
 if { [env_var_exists_and_non_empty FASTROUTE_TCL] } {
   log_cmd source $::env(FASTROUTE_TCL)
 } else {

flow/scripts/variables.yaml

@@ -305,7 +305,7 @@ SWAP_ARITH_OPERATORS:
     - All stages
 FLOORPLAN_DEF:
   description: |
-    Use the DEF file to initialize floorplan.
+    Use the DEF file to initialize floorplan. Mutually exclusive with FOOTPRINT or DIE_AREA/CORE_AREA or CORE_UTILIZATION.
   stages:
     - floorplan
     - place
@@ -1019,6 +1019,16 @@ YOSYS_FLAGS:
   stages:
     - synth
   default: -v 3
+FOOTPRINT:
+  description: |
+    Custom footprint definition file for ICeWall-based floorplan initialization. Mutually exclusive with FLOORPLAN_DEF or DIE_AREA/CORE_AREA or CORE_UTILIZATION.
+  stages:
+    - floorplan
+FOOTPRINT_TCL:
+  description: |
+    Specifies a Tcl script with custom footprint-related commands for floorplan setup.
+  stages:
+    - floorplan
 FLOW_VARIANT:
   description: >
     Flow variant to use, used in the flow variant directory name.