Merge pull request #1132 from luarss/docs_fix

Docs Update for build preferences, prebuilt binaries

Author: vvbandeira

.gitignore

@@ -83,3 +83,6 @@ dependencies/
 .metals/
 perf.data
 perf.data.old
+
+docs/main
+docs/build

README.md

@@ -13,10 +13,6 @@ flow stages through Tcl commands and Python APIs.
 
 ## Tool Installation
 
-### Local Installation
-
-Document for detailed local installation steps found [here](./docs/user/BuildLocally.md).
-
 ### Docker Based Installation
 
 To ease dependency installation issues, ORFS uses docker images.
@@ -36,6 +32,25 @@ To manage docker as non-root user and verify that you can run
 Document for detailed steps on docker based installation found
 [here](./docs/user/BuildWithDocker.md).
 
+### Pre-built Binaries
+
+You can download, set up and run ORFS easily with pre-built
+binaries, including OpenROAD, Yosys and Klayout. See instructions
+[here](./docs/user/BuildWithPrebuilt.md).
+
+> **Thanks** to [Precision Innovations](https://precisioninno.com/) for
+> providing and supporting OpenROAD based binaries.
+
+> **Note** Only the latest version of OpenROAD is guaranteed to work with
+> the latest version of ORFS.
+
+> **Disclaimer** The versions of OpenROAD, Yosys and Klayout provided by
+> other third-party vendors are not guaranteed to work with ORFS.
+
+### Local Installation
+
+Document for detailed local installation steps found [here](./docs/user/BuildLocally.md).
+
 ## Using the Flow
 
 - For details about the OpenROAD and the available features and

docs/conf.py

@@ -75,7 +75,7 @@
     '**/LICENSE.md',
     'README.md',
     'docs/releases/PostAlpha2.1BranchMethodology.md',
-    'main/docs',
+    'main',
 ]
 
 # The name of the Pygments (syntax highlighting) style to use.

docs/contrib/DeveloperGuide.md

@@ -2,8 +2,8 @@
 
 ## Building
 
-Instructions for building are available [here](../user/Build.md).
+Instructions for building are available [here](../index.md#getting-started-with-openroad-flow-scripts).
 
 ## Logger
 
-Instructions for logging are available on [OpenROAD documentation](https://openroad.readthedocs.io/en/latest/contrib/Logger.html).
+Instructions for logging are available on [OpenROAD documentation](https://openroad.readthedocs.io/en/latest/contrib/Logger.html).

docs/contrib/GettingInvolved.md

@@ -75,11 +75,11 @@ project like OpenROAD with many application subcomponents, the software
 architecture can quickly get out of control. Changes with lots of new
 dependencies which are not necessary are less likely to be integrated.
 
-If you want to add Tcl code to define a new tool command, look at pdngen
+If you want to add Tcl code to define a new tool command, look at [pdngen](https://github.com/The-OpenROAD-Project/OpenROAD/tree/master/src/pdn)
 as an example of how to do so. Take a look at the
-[cmake file](https://github.com/The-OpenROAD-Project/OpenROAD/blob/master/src/CMakeLists.txt)
+[CMakeLists file](https://github.com/The-OpenROAD-Project/OpenROAD/blob/master/src/CMakeLists.txt)
 which automatically sources the Tcl code and the
-[Tcl file](https://github.com/The-OpenROAD-Project/OpenROAD/blob/master/src/pdn/src/PdnGen.tcl)
+[Tcl file](https://github.com/The-OpenROAD-Project/OpenROAD/blob/master/src/pdn/src/pdn.tcl)
 itself.
 
 To accept contributions, we require each commit to be made with a DCO (Developer

docs/contrib/PlatformBringUp.md

@@ -40,7 +40,7 @@ They include :
 Adding a new platform additionally requires the following:
 
 *   A validated installation of the OpenROAD flow scripts is available. See
-    instructions [here](../user/GettingStarted.md).
+    instructions [here](../index.md#build-or-installing-orfs-dependencies).
 *   A general knowledge of VLSI design and RTL to GDS flows.  OpenROAD
     implements a fully-automated RTL-GDSII but it requires familiarity with
     the OpenROAD flow scripts to debug problems.
@@ -114,8 +114,8 @@ for the OpenROAD flow. Specifically the `config.mk` file in the platform
 directory has all of the configuration variables that the flow uses. Refer
 to the OpenROAD-flow-scripts documentation for a full list of configuration
 variables that can be set.
-Refer to the [Flow variables](../user/FlowVariables.md) document for details on how to use 
-environment variables in OpenROAD-flow-scripts to configure platform and design specific parameters. 
+Refer to the [Flow variables](../user/FlowVariables.md) document for details on how to use
+environment variables in OpenROAD-flow-scripts to configure platform and design specific parameters.
 
 For an example of a platform `config.mk` file, refer to
 `flow/platforms/sky130hd/config.mk.`
@@ -207,7 +207,6 @@ place them in their respective directories and set the `lib`, `lef`, and
 
 ### Clock Gates
 
---------------------------------------------------------------------------------
 Yosys cannot (currently) infer clock gates automatically. However, users can
 manually instantiate clock gates in their RTL using a generic interface. The
 purpose of this interface is to separate platform-specific RTL (also called

docs/index.md

@@ -1,26 +1,25 @@
-# Welcome to OpenROAD Flow's documentation!
+# Welcome to the OpenROAD Flow Scripts documentation!
 
 The OpenROAD ("Foundations and Realization of Open, Accessible Design")
 project was launched in June 2018 within the DARPA IDEA program. OpenROAD
 aims to bring down the barriers of cost, expertise and unpredictability that
 currently block designers' access to hardware implementation in advanced
 technologies. The project team (Qualcomm, Arm and multiple universities and
 partners, led by UC San Diego) is developing a fully autonomous, open-source
-tool chain for digital SoC layout generation, focusing on
-the RTL-to-GDSII phase of system-on-chip design. Thus,
-OpenROAD holistically attacks the multiple facets of today's design cost
-crisis: engineering resources, design tool licenses, project schedule,
-and risk.
+tool chain for digital SoC layout generation, focusing on the RTL-to-GDSII
+phase of system-on-chip design. Thus, OpenROAD holistically attacks the
+multiple facets of today's design cost crisis: engineering resources,
+design tool licenses, project schedule, and risk.
 
 The IDEA program targets no-human-in-loop (NHIL) design, with 24-hour
 turnaround time and zero loss of power-performance-area (PPA) design quality.
 
-The NHIL target requires tools to adapt and auto-tune successfully to flow
-completion, without (or, with minimal) human intervention. Machine
+The NHIL target requires tools to adapt and auto-tune successfully to
+flow completion, without (or, with minimal) human intervention. Machine
 intelligence augments human expertise through efficient modeling and
-prediction of flow and optimization outcomes throughout the synthesis, placement
-and routing process. This is complemented by development of metrics
-and machine learning infrastructure.
+prediction of flow and optimization outcomes throughout the synthesis,
+placement and routing process. This is complemented by development of
+metrics and machine learning infrastructure.
 
 The 24-hour runtime target implies that problems must be strategically
 decomposed throughout the design process, with clustered and partitioned
@@ -31,34 +30,160 @@ resources. Decomposition that enables parallel and distributed search over
 cloud resources incurs a quality-of-results loss, but this is subsequently
 recovered through improved flow predictability and enhanced optimization.
 
-For a technical description of the OpenROAD flow, please refer to our DAC-2019 paper:
-[Toward an Open-Source Digital Flow: First Learnings from the OpenROAD Project](https://vlsicad.ucsd.edu/Publications/Conferences/371/c371.pdf).
-The paper is also available from [ACM Digital Library](https://dl.acm.org/doi/10.1145/3316781.3326334).
-Other publications and presentations are
-linked [here](https://theopenroadproject.org/publications/).
+Learn more about the project at our website and our resources page
+[here](https://theopenroadproject.org/resources/).
 
-## Code of conduct
+## Getting Started with OpenROAD Flow Scripts
 
-Please read our code of conduct [here](./contrib/CODE_OF_CONDUCT.md).
+OpenROAD Flow is a full RTL-to-GDS flow built entirely on open-source tools.
+The project aims for automated, no-human-in-the-loop digital circuit design
+with 24-hour turnaround time.
+
+### Setup
+
+#### System Requirements
+
+To build the binaries and run `gcd` through the flow:
+
+- Minimum: 1 CPU core and 8GB RAM.
+- Recommend: 4 CPU cores and 16GB of RAM.
+
+> **Note** `gcd` is a small design, and thus requires less computational power.
+> Larger designs may require better hardware.
+
+#### Build or Installing ORFS Dependencies
+
+We support three major ways of installation:
+
+- [Docker](./user/BuildWithDocker.md)
+- [Pre-built Binaries](./user/BuildWithPrebuilt.md)
+- [Local Installation](./user/BuildLocally.md)
+
+You may also choose use the build script to customise your build process.
+See more in the next section.
+
+##### Build Command and options
+
+``` shell
+./build_openroad.sh --help
+```
+
+Options for `./build_openroad.sh` script
+| Argument                      | Description                                                                           |
+|-------------------------------|---------------------------------------------------------------------------------------|
+| `-h` or `--help`              | Print help message.                                                                   |
+| `-o` or  `--local`            | Build locally instead of building a Docker image.                                     |
+| `-l` or  `--latest`           | Use the head of branch --or_branch or 'master' by default for tools/OpenROAD.         |
+| `--or_branch BRANCH_NAME`     | Use the head of branch BRANCH for tools/OpenROAD.                                     |
+| `--or_repo REPO_URL`          | Use a fork at REPO-URL (https/ssh) for tools/OpenROAD.                                |
+| `--no_init`                   | Skip initializing submodules.                                                         |
+| `-t N` or `--threads N`       | Use N cpus when compiling software.                                                   |
+| `-n` or `--nice`              | Nice all jobs. Use all cpus unless `--threads` is also given, then use N threads.     |
+| `--yosys-args-overwrite`      | Do not use default flags set by this scrip during Yosys compilation.                  |
+| `--yosys-args STRING`         | Aditional compilation flags for Yosys compilation.                                    |
+| `--openroad-args-overwrite`   | Do not use default flags set by this script during OpenROAD app compilation.          |
+| `--openroad-args STRING`      | Aditional compilation flags for OpenROAD app compilation.                             |
+| `--lsoracle-enable`           | Compile LSOracle. Disable by default as it is not currently used on the flow.         |
+| `--lsoracle-args-overwrite`   | Do not use default flags set by this scrip during LSOracle compilation.               |
+| `--lsoracle-args STRING`      | Aditional compilation flags for LSOracle compilation.                                 |
+| `--install-path PATH`         | Path to install tools. Default is `${INSTALL_PATH}`.                                  |
+| `--clean`                     | Call git clean interactively before compile. Useful to remove old build files.        |
+| `--clean-force`               | Call git clean before compile. WARNING: this option will not ask for confirmation. Useful to remove old build files. |
+| `-c` or `--copy-platforms`    | Only applicable for docker builds. Copy platforms to inside docker image.             |
+| `--docker-args-overwrite`     | Only applicable for docker builds. Do not use default flags set by this script for Docker builds.  |
+| `--docker-args STRING`        | Only applicable for docker builds. Additional compilation flags for Docker build.     |
+
+
+### Running a Design
+
+Sample design configurations are available in the `designs` directory.
+You can select a design using either of the following methods:
+
+1. The flow
+   [Makefile](https://github.com/The-OpenROAD-Project/OpenROAD-flow-scripts/blob/master/flow/Makefile)
+   contains a list of sample design configurations at the top of the
+   file. Uncomment the respective line to select the design.
+2. Specify the design using the shell environment. For example:
+
+```shell
+make DESIGN_CONFIG=./designs/nangate45/swerv/config.mk
+# or
+export DESIGN_CONFIG=./designs/nangate45/swerv/config.mk
+make
+```
+
+By default, the `gcd` design is selected using the
+`nangate45` platform. The resulting GDS will be available at
+`flow/results/nangate45/gcd/6_final.gds`. The flow should take only a few
+minutes to produce a GDS for this design. We recommend implementing this
+design first to validate your flow and tool setup.
+
+### Design exploration and automatic parameter tuning
+
+AutoTuner is an automatic parameter tuning framework capable of performing
+automatic parameter tuning framework for commercial and academic RTL-to-GDS
+flows. The two main functionalities that AutoTuner provides are:
 
-## Documentation
+- Automatic hyperparameter tuning framework for OpenROAD-flow-scripts
+- Parametric sweeping experiments for OpenROAD-flow-scripts
 
-The OpenROAD Project has two releases:
+> **Tip**: Refer to the detailed [instructions here](./user/InstructionsForAutoTuner.md) for AutoTuner.
 
-### [Application](https://github.com/The-OpenROAD-Project/OpenROAD)
+### Adding a Design
 
-The application is a standalone binary capable of performing RTL-to-GDSII SoC design,
-from logic synthesis and floorplanning through detailed routing with metal fill insertion,
-signoff parasitic extraction and timing analysis.
+To add a new design to the `flow` directory, refer to the document [here](./user/AddingNewDesign.md).
 
-See documentation for the application [here](https://openroad.readthedocs.io/en/latest/).
+### Platforms
 
-### [Flow](https://github.com/The-OpenROAD-Project/OpenROAD-flow-scripts)
+OpenROAD-flow-scripts supports Verilog to GDS for the following open platforms:
 
-The flow is a set of integrated scripts that allow for RTL-to-GDSII flow
-using open-source tools.
+- ASAP7
+- Nangate45 / FreePDK45
+- SKY130
 
-See documentation for the flow [here](user/GettingStarted.md).
+These platforms have a permissive license which allows us to
+redistribute the PDK and OpenROAD platform-specific files. The platform
+files and license(s) are located in `platforms/{platform}`.
+
+OpenROAD-flow-scripts also supports the following commercial platforms:
+
+- GF12
+- TSMC65LP
+
+The PDKs and platform-specific files for these kits cannot be provided
+due to NDA restrictions. However, if you are able to access these
+platforms, you can create the necessary platform-specific files
+yourself.
+
+Once the platform is set up, you can create a new design configuration with
+information about the design. See sample configurations in the `design`
+directory.
+Refer to the [Flow variables](./user/FlowVariables.md) document for details on how to use
+environment variables in OpenROAD-flow-scripts to configure platform and design specific parameters.
+
+#### Adding a Platform
+
+Refer to the [platform bring up](./contrib/PlatformBringUp.md) documentation
+to set up a new platform for OpenROAD-flow-scripts.
+
+### Implement the Design
+
+Run `make` to perform Verilog to GDS. The final output will be located
+at `flow/results/{platform}/{design_name}/6_final.gds`
+
+### Miscellaneous
+
+#### Smoke-test harness for top-level Verilog designs
+
+1. Drop your Verilog files into `designs/src/harness`
+2. Start the workflow:
+
+> **TIP!**
+> Start with a very small submodule in your design that has only a few pins.
+
+```shell
+make DESIGN_NAME=TopLevelName DESIGN_CONFIG=$(pwd)/designs/harness.mk
+```
 
 ## How to contribute
 
@@ -73,18 +198,23 @@ can use OpenROAD as the infrastructure for your tools in the
 
 We maintain the following channels for communication:
 
--   Project homepage and news: <https://theopenroadproject.org>
--   Twitter: <https://twitter.com/OpenROAD_EDA>
--   Issues and bugs:
-    -   OpenROAD Flow: <https://github.com/The-OpenROAD-Project/OpenROAD-flow-scripts/issues>
-    -   OpenROAD with OpenROAD Flow Scripts: <https://github.com/The-OpenROAD-Project/OpenROAD/issues/>
--   Discussions:
-    -   OpenROAD Flow: <https://github.com/The-OpenROAD-Project/OpenROAD-flow-scripts/discussions>
--   Inquiries: [email protected]
+- Project homepage and news: <https://theopenroadproject.org>
+- Twitter: <https://twitter.com/OpenROAD_EDA>
+- Issues and bugs:
+  - OpenROAD Flow: <https://github.com/The-OpenROAD-Project/OpenROAD-flow-scripts/issues>
+  - OpenROAD with OpenROAD Flow Scripts: <https://github.com/The-OpenROAD-Project/OpenROAD/issues/>
+- Discussions:
+  - OpenROAD Flow: <https://github.com/The-OpenROAD-Project/OpenROAD-flow-scripts/discussions>
+- Inquiries: [email protected]
 
 See also our [FAQs](user/FAQS.md).
 
+## Code of conduct
+
+Please read our code of conduct [here](./contrib/CODE_OF_CONDUCT.md).
+
 ## Site Map
 
 ```{tableofcontents}
+
 ```