Documentation Fixes (The-OpenROAD-Project#1333)

+ Local installer re-documented, volare integrated + Create new "Macros/Chip Integration" section in `configuration.md`, document EXTRA_LIBS + Document `CVC_SCRIPTS_DIR` in PDK variables ~ Replace broken links with permalinks in `chip_integration.md` ~ `SYNTH_CLOCK_UNCERTAINITY` -> `SYNTH_CLOCK_UNCERTAINTY` (with translation behavior) - Remove unused `FP_CORE_MARGIN` variable
efabless · Sep 7, 2022 · 63b5966 · 63b5966
1 parent 4dd0170
commit 63b5966
Show file tree

Hide file tree

Showing 15 changed files with 89 additions and 49 deletions.
diff --git a/configuration/floorplan.tcl b/configuration/floorplan.tcl
@@ -18,7 +18,6 @@ set ::env(DESIGN_IS_CORE) 1
 set ::env(FP_SIZING) relative
 set ::env(FP_CORE_UTIL) 50
 # PL_TARGET_DENSITY default value set in all.tcl because of the order of sourcing.
-set ::env(FP_CORE_MARGIN) 0
 set ::env(FP_ASPECT_RATIO) 1
 
 set ::env(FP_PDN_VOFFSET) 16.32

diff --git a/configuration/synthesis.tcl b/configuration/synthesis.tcl
@@ -16,7 +16,7 @@
 set ::env(SYNTH_BIN) yosys
 set ::env(SYNTH_SCRIPT) $::env(SCRIPTS_DIR)/yosys/synth.tcl
 set ::env(SYNTH_NO_FLAT) 0
-set ::env(SYNTH_CLOCK_UNCERTAINITY) 0.25
+set ::env(SYNTH_CLOCK_UNCERTAINTY) 0.25
 set ::env(SYNTH_CLOCK_TRANSITION) 0.15
 set ::env(SYNTH_TIMING_DERATE) 0.05
 set ::env(SYNTH_SHARE_RESOURCES) 1

diff --git a/dependencies/installer.py b/dependencies/installer.py
@@ -156,7 +156,7 @@ def run(self):
         )
 
         print(
-            "[ALERT] The local installer is deprecated and will be removed in a future version of OpenLane.\nIf you're still using it, please file an issue at https://github.com/The-OpenROAD-Project/OpenLane/issues."
+            "[ALERT] The local installer is no longer actively supported.\nSee https://github.com/The-OpenROAD-Project/OpenLane/issues/1300 for more info."
         )
 
         install_dir = realpath("./install")
@@ -415,11 +415,14 @@ def install():
                     {pip_install_cmd} -r ../dependencies/python/precompile_time.txt
                     {pip_install_cmd} -r ../dependencies/python/compile_time.txt
                     {pip_install_cmd} -r ../dependencies/python/run_time.txt
+                    pip3 install --upgrade volare
+                    mkdir -p ./pdks
+                    volare enable --pdk-root ./pdks {tools['open_pdks'].commit}
                     """,
                 ]
             )
 
-            print("Installing dependencies...")
+            print("Building dependencies...")
             with chdir("build"):
                 for folder in ["repos", "versions"]:
                     sh("mkdir", "-p", folder)
@@ -466,8 +469,8 @@ def pop():
 
                             with chdir(tool.name):
                                 sh("git", "fetch")
-                                sh("git", "submodule", "update", "--init")
                                 sh("git", "checkout", tool.commit)
+                                sh("git", "submodule", "update", "--init")
                                 subprocess.run(
                                     [
                                         "bash",
@@ -476,7 +479,7 @@ def pop():
                                         set -e
                                         source {install_dir}/venv/bin/activate
                                         {tool.build_script}
-                                    """,
+                                        """,
                                     ],
                                     env=run_env,
                                     check=True,
@@ -493,13 +496,16 @@ def pop():
                 f.write(
                     textwrap.dedent(
                         f"""\
-                set OL_INSTALL_DIR [file dirname [file normalize [info script]]]
-
-                set ::env(OPENLANE_LOCAL_INSTALL) 1
-                set ::env(OL_INSTALL_DIR) "$OL_INSTALL_DIR"
-                set ::env(PATH) "{":".join(path_elements)}:$::env(PATH)"
-                set ::env(VIRTUAL_ENV) "$OL_INSTALL_DIR/venv"
-                """
+                        set OL_INSTALL_DIR [file dirname [file normalize [info script]]]
+
+                        set ::env(OPENLANE_LOCAL_INSTALL) 1
+                        set ::env(OL_INSTALL_DIR) "$OL_INSTALL_DIR"
+                        set ::env(PATH) "{":".join(path_elements)}:$::env(PATH)"
+                        set ::env(VIRTUAL_ENV) "$OL_INSTALL_DIR/venv"
+                        if {{ ![info exists ::env(PDK_ROOT) ]}} {{
+                            set ::env(PDK_ROOT) "$OL_INSTALL_DIR/pdks"
+                        }}
+                        """
                     )
                 )
 

diff --git a/designs/xtea/src/xtea.sdc b/designs/xtea/src/xtea.sdc
@@ -20,8 +20,8 @@ set cap_load [expr $::env(SYNTH_CAP_LOAD) / 1000.0]
 puts "\[INFO\]: Setting load to: $cap_load"
 set_load  $cap_load [all_outputs]
 
-puts "\[INFO\]: Setting clock uncertainity to: $::env(SYNTH_CLOCK_UNCERTAINITY)"
-set_clock_uncertainty $::env(SYNTH_CLOCK_UNCERTAINITY) [get_clocks $::env(CLOCK_PORT)]
+puts "\[INFO\]: Setting clock uncertainty to: $::env(SYNTH_CLOCK_UNCERTAINTY)"
+set_clock_uncertainty $::env(SYNTH_CLOCK_UNCERTAINTY) [get_clocks $::env(CLOCK_PORT)]
 
 puts "\[INFO\]: Setting clock transition to: $::env(SYNTH_CLOCK_TRANSITION)"
 set_clock_transition $::env(SYNTH_CLOCK_TRANSITION) [get_clocks $::env(CLOCK_PORT)]

diff --git a/docs/source/advanced_power_grid_control.md b/docs/source/advanced_power_grid_control.md
@@ -1,5 +1,4 @@
-**THIS PAGE IS STILL UNDER DEVELOPMENT.**
-**THE INFORMATION HERE MIGHT BE PARTIALLY INCORRECT OR OUTDATED.**
+> Note: Information in this document may be out of date. It's always a good idea to take a look at the canonical documentation for OpenROAD's pdngen utility: https://openroad.readthedocs.io/en/latest/main/src/pdn/README.html
 
 # Power Grid/Power Distribution Network
 

diff --git a/docs/source/chip_integration.md b/docs/source/chip_integration.md
@@ -1,12 +1,7 @@
-**THIS PAGE IS STILL UNDER DEVELOPMENT.**
-**THE INFORMATION HERE MIGHT BE PARTIALLY INCORRECT OR OUTDATED.**
-
 # Chip Level Integration
+Using OpenLane, you can produce a GDSII from a chip RTL.
 
-Using openlane, you can produce a GDSII from a chip RTL.
-
-
-## The current Methodology
+## The Current Methodology
 
 The current methodology views the chip using the following hierarchy:
 - Chip Core
@@ -39,6 +34,7 @@ You need to set the following environment variables in your configuration file f
 | `VERILOG_FILES` | Space-delimited list of Verilog files*. |
 | `VERILOG_FILES_BLACKBOX` | Black-box, Verilog files where the implementation is ignored. Useful for pre-hardened macros you incorporate into your design. |
 | `EXTRA_LEFS` | LEF files for pre-hardened macros you incorporate into your design. |
+| `EXTRA_LIBS` | Specifies LIB files of pre-hardened macros used in the current design, used to improve timing analysis. (Optional) |
 | `EXTRA_GDS_FILES` | GDS files for pre-hardened macros you incorporate into your design. |
 | `SYNTH_READ_BLACKBOX_LIB` | `1/0` (Tcl), `true/false` (json): Should be set to true if you're using any standard cells directly in your design, i.e., your design does not function purely at the register transfer level. |
 | `MACRO_PLACEMENT_CFG` | A path to a file containing a line-break delimited list of instances and positions if you want to manually place the macros in specific locations, in the format `instance_name X_pos Y_pos Orientation`. The [`manual_macro_placement_test` example][9] under designs should be a good example. |
@@ -134,12 +130,12 @@ When you use the `power_routing` command in the chip interactive script, the pow
 [0]: ./configuration.md
 [1]: ./openlane_commands.md
 [2]: ./advanced_readme.md
-[3]: https://github.com/The-OpenROAD-Project/OpenROAD/blob/master/src/pdn/doc/PDN.md
-[4]: https://github.com/efabless/caravel/blob/mpw-one-b/openlane/chip_io/interactive.tcl
-[5]: https://github.com/efabless/caravel/blob/mpw-one-b/openlane/caravel/interactive.tcl
-[6]: https://github.com/efabless/caravel/blob/mpw-one-b/openlane/chip_io/padframe.cfg
+[3]: https://openroad.readthedocs.io/en/latest/main/src/pdn/README.html
+[4]: https://github.com/efabless/caravel/blob/9949306c42ded3cad03e1f4566d7cd1f8215b0bb/openlane/chip_io/interactive.tcl
+[5]: https://github.com/efabless/caravel/blob/9949306c42ded3cad03e1f4566d7cd1f8215b0bb/openlane/caravel/interactive.tcl
+[6]: https://github.com/efabless/caravel/blob/9949306c42ded3cad03e1f4566d7cd1f8215b0bb/openlane/chip_io/padframe.cfg
 [7]: ./../../scripts/topModuleGen/README.md
 [8]: ./hardening_macros.md
 [9]: https://github.com/The-OpenROAD-Project/openlane/tree/master/designs/manual_macro_placement_test
 [10]: ./advanced_power_grid_control.md
-[11]: https://github.com/efabless/caravel/blob/mpw-one-b/openlane/caravel/interactive.lvs.tcl
+[11]: https://github.com/efabless/caravel/blob/9949306c42ded3cad03e1f4566d7cd1f8215b0bb/openlane/caravel/interactive.lvs.tcl
diff --git a/docs/source/configuration.md b/docs/source/configuration.md
@@ -29,8 +29,15 @@ These variables are optional that can be specified in the design configuration f
 | `MERGED_LEF` | Points to `merged.lef`, which is a merger of various LEF files, including the technology lef, cells lef, any custom lefs, and IO lefs. |
 | `NO_SYNTH_CELL_LIST` | Specifies the file that contains the don't-use-cell-list to be excluded from the liberty file during synthesis. If it's not defined, this path is searched `$::env(PDK_ROOT)/$::env(PDK)/libs.tech/openlane/$::env(STD_CELL_LIBRARY)/no_synth.cells` and if it's not found, then the original liberty will be used as is. |
 | `DRC_EXCLUDE_CELL_LIST` | Specifies the file that contains the don't-use-cell-list to be excluded from the liberty file during synthesis and timing optimizations. If it's not defined, this path is searched `$::env(PDK_ROOT)/$::env(PDK)/libs.tech/openlane/$::env(STD_CELL_LIBRARY)/drc_exclude.cells` and if it's not found, then the original liberty will be used as is. In other words, `DRC_EXCLUDE_CELL_LIST` contain the only excluded cell list in timing optimizations. |
-| `EXTRA_LEFS` | Specifies LEF files of pre-hardened macros to be merged in the design currently getting hardened |
-| `EXTRA_GDS_FILES` | Specifies GDS files of pre-hardened macros to be merged in the design currently getting hardened |
+
+#### Macros/Chip Integration
+
+|Variable|Description|
+|-|-|
+| `VERILOG_FILES_BLACKBOX` | Black-boxed, Verilog files where the implementation is ignored. Useful for pre-hardened macros you incorporate into your design, used during synthesis. |
+| `EXTRA_LEFS` | Specifies LEF files of pre-hardened macros used in the current design, used in placement and routing. |
+| `EXTRA_LIBS` | Specifies LIB files of pre-hardened macros used in the current design, used during timing analysis. (Optional) |
+| `EXTRA_GDS_FILES` | Specifies GDS files of pre-hardened macros used in the current design, used during tape-out. |
 
 ### Synthesis
 
@@ -40,8 +47,8 @@ These variables are optional that can be specified in the design configuration f
 | `SYNTH_CAP_LOAD` | The capacitive load on the output ports in femtofarads. <br> (Default: `33.5` ff)|
 | `SYNTH_MAX_FANOUT`  | The max load that the output ports can drive. <br> (Default: `10` cells) |
 | `SYNTH_MAX_TRAN` | The max transition time (slew) from high to low or low to high on cell inputs in ns. Used in synthesis <br> (Default: Calculated at runtime as `10%` of the provided clock period, unless this exceeds a set DEFAULT_MAX_TRAN, in which case it will be used as is). |
-| `SYNTH_CLOCK_UNCERTAINITY`  | Specifies a value for the clock uncertainity in the pre-CTS stages. <br> (Default: `0.25`) |
-| `SYNTH_CLOCK_TRANSITION`  |  Specifies a value for the clock transition in the pre-CTS stages. <br> (Default: `0.15`) |
+| `SYNTH_CLOCK_UNCERTAINTY`  | Specifies a value for the clock uncertainty/jitter for timing analysis. <br> (Default: `0.25`) |
+| `SYNTH_CLOCK_TRANSITION`  |  Specifies a value for the clock transition /slew for timing analysis. <br> (Default: `0.15`) |
 | `SYNTH_TIMING_DERATE`  | Specifies a derating factor to multiply the path delays with. It specifies the upper and lower ranges of timing. <br> (Default: `+5%/-5%`) |
 | `SYNTH_STRATEGY` | Strategies for abc logic synthesis and technology mapping <br> Possible values are `DELAY/AREA 0-4/0-3`; the first part refers to the optimization target of the synthesis strategy (area vs. delay) and the second one is an index. <br> (Default: `AREA 0`)|
 | `SYNTH_BUFFERING` | Enables abc cell buffering <br> Enabled = 1, Disabled = 0 <br> (Default: `1`)|
@@ -57,16 +64,16 @@ These variables are optional that can be specified in the design configuration f
 | `VERILOG_INCLUDE_DIRS` | Specifies the verilog includes directories. <br> Optional. |
 | `SYNTH_FLAT_TOP` | Specifies whether or not the top level should be flattened during elaboration. 1 = True, 0= False <br> Default: `0`. |
 | `IO_PCT` | Specifies the percentage of the clock period used in the input/output delays. Ranges from 0 to 1.0. <br> (Default: `0.2`) |
-| `VERILOG_FILES_BLACKBOX` | To point at the blackboxes (the hardened macros). Ideally, this should include all the other verilog files |
 
 ### Floorplanning
 
 |Variable|Description|
 |-|-|
 | `FP_CORE_UTIL`  | The core utilization percentage. <br> (Default: `50` percent)|
 | `FP_ASPECT_RATIO`  | The core's aspect ratio (height / width). <br> (Default: `1`)|
-| `FP_SIZING`  | Whether to use relative sizing by making use of `FP_CORE_UTIL` or absolute one using `DIE_AREA`. <br> (Default: `"relative"` - accepts "absolute" as well)|
-| `DIE_AREA`  | Specific die area to be used in floorplanning. Specified as a 4-corner rectangle "x0 y0 x1 y1". Units in um <br> (Default: unset)|
+| `FP_SIZING`  | Whether to use relative sizing by making use of `FP_CORE_UTIL` or absolute one using `DIE_AREA`. <br> (Default: `"relative"` - accepts `"absolute"` as well)|
+| `DIE_AREA`  | Specific die area to be used in floorplanning when `FP_SIZING` is set to `absolute`. Specified as a 4-corner rectangle "x0 y0 x1 y1". Units in μm <br> (Default: unset)|
+| `CORE_AREA` | Specific core area (i.e. die area minus margins) to be used in floorplanning when `FP_SIZING` is set to `absolute`. Specified as a 4-corner rectangle "x0 y0 x1 y1". Units in μm <br> (Default: unset)|
 | `FP_IO_MODE`  | Decides the mode of the random IO placement option. 0=matching mode, 1=random equidistant mode <br> (Default: `1`)|
 | `FP_WELLTAP_CELL`  | The name of the welltap cell during welltap insertion. |
 | `FP_ENDCAP_CELL`  | The name of the endcap cell during endcap insertion. |
@@ -83,10 +90,10 @@ These variables are optional that can be specified in the design configuration f
 | `FP_IO_VTHICKNESS_MULT`  | A multiplier for vertical pin thickness. Base thickness is the pins layer minwidth <br> (Default: `2`) |
 | `FP_IO_HTHICKNESS_MULT`  | A multiplier for horizontal pin thickness. Base thickness is the pins layer minwidth <br> (Default: `2`) |
 | `FP_IO_UNMATCHED_ERROR`  | Exit on unmatched pins in a provided `FP_PIN_ORDER_CFG` file. 0=Disable 1=Enable. <br> (Default: `1` Enabled) |
-| `BOTTOM_MARGIN_MULT`     | The core margin, in multiples of site heights, from the bottom boundary. <br> (Default: `4`) |
-| `TOP_MARGIN_MULT`        | The core margin, in multiples of site heights, from the top boundary. <br> (Default: `4`) |
-| `LEFT_MARGIN_MULT`       | The core margin, in multiples of site widths, from the left boundary.  <br> (Default: `12`) |
-| `RIGHT_MARGIN_MULT`      | The core margin, in multiples of site widths, from the right boundary.   <br> (Default: `12`) |
+| `BOTTOM_MARGIN_MULT`     | The core margin, in multiples of site heights, from the bottom boundary. If `FP_SIZING` is absolute and `CORE_AREA` is set, this variable has no effect. <br> (Default: `4`) |
+| `TOP_MARGIN_MULT`        | The core margin, in multiples of site heights, from the top boundary. If `FP_SIZING` is absolute and `CORE_AREA` is set, this variable has no effect. <br> (Default: `4`) |
+| `LEFT_MARGIN_MULT`       | The core margin, in multiples of site widths, from the left boundary. If `FP_SIZING` is absolute and `CORE_AREA` is set, this variable has no effect.  <br> (Default: `12`) |
+| `RIGHT_MARGIN_MULT`      | The core margin, in multiples of site widths, from the right boundary. If `FP_SIZING` is absolute and `CORE_AREA` is set, this variable has no effect.   <br> (Default: `12`) |
 | `FP_PDN_CORE_RING` | Enables adding a core ring around the design. More details on the control variables in the pdk configurations documentation. 0=Disable 1=Enable. <br> (Default: `0`) |
 | `FP_PDN_ENABLE_RAILS` | Enables the creation of rails in the power grid. 0=Disable 1=Enable. <br> (Default: `1`) |
 | `FP_PDN_ENABLE_MACROS_GRID` | Enables the connection of macros to the top level power grid. 0=Disable 1=Enable. <br> (Default: `1`) |
@@ -145,10 +152,10 @@ These variables worked initially, but they were too sky130 specific and will be
 | `PL_RESIZER_BUFFER_INPUT_PORTS` | Specifies whether or not to insert buffers on input ports whenever resizer optimizations are run. For this to be used, `PL_RESIZER_DESIGN_OPTIMIZATIONS` must be set to 1. 1 = Enabled, 0 = Disabled. <br> (Default: `1`) |
 | `PL_RESIZER_BUFFER_OUTPUT_PORTS` | Specifies whether or not to insert buffers on output ports whenever resizer optimizations are run. For this to be used, `PL_RESIZER_DESIGN_OPTIMIZATIONS` must be set to 1. 1 = Enabled, 0 = Disabled. <br> (Default: `1`) |
 | `PL_RESIZER_REPAIR_TIE_FANOUT` | Specifies whether or not to repair tie cells fanout whenever resizer optimizations are run. For this to be used, `PL_RESIZER_DESIGN_OPTIMIZATIONS` must be set to 1. 1 = Enabled, 0 = Disabled. <br> (Default: `1`) |
-| `PL_MAX_DISPLACEMENT_X` | Specifies how far an instance can be moved along the X-axis when finding a site where it can be placed during detailed placement. <br> (Default: `500`um) |
-| `PL_MAX_DISPLACEMENT_Y` | Specifies how far an instance can be moved along the Y-axis when finding a site where it can be placed during detailed placement. <br> (Default: `100`um) |
-| `PL_MACRO_HALO` | Macro placement halo. Format: `{Horizontal} {Vertical}` <br> (Default: `0 0`um). |
-| `PL_MACRO_CHANNEL` | Channel widths between macros. Format: `{Horizontal} {Vertical}` <br> (Default: `0 0`um). |
+| `PL_MAX_DISPLACEMENT_X` | Specifies how far an instance can be moved along the X-axis when finding a site where it can be placed during detailed placement. <br> (Default: `500`μm) |
+| `PL_MAX_DISPLACEMENT_Y` | Specifies how far an instance can be moved along the Y-axis when finding a site where it can be placed during detailed placement. <br> (Default: `100`μm) |
+| `PL_MACRO_HALO` | Macro placement halo. Format: `{Horizontal} {Vertical}` <br> (Default: `0 0`μm). |
+| `PL_MACRO_CHANNEL` | Channel widths between macros. Format: `{Horizontal} {Vertical}` <br> (Default: `0 0`μm). |
 | `MACRO_PLACEMENT_CFG` | Specifies the path a file specifying how openlane should place certain macros |
 | `UNBUFFER_NETS` | A regular expression used to match nets from which to remove buffers after every resizer run. Useful for analog ports in mixed-signal designs where OpenROAD may sometimes add a buffer. <br> (Default: `^$`, matches nothing.) |
 | `DONT_BUFFER_PORTS` | **Removed: Use `UNBUFFER_NETS`.** Semicolon;delimited list of nets from which to remove buffers. <br> (Default: Empty) |

diff --git a/docs/source/contributing_to_docs.rst b/docs/source/contributing_to_docs.rst
@@ -105,7 +105,6 @@ In order to improve the readability of the documentation, please use and capital
     OpenRoad → OpenROAD
     Mac OS X → macOS
     MAGIC → Magic
-    open source → open-source
     Skywater130 → sky130
     Klayout → KLayout
     Pip -> pip or PIP 
@@ -120,6 +119,9 @@ In order to improve the readability of the documentation, please use and capital
     key value pair → key-value pair
     micrometre → micron (or, micrometer)
 
+.. note:: Also, when documenting micrometer-based variables, use the actual unicode character "μ", not "u", to avoid potential confusion. 
+
+
 Taking screenshots
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 The screenshots in documentation should use following prompt:

diff --git a/docs/source/eco_flow.md b/docs/source/eco_flow.md
@@ -3,6 +3,8 @@ The ECO flow starts from checking the report generated in the route step. A pyth
 
 ![image](../_static/eco_flow.png)
 
+> Note: The ECO flow is in very early alpha and is only compatible with the `sky130_fd_sc_hd` standard cell library in sky130 PDK variants.
+
 ## Flow to Insert Buffer
 1. Run the OL flow 
 2. Hold violations will be present in the log files