[Docs] ORFS doc review (The-OpenROAD-Project#1490)

* add or to orfs support matrix Signed-off-by: Song Luar <[email protected]> Co-authored-by: Vitor Bandeira <[email protected]>
antmicro · Jul 12, 2024 · 788947f · 788947f
1 parent 96dd589
commit 788947f
Show file tree

Hide file tree

Showing 7 changed files with 73 additions and 44 deletions.
diff --git a/.gitignore b/.gitignore
@@ -88,6 +88,8 @@ perf.data.old
 docs/main
 docs/build
 GitGuide.md
+SupportedOS.md
+index2.md
 Manpage.md
 mainREADME.md
 build

diff --git a/docs/conf.py b/docs/conf.py
@@ -63,7 +63,7 @@
 source_suffix = ['.md']
 
 # The master toctree document.
-master_doc = 'index'
+master_doc = 'index2.md'
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
@@ -77,6 +77,7 @@
     'README.md',
     'docs/releases/PostAlpha2.1BranchMethodology.md',
     'main',
+    'index.md'
 ]
 
 # The name of the Pygments (syntax highlighting) style to use.
@@ -151,20 +152,55 @@ def setup(app):
     shutil.copy('../README.md', 'mainREADME.md')
     swap_prefix('mainREADME.md', '```mermaid', '```{mermaid}\n:align: center\n')   
 
-    # Get GitGuide file
+    # Grab the reference file from OR
     url = 'https://raw.githubusercontent.com/The-OpenROAD-Project/OpenROAD/master/docs/contrib/GitGuide.md'
     get_file_from_url(url, 'contrib/GitGuide.md') 
+
+    # Temporarily using commit number, will change once OR commit merged.
+    url = 'https://raw.githubusercontent.com/The-OpenROAD-Project/OpenROAD/3563176d00daeb613eed2ccf9442137b0ae2cad3/docs/index.md'
+    get_file_from_url(url, 'SupportedOS.md')
 
     # edit OpenROAD to OpenROAD-flow-scripts for GitGuide
     with open('contrib/GitGuide.md', 'r') as f:
         content = f.read()
-
     content = content.replace('user/Build.md', '../index.md#build-or-installing-orfs-dependencies')
     content = content.replace('OpenROAD', 'OpenROAD-flow-scripts')
     content = content.replace('The-OpenROAD-flow-scripts', 'The-OpenROAD')
     with open('contrib/GitGuide.md', 'w') as f:
         f.write(content)
 
+    # Create a copy of the index.md file
+    import shutil
+    shutil.copy('index.md', 'index2.md')
+
+    # Use re to find the desired content 
+    start_pattern = '## Supported Operating Systems'
+    end_pattern = '## Code of conduct'
+    with open('SupportedOS.md', 'r') as f:
+        markdown_content = f.read()
+
+    match = re.search(f'{start_pattern}(.*?){end_pattern}', markdown_content, re.DOTALL)
+
+    assert match is not None, 'No match found, check the OR Doc pattern on index.md'
+    extracted_content = match.group(1)
+    extracted_content = "\n#### Supported Operating Systems" + extracted_content
+    print(extracted_content)
+
+    # Find insert position
+    with open('index2.md', 'r') as f:
+        existing_content = f.read()
+    match = re.search(r'### Setup', existing_content)
+    assert match is not None, 'Check search keyword.'
+    with open('index2.md', 'w') as f:
+        insert_position = match.end() + 1
+        before_insert = existing_content[:insert_position]
+        after_insert = existing_content[insert_position:]
+
+        # Combine the parts with the extracted content
+        updated_content = before_insert + extracted_content + after_insert
+
+        f.write(updated_content)
+
     # Get Manpage file
     url = 'https://raw.githubusercontent.com/The-OpenROAD-Project/OpenROAD/master/src/utl/README.md'
     get_file_from_url(url, 'Manpage.md')
diff --git a/docs/index.md b/docs/index.md
@@ -3,7 +3,7 @@
 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
+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
@@ -46,33 +46,6 @@ See these [tips](user/FAQS.md#how-do-i-get-better-search-results) to help improv
 
 ### Setup
 
-#### Supported Operating Systems
-
-Note that depending on the installation method, we have varying levels of 
-support for various operating systems. 
-
-Legend:
-- `Y` for supported.
-- `-` for unsupported.
-
-| Operating System | Local Installation | Prebuilt Binaries | Docker Installation | Windows Subsystem for Linux | 
-| --- | --- | --- | --- | --- |
-| Ubuntu 20.04 | `Y` | `Y` | `Y` | `-` |  
-| Ubuntu 22.04 | `Y` | `Y` | `Y` | `-` |
-| CentOS 7     | `Y` | `-` | `Y` | `-` |
-| CentOS 8     | `Y` | `-` | `Y` | `-` |
-| Debian 10    | `Y` | `Y` | `Y` | `-` |
-| Debian 11    | `Y` | `Y` | `Y` | `-` |
-| RHEL         | `Y` | `-` | `Y` | `-` |
-| Windows 10 and above | `-` | `-` | `Y` | `Y` |
-| macOS        | `Y*` | `-` | `Y` | `-` |
-
-```{warning}
-For macOS, local compilation for the modules `par` and `mpl2` are not
-fully supported due to an upstream issue with `or-tools`. We recommend
-Docker installation wherever possible.
-```
-
 #### System Requirements
 
 To build the binaries and run `gcd` through the flow:
@@ -94,7 +67,7 @@ We support four major ways of installation:
 - [Windows Subsystem for Linux (WSL)](./user/BuildWithWSL.md)
 - [Local Installation](./user/BuildLocally.md)
 
-You may also choose use the build script to customise your build process.
+You may also choose and use the build script to customise your build process.
 See more in the next section.
 
 ##### Build Command and options
@@ -178,15 +151,19 @@ OpenROAD-flow-scripts supports Verilog to GDS for the following open platforms:
 - ASAP7
 - Nangate45 / FreePDK45
 - SKY130
+- GF180
 
 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 proprietary platforms:
 
+- GF55
 - GF12
-- TSMC65LP
+- Intel22
+- Intel16
+- TSMC65
 
 The PDKs and platform-specific files for these kits cannot be provided
 due to NDA restrictions. However, if you are able to access these

diff --git a/docs/toc.yml b/docs/toc.yml
@@ -1,16 +1,16 @@
-root: index
+root: index2
 entries:
 
 - file: user/UserGuide.md
   title: User Guide
   entries:
+  - file: user/BuildWithPrebuilt.md
+    title: Build Using Pre-built Binaries
   - file: user/BuildWithDocker
     title: Build Using Docker
     entries:
     - file: user/DockerShell.md
       title: Docker Shell utility
-  - file: user/BuildWithPrebuilt.md
-    title: Build Using Pre-built Binaries
   - file: user/BuildLocally.md
     title: Build Locally
   - file: user/BuildWithWSL.md

diff --git a/docs/user/BuildWithDocker.md b/docs/user/BuildWithDocker.md
@@ -30,10 +30,10 @@ and Debian on a regular basis.
 This greatly helps to reduce the compilation time needed.
 
 We recommend to use a Docker image of a supported OS
-and install OpenROAD using the prebuilt binaries from
-Precision Innovations.
-You can start the container in an interactive mode using
-the command below.
+and install OpenROAD using the pre-built binaries from
+Precision Innovations. 
+You can start the container in an interactive mode using 
+the command below. 
 
 ```shell
 docker run -it ubuntu:22.04

diff --git a/docs/user/BuildWithPrebuilt.md b/docs/user/BuildWithPrebuilt.md
@@ -12,8 +12,8 @@ Instructions for installing:
 
 ## Install OpenROAD
 Download pre-built binaries with self-contained dependencies
-included from the Precision Innovations' Github releases
-[here](https://github.com/Precision-Innovations/OpenROAD/actions/workflows/github-actions-build-deb-package.yml).
+included from the Precision Innovations' GitHub releases
+[here](https://github.com/Precision-Innovations/OpenROAD/releases).
 
 Thanks to [Precision Innovations](https://precisioninno.com/) for hosting and maintaining these binaries.
 
@@ -34,7 +34,15 @@ Step 3: Run the install command based on platform use package installer.
 sudo apt install ./openroad_2.0_amd64-ubuntu20.04.deb
 ```
 
-You can install these binaries within docker as well.
+## Install Klayout and Yosys
+Please ensure the Klayout version (denoted with `klayoutVersion` variable) is consistent with the one used in [DependencyInstaller script](https://github.com/The-OpenROAD-Project/OpenROAD-flow-scripts/blob/master/etc/DependencyInstaller.sh). 
+
+Instructions for installing:
+- [Klayout>=0.28.8](https://www.klayout.de/build.html)
+- [Yosys>=0.39](https://github.com/YosysHQ/oss-cad-suite-build/blob/master/README.md#installation)
+
+```{tip} Unfortunately KLayout maintainers do not provide Debian 10/11 compatible packages. You can follow the build-from-sources instruction (Version >=0.25) and Ubuntu 22 instructions [here](https://www.klayout.de/build.html#:~:text=Building%20KLayout%20on%20Linux%20(Version%20%3E%3D%200.25)). 
+```
 
 
 ## Verify Installation

diff --git a/docs/user/InstructionsForAutoTuner.md b/docs/user/InstructionsForAutoTuner.md
@@ -145,6 +145,12 @@ python3 distributed.py --design gcd --platform sky130hd \
                        sweep
 ```
 
+
+### Google Cloud Platform (GCP) distribution with Ray
+
+GCP Setup Tutorial coming soon.
+
+
 ### List of input arguments
 | Argument                      | Description                                                                                           |
 |-------------------------------|-------------------------------------------------------------------------------------------------------|
@@ -173,7 +179,7 @@ python3 distributed.py --design gcd --platform sky130hd \
 | `--openroad_threads`          | Max number of threads usable.                                                                         |
 | `--server`                    | The address of Ray server to connect.                                                                 |
 | `--port`                      | The port of Ray server to connect.                                                                    |
-| `-v` or `--verbose`           | Verbosity Level. [0: Only ray status, 1: print stderr, 2: also print training stdout.                  |
+| `-v` or `--verbose`           | Verbosity Level. [0: Only ray status, 1: print stderr, 2: print stdout on top of what is in level 0 and 1. ]                  |
 |                               |                                                                                                       |
 ### GUI