docs: autogenerate flow variables table

oharboe · oharboe · commit 81057c604bf3 · 2024-10-04T14:30:54.000+02:00
- erase variables that should not be used for a stage
- generate doc
- initial pass at assigning variables to stages, no stages
  listed puts the variables into the "all" category and
  the variables are never erased.

Signed-off-by: Øyvind Harboe &lt;oyvind.harboe@zylin.com&gt;
diff --git a/docs/user/FlowVariables.md b/docs/user/FlowVariables.md
diff --git a/flow/scripts/cdl.tcl b/flow/scripts/cdl.tcl
@@ -1,4 +1,5 @@
 source $::env(SCRIPTS_DIR)/load.tcl
+erase_non_stage_variables final
 load_design 6_final.odb 6_final.sdc
 
 write_cdl -masters $::env(CDL_FILE) $::env(RESULTS_DIR)/6_final.cdl
diff --git a/flow/scripts/cts.tcl b/flow/scripts/cts.tcl
@@ -1,5 +1,6 @@
 utl::set_metrics_stage "cts__{}"
 source $::env(SCRIPTS_DIR)/load.tcl
+erase_non_stage_variables cts
 load_design 3_place.odb 3_place.sdc
 
 # Clone clock tree inverters next to register loads
diff --git a/flow/scripts/defaults.py b/flow/scripts/defaults.py
@@ -5,11 +5,11 @@
 
 dir_path = os.path.dirname(os.path.realpath(__file__))
 
-yaml_path = os.path.join(dir_path, "defaults.yaml")
+yaml_path = os.path.join(dir_path, "variables.yaml")
 with open(yaml_path, "r") as file:
     data = yaml.safe_load(file)
 
 for key, value in data.items():
-    if value["value"] is None:
+    if value.get("value", None) is None:
         continue
     print(f'{key}?={value["value"]}')
diff --git a/flow/scripts/defaults.yaml b/flow/scripts/defaults.yaml
diff --git a/flow/scripts/density_fill.tcl b/flow/scripts/density_fill.tcl
@@ -1,4 +1,5 @@
 source $::env(SCRIPTS_DIR)/load.tcl
+erase_non_stage_variables final
 load_design 5_route.odb 5_route.sdc
 
 if {[env_var_equals USE_FILL 1]} {
diff --git a/flow/scripts/detail_place.tcl b/flow/scripts/detail_place.tcl
@@ -1,5 +1,6 @@
 utl::set_metrics_stage "detailedplace__{}"
 source $::env(SCRIPTS_DIR)/load.tcl
+erase_non_stage_variables place
 load_design 3_4_place_resized.odb 2_floorplan.sdc
 
 source $::env(PLATFORM_DIR)/setRC.tcl
diff --git a/flow/scripts/detail_route.tcl b/flow/scripts/detail_route.tcl
@@ -7,6 +7,7 @@ if {[expr [file exists $::env(REPORTS_DIR)/congestion.rpt] && \
 utl::set_metrics_stage "detailedroute__{}"
 source $::env(SCRIPTS_DIR)/load.tcl
 load_design 5_1_grt.odb 4_cts.sdc
+erase_non_stage_variables route
 set_propagated_clock [all_clocks]
 
 set additional_args ""
diff --git a/flow/scripts/fillcell.tcl b/flow/scripts/fillcell.tcl
@@ -1,4 +1,5 @@
 source $::env(SCRIPTS_DIR)/load.tcl
+erase_non_stage_variables route
 if {[env_var_exists_and_non_empty FILL_CELLS]} {
   load_design 5_2_route.odb 4_cts.sdc
 
diff --git a/flow/scripts/final_report.tcl b/flow/scripts/final_report.tcl
@@ -1,5 +1,6 @@
 utl::set_metrics_stage "finish__{}"
 source $::env(SCRIPTS_DIR)/load.tcl
+erase_non_stage_variables final
 load_design 6_1_fill.odb 6_1_fill.sdc
 
 set_propagated_clock [all_clocks]
diff --git a/flow/scripts/floorplan.tcl b/flow/scripts/floorplan.tcl
@@ -1,5 +1,6 @@
 utl::set_metrics_stage "floorplan__{}"
 source $::env(SCRIPTS_DIR)/load.tcl
+erase_non_stage_variables floorplan
 load_design 1_synth.v 1_synth.sdc
 
 proc report_unused_masters {} {
diff --git a/flow/scripts/global_place.tcl b/flow/scripts/global_place.tcl
@@ -1,5 +1,6 @@
 utl::set_metrics_stage "globalplace__{}"
 source $::env(SCRIPTS_DIR)/load.tcl
+erase_non_stage_variables place
 load_design 3_2_place_iop.odb 2_floorplan.sdc
 
 set_dont_use $::env(DONT_USE_CELLS)
diff --git a/flow/scripts/global_place_skip_io.tcl b/flow/scripts/global_place_skip_io.tcl
@@ -1,4 +1,5 @@
 source $::env(SCRIPTS_DIR)/load.tcl
+erase_non_stage_variables place
 load_design 2_floorplan.odb 2_floorplan.sdc
 
 
diff --git a/flow/scripts/global_route.tcl b/flow/scripts/global_route.tcl
@@ -1,11 +1,11 @@
 utl::set_metrics_stage "globalroute__{}"
+source $::env(SCRIPTS_DIR)/load.tcl
+erase_non_stage_variables grt
+load_design 4_cts.odb 4_cts.sdc
 
 # This proc is here to allow us to use 'return' to return early from this
 # file which is sourced
 proc global_route_helper {} {
-  source $::env(SCRIPTS_DIR)/load.tcl
-  load_design 4_cts.odb 4_cts.sdc
-
   if {[env_var_exists_and_non_empty PRE_GLOBAL_ROUTE]} {
     source $::env(PRE_GLOBAL_ROUTE)
   }
diff --git a/flow/scripts/io_placement.tcl b/flow/scripts/io_placement.tcl
@@ -1,4 +1,5 @@
 source $::env(SCRIPTS_DIR)/load.tcl
+erase_non_stage_variables place
 
 if {![env_var_equals IS_CHIP 1]} {
   load_design 3_1_place_gp_skip_io.odb 2_floorplan.sdc
diff --git a/flow/scripts/io_placement_random.tcl b/flow/scripts/io_placement_random.tcl
@@ -1,4 +1,5 @@
 source $::env(SCRIPTS_DIR)/load.tcl
+erase_non_stage_variables floorplan
 
 if {![env_var_equals IS_CHIP 1]} {
   load_design 2_1_floorplan.odb 1_synth.sdc
diff --git a/flow/scripts/macro_place.tcl b/flow/scripts/macro_place.tcl
@@ -1,4 +1,5 @@
 source $::env(SCRIPTS_DIR)/load.tcl
+erase_non_stage_variables floorplan
 load_design 2_3_floorplan_tdms.odb 1_synth.sdc
 
 source $::env(SCRIPTS_DIR)/macro_place_util.tcl
diff --git a/flow/scripts/pdn.tcl b/flow/scripts/pdn.tcl
@@ -1,4 +1,5 @@
 source $::env(SCRIPTS_DIR)/load.tcl
+erase_non_stage_variables floorplan
 load_design 2_5_floorplan_tapcell.odb 1_synth.sdc
 
 source $::env(PDN_TCL)
diff --git a/flow/scripts/resize.tcl b/flow/scripts/resize.tcl
@@ -1,5 +1,6 @@
 utl::set_metrics_stage "placeopt__{}"
 source $::env(SCRIPTS_DIR)/load.tcl
+erase_non_stage_variables place
 load_design 3_3_place_gp.odb 2_floorplan.sdc
 
 estimate_parasitics -placement
diff --git a/flow/scripts/stage_variables.py b/flow/scripts/stage_variables.py
@@ -0,0 +1,19 @@
+#!/usr/bin/env python3
+
+import os
+import sys
+import yaml
+
+dir_path = os.path.dirname(os.path.realpath(__file__))
+
+yaml_path = os.path.join(dir_path, "variables.yaml")
+with open(yaml_path, "r") as file:
+    data = yaml.safe_load(file)
+
+for key, value in data.items():
+    if "stages" not in value:
+        continue
+    if sys.argv[1] in value["stages"]:
+        continue
+    # This variable is in a stage, but not in this stage
+    print(key)
diff --git a/flow/scripts/synth_preamble.tcl b/flow/scripts/synth_preamble.tcl
@@ -1,6 +1,7 @@
 yosys -import
 
 source $::env(SCRIPTS_DIR)/util.tcl
+erase_non_stage_variables synth
 
 if {[env_var_exists_and_non_empty CACHED_NETLIST]} {
   exec cp $::env(CACHED_NETLIST) $::env(RESULTS_DIR)/1_1_yosys.v
diff --git a/flow/scripts/tapcell.tcl b/flow/scripts/tapcell.tcl
@@ -1,4 +1,5 @@
 source $::env(SCRIPTS_DIR)/load.tcl
+erase_non_stage_variables floorplan
 
 if {[env_var_exists_and_non_empty TAPCELL_TCL]} {
   load_design 2_4_floorplan_macro.odb 1_synth.sdc
diff --git a/flow/scripts/tdms_place.tcl b/flow/scripts/tdms_place.tcl
@@ -1,4 +1,5 @@
 source $::env(SCRIPTS_DIR)/load.tcl
+erase_non_stage_variables floorplan
 
 proc find_macros {} {
   set macros ""
diff --git a/flow/scripts/util.tcl b/flow/scripts/util.tcl
@@ -99,3 +99,19 @@ proc find_macros {} {
   }
   return $macros
 }
+
+proc erase_non_stage_variables {stage_name} {
+  # "$::env(SCRIPTS_DIR)/stage_variables.py stage_name" returns list of
+  # variables to erase.
+  # 
+  # Tcl yaml package can't be imported in the sta/openroad environment:
+  # 
+  # https://github.com/The-OpenROAD-Project/OpenROAD/issues/5875
+  set variables [exec $::env(SCRIPTS_DIR)/stage_variables.py $stage_name]
+  foreach var $variables {
+    if {[info exists ::env($var)]} {
+      unset ::env($var)
+    }
+  }
+}
+
diff --git a/flow/scripts/variables.py b/flow/scripts/variables.py
@@ -0,0 +1,76 @@
+#!/usr/bin/env python3
+import os
+import yaml
+
+dir_path = os.path.dirname(os.path.realpath(__file__))
+
+yaml_path = os.path.join(dir_path, "variables.yaml")
+
+with open(yaml_path, "r") as file:
+    data = yaml.safe_load(file)
+
+preferred_order = [
+    "synth",
+    "floorplan",
+    "place",
+    "cts",
+    "grt",
+    "route",
+    "final",
+    "generate_abstract",
+    "all",
+]
+stages = {stage for value in data.values() for stage in value.get("stages", [])}
+# convert set of stages to stages in a list in the preferred order, but
+# list all stages
+stages = [stage for stage in preferred_order if stage in stages] + [
+    stage for stage in stages if stage not in preferred_order
+]
+
+markdown_table = ""
+
+markdown_table += "## Variables in alphabetic order\n\n"
+table_header = "| Variable | Description |\n| --- | --- |\n"
+table_rows = ""
+for key in sorted(data):
+    value = data[key]
+    description = value.get("description", "").replace("\n", " ").strip()
+    table_rows += f"| {key} | {description} |\n"
+
+markdown_table += table_header + table_rows
+
+for stage in stages:
+    markdown_table += f"## {stage}\n\n"
+    stage_keys = [
+        key
+        for key in sorted(data)
+        if "stages" not in data[key] or stage in data[key]["stages"]
+    ]
+    markdown_table += " ".join(stage_keys) + "\n\n"
+
+docs = os.path.join(dir_path, "..", "..", "docs", "user", "FlowVariables.md")
+with open(docs, "r") as file:
+    lines = file.readlines()
+
+# Find the section to replace
+start_marker = "# Automatically generated"
+end_marker = "# "
+start_index = None
+end_index = len(lines)
+
+for i, line in enumerate(lines):
+    if line.startswith(start_marker):
+        start_index = i + 1
+    elif start_index is not None and line.startswith(end_marker):
+        end_index = i
+        break
+
+if start_index is None:
+    raise ValueError("Start marker not found")
+
+# Replace the section with the new table
+new_lines = lines[:start_index] + [markdown_table] + lines[end_index:]
+
+# Write the updated content back to FlowVariables.md
+with open(docs, "w") as file:
+    file.writelines(new_lines)
diff --git a/flow/scripts/variables.yaml b/flow/scripts/variables.yaml

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,5 @@`
`1`	`1`	`source $::env(SCRIPTS_DIR)/load.tcl`
	`2`	`+erase_non_stage_variables final`
`2`	`3`	`load_design 5_route.odb 5_route.sdc`
`3`	`4`
`4`	`5`	`if {[env_var_equals USE_FILL 1]} {`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,5 @@`
`1`	`1`	`source $::env(SCRIPTS_DIR)/load.tcl`
	`2`	`+erase_non_stage_variables route`
`2`	`3`	`if {[env_var_exists_and_non_empty FILL_CELLS]} {`
`3`	`4`	`load_design 5_2_route.odb 4_cts.sdc`
`4`	`5`