Merge pull request #2416 from Pinata-Consulting/variables-docs

maliberty · web-flow · commit faa7570dd72f · 2024-10-09T16:34:37.000-07:00
docs: autogenerate flow variables table
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/generate-variables-docs.py b/flow/scripts/generate-variables-docs.py
@@ -0,0 +1,79 @@
+#!/usr/bin/env python3
+# variables.yaml is the single source of truth w.r.t. metainformation about
+# the ORFS variables.
+#
+# This script injects an autogenerated section in FlowVariables.md with
+# information about the variables from variables.yaml.
+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"]
+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'| <a name="{key}"></a>{key} | {description} |\n'
+
+markdown_table += table_header + table_rows
+
+for stage in stages + ["All stages", "Uncategorized"]:
+    markdown_table += f"## {stage} variables\n\n"
+    stage_keys = [
+        key
+        for key in sorted(data)
+        if (
+            ("stages" in data[key] and stage in data[key]["stages"])
+            or ("stages" not in data[key] and stage == "Uncategorized")
+            or (
+                stage == "All stages"
+                and set(data[key].get("stages", [])) == set(stages)
+            )
+        )
+    ]
+    markdown_table += "\n".join(map(lambda k: f"- [{k}](#{k})", stage_keys))
+    markdown_table += "\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/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/non_stage_variables.py b/flow/scripts/non_stage_variables.py
@@ -0,0 +1,24 @@
+#!/usr/bin/env python3
+#
+# Reading .yaml from tcl is tedious and we already have
+# a yaml library in Python.
+#
+# This script generates a list of variables known
+# not to be in the current stage.
+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/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/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
 
 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)/non_stage_variables.py $stage_name]
+  foreach var $variables {
+    if {[info exists ::env($var)]} {
+      unset ::env($var)
+    }
+  }
+}
+
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`