Document floorplanning methods and flow variables

Signed-off-by: kcaisley <[email protected]>

Author: kcaisley

docs/user/FlowVariables.md

@@ -134,7 +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="FLOW_VARIANT"></a>FLOW_VARIANT| Flow variant to use, used in the flow variant directory name.| base|
 | <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.| |
@@ -293,6 +296,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,7 @@ 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 {