Artifact Reorganization (#723)

The best thing to happen to OpenLane since OpenLane. Variables related to output files: i.e. logs, results and reports, are becoming more uniform. * Variables now point to folders * Variables now called `{stage}_{type}s` * All variables renamed to be tool-generic * magic, klayout, cvc and lvs all unified, renamed "finishing" * Better flow runtime calculation * All step runtimes are now stored in a yaml file, which can easily be read by a human or parsed by a computer. * Better step indexing * You have to increment the step index explicitly using `increment_index`. * Functions that take log arguments now require you to not use an indexed file, it's their responsibility to index them. * Changed names for many logs to make more sense * A plethora of files being moved and/or renamed * Yosys scripts were moved into their own folder * All references to OpenLANE that are not a published paper have been replaced with OpenLane * Copyright dates updated on some files
The-OpenROAD-Project · Nov 23, 2021 · 3bc6fcd · 3bc6fcd
1 parent e1883ed
commit 3bc6fcd
Show file tree

Hide file tree

Showing 52 changed files with 1,836 additions and 1,850 deletions.
diff --git a/.github/scripts/run_tests.py b/.github/scripts/run_tests.py
@@ -1,6 +1,6 @@
 #!/usr/bin/env python3
 # -*- coding: utf-8 -*-
-# Copyright 2020 Efabless Corporation
+# Copyright 2020-2021 Efabless Corporation
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -22,33 +22,32 @@
 import subprocess
 from gh import gh
 
-
 threads_used = int(subprocess.check_output(["nproc"]).decode("utf-8")) - 1
 test_name = "TEST"
 design_list = sys.argv[1:]
 test_set = os.getenv("TEST_SET")
 if test_set is not None:
-    test_name = "TEST_%s" % test_set
+    test_name = f"TEST_{test_set}"
     test_set_file = os.path.join(gh.root, ".github", "test_sets", test_set)
     if os.path.exists(test_set_file):
         design_list = open(test_set_file).read().split()
     else:
-        raise Exception("Test set %s not found." % test_set)
+        raise Exception(f"Test set {test_set} not found.")
 
-    print("Running test set %s using %i threads…" % (test_set, threads_used))
+    print(f"Running test set {test_set} using {threads_used} threads…")
 else:
-    print("Running on designs %s using %i threads…" % (design_list, threads_used))
+    print(f"Running on designs {design_list} using {threads_used} threads…")
 
 username = getpass.getuser()
 user = subprocess.check_output(["id", "-u", username]).decode("utf8")[:-1]
 group = subprocess.check_output(["id", "-g", username]).decode("utf8")[:-1]
 
 docker_command = [
     "docker", "run",
-    "-v", "%s:/openlane" % os.path.realpath(gh.root),
-    "-v", "{p}:{p}".format(p=gh.pdk),
-    "-u", "%s:%s" % (user, group),
-    "-e", "PDK_ROOT=%s" % gh.pdk,
+    "-v", f"{os.path.realpath(gh.root)}:/openlane",
+    "-v", f"{gh.pdk}:{gh.pdk}",
+    # "-u", f"{user}:{group}",
+    "-e", f"PDK_ROOT={gh.pdk}",
     gh.image,
     "bash", "-c",
     shlex.join([
@@ -69,22 +68,22 @@
 subprocess.run(docker_command, check=True)
 
 
-df = lambda x: print(open(x).read())
+cat = lambda x: print(open(x).read())
 
 results_folder = os.path.join(gh.root, "regression_results", test_name)
 
 print("Verbose differences within the benchmark:")
-for report in glob.glob(os.path.join(results_folder, "%s*.rpt" % test_name)):
-    df(report)
+for report in glob.glob(os.path.join(results_folder, f"{test_name}*.rpt")):
+    cat(report)
 print("Full report:")
-df(os.path.join(results_folder, "%s.csv" % test_name))
+cat(os.path.join(results_folder, f"{test_name}.csv"))
 
-design_test_report = os.path.join(results_folder, "%s_design_test_report.csv" % test_name)
+design_test_report = os.path.join(results_folder, f"{test_name}.csv")
 if not os.path.exists(design_test_report):
-    print("Couldn't find final design test report at %s." % design_test_report)
+    print(f"Couldn't find final design test report at {design_test_report}.")
     exit(-1)
 
-df(design_test_report)
+cat(design_test_report)
 
 if "FAILED" in open(design_test_report).read():
     print("At least one test has failed.")

diff --git a/README.md b/README.md
@@ -520,7 +520,7 @@ To check the original author list of OpenLane, check [this][33].
 # Additional Material
 
 ## Papers
-- Ahmed Ghazy and Mohamed Shalan, "OpenLane: The Open-Source Digital ASIC Implementation Flow", Article No.21, Workshop on Open-Source EDA Technology (WOSET), 2020. [Paper](https://github.com/woset-workshop/woset-workshop.github.io/blob/master/PDFs/2020/a21.pdf)
+- Ahmed Ghazy and Mohamed Shalan, "OpenLANE: The Open-Source Digital ASIC Implementation Flow", Article No.21, Workshop on Open-Source EDA Technology (WOSET), 2020. [Paper](https://github.com/woset-workshop/woset-workshop.github.io/blob/master/PDFs/2020/a21.pdf)
 - M. Shalan and T. Edwards, "Building OpenLANE: A 130nm OpenROAD-based Tapeout- Proven Flow : Invited Paper," 2020 IEEE/ACM International Conference On Computer Aided Design (ICCAD), San Diego, CA, USA, 2020, pp. 1-6. [Paper](https://ieeexplore.ieee.org/document/9256623/)
 - R. Timothy Edwards, M. Shalan and M. Kassem, "Real Silicon using Open Source EDA," in IEEE Design & Test, doi: 10.1109/MDAT.2021.3050000. [Paper](https://ieeexplore.ieee.org/document/9336682)
 
@@ -560,16 +560,16 @@ To check the original author list of OpenLane, check [this][33].
 [20]: https://github.com/git-lfs/git-lfs/wiki/Installation
 [21]: ./regression_results/README.md
 [22]: https://github.com/RTimothyEdwards/netgen
-[24]: ./docs/source/PDK_STRUCTURE.md
+[24]: ./docs/source/pdk_structure.md
 [25]: ./docs/source/advanced_readme.md
 [26]: ./docs/source/chip_integration.md
 [27]: https://github.com/HanyMoussa/SPEF_EXTRACTOR
 [28]: https://github.com/scale-lab/OpenPhySyn
 [29]: ./docs/source/hardening_macros.md
-[30]: ./docs/source/Manual_PDK_installation.md
+[30]: ./docs/source/manual_pdk_installation.md
 [31]: https://github.com/d-m-bailey/cvc
 [32]: ./CONTRIBUTING.md
 [33]: ./AUTHORS.md
-[34]: ./docs/source/OpenLANE_commands.md
+[34]: ./docs/source/openlane_commands.md
 [35]: https://github.com/KLayout/klayout
 [36]: https://github.com/cuhk-eda/cu-gr
diff --git a/configuration/README.md b/configuration/README.md
@@ -119,7 +119,7 @@ These variables are optional that can be specified in the design configuration f
 | `PL_RESIZER_HOLD_MAX_BUFFER_PERCENT` | Specifies a max number of buffers to insert to fix hold violations. This number is calculated as a percentage of the number of instances in the design. <br> (Default: `50`)|
 | `PL_RESIZER_SETUP_MAX_BUFFER_PERCENT` | Specifies a max number of buffers to insert to fix setup violations. This number is calculated as a percentage of the number of instances in the design. <br> (Default: `50`)|
 | `PL_RESIZER_ALLOW_SETUP_VIOS` | Allows setup violations when fixing hold. <br> (Default: `0`)|
-| `LIB_RESIZER_OPT` | Points to the lib file, corresponding to the typical corner, that is used during resizer optimizations. This is copy of `LIB_SYNTH_COMPLETE`. <br> Default: `$::env(TMP_DIR)/resizer_<library-name>.lib` |
+| `LIB_RESIZER_OPT` | Points to the lib file, corresponding to the typical corner, that is used during resizer optimizations. This is copy of `LIB_SYNTH_COMPLETE`. <br> Default: `$::env(synthesis_tmpfiles)/resizer_<library-name>.lib` |
 | `DONT_USE_CELLS` | The list of cells to not use during resizer optimizations. <br> Default: the contents of `DRC_EXCLUDE_CELL_LIST`. |
 | `PL_ESTIMATE_PARASITICS` | Specifies whether or not to run STA after global placement using OpenROAD's estimate_parasitics -placement and generates reports under `logs/placement`. 1 = Enabled, 0 = Disabled. <br> (Default: `1`) |
 | `PL_OPTIMIZE_MIRRORING` | Specifies whether or not to run an optimize_mirroring pass whenever detailed placement happens. This pass will mirror the cells whenever possible to optimize the design. 1 = Enabled, 0 = Disabled. <br> (Default: `1`) |
@@ -149,7 +149,7 @@ These variables are optional that can be specified in the design configuration f
 | `CTS_SINK_CLUSTERING_MAX_DIAMETER` | Specifies maximum diameter (in micron) of sink cluster. <br> (Default: `50`) |
 | `CTS_REPORT_TIMING` | Specifies whether or not to run STA after clock tree synthesis using OpenROAD's estimate_parasitics -placement and generates reports under `logs/cts`. 1 = Enabled, 0 = Disabled. <br> (Default: `1`) |
 | `CTS_CLK_MAX_WIRE_LENGTH` | Specifies the maximum wire length on the clock net. Value in microns. <br> (Default: `0`) |
-| `LIB_CTS` | The liberty file used for CTS. By default, this is the `LIB_SYNTH_COMPLETE` minus the cells with drc errors as specified by the drc exclude list. <br> (Default: `$::env(TMP_DIR)/cts.lib`) |
+| `LIB_CTS` | The liberty file used for CTS. By default, this is the `LIB_SYNTH_COMPLETE` minus the cells with drc errors as specified by the drc exclude list. <br> (Default: `$::env(cts_tmpfiles)/cts.lib`) |
 
 ### Routing
 

diff --git a/configuration/synthesis.tcl b/configuration/synthesis.tcl
@@ -14,7 +14,7 @@
 
 # Synth defaults
 set ::env(SYNTH_BIN) yosys
-set ::env(SYNTH_SCRIPT) $::env(SCRIPTS_DIR)/synth.tcl
+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_TRANSITION) 0.15

diff --git a/docs/source/advanced_power_grid_control.md b/docs/source/advanced_power_grid_control.md
@@ -10,7 +10,7 @@ An example utilizing the controls and logic provided in this documentation is th
 
 ## Chip Level:
 
-According to the current methodology of [OpenLANE Chip Integration][0], the process goes as follows:
+According to the current methodology of [OpenLane Chip Integration][0], the process goes as follows:
 1. Hardening the hard/internal macros.
 2. Hardening the core with the hard macros inside it.
 3. Hardening the full chip with the padframe and the chip core.

diff --git a/docs/source/advanced_readme.md b/docs/source/advanced_readme.md
@@ -19,7 +19,7 @@ Then, you should be able to run the following main commands:
 4. `run_placement`
 5. `run_cts`
 6. `run_routing`
-7. `write_powered_verilog` followed by `set_netlist $::env(lvs_result_file_tag).powered.v`
+7. `write_powered_verilog` followed by `set_netlist $::env(routing_logs)/$::env(DESIGN_NAME).powered.v`
 8. `run_magic`
 9. `run_magic_spice_export`
 10. `run_magic_drc`
@@ -41,5 +41,5 @@ A more detailed list of all the commands supported by openlane could be found [h
 
 **Note 3:** You can pass the -design, -tag, etc.. flags to ```./flow.tcl -interactive``` directly without the need of entering the interactive mode and then executing the prep command.
 
-[0]:./OpenLANE_commands.md
+[0]:./openlane_commands.md
 
diff --git a/docs/source/chip_integration.md b/docs/source/chip_integration.md
@@ -46,7 +46,7 @@ You can follow the same instructions provided [here][8] for the rest of the hard
 
 In case you want to manually place the macros in specific locations, [this][9] should provide a good example on how to do it. This is done by creating a configuration file containing an endline separated list of `instance_name X_pos Y_pos Orientation` and pointing to it with this configuartion: `::env(MACRO_PLACEMENT_CFG)`.
 
-[Here][0] you can find a list of all the available OpenLANE configuartions.
+[Here][0] you can find a list of all the available OpenLane configuartions.
 
 Check this [section](#power-routing) for more details on power routing setup.
 
@@ -119,12 +119,12 @@ When you use the `power_routing` command in the chip interactive script, the pow
 
 [This][2] includes more guidance on how to create an interactive script.
 
-[This][0] documents all OpenLANE configurations.
+[This][0] documents all OpenLane configurations.
 
-[This][1] has a description for all OpenLANE commands.
+[This][1] has a description for all OpenLane commands.
 
 [0]: ./../../configuration/README.md
-[1]: ./OpenLANE_commands.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

diff --git a/docs/source/hardening_macros.md b/docs/source/hardening_macros.md
@@ -223,10 +223,10 @@ The final GDS-II should be found under `<run-path>/results/magic/`.
 
 To integrate that macro into a core or a chip, check this [documentation on chip integration][4].
 
-If you want to create further tweaks in the flow that the abundant configurations don't allow, make sure to check [this][2] for more details about the interactive mode of the OpenLANE flow.
+If you want to create further tweaks in the flow that the abundant configurations don't allow, make sure to check [this][2] for more details about the interactive mode of the OpenLane flow.
 
 [0]: ./../../configuration/README.md
-[1]: ./OpenLANE_commands.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]: ./chip_integration.md

diff --git a/docs/source/Manual_PDK_installation.md → docs/source/manual_pdk_installation.md b/docs/source/Manual_PDK_installation.md → docs/source/manual_pdk_installation.md
@@ -27,7 +27,7 @@
             - sky130_fd_sc_ls
             - sky130_fd_sc_hdll
 
-- Setup the configurations and tech files for Magic, Netgen, OpenLANE using [open_pdks](https://github.com/RTimothyEdwards/open_pdks):
+- Setup the configurations and tech files for Magic, Netgen, OpenLane using [open_pdks](https://github.com/RTimothyEdwards/open_pdks):
 
     ```bash
         cd $PDK_ROOT

diff --git a/docs/source/OpenLANE_commands.md → docs/source/openlane_commands.md b/docs/source/OpenLANE_commands.md → docs/source/openlane_commands.md
@@ -1,4 +1,4 @@
-# OpenLANE Interactive Mode Commands
+# OpenLane Interactive Mode Commands
 
 This page describes the list of commands available in openlane, their functionality, and their expected inputs and outputs.
 
@@ -84,7 +84,7 @@ Most of the following commands' implementation exists in this [file][0]
 |    | `-log_path <path>` | The path to write the logs into. |
 | `run_spef_extraction` | | Runs SPEF extraction on the `::env(CURRENT_DEF)` file followed by Static Timing Analysis using OpenSTA. The results are reported under `<run_path>/reports/synthesis/opensta_spef_*`. |
 | `run_antenna_check` | | Runs antenna checks based on the value of `::env(USE_ARC_ANTENNA_CHECK)` either calling `run_or_antenna_check` or `run_magic_antenna_check`. |
-| `run_or_antenna_check` | | Runs antenna checks using OpenROAD's Antenna Rule Checker on the `::env(CURRENT_DEF)`, the result is saved in `<run_path>/reports/routing/antenna.rpt`|
+| `run_or_antenna_check` | | Runs antenna checks using OpenROAD's Antenna Rule Checker on the `::env(CURRENT_DEF)`, the result is saved in `<run_path>/reports/finishing/antenna.rpt`|
 | `save_state` | | Saves environment variables to  `<run_path>/config.tcl`, needed for -from -to|
 
 ## Checker Commands
@@ -184,7 +184,6 @@ Most of the following commands' implementation exists in this [file][7]
 | `manual_macro_placement [f]` | | Uses the configuration file generated by `add_macro_placement` (`/run_path/tmp/macro_placements.cfg`) to manually initialize the placement of the macros to the locations determined in the file. It works on the currently processed design and it overwrites the `CURRENT_DEF`. if `f` is passed as the first argument, the placement will be fixed and final, and the placement tools will not be allowed to change it.|
 | `basic_macro_placement` | | Runs basic macro placement on the chip level using the openroad app, and it writes into `::env(CURRENT_DEF).macro_placement.def`. |
 | `run_resizer_design` | | Runs resizer design optimizations to insert buffers on nets to repair max slew, max capacitance, max fanout violations, and on long wires to reduce RC delay in the wire. It also resizes cells. |
-| `run_resizer_timing` | | Runs resizer timing optimizations which repairs setup and hold violations.  |
 | `run_placement`| | Runs global placement (`global_placement_or` or `random_global_placement` based on the value of `PL_RANDOM_GLB_PLACEMENT`), then applies the optional optimizations `repair_wire_length` followed by `run_openPhySyn` if enabled, then runs the detailed placement (`detailed_placement_or`). |
 
 ## CTS Commands
@@ -204,6 +203,7 @@ Most of the following commands' implementation exists in this [file][2]
 |    | `-cell_clk_port <name>` | Clock buffer port name.    |
 |    | `-output <output_file>` | Output file path.    |
 | `run_cts` | | Runs clock tree synthesis using the openroad app on the processed design. The resulting file is under `/<run_path>/results/cts/`. It also generates a the updated netlist using yosys and stores the results under `/<run_path>/results/synthesis` and runs yosys logic verification if enabled. |
+| `run_resizer_timing` | | Runs resizer timing optimizations which repairs setup and hold violations.  |
 
 
 ## Fill Insertion/Diode Insertion Commands
@@ -271,6 +271,7 @@ Most of the following commands' implementation exists in this [file][17]
 |---------------|------------------------|-----------------------------------------|
 | `run_klayout` | | Streams the back-up final GDS-II, generates a PNG screenshot, then runs Klayout DRC deck on it. This is controlled by `RUN_KLAYOUT`, `TAKE_LAYOUT_SCROT` ,and `KLAYOUT_DRC_KLAYOUT_GDS`. The resulting file is under `/<run_path>/results/klayout/` . |
 | `scrot_klayout` | | Export a PNG view of a given GDS-II or DEF file. This is controlled by `TAKE_LAYOUT_SCROT`. |
+|    | `[-log <log_file>]` | Output log file. |
 |    | `[-layout <layout_file>]` | The input GDS or DEF file, the default is `::env(CURRENT_GDS)`. |
 | `run_klayout_drc` | | Runs Klayout DRC on a given GDS-II file. This is controlled by `RUN_KLAYOUT_DRC`. |
 |    | `[-gds <gds_file>]` | The input GDS file, the default is `::env(CURRENT_GDS)`. |
@@ -286,7 +287,7 @@ Most of the following commands' implementation exists in this [file][5]
 
 | Command      | Flags                   | Description                                           |
 |---------------|------------------------|-----------------------------------------|
-| `run_lvs` | | Runs an lvs check between an extracted spice netlist `EXT_NETLIST` (so `run_magic_spice_export` should be run before it.) and the current verilog netlist of the processed design `CURRENT_NETLIST`. The resulting file is under `/<run_path>/results/lvs/` and `/<run_path>/reports/lvs/`. The LVS could be on the block/cell level or on the device/transistor level, this is controlled by the extraction type set by `MAGIC_EXT_USE_GDS`. If the GDS is used in extraction then the LVS will be run down to the device/transistor level, otherwise it will be run on the block/cell level which is the default behavior in OpenLANE. |
+| `run_lvs` | | Runs an lvs check between an extracted spice netlist `EXT_NETLIST` (so `run_magic_spice_export` should be run before it.) and the current verilog netlist of the processed design `CURRENT_NETLIST`. The resulting file is under `/<run_path>/results/lvs/` and `/<run_path>/reports/lvs/`. The LVS could be on the block/cell level or on the device/transistor level, this is controlled by the extraction type set by `MAGIC_EXT_USE_GDS`. If the GDS is used in extraction then the LVS will be run down to the device/transistor level, otherwise it will be run on the block/cell level which is the default behavior in OpenLane. |
 
 ## CVC Commands
 
@@ -336,9 +337,9 @@ Most of the following commands' implementation exists in these files: [deflef][1
 | `puts_warn <text>` | | Prints `[WARNING]: ` followed by the `<text>` in yellow. |
 | `puts_info <text>` | | Prints `[INFO]: ` followed by the `<text>` in cyan. |
 | `copy_gds_properties <arg_1.mag> <arg2.mag>` | | copies the GDS properties from `<arg_1.mag>` to `<arg2.mag>`. |
-| `index_file <file> [<increment>]` | | Adds an index prefix to the file name keeping it's path. The prefix is governed by `CURRENT_INDEX`+`increment`, and `CURRENT_INDEX` is stored/overwritten every time an increment is added. The current value of the `CURRENT_INDEX` could be found in `<run_path>/config.tcl`. The default increment is `1`. |
-| `calc_total_runtime` | | Creates a `<-report>` file with `<-status>` for the design followed by the total runtime from the beginning of the flow. |
-|    | `[-report <report_file>]` | The ouput total runtime file path. <br> Defaults to being generated under `<run_path>/reports/total_runtime.txt`. |
+| `increment_index` | |  Increments `CURRENT_INDEX` by 1. |
+| `index_file <file>` | | Adds an index prefix to the file name keeping it's path. The prefix is `CURRENT_INDEX`. The current value of the `CURRENT_INDEX` could be found in `<run_path>/config.tcl`. |
+| `calc_total_runtime` | | Finalizes the generated `runtime.yaml` file for the design followed  with the total runtime from the beginning of the flow. |
 |    | `[-status <status>]` | The status message printed in the file. <br> Defaults to `flow completed`. |
 | `flow_fail` | | Calls `generate_final_summary_report`, calls `calc_total_runtime` with status `flow failed`, and finally prints `Flow Failed` to the terminal. |
 | `find_all <ext>` | | Print a sorted list of *.ext files that are found in the current run directory. |

diff --git a/docs/source/PDK_STRUCTURE.md → docs/source/pdk_structure.md b/docs/source/PDK_STRUCTURE.md → docs/source/pdk_structure.md