Documentation Restructure (#1337)

~ Documentation all moved under `docs/source`, arranged hierarchically according to the table of contents ~ `Klayout` changed to `KLayout` in all logging messages ~ Readme rewritten to just be concise, parts of it isolated into standalone documentation ~ RTD builds no longer use conda (saves some time) ~ Fixed all broken links
The-OpenROAD-Project · Sep 12, 2022 · cbb9e6b · cbb9e6b
1 parent 63b5966
commit cbb9e6b
Show file tree

Hide file tree

Showing 50 changed files with 449 additions and 597 deletions.
diff --git a/.github/workflows/Readme.md b/.github/workflows/Readme.md
@@ -0,0 +1 @@
+For more information about the OpenLane CI/CD, visit https://openlane.readthedocs.io/en/latest/for_developers/gha_workflow.html.
diff --git a/.readthedocs.yml b/.readthedocs.yml
@@ -5,9 +5,11 @@
 # Required
 version: 2
 
-# Build documentation in the docs/ directory with Sphinx
-sphinx:
-  configuration: conf.py
-
-conda:
-  environment: docs/environment.yml
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.10"
+  commands:
+    - pip3 install -r ./docs/requirements.txt
+    - cd docs && python3 -m sphinx.cmd.build -M html "source" "_build"
+    - mv docs/_build _readthedocs
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,4 +1,4 @@
-# How to Contribute
+# Contributing Code
 We'd love to accept your patches and contributions to this project. There are just a few small guidelines you need to follow.
 
 ## Branching
@@ -18,7 +18,7 @@ Please do not write new shell scripts, no matter how trivial.
 ### Python
 Python code should run on Python 3.6+.
 
-You will need to ensure that your Python code passes linting with the tools and plugins in [`requirements_lint.txt`](./requirements_lint.txt). The commands are simply `black .` and `flake8 .`. Please fix all warnings.
+You will need to ensure that your Python code passes linting with the tools and plugins in [`requirements_lint.txt`](https://github.com/The-OpenROAD-Project/OpenLane/tree/master/requirements_lint.txt). The commands are simply `black .` and `flake8 .`. Please fix all warnings.
 
 For new code, please follow [PEP-8 naming conventions](https://peps.python.org/pep-0008/#naming-conventions). The linters do not enforce them just yet because of the corpus of existing code that does not do that, but they will in the future.
 

diff --git a/README.md b/README.md
diff --git a/docker/README.md b/docker/README.md
@@ -1,6 +1,4 @@
-# For developers: Building the Docker Image
-Note: You probably shouldn't be here.
-
+# Building and Customizing the Docker Image
 ## Structure
 
 There are two "families" of images: one is for building tools, and the other is for running tools.
@@ -61,7 +59,7 @@ OpenLane scripts depend upon a variety of different shell environment variables
 ```
 
 ## Running as root
-* For security reasons, we don't recommend the default root Docker installation. See https://docs.docker.com/engine/security/rootless/ for a safer Docker installation also supported by OpenLane.
+* For security reasons, we don't recommend the default root Docker installation on GNU/Linux. See https://docs.docker.com/engine/security/rootless/ for a safer Docker installation also supported by OpenLane.
 
 By default `make mount` logs into the image with the user ID that is currently active. If you are running as an unprivileged user, you can use `make mount` to log in as root to the Docker image, but you will need to use `sudo` to do this. But, if you are depending on shell environment variables that you may have set during the current session they will be dropped by the `sudo` command. One way to pass those on to the sudo shell is to use the `-E` option. The following shows how you can do that:
 

diff --git a/docker/klayout/Dockerfile b/docker/klayout/Dockerfile
@@ -1,5 +1,3 @@
-# This file is unused. Building Klayout simply takes too damn long.
-
 # Copyright 2020-2021 Efabless Corporation
 #
 # Licensed under the Apache License, Version 2.0 (the "License");

diff --git a/docs/Makefile b/docs/Makefile
@@ -22,7 +22,7 @@ export SHELL=/bin/bash
 # from the environment for the first two.
 SPHINXOPTS    ?=
 SPHINXBUILD   ?= source ../venv/bin/activate && sphinx-build
-SOURCEDIR     = ..
+SOURCEDIR     = source
 BUILDDIR      = _build
 
 # Put it first so that "make" without argument is like "make help".
@@ -37,4 +37,4 @@ install:
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
-	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/docs/_static/openlane.flow.1.png → docs/_static/flow_v1.png b/docs/_static/openlane.flow.1.png → docs/_static/flow_v1.png
diff --git a/.github/diagrams/flow.png → docs/_static/gha.png b/.github/diagrams/flow.png → docs/_static/gha.png
diff --git a/.github/diagrams/src/actor.png → docs/_static/src/actor.png b/.github/diagrams/src/actor.png → docs/_static/src/actor.png
diff --git a/.github/diagrams/src/flow.dot → docs/_static/src/flow.dot b/.github/diagrams/src/flow.dot → docs/_static/src/flow.dot
diff --git a/docs/environment.yml b/docs/environment.yml
diff --git a/docs/source/additional_material.md b/docs/source/additional_material.md
@@ -0,0 +1,34 @@
+# Additional Material
+There are some cool tutorials and guides on using OpenLane to harden chips. Though do note, guides, especially video tutorials and webinars, tend to become out of date.
+
+Additionally, we're also going to link to academic publications about OpenLane if you're interested in reading and/or citing it.
+
+## Text Guides
+### Official
+- [OpenLane ReadTheDocs](https://openlane.readthedocs.io/)
+    - You're probably already here, though! Hi.
+- [Quick-Start Guide, Caravel User Project ReadTheDocs](https://caravel-harness.readthedocs.io/en/latest/getting-started.html#quick-start-for-user-projects)
+    - If you're looking to submit a project for an OpenMPW or ChipIgnite shuttle, start here.
+- [Digital inverter with OpenLane and Colab, Build Custom Silicon with Google](https://developers.google.com/silicon/guides/digital-inverter-openlane)
+    - This is a very simple introduction using Google Colab- you don't even need to install anything!
+
+### Community
+- [Introduction to OpenMPW, VLSI.jp](https://vlsi.jp/Introduction_to_OpenMPW.html#introduction-to-openmpw)
+- [OpenMPW入門 改訂版, VLSI.jp](https://vlsi.jp/OpenMPW.html)
+
+## Videos
+- [Aboard Caravel, Ahmed Ghazy](https://www.youtube.com/watch?v=9QV8SDelURk)
+- [FOSSi Dial-Up - Skywater PDK: Fully open source manufacturable PDK for a 130nm process, Tim Ansell](https://www.youtube.com/watch?v=EczW2IWdnOM&)
+- [FOSSi Dial-Up - OpenLane, A Digital ASIC Flow for SkyWater 130nm Open PDK, Mohamed Shalan](https://www.youtube.com/watch?v=Vhyv0eq_mLU)
+- [OpenLane Overview, Ahmed Ghazy](https://www.youtube.com/watch?v=d0hPdkYg5QI)
+- [Free VLSI Tutorial - VSD - A complete guide to install OpenLane and Sky130nm PDK](https://www.udemy.com/course/vsd-a-complete-guide-to-install-openlane-and-sky130nm-pdk)
+- [Sky130 - Exploring OpenLane and OpenDB to create a register file, Sylvain Munaut](https://www.youtube.com/watch?v=AT_LcmaCZmw)
+- [Skywater 130nm PDK - Initial Discovery, Sylvain Munaut](https://www.youtube.com/watch?v=gRYBdTXbxiU)
+- [VLSI SoC EDA OpenLane with Skywater 130 PDK, Gary Huang](https://www.youtube.com/watch?v=QnJzoJjC7RQ)
+
+## Publications
+This is a list of publications about OpenLane, sorted from newest to oldest.
+
+- 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)
+- 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/)
+- 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)
diff --git a/docs/source/authors.md b/docs/source/authors.md
@@ -0,0 +1 @@
+../../AUTHORS.md
diff --git a/conf.py → docs/source/conf.py b/conf.py → docs/source/conf.py
@@ -22,12 +22,14 @@
 import os
 import sys
 
-sys.path.insert(0, os.path.abspath("docs/_ext"))
+sys.path.insert(0, os.path.abspath("../_ext"))
 
 # -- Project information -----------------------------------------------------
 project = "OpenLane"
-copyright = "2020-2022 Efabless Corporation"
+copyright = "2020-2022 Efabless Corporation and contributors"
 author = "Efabless Corporation"
+repo = "https://github.com/The-OpenROAD-Project/OpenLane"
+branch = "master"
 
 
 # -- General configuration ---------------------------------------------------
@@ -61,6 +63,7 @@
     "Thumbs.db",
     "scripts/tcl_commands/README.md",
     "venv",
+    "install",
     "pdks",
     ".github",
     # Files included in other rst files.
@@ -79,18 +82,34 @@
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
-html_theme_options = {}
+html_theme_options = {
+    "source_repository": repo,
+    "source_branch": branch,
+    "source_directory": "docs/source",
+    "footer_icons": [
+        {
+            "name": "GitHub",
+            "url": repo,
+            "html": """
+                <svg stroke="currentColor" fill="currentColor" stroke-width="0" viewBox="0 0 16 16">
+                    <path fill-rule="evenodd" d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0 0 16 8c0-4.42-3.58-8-8-8z"></path>
+                </svg>
+            """,
+            "class": "",
+        },
+    ],
+}
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ["docs/_static"]
+html_static_path = ["../_static"]
 
 todo_include_todos = True
 numfig = True
 
-markdown_code_links_githubrepo = "https://github.com/The-OpenROAD-Project/OpenLane"
-markdown_code_links_githubbranch = "blob/master"
+markdown_code_links_githubrepo = repo
+markdown_code_links_githubbranch = f"blob/{branch}"
 markdown_code_links_codefileextensions = [
     ".tcl",
     ".sh",
@@ -108,4 +127,9 @@
 myst_heading_anchors = 3
 
 
+myst_enable_extensions = [
+    "colon_fence",
+]
+
+
 root_doc = "index"
diff --git a/docs/source/flow_overview.md b/docs/source/flow_overview.md
@@ -0,0 +1,118 @@
+# OpenLane Architecture
+
+![A diagram showing the general stages of the OpenLane flow as a series of blocks](../_static/flow_v1.png)
+
+
+## OpenLane Design Stages
+
+OpenLane flow consists of several stages. By default all flow steps are run in sequence. Each stage may consist of multiple sub-stages. OpenLane can also be run interactively as shown [here][25].
+
+1. **Synthesis**
+    1. `yosys/abc` - Perform RTL synthesis and technology mapping.
+    2. `OpenSTA` - Performs static timing analysis on the resulting netlist to generate timing reports
+2. **Floorplaning**
+    1. `init_fp` - Defines the core area for the macro as well as the rows (used for placement) and the tracks (used for routing)
+    2. `ioplacer` - Places the macro input and output ports
+    3. `pdngen` - Generates the power distribution network
+    4. `tapcell` - Inserts welltap and decap cells in the floorplan
+3. **Placement**
+    1. `RePLace` - Performs global placement
+    2. `Resizer` - Performs optional optimizations on the design
+    3. `OpenDP` - Perfroms detailed placement to legalize the globally placed components
+4. **CTS**
+    1. `TritonCTS` - Synthesizes the clock distribution network (the clock tree)
+5. **Routing**
+    1. `FastRoute` - Performs global routing to generate a guide file for the detailed router
+    2. `TritonRoute` - Performs detailed routing
+    3. `OpenRCX` - Performs SPEF extraction
+6. **Tapeout**
+    1. `Magic` - Streams out the final GDSII layout file from the routed def
+    2. `KLayout` - Streams out the final GDSII layout file from the routed def as a back-up
+7. **Signoff**
+    1. `Magic` - Performs DRC Checks & Antenna Checks
+    2. `KLayout` - Performs DRC Checks
+    3. `Netgen` - Performs LVS Checks
+    4. `CVC` - Performs Circuit Validity Checks
+
+OpenLane integrated several key open source tools over the execution stages:
+- RTL Synthesis, Technology Mapping, and Formal Verification : [yosys + abc][4]
+- Static Timing Analysis: [OpenSTA][8]
+- Floor Planning: [init_fp][5], [ioPlacer][6], [pdn][16] and [tapcell][7]
+- Placement: [RePLace][9] (Global), [Resizer][15] and [OpenPhySyn][28] (formerly), and [OpenDP][10] (Detailed)
+- Clock Tree Synthesis: [TritonCTS][11]
+- Fill Insertion: [OpenDP/filler_placement][10]
+- Routing: [FastRoute][12] or [CU-GR][36] (formerly) and [TritonRoute][13] (Detailed) or [DR-CU][36]
+- SPEF Extraction: [OpenRCX][37] or [SPEF-Extractor][27] (formerly)
+- GDSII Streaming out: [Magic][14] and [KLayout][35]
+- DRC Checks: [Magic][14] and [KLayout][35]
+- LVS check: [Netgen][22]
+- Antenna Checks: [Magic][14]
+- Circuit Validity Checker: [CVC][31]
+
+> Everything in Floorplanning through Routing is done using [OpenROAD](https://github.com/The-OpenROAD-Project/OpenROAD) and its various sub-utilities.
+
+## OpenLane Output
+
+All output run data is placed by default under ./designs/design_name/runs. Each flow cycle will output a timestamp-marked folder containing the following file structure:
+
+```
+<design_name>
+├── config.json/config.tcl
+├── runs
+│   ├── <tag>
+│   │   ├── config.tcl
+│   │   ├── {logs, reports, tmp}
+│   │   │   ├── cts
+│   │   │   ├── signoff
+│   │   │   ├── floorplan
+│   │   │   ├── placement
+│   │   │   ├── routing
+│   │   │   └── synthesis
+│   │   ├── results
+│   │   │   ├── final
+│   │   │   ├── cts
+│   │   │   ├── signoff
+│   │   │   ├── floorplan
+│   │   │   ├── placement
+│   │   │   ├── routing
+│   │   │   └── synthesis
+```
+
+To delete all generated runs under all designs:
+`make clean_runs`
+
+[1]: ../for_developers/docker.md
+[4]: https://github.com/YosysHQ/yosys
+[5]: https://github.com/The-OpenROAD-Project/OpenROAD/tree/master/src/ifp
+[6]: https://github.com/The-OpenROAD-Project/OpenROAD/tree/master/src/ppl
+[7]: https://github.com/The-OpenROAD-Project/OpenROAD/tree/master/src/tap
+[8]: https://github.com/The-OpenROAD-Project/OpenSTA
+[9]: https://github.com/The-OpenROAD-Project/OpenROAD/tree/master/src/replace
+[10]: https://github.com/The-OpenROAD-Project/OpenROAD/tree/master/src/dpl
+[11]: https://github.com/The-OpenROAD-Project/OpenROAD/tree/master/src/cts
+[12]: https://github.com/The-OpenROAD-Project/OpenROAD/tree/master/src/grt
+[13]: https://github.com/The-OpenROAD-Project/OpenROAD/tree/master/src/TritonRoute
+[14]: https://github.com/RTimothyEdwards/magic
+[15]: https://github.com/The-OpenROAD-Project/OpenROAD/tree/master/src/rsz
+[16]: https://github.com/The-OpenROAD-Project/OpenROAD/tree/master/src/pdn
+[18]: https://github.com/RTimothyEdwards/qflow/blob/master/src/addspacers.c
+[19]: https://github.com/The-OpenROAD-Project/
+[20]: https://github.com/git-lfs/git-lfs/wiki/Installation
+[21]: /usage/exploration_script.md
+[22]: https://github.com/RTimothyEdwards/netgen
+[24]: ./for_developers/pdk_structure.md
+[25]: ./reference/interactive_mode.md
+[26]: ./usage/chip_integration.md
+[27]: https://github.com/AUCOHL/spef-extractor
+[28]: https://github.com/scale-lab/OpenPhySyn
+[29]: ./usage/hardening_macros.md
+[30]: ./usage/building_the_pdk.md
+[31]: https://github.com/d-m-bailey/cvc
+[32]: ./for_developers/code_contribution.md
+[33]: ./authors.md
+[34]: ./reference/openlane_commands.md
+[35]: https://github.com/KLayout/klayout
+[36]: https://github.com/cuhk-eda/cu-gr
+[37]: https://github.com/The-OpenROAD-Project/OpenROAD/tree/master/src/rcx
+[38]: ./for_developers/issue_regression_tests.md
+[39]: https://github.com/cuhk-eda/dr-cu
diff --git a/docs/source/for_developers/code_contribution.md b/docs/source/for_developers/code_contribution.md
@@ -0,0 +1 @@
+../../../CONTRIBUTING.md
diff --git a/docs/source/for_developers/docker.md b/docs/source/for_developers/docker.md
@@ -0,0 +1 @@
+../../../docker/README.md