diff --git a/.github/workflows/Readme.md b/.github/workflows/Readme.md new file mode 100644 index 000000000..3c479e0b8 --- /dev/null +++ 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. \ No newline at end of file diff --git a/.readthedocs.yml b/.readthedocs.yml index c2976e98a..ceb4b1828 100644 --- 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 index e46632588..dd7afc986 100644 --- 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 index f27cfbb7d..31b21cfcb 100644 --- a/README.md +++ b/README.md @@ -1,390 +1,64 @@ -# OpenLane -[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) [![Documentation Status](https://readthedocs.org/projects/openlane/badge/?version=latest)](https://openlane.readthedocs.io/) [![CI](https://github.com/The-OpenROAD-Project/OpenLane/workflows/CI/badge.svg?branch=master)](#) [![Slack Invite](https://img.shields.io/badge/Community-Skywater%20PDK%20Slack-ff69b4?logo=slack)](https://invite.skywater.tools) [![Python code style: black](https://img.shields.io/badge/python%20code%20style-black-000000.svg)](https://github.com/psf/black) +

OpenLane

+

+ Open in Colab + License: Apache 2.0 + GitHub Actions Status Badge + Documentation Build Status Badge + Invite to the Open Source Silicon Slack + Python Code Style: black +

-OpenLane is an automated RTL to GDSII flow based on several components including OpenROAD, Yosys, Magic, Netgen, CVC, SPEF-Extractor, CU-GR, Klayout and a number of custom scripts for design exploration and optimization. The flow performs full ASIC implementation steps from RTL all the way down to GDSII. +OpenLane is an automated RTL to GDSII flow based on several components including OpenROAD, Yosys, Magic, Netgen, CVC, SPEF-Extractor, KLayout and a number of custom scripts for design exploration and optimization. The flow performs all ASIC implementation steps from RTL all the way down to GDSII. -You can find the latest release of OpenLane [here](https://github.com/The-OpenROAD-Project/OpenLane/releases). +You can check out the documentation, including in-depth guides and reference manuals at [ReadTheDocs](https://openlane.readthedocs.io/). -This documentation is also available at [ReadTheDocs](https://openlane.readthedocs.io/). +## Quick-start Guide +If you just want to try OpenLane out, try [this Colaboratory](https://colab.research.google.com/github/chipsalliance/silicon-notebooks/blob/main/digital-inverter-openlane.ipynb) by our friends at Google and ChipsAlliance. It's an online Python-based utility, and the best part is, *you don't need to install anything.* -# Table Of Contents -- [Prerequisites](#prerequisites) -- [Setting up OpenLane](#setting-up-openlane) - - [Updating OpenLane](#updating-openlane) -- [Running OpenLane](#running-openlane) - - [Command line arguments](#command-line-arguments) - - [Adding a design](#adding-a-design) -- [OpenLane Architecture](#openlane-architecture) - - [OpenLane Design Stages](#openlane-design-stages) - - [OpenLane Output](#openlane-output) - - [Flow configuration](#flow-configuration) -- [Regression And Design Configurations Exploration](#regression-and-design-configurations-exploration) -- [Hardening Macros](#hardening-macros) -- [Chip Integration](#chip-integration) -- [Commands and Configurations](#commands-and-configurations) -- [How To Contribute](#how-to-contribute) -- [Authors](#authors) -- [Additional Material](#additional-material) - - [Papers](#papers) - - [Videos And Tutorials](#videos-and-tutorials) +## Installation, the short version +The short version is, to install the OpenLane environment... -# Prerequisites -At a minimum: +> On Windows, install and launch the [Windows Subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/install) before doing anything. We recommend and provide instructions for Ubuntu 20.04. -- GNU Make -- Python 3.6+ with pip and virtualenv -- Git 2.22+ -- Docker 19.03.12+ +> On macOS, [get brew](https://brew.sh) +. +1. [Get Docker](https://docs.docker.com/get-docker/) (or a compatible container engine) +2. Get Python 3.6 or higher ([macOS](https://formulae.brew.sh/formula/python3) | [Ubuntu](https://packages.ubuntu.com/focal/python3)) + * On Ubuntu, you may also need to install venv: `apt-get install python3-venv`, and pip: `apt-get install python3-pip`. +3. Get git ([macOS](https://formulae.brew.sh/formula/git) | [Ubuntu](https://packages.ubuntu.com/focal/git)) +4. Get GNU Make ([macOS](https://formulae.brew.sh/formula/make) | [Ubuntu](https://packages.ubuntu.com/focal/make)) -## On Ubuntu, that's... -`apt install -y build-essential python3 python3-venv python3-pip` -* [Docker Installation Instructions](https://docs.docker.com/engine/install/ubuntu/) +Run the following commands in your command-line prompt: -## On macOS, that's... -Get [Homebrew](https://brew.sh/), then: - -`brew install python make` -`brew install --cask docker` - -## Containerless/Local Installations -Please see [here](./docs/source/local_installs.md). - -# Setting Up OpenLane -You can set up the Sky130 PDK and OpenLane by running: - -```bash - git clone https://github.com/The-OpenROAD-Project/OpenLane.git - cd OpenLane/ - make - make test # This a ~5 minute test that verifies that the flow and the pdk were properly installed -``` - -- The Makefile should do the following when you run the above: - - Pulls the OpenLane Docker image. - - Pulls and updates the PDK - - Test the whole setup with a complete run on a small design, `spm`. - -This should produce a clean run for the spm. The final layout will be generated at this path: `./designs/spm/runs/openlane_test/results/magic/spm.gds`. - -If everything is okay, you can skip forward to [running OpenLane](#running-openlane). - -## Updating OpenLane - -If you already have the repo locally, then there is no need to re-clone it. You can run the following: - -```bash - cd OpenLane/ - git checkout master - git pull - make - make test # This is to test that the flow and the pdk were properly updated -``` - -## Building the PDK Manually -If you need other libraries, however, you will have to build the PDK manually. - -## Building the PDK Manually -The pre-built version of the PDK automatically installed as part of the previous steps includes a limited set of standard cell libraries that are appropriate for most users. - -If you need other libraries, however, you will have to build the PDK manually. See [this document][30] for more information. - - -# Running OpenLane -You need to start the Docker container with proper paths mounted. There are two ways to do this. - -The easiest way to mount the proper directories into the docker container would be to rely on the Makefile: - -```bash - make mount +```sh +cd $HOME +git clone https://github.com/The-OpenROAD-Project/OpenLane +cd OpenLane +make +make test ``` -* **Note:** - - Default PDK_ROOT is `$(pwd)/pdks`. If you have installed the PDK at a different location, run the following before `make mount`: - ```bash - export PDK_ROOT= - ``` - - Default OPENLANE_IMAGE_NAME is dynamically obtained using your current git version. If you want to use a specific image, run the following before `make mount`: - ```bash - export OPENLANE_IMAGE_NAME= - ``` - -The following is roughly what happens under the hood when you run `make mount` + the required exports: +If everything's gone smoothly, that's it. OpenLane is set up on your computer. To enter the OpenLane environment, `cd $HOME/OpenLane` and then `make mount`. -```bash - export PDK_ROOT= - export OPENLANE_IMAGE_NAME= - docker run -it -v $(pwd):/openlane -v $PDK_ROOT:$PDK_ROOT -e PDK_ROOT=$PDK_ROOT -u $(id -u $USER):$(id -g $USER) $OPENLANE_IMAGE_NAME -``` - -**Note: this will mount the OpenLane directory and the PDK_ROOT directory inside the container.** +## Installation, the long version +See the installation docs at https://openlane.readthedocs.io/en/latest/docs/source/installation.html. -You can use the following example as a smoke test: +## Usage +After entering the OpenLane environment, you can start hardening chips: the following command, for example, runs the included [spm design](./designs/spm). -```bash +```sh ./flow.tcl -design spm ``` -To run OpenLane on multiple designs at the same time, check this [section](#regression-and-design-configurations-exploration). - -## Command line arguments - -The following are arguments that can be passed to `flow.tcl` - -| Argument | Description | -| - | - | -| `-design `
(Optional) | Specifies the design folder. A design folder should contain a `config.json` or `config.tcl` file defining the design parameters.
If the folder is not found, ./designs directory is searched, and if this parameter is omitted, the current working directory is treated as the design. | -| `-from `
(Optional) | Specifies stage to start flow execution from | -| `-to `
(Optional) | Specifies stage to stop flow execution at (included) | -| `-config_file `
(Optional) | Specifies the design's configuration file for running the flow.
For example, to run the flow using `./designs/spm/config2.tcl`
Use run `./flow.tcl -design ./designs/spm -config_file ./designs/spm/config2.tcl`
By default `config.tcl` is used, and if not found, `config.json` is used instead. | -| `-override_env`
Optional | Allows you to override certain configuration environment variables for this run. Format: `KEY1=VALUE1,KEY2=VALUE2` | -| `-tag `
(Optional) | Specifies a "name" for a specific run. If the tag is not specified, a timestamp is generated for identification of that run. | -| `-run_path `
(Optional) | Specifies a `path` to save the run in. By default the run is in `design_path/`, where the design path is the one passed to `-design` | -| `-src `
(Optional) | Sets the verilog source code file(s) in case of using `-init\_design\_config`.
The default is that the source code files are under `design_path/src/`, where the design path is the one passed to `-design` | -| `-init_design_config`
(Optional) | Creates a configuration file for a design. The config file is by default `openlane/config.json`, but can be overriden using the value from `-config_file`. | -| `-add_to_designs`
(Optional) | Adds the design to the OpenLane folder instead of creating an `openlane` folder. This is the default behavior on earlier versions of OpenLane. | -| `-overwrite`
(Optional) | Flag to overwrite an existing run with the same tag | -| `-interactive`
(Optional) | Flag to run openlane flow in interactive mode | -| `-file `
(Optional) | Passes a script of interactive commands in interactive mode | -| `-synth_explore`
(Boolean) | If enabled, synthesis exploration will be run (only synthesis exploration), which will try out the available synthesis strategies against the input design. The output will be the four possible gate level netlists under <run_path/results/synthesis> and a summary report under reports that compares the 4 outputs. | -| `-lvs`
(Boolean) | If enabled, only LVS will be run on the design. in which case the user must also pass: -design DESIGN\_DIR -gds DESIGN\_GDS -net DESIGN_NETLIST. | -| `-drc`
(Boolean) | If enabled, only DRC will be run on the design. in which case the user must also pass: -design DESIGN\_DIR -gds DESIGN\_GDS -report OUTPUT\_REPORT\_PATH -magicrc MAGICRC. | -| `-save`
(Optional) | A flag to save a runs results like .mag and .lef in the design's folder. | -| `-save_path `
(Optional) | Specifies a different path to save the design's result. This option is to be used with the `-save` flag. | -| `-verbose `
(Optional) | Specifies a level of verbosity. 0, the default, only outputs high-level messages. 1 also outputs some of the inner workings of the flow scripts. 2 or higher forwards outputs from _all_ tools to your terminal. | -| `-test_mismatches `
(Optional) | Test for mismatches between the OpenLane tool versions and the current environment. `all`, the default, tests all mismatches. `tools` tests all except the PDK. `pdk` only tests the PDK. `none` disables the check.
(Default: `all`) | -| `-ignore_mismatches` | If specified, halts the flow on detected environment mismatches. | - -## Adding a design - -To add a new design, follow the instructions provided [here](./designs/README.md) - -This [file](./designs/README.md) also includes useful information about the design configuration files. It also includes useful utilities for exploring and updating design configurations for each (PDK,STD_CELL_LIBRARY) pair. - -# OpenLane Architecture - - - - - - -
- - -## 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` - Performs RTL synthesis - 2. `abc` - Performs technology mapping - 3. `OpenSTA` - Performs static timing analysis on the resulting netlist to generate timing reports -2. **Floorplan and PDN** - 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. `pdn` - 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. `CU-GR` - Another option for performing global routing. - 3. `TritonRoute` - Performs detailed routing - 4. `SPEF-Extractor` - Performs SPEF extraction -6. **GDSII Generation** - 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. **Checks** - 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] (Global) and [TritonRoute][13] (Detailed) -- SPEF Extraction: [SPEF-Extractor][27] (formerly), [OpenRCX][37] -- 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] - -## 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: - -``` - -├── config.json/config.tcl -├── runs -│ ├── -│ │ ├── 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` - -## Flow configuration - -1. PDK / technology specific -2. Flow specific -3. Design specific - -- A PDK should define at least one standard cell library(SCL) for the PDK. A common configuration file for all SCLs is located in: - - ``` - $PDK_ROOT/$PDK/config.tcl - ``` - - - Sometimes the PDK comes with several standard cell libraries. Each has an own configuration file that defines extra variables specific to the SCL. It may also override variables in the common PDK configuration file which is located in: - - ``` - $PDK_ROOT/$PDK/$STD_CELL_LIBRARY/config.tcl - ``` - - More on configuring a new PDK in this [section](#setting-up-openlane) - -- Flow specific variables are related to the flow and are initialized with default values in: - - ``` - ./configuration/ - ``` - -- Finally, each design should have it's own configuration file with some required variables which are available in this [list][17]. A design configuration file may override any of the variables defined in PDK or flow configuration files. This is the global configurations for the design: - - ``` - ./designs//config.tcl - ``` - - More on design configurations in [here](./designs/README.md) - -A list of all available variables can be found [here][17]. - - - -# Regression And Design Configurations Exploration - -As mentioned earlier, everytime a new design or a new (PDK,STD_CELL_LIBRARY) pair is added, or any update happens in the flow tools, a re-configuration for the designs is needed. The reconfiguration is methodical and so an exploration script was developed to aid the designer in reconfiguring his designs if needed. -As explained [here](#adding-a-design) that each design has multiple configuration files for each (PDK,STD_CELL_LIBRARY) pair. - -OpenLane provides `run_designs.py`, a script that can do multiple runs in a parallel using different configurations. A run consists of a set of designs and a configuration file that contains the configuration values. It is useful to explore the design implementation using different configurations to figure out the best one(s). - -Also, it can be used for testing the flow by running the flow against several designs using their best configurations. For example the following run: spm using its default configuration files: -``` -python3 run_designs.py --tag test --threads 3 spm xtea md5 aes256 -``` - -For more information on how to run this script, refer to this [file][21] - -OpenLane also has flow for issue regression testing. Refer to this [document][38]. - -For more information on design configurations, how to update them, and the need for an exploration for each design, refer to this [file](./designs/README.md) - -# Hardening Macros - -This is discussed in more detail [here][29]. - -# Chip Integration - -The first step of chip integration is hardening the macros. To learn more about this check this [file][29]. - -Using OpenLane, you can produce a GDSII from a chip RTL. This is done by applying a certain methodology that we follow using our custom scripts and the integrated tools. - -To learn more about Chip Integration. Check this [file][26] - -# Commands and Configurations - -To get a full list of the OpenLane commands, first introduce yourself to the interactive mode of OpenLane [here][25]. Then check the full documentation of the OpenLane commands [here][34]. - -The full documentation of OpenLane run configurations could be found [here][2]. - -# How To Contribute - -We discuss the details of how to contribute to OpenLane in [this documentation][32]. - -# Authors - -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) -- 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) - -## Videos and Tutorials -### OpenLane Specific -- [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) -- [VLSI SoC EDA openLANE with Skywater 130 PDK, Gary Huang](https://www.youtube.com/watch?v=QnJzoJjC7RQ) +## Need more help? +You can join the [Open Source Silicon Slack](https://invite.skywater.tools), where you can ask thousands of other open source hardware enthusiasts for help with setting up or running OpenLane. -### Caravel & SkyWater PDK -- [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&) -- [Skywater 130nm PDK - Initial Discovery, Sylvain Munaut](https://www.youtube.com/watch?v=gRYBdTXbxiU) +## License +[The Apache License, version 2.0](https://www.apache.org/licenses/LICENSE-2.0.txt). -[1]: ./docker/README.md -[2]: ./configuration/README.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 -[17]: ./configuration/README.md -[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]: ./regression_results/README.md -[22]: https://github.com/RTimothyEdwards/netgen -[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/building_the_pdk.md -[31]: https://github.com/d-m-bailey/cvc -[32]: ./CONTRIBUTING.md -[33]: ./AUTHORS.md -[34]: ./docs/source/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]: ./docs/source/issue_regression_tests.md +Docker images distributed by Efabless Corporation under the same license. +Binaries in OpenLane distributions may fall under stricter open source licenses. \ No newline at end of file diff --git a/docker/README.md b/docker/README.md index d0a1e5f97..936b577d1 100644 --- 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 index 8eb629439..e4ea97727 100644 --- 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 index 1798e84f5..5c232d85f 100644 --- 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 b/docs/_static/flow_v1.png similarity index 100% rename from docs/_static/openlane.flow.1.png rename to docs/_static/flow_v1.png diff --git a/.github/diagrams/flow.png b/docs/_static/gha.png similarity index 100% rename from .github/diagrams/flow.png rename to docs/_static/gha.png diff --git a/.github/diagrams/src/actor.png b/docs/_static/src/actor.png similarity index 100% rename from .github/diagrams/src/actor.png rename to docs/_static/src/actor.png diff --git a/.github/diagrams/src/flow.dot b/docs/_static/src/flow.dot similarity index 100% rename from .github/diagrams/src/flow.dot rename to docs/_static/src/flow.dot diff --git a/docs/environment.yml b/docs/environment.yml deleted file mode 100644 index b247c1af0..000000000 --- a/docs/environment.yml +++ /dev/null @@ -1,22 +0,0 @@ -# SPDX-FileCopyrightText: 2020 Efabless Corporation -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -# SPDX-License-Identifier: Apache-2.0 - -name: openlane-docs -channels: -- defaults -dependencies: -- python>=3.8 -- pip: - - -r ./requirements.txt diff --git a/docs/source/additional_material.md b/docs/source/additional_material.md new file mode 100644 index 000000000..85918b2fa --- /dev/null +++ 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) \ No newline at end of file diff --git a/docs/source/authors.md b/docs/source/authors.md new file mode 120000 index 000000000..2d2e8405f --- /dev/null +++ b/docs/source/authors.md @@ -0,0 +1 @@ +../../AUTHORS.md \ No newline at end of file diff --git a/conf.py b/docs/source/conf.py similarity index 68% rename from conf.py rename to docs/source/conf.py index 91b21c9ad..85300f22e 100644 --- a/conf.py +++ b/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": """ + + + + """, + "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 new file mode 100644 index 000000000..817a1f091 --- /dev/null +++ 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: + +``` + +├── config.json/config.tcl +├── runs +│ ├── +│ │ ├── 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 \ No newline at end of file diff --git a/docs/source/for_developers/code_contribution.md b/docs/source/for_developers/code_contribution.md new file mode 120000 index 000000000..c97564d93 --- /dev/null +++ b/docs/source/for_developers/code_contribution.md @@ -0,0 +1 @@ +../../../CONTRIBUTING.md \ No newline at end of file diff --git a/docs/source/for_developers/docker.md b/docs/source/for_developers/docker.md new file mode 120000 index 000000000..92a637ce8 --- /dev/null +++ b/docs/source/for_developers/docker.md @@ -0,0 +1 @@ +../../../docker/README.md \ No newline at end of file diff --git a/docs/source/contributing_to_docs.rst b/docs/source/for_developers/docs_contribution.rst similarity index 87% rename from docs/source/contributing_to_docs.rst rename to docs/source/for_developers/docs_contribution.rst index feb77c116..06ea7fa13 100644 --- a/docs/source/contributing_to_docs.rst +++ b/docs/source/for_developers/docs_contribution.rst @@ -1,7 +1,7 @@ -Documentation Contributors guide +Contributing Docs ================================================================================ -.. note:: This page is for documentation contributors. For prospecting OpenLane contributors, please see `CONTRIBUTING.md <../../CONTRIBUTING.html>`_ +.. note:: This page is for documentation contributors. For prospecting code contributors, please see `Code Contributions <../../CONTRIBUTING.html>`_ Introduction -------------------------------------------------------------------------------- @@ -11,9 +11,7 @@ while staying readable, up-to-date and clean. This page covers installation of required tools and outlines simple principles to be followed when writing documentation. -.. note:: To simply fix typos, you do not need to install anything. -Pull requests can be created from the relevant ReadTheDocs page, -using GitHub's editor. +.. note:: To simply fix typos, you do not need to install anything. Pull requests can be created from the relevant ReadTheDocs page, using GitHub's editor. For more complex documentation, it is recommended to follow these steps: @@ -31,8 +29,8 @@ For more complex documentation, it is recommended to follow these steps: 7. Rebuild documentation and repeat. 8. Once satisfied, commit the changes to your repository using git. 9. Create a pull request to the main repository, so the maintainers can review your changes. -13. Maintainers may request some tweaks (or do the tweaks themselves.) Execute them and then push the changes again. -14. Once changes are approved they will be merged and then you can delete your branch or repository. +10. Maintainers may request some tweaks (or do the tweaks themselves.) Execute them and then push the changes again. +11. Once changes are approved they will be merged and then you can delete your branch or repository. .. _building_docs_locally: @@ -88,16 +86,17 @@ If you want to create new category than take a look at the source code of existi Writing Style and Consistency -------------------------------------------------------------------------------- -* New documentation should be written in reStructuredText not Markdown. Take a look at existing RST documentation to get a glimpse of its syntax. +* New documentation should be written in [MyST Markdown](https://myst-parser.readthedocs.io/en/latest/), a flavor of Markdown with some RST extensions. * Use ``of`` instead of ``'``, for example: ``Docker's Installation`` → ``after the installation of Docker``. -* Instead of ``don't`` and ``can't`` use full forms: ``do not`` and ``cannot`` +* Avoid contractions: Substitute ``don't`` and ``can't`` for ``do not`` and ``cannot`` * The first command of the page should have `cd` in it to specify where you are running and all following commands assume the continuation of the session and don't need the cd command. -* In Markdown avoid using same header type both for the title of the document and its content. It looks awful in the table of content. +* Avoid using same header type both for the title of the document and its content. It looks awful in the table of content. + * To that end, only use ``#`` once at the beginning of the document. Terms Consistency ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -In order to improve the readability of the documentation, please use and capitalize trademarks properly. Some examples you can see below: +In order to improve the readability of the documentation, please use and capitalize names and trademarks properly. Some examples you can see below: .. code-block:: @@ -107,7 +106,7 @@ In order to improve the readability of the documentation, please use and capital MAGIC → Magic Skywater130 → sky130 Klayout → KLayout - Pip -> pip or PIP + Pip -> pip * For technical terms, use the following terms preferred by OpenROAD documentation for consistency: @@ -119,8 +118,7 @@ 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. - +.. note:: Also, when documenting micrometer-based variables, use the actual unicode character "μ", not "u", to avoid potential confusion. It's Alt+230 on Windows, Alt+M on macOS and on Linux, press the Compose Key then type ``mu``. Taking screenshots ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -166,15 +164,15 @@ Your ``code-block`` s do not look like they are supposed to How it looks: -.. image:: ../_static/docs_contribution/code_block_issue.png +.. image:: ../../_static/docs_contribution/code_block_issue.png How it is supposed to look: -.. image:: ../_static/docs_contribution/code_block_supposed_look.png +.. image:: ../../_static/docs_contribution/code_block_supposed_look.png This is because ``code-blocks`` need to have empty lines around code sections, like shown in the picture below: -.. image:: ../_static/docs_contribution/code_block_spaces_around_the_code.png +.. image:: ../../_static/docs_contribution/code_block_spaces_around_the_code.png ``pip`` module related errors ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/.github/workflow-documentation.md b/docs/source/for_developers/gha_workflow.md similarity index 95% rename from .github/workflow-documentation.md rename to docs/source/for_developers/gha_workflow.md index f3ab80fbb..e2a00ef01 100644 --- a/.github/workflow-documentation.md +++ b/docs/source/for_developers/gha_workflow.md @@ -1,9 +1,11 @@ -# For developers: CI/CD +# Continuous Integration +OpenLane's CI runs on GitHub Actions. + There are two primary flows: the pull request flow and the deployment flow. The deployment flow occurs on a daily basis. The PR flow happens whenever someone creates a new Pull Request. PRs can be created by contributors or by an automated tool updater that runs on a schedule. -![A Diagram Of The Flow](./diagrams/flow.png) +![A Diagram Of The Flow](../../_static/gha.png) * A maintainer cannot review their own code, but they can merge it after a review by another maintainer. ## Required Secrets diff --git a/docs/source/for_developers.rst b/docs/source/for_developers/index.rst similarity index 54% rename from docs/source/for_developers.rst rename to docs/source/for_developers/index.rst index c33a76317..7adb34fa8 100644 --- a/docs/source/for_developers.rst +++ b/docs/source/for_developers/index.rst @@ -1,14 +1,14 @@ -Contributing to OpenLane +Developer's Guide ################################################################################ .. toctree:: :glob: - ../../CONTRIBUTING - contributing_to_docs + code_contribution + docs_contribution pdk_structure using_or_issue - ../../.github/workflow-documentation.md - ../../docker/README.md + gha_workflow.md + docker.md issue_regression_tests diff --git a/docs/source/issue_regression_tests.md b/docs/source/for_developers/issue_regression_tests.md similarity index 100% rename from docs/source/issue_regression_tests.md rename to docs/source/for_developers/issue_regression_tests.md diff --git a/docs/source/pdk_structure.md b/docs/source/for_developers/pdk_structure.md similarity index 98% rename from docs/source/pdk_structure.md rename to docs/source/for_developers/pdk_structure.md index f397fd5f5..f4dccc100 100644 --- a/docs/source/pdk_structure.md +++ b/docs/source/for_developers/pdk_structure.md @@ -40,7 +40,7 @@ This section defines the neccessary variables for PDK configuration file. Note t | `TECH_LEF` | Points to the path of the tech lef used for nominal corner extraction. | | `TECH_LEF_MAX` | Points to the path of the tech lef used for maximum corner extraction. (Optional) | | `CELLS_LEF` | A list of paths to the cells lef views. Recommended to use wild card to catch all the files as follows: `[glob "$::env(PDK_ROOT)/sky130A/libs.ref/$::env(STD_CELL_LIBRARY)/lef/*.lef"]` | -| `GDS_FILES` | A list of paths to the cells GDS-II views. Recommended to use wild card to catch all the files as follows: `[glob "$::env(PDK_ROOT)/sky130A/libs.ref/$::env(STD_CELL_LIBRARY)/gds/*.gds"]` | +| `GDS_FILES` | A list of paths to the cells GDSII views. Recommended to use wild card to catch all the files as follows: `[glob "$::env(PDK_ROOT)/sky130A/libs.ref/$::env(STD_CELL_LIBRARY)/gds/*.gds"]` | | `MAGIC_TECH_FILE` | Points to the magic tech file which mainly has drc rules. | | `KLAYOUT_TECH` | Points to the klayout tech file (.lyt). | | `KLAYOUT_PROPERTIES` | Points to the klayout properties file (.lyp). | diff --git a/docs/source/using_or_issue.md b/docs/source/for_developers/using_or_issue.md similarity index 90% rename from docs/source/using_or_issue.md rename to docs/source/for_developers/using_or_issue.md index b15914d90..8a8085e4b 100644 --- a/docs/source/using_or_issue.md +++ b/docs/source/for_developers/using_or_issue.md @@ -6,13 +6,13 @@ It creates a folder with all the needed files that you can inspect, then zip or ## Warning about proprietary files When working with a proprietary PDK, also inspect the folder and ensure no proprietary data resulting ends up in there. This is *critical*, if something leaks, this scripts' authors take no responsibility and you are very much on your own. We will try our best to output warnings for your own good if something looks like a part of a proprietary PDK, but the absence of this message does not necessarily indicate that your folder is free of confidential material. -# Usage -## Failures -If you're using OpenLane 2021.12.17 or later (OpenLane 2022.06.21 or later for Magic,) chances, `or_issue.py` will **automatically** be run for you if Magic or OpenROAD exit with a non-zero code. +## Usage +### Failures +If you're using OpenLane 2022.06.21 or later, chances are, `or_issue.py` will **automatically** be run for you if Magic or OpenROAD exit with a non-zero code. -You'll find a message in the log that says something along the lines of: `Reproducible packaged: Please tarball and upload if you're going to submit an issue.` The path will be under the current run_path, i.e., ./designs//runs//issue_reproducible. You can then tarball/zip and upload that file. +You'll find a message in the log that says something along the lines of: `Reproducible packaged: Please tarball and upload if you're going to submit an issue.` The path will be under the current run_path, i.e., `./designs//runs//issue_reproducible`. You can then tarball/zip and upload that file. -## Odd Behavior +### Odd Behavior If the Tcl-based script doesn't fail outright, but simply exhibits weird behavior, starting OpenLane 2022.07.20, you can have the flow simply stop execution and package a reproducible instead. If you know the name of the script causing the issue, you can set the environment variable `CREATE_REPRODUCIBLE_FROM_SCRIPT` to the name of the script. For example, to quit on Magic's DRC script, you can set the variable as follows: @@ -24,7 +24,7 @@ export CREATE_REPRODUCIBLE_FROM_SCRIPT=magic/drc.tcl The flow will automatically quit right before executing any script matching `CREATE_REPRODUCIBLE_FROM_SCRIPT`. The last message printed will be something among the lines of `[INFO]: Reproducible packaged at ''.` -## Manually +### Manually If neither option above works for you for some reason, there's always the hard way, and the hard way involves invoking the script manually. You'll have to extract three key elements from the **verbose** logs (i.e. ./flow.tcl must be run with `-verbose`): @@ -37,7 +37,7 @@ You'll have to extract three key elements from the **verbose** logs (i.e. ./flow As a practical example, for this log from openlane.log: -```log +``` [INFO]: Changing layout to designs/spm/runs/RUN_2022.03.01_19.21.10/tmp/routing/17-fill.def [...] [INFO]: Running Detailed Routing... diff --git a/docs/source/getting_started.rst b/docs/source/getting_started/index.rst similarity index 81% rename from docs/source/getting_started.rst rename to docs/source/getting_started/index.rst index 3158de747..acfe242a4 100644 --- a/docs/source/getting_started.rst +++ b/docs/source/getting_started/index.rst @@ -6,4 +6,5 @@ Getting Started installation + installation_local quickstart \ No newline at end of file diff --git a/docs/source/installation.rst b/docs/source/getting_started/installation.rst similarity index 99% rename from docs/source/installation.rst rename to docs/source/getting_started/installation.rst index f6efb84a1..a2358c351 100644 --- a/docs/source/installation.rst +++ b/docs/source/getting_started/installation.rst @@ -144,6 +144,7 @@ Step 3. Checking the Docker Installation If every thing has been set up correctly, you can run the Docker ``hello-world`` image without root. To test, it use following command: .. code-block:: shell + docker run hello-world You will get a happy little "Hello, world!" message, once again, but this time without root. @@ -172,7 +173,7 @@ You will get a happy little "Hello, world!" message, once again, but this time w https://docs.docker.com/get-started/ -Troubleshooting Step 3. +Troubleshooting Step 3 """""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" If you get Docker permission error when running any Docker images: @@ -319,7 +320,7 @@ On Linux, you can open the final layout of the test design using KLayout. This w # Leave the Docker exit -.. image:: ../_static/installation/spm.png +.. image:: ../../_static/installation/spm.png Updating OpenLane diff --git a/docs/source/local_installs.md b/docs/source/getting_started/installation_local.md similarity index 82% rename from docs/source/local_installs.md rename to docs/source/getting_started/installation_local.md index 8e3b845f1..b314abd67 100644 --- a/docs/source/local_installs.md +++ b/docs/source/getting_started/installation_local.md @@ -1,13 +1,18 @@ -> Note: The local installer is no longer actively supported. Unless you ***absolutely*** know what you're doing, please use the Docker image. +# Installation (Containerless/Local) -# Using OpenLane without Docker -At its core, OpenLane is a set of scripts working with a set of tools. If you'd like to avoid using a Docker container, you can, but you will have to set up all of the tools required by OpenLane on your computer. We do provide a best-effort script to assist you with that. +:::{warning} +The local installer is no longer actively supported. Unless you ***absolutely*** know what you're doing, please use the Docker image. +::: -# Base Requirements -* Python 3.6+ with PIP -* pyyaml, venv: `python3 -m pip install pyyaml venv` +At its core, OpenLane is a set of scripts working with a set of tools. If you'd like to avoid using a Docker container, you can, but you will have to set up all of the tools required by OpenLane on your computer. We do provide a best-effort script to assist you with that. -# Tool Library +## Base Requirements +* Python 3.6+ + - pip + - venv + - pyyaml (`python3 -m pip install pyyaml`) + +## Tool Library You can run `python3 ./env.py tool-list` for a list. There are at least a dozen tools to install here. Luckily, you don't have to install them all one-by-one: There is an installation script that installs most of them. You can invoke `python3 ./env.py local-install`. This tool copies the skeleton and installs all the tools to `$OPENLANE_ROOT_DIR/install`. Furthermore, if you are on CentOS 7, macOS, Ubuntu 20.04 or Arch Linux, the installer will offer to install all the required apt, yum or brew packages for you. @@ -21,7 +26,7 @@ The tools will all be installed with `./install` as a prefix. You'll find all th After the installer is done, you can simply invoke `./flow.tcl` outside of Docker and it should work okay. -# More about how this works +## How this works `flow.tcl` looks for a file called `./install/env.tcl` before it does anything. If it finds it, it sources it. The `./install` directory is aliased in Docker environments, which already have the proper tools installed. `./install/env.tcl` contains the necessary environment variables to add the installed tools to PATH and activate the Python virtual environment. \ No newline at end of file diff --git a/docs/source/quickstart.rst b/docs/source/getting_started/quickstart.rst similarity index 85% rename from docs/source/quickstart.rst rename to docs/source/getting_started/quickstart.rst index 3ad8c88ae..6ffb5c591 100644 --- a/docs/source/quickstart.rst +++ b/docs/source/getting_started/quickstart.rst @@ -1,17 +1,10 @@ -Quick start +Quick-Start Guide ======================= Overview ------------------------------------ -OpenLane is an automated RTL-to-GDSII flow that uses open source tools like OpenROAD, -Yosys, Magic, Netgen, CVC and KLayout. -It also provides a number of custom scripts for design exploration, optimization and ECO. -The flow performs a complete synthesis, floorplanning, placement and routing of your designs. -Currently, it supports both A and B variants of the sky130 PDK, but there are instructions on porting more PDKs. +.. note:: This page assumes `OpenLane installation `_ is done. If you have not yet installed OpenLane, please visit the link and follow the instructions there. -The tool encapsulates the underlying tools to allow users to configure them all in one place: ``config.json/tcl``. This file contains assignments to the variables that the flow uses. - -The rest of the tutorial assumes `OpenLane installation `_ is done. This guide covers running the flow on existing desings, adding new designs and quick overview of the design directory strucutre. Starting the OpenLane Environment @@ -109,7 +102,7 @@ The main files are a configuration file and a ``src/`` folder that contains sour You can find more information `regarding the ./flow.tcl in the documentation here `_. And here is the `reference documentation regarding the configuration valirables `_. Advanced: Using custom PDK locations and OpenLane Docker images ------------------------------------------------------------ +--------------------------------------------------------------- .. warning:: If you accidently use the wrong version of a PDK or the OpenLane Docker image, then you may have *significant issues* down the line. If you don't know what you're doing, this section is not for you. diff --git a/docs/source/index.md b/docs/source/index.md new file mode 100644 index 000000000..f56d755db --- /dev/null +++ b/docs/source/index.md @@ -0,0 +1,18 @@ +# The OpenLane Documentation +OpenLane is an automated RTL to GDSII flow based on several components including OpenROAD, Yosys, Magic, Netgen, CVC, SPEF-Extractor, KLayout and a number of custom scripts for design exploration and optimization. It also provides a number of custom scripts for design exploration, optimization and ECO. + +The flow performs all ASIC implementation steps from RTL all the way down to GDSII. Currently, it supports both A and B variants of the sky130 PDK, but support for the newly released GF180MCU PDK is in the works, and instructions to add support for other (including proprietary) PDKs are documented. + +OpenLane abstracts the underlying open source utilities, and allows users to configure all their behavior with just a single configuration file. + +Check the sidebar to the left to get started. + +```{toctree} +getting_started/index +flow_overview +usage/index +for_developers/index +reference/index +additional_material +authors +``` diff --git a/docs/source/reference/cli.md b/docs/source/reference/cli.md new file mode 100644 index 000000000..273d4d407 --- /dev/null +++ b/docs/source/reference/cli.md @@ -0,0 +1,27 @@ +# Command-Line Arguments + +The following are the command-line arguments that can be passed to `flow.tcl`: + +| Argument | Description | +| - | - | +| `-design `
(Optional) | Specifies the design folder. A design folder should contain a `config.json` or `config.tcl` file defining the design parameters.
If the folder is not found, ./designs directory is searched, and if this parameter is omitted, the current working directory is treated as the design. | +| `-from `
(Optional) | Specifies stage to start flow execution from | +| `-to `
(Optional) | Specifies stage to stop flow execution at (included) | +| `-config_file `
(Optional) | Specifies the design's configuration file for running the flow.
For example, to run the flow using `./designs/spm/config2.tcl`
Use run `./flow.tcl -design ./designs/spm -config_file ./designs/spm/config2.tcl`
By default `config.tcl` is used, and if not found, `config.json` is used instead. | +| `-override_env`
Optional | Allows you to override certain configuration environment variables for this run. Format: `KEY1=VALUE1,KEY2=VALUE2` | +| `-tag `
(Optional) | Specifies a "name" for a specific run. If the tag is not specified, a timestamp is generated for identification of that run. | +| `-run_path `
(Optional) | Specifies a `path` to save the run in. By default the run is in `design_path/`, where the design path is the one passed to `-design` | +| `-src `
(Optional) | Sets the verilog source code file(s) in case of using `-init\_design\_config`.
The default is that the source code files are under `design_path/src/`, where the design path is the one passed to `-design` | +| `-init_design_config`
(Optional) | Creates a configuration file for a design. The config file is by default `openlane/config.json`, but can be overriden using the value from `-config_file`. | +| `-add_to_designs`
(Optional) | Adds the design to the OpenLane folder instead of creating an `openlane` folder. This is the default behavior on earlier versions of OpenLane. | +| `-overwrite`
(Optional) | Flag to overwrite an existing run with the same tag | +| `-interactive`
(Optional) | Flag to run openlane flow in interactive mode | +| `-file `
(Optional) | Passes a script of interactive commands in interactive mode | +| `-synth_explore`
(Boolean) | If enabled, synthesis exploration will be run (only synthesis exploration), which will try out the available synthesis strategies against the input design. The output will be the four possible gate level netlists under <run_path/results/synthesis> and a summary report under reports that compares the 4 outputs. | +| `-lvs`
(Boolean) | If enabled, only LVS will be run on the design. in which case the user must also pass: -design DESIGN\_DIR -gds DESIGN\_GDS -net DESIGN_NETLIST. | +| `-drc`
(Boolean) | If enabled, only DRC will be run on the design. in which case the user must also pass: -design DESIGN\_DIR -gds DESIGN\_GDS -report OUTPUT\_REPORT\_PATH -magicrc MAGICRC. | +| `-save`
(Optional) | A flag to save a runs results like .mag and .lef in the design's folder. | +| `-save_path `
(Optional) | Specifies a different path to save the design's result. This option is to be used with the `-save` flag. | +| `-verbose `
(Optional) | Specifies a level of verbosity. 0, the default, only outputs high-level messages. 1 also outputs some of the inner workings of the flow scripts. 2 or higher forwards outputs from _all_ tools to your terminal. | +| `-test_mismatches `
(Optional) | Test for mismatches between the OpenLane tool versions and the current environment. `all`, the default, tests all mismatches. `tools` tests all except the PDK. `pdk` only tests the PDK. `none` disables the check.
(Default: `all`) | +| `-ignore_mismatches` | If specified, halts the flow on detected environment mismatches. | \ No newline at end of file diff --git a/docs/source/configuration.md b/docs/source/reference/configuration.md similarity index 97% rename from docs/source/configuration.md rename to docs/source/reference/configuration.md index ee8e2f73f..64e7ff473 100644 --- a/docs/source/configuration.md +++ b/docs/source/reference/configuration.md @@ -1,4 +1,4 @@ -# Variables information +# Configuration Variables This page describes user-configurable variables and their default values. ## Load Order @@ -239,7 +239,7 @@ These variables worked initially, but they were too sky130 specific and will be | `MAGIC_DRC_USE_GDS` | A flag to choose whether to run the magic DRC checks on GDS or not. If not, then the checks will be done on the DEF/LEF. 1 = GDS, 0 = DEF/LEF
(Default: `1` )| | `MAGIC_EXT_USE_GDS` | A flag to choose whether to run the magic extractions on GDS or DEF/LEF. If GDS was used Device Level LVS will be run. Otherwise, blackbox LVS will be run. 1 = GDS, 0 = DEF/LEF
(Default: `0` )| | `MAGIC_INCLUDE_GDS_POINTERS` | A flag to choose whether to include GDS pointers in the generated mag files or not. 1 = Enabled, 0 = Disabled
(Default: `0` )| -| `MAGIC_DISABLE_HIER_GDS` | A flag to disable cif hier and array during GDS-II writing.* 1=Enabled ``, 0=Disabled ``.
(Default: `1` )| +| `MAGIC_DISABLE_HIER_GDS` | A flag to disable cif hier and array during GDSII writing.* 1=Enabled ``, 0=Disabled ``.
(Default: `1` )| > * Tim Edwards's Explanation on disabling hier gds: The following is an explanation by Tim Edwards, provided in a slack thread, on how this affects the GDS writing process: "Magic can take a very long time writing out GDS while checking hierarchical interactions in a standard cell layout. If your design is all digital, I recommend using "gds *hier write disable" before "gds write" so that it does not try to resolve hierarchical interactions (since by definition, standard cells are designed to just sit next to each other without creating DRC issues). That can actually make the difference between a 20 hour GDS write and a 2 minute GDS write. For a standard cell design that takes up the majority of the user space, a > 24 hour write time (without disabling the hierarchy checks) would not surprise me." @@ -261,14 +261,14 @@ These variables worked initially, but they were too sky130 specific and will be | `RUN_LVS` | Enables running LVS. 1 = Enabled, 0 = Disabled
(Default: `1`)| | `PRIMARY_SIGNOFF_TOOL` | Determines whether `magic` or `klayout` is the primary signoff tool.
(Default: `magic`) | | `RUN_MAGIC` | Enables running magic and GDSII streaming. 1 = Enabled, 0 = Disabled
(Default: `1`)| -| `RUN_MAGIC_DRC` | Enables running magic DRC on GDS-II produced by magic. 1 = Enabled, 0 = Disabled
(Default: `1`)| -| `RUN_KLAYOUT` | Enables running Klayout and GDSII streaming. 1 = Enabled, 0 = Disabled
(Default: `1`)| -| `RUN_KLAYOUT_DRC` | Enables running Klayout DRC on GDS-II produced by magic. 1 = Enabled, 0 = Disabled
(Default: `0`)| -| `KLAYOUT_DRC_KLAYOUT_GDS` | Enables running Klayout DRC on GDS-II produced by Klayout. 1 = Enabled, 0 = Disabled
(Default: `0`)| -| `RUN_KLAYOUT_XOR` | Enables running Klayout XOR on 2 GDS-IIs, the defaults are the one produced by magic vs the one produced by klayout. 1 = Enabled, 0 = Disabled
(Default: `1`)| +| `RUN_MAGIC_DRC` | Enables running magic DRC on GDSII produced by magic. 1 = Enabled, 0 = Disabled
(Default: `1`)| +| `RUN_KLAYOUT` | Enables running KLayout and GDSII streaming. 1 = Enabled, 0 = Disabled
(Default: `1`)| +| `RUN_KLAYOUT_DRC` | Enables running KLayout DRC on GDSII produced by magic. 1 = Enabled, 0 = Disabled
(Default: `0`)| +| `KLAYOUT_DRC_KLAYOUT_GDS` | Enables running KLayout DRC on GDSII produced by KLayout. 1 = Enabled, 0 = Disabled
(Default: `0`)| +| `RUN_KLAYOUT_XOR` | Enables running KLayout XOR on 2 GDSIIs, the defaults are the one produced by magic vs the one produced by klayout. 1 = Enabled, 0 = Disabled
(Default: `1`)| | `KLAYOUT_XOR_GDS` | If `RUN_KLAYOUT_XOR` is enabled, this will enable producing a GDS output from the XOR along with it's PNG export. 1 = Enabled, 0 = Disabled
(Default: `1`)| | `KLAYOUT_XOR_XML` | If `RUN_KLAYOUT_XOR` is enabled, this will enable producing an XML output from the XOR. 1 = Enabled, 0 = Disabled
(Default: `1`)| -| `TAKE_LAYOUT_SCROT` | Enables running Klayout to take a PNG screenshot of the produced layout (currently configured to run on the results of each stage).1 = Enabled, 0 = Disabled
(Default: `0`)| +| `TAKE_LAYOUT_SCROT` | Enables running KLayout to take a PNG screenshot of the produced layout (currently configured to run on the results of each stage).1 = Enabled, 0 = Disabled
(Default: `0`)| | `TAP_DECAP_INSERTION` | Enables tap and decap cells insertion after floorplanning (if enabled) .1 = Enabled, 0 = Disabled
(Default: `1`) | | `DIODE_INSERTION_STRATEGY` | Specifies the insertion strategy of diodes to be used in the flow. 0 = No diode insertion, 1 = Spray diodes, 2 = insert fake diodes and replace them with real diodes if needed. 3= use FastRoute Antenna Avoidance flow, 4 = Use Sylvian's Custom Script for diode insertion on design pins and smartly inserting needed diodes inside the design, 5 = a mix of strategy 2 and 4.
(Default: `3`) | | `WIDEN_SITE` | Specifies the new virtual width of the site to be used in all stages up to diode insertion, then switched back to the original site width. It can be either a factor or an absolute value controlled by `WIDEN_SITE_IS_FACTOR`
(Default: `1`) | diff --git a/docs/source/configuration_files.md b/docs/source/reference/configuration_files.md similarity index 98% rename from docs/source/configuration_files.md rename to docs/source/reference/configuration_files.md index 24ead08c1..26f92e077 100644 --- a/docs/source/configuration_files.md +++ b/docs/source/reference/configuration_files.md @@ -1,4 +1,4 @@ -# Configuration Files +# Design Configuration Files Each OpenLane-compatible design must come with a configuration file. These configuration files can be written in one of two grammars: JSON or Tcl. Tcl offers more flexibility at the detriment of security, while JSON is more straightforward at the cost of flexbility. While Tcl allows you to do all manners of computation on your variables, JSON has a limited expression engine that will be detailed later in this document. Nevertheless, for security (and future-proofing), we recommend you use the JSON format. @@ -177,7 +177,7 @@ if { [file exists $filename] == 1} { This implies that if the `{PDK}_{STD_CELL_LIBRARY}_config.tcl` doesn't exist for a specific technology combination the flow would resume normally with only the global config.tcl. This structure allows for storing the best configurations for a given design on all different PDKs and their STD_CELL_LIBRARYs. The best configuration for a given design differ from one PDK and STD_CELL_LIBRARY to another. -For this reason, upon installing a new PDK/STD_CELL_LIBRARY or a new design, an exploration should be run on different configuration parameters to reach the best configuration. The script that enables this is documented [here][1]. +For this reason, upon installing a new PDK/STD_CELL_LIBRARY or a new design, an exploration should be run on different configuration parameters to reach the best configuration. The script that enables this is documented [here][exploration_script]. After running the exploration, you will find in the logs two .csv newly generated files: `{tag}_{timestamp}.csv` and `{tag}_{timestamp}_best.csv`. The configuration name reported in the _best.csv file contains the best added configurations to the current run of the given design using the specified PDK/STD_CELL_LIBRARY. Two scripts were created for this purpose: @@ -207,11 +207,10 @@ To run the script to update configurations for a (PDK,STD_CELL_LIBRARY) pair aft You can invoke `python3 ./scripts/config/update.py` for a full list of options. -Check [this][1] for more details on the log files. +Check [this][exploration_script] for more details on the log files. > **Note 1:** `update.py` skips designs that fail during the exploration, which means their `flow_status` is not `flow_completed`. > > **Note 2:** The `update.py` script only copies new configuration to the file. The new configurations are marked with a preceeding `# Regression` comment that is automatically written before them by the exploration script. However, the `replicate.py` script copies the whole file. -[1]: ../../regression_results/README.md -[2]: ../../configuration/README.md +[exploration_script]: ../usage/exploration_script.md diff --git a/regression_results/datapoint_definitions.md b/docs/source/reference/datapoint_definitions.md similarity index 98% rename from regression_results/datapoint_definitions.md rename to docs/source/reference/datapoint_definitions.md index ae7f4536e..cd548dd4b 100644 --- a/regression_results/datapoint_definitions.md +++ b/docs/source/reference/datapoint_definitions.md @@ -1,4 +1,4 @@ -# Datapoint Definitions +# Report Data Definitions ***NOTE:** The value `-1`, if not meaningful, indicates that the report/log from which the information is extracted wasn't found (the stage responsible for it was skipped or failed). ## Default Printed Information Variables @@ -27,7 +27,7 @@ | `antenna_violations` | The total number of antenna violations in the design. Extracted from Magic antenna check or OpenROAD ARC. | | `lvs_total_errors` | The total number of mismatches and differences between the final layout and the netlist of the design. Extracted from Netgen LVS report. | | `cvc_total_errors` | The total number of electric errors detected by CVC. Extracted from CVC report. | -| `klayout_violations` | The total number of klayout drc violations in the design. Extracted from klayout drc report ran on the magic generated GDS-II. | +| `klayout_violations` | The total number of klayout drc violations in the design. Extracted from klayout drc report ran on the magic generated GDSII. | | `wire_length` | The total wire length in the design. Extracted from tritonRoute logs. | | `vias` | The number of vias in the final design. Extracted from tritonRoute logs. | | `wns` | Worst Negative Slack. Reported after Synthesis. Extracted from OpenSTA. | @@ -100,4 +100,4 @@ ## Optional variables -These variables are optional that can be specified in the configuration parameters file. Please refere to this [file](../docs/source/configuration.md) for the full list of configurations. +These variables are optional that can be specified in the configuration parameters file. Please refere to this [file](./configuration.md) for the full list of configurations. diff --git a/docs/source/eco_flow.md b/docs/source/reference/eco_flow.md similarity index 97% rename from docs/source/eco_flow.md rename to docs/source/reference/eco_flow.md index 3b92fdc81..dd7f0fc74 100644 --- a/docs/source/eco_flow.md +++ b/docs/source/reference/eco_flow.md @@ -1,7 +1,7 @@ # The ECO Flow (Alpha) The ECO flow starts from checking the report generated in the route step. A python script is used to check the report, insert buffers, and do the resize. Inside the ECO loop, the python script, cts and route step are called sequentially. The reports are generated each time, and the loop stops until no hold time violations are found. See overview diagram below: -![image](../_static/eco_flow.png) +![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. @@ -30,7 +30,7 @@ For the 1st iteration, the design has 131 hold violations with a -1.48 worst cas The following table shows the timing results of the ECO flow for each ECO iteration: -![image](../_static/eco_results.png) +![image](../../_static/eco_results.png) ## How to enable the ECO flow diff --git a/docs/source/reference.rst b/docs/source/reference/index.rst similarity index 62% rename from docs/source/reference.rst rename to docs/source/reference/index.rst index a50e4d9f8..d590bf455 100644 --- a/docs/source/reference.rst +++ b/docs/source/reference/index.rst @@ -1,11 +1,13 @@ -Reference documentation +Reference Manual -------------------------------------------------------------------------------- .. toctree:: :glob: + cli + configuration_files configuration - designs - eco_flow openlane_commands - advanced_readme - manual_pdk_installation \ No newline at end of file + eco_flow + interactive_mode + datapoint_definitions + diff --git a/docs/source/advanced_readme.md b/docs/source/reference/interactive_mode.md similarity index 96% rename from docs/source/advanced_readme.md rename to docs/source/reference/interactive_mode.md index 830e7bfda..3229ceec8 100644 --- a/docs/source/advanced_readme.md +++ b/docs/source/reference/interactive_mode.md @@ -1,4 +1,4 @@ -## Interactive Mode +# Interactive Mode You may run the flow interactively by using the `-interactive` option: ``` @@ -12,7 +12,7 @@ A tcl shell will be opened where the openlane package is automatically sourced: Then, you should be able to run the following main commands: -0. Any tcl command. +0. Any **valid** Tcl code. 1. `prep -design -tag -config -init_design_config -overwrite` similar to the command line arguments, design is required and the rest is optional 2. `run_synthesis` 3. `run_floorplan` diff --git a/docs/source/openlane_commands.md b/docs/source/reference/openlane_commands.md similarity index 94% rename from docs/source/openlane_commands.md rename to docs/source/reference/openlane_commands.md index 3279c2cee..358951504 100644 --- a/docs/source/openlane_commands.md +++ b/docs/source/reference/openlane_commands.md @@ -1,15 +1,10 @@ -# OpenLane Interactive Mode Commands +# Tcl Commands -This page describes the list of commands available in openlane, their functionality, and their expected inputs and outputs. +This page describes the list of commands available in OpenLane, their functionality, and their expected inputs and outputs. **NOTE:** You must run the `prep` command before running any of the other commands, in order to have the necessary files and configurations loaded. -The Following list is available in the interactive mode: `./flow.tcl -interactive` and under: -``` -% package require openlane 0.9 -``` -Which runs automatically when you enter the interactive mode. - +The following commands are available in the interactive mode: `./flow.tcl -interactive`, or in Tclsh using `% package require openlane 0.9`. ## General Commands @@ -259,25 +254,25 @@ Most of the following commands' implementation exists in this [file][6] | | `-output ` | The output mag file path. | | `run_magic_antenna_check` | | Runs spice extractions on the processed design and performs antenna checks. The resulting file is under `//results/magic/` and `//reports/magic/` . | -## Klayout Commands +## KLayout Commands Most of the following commands' implementation exists in this [file][17] | Command | Flags | Description | |---------------|------------------------|-----------------------------------------| -| `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 `//results/klayout/` . | -| `scrot_klayout` | | Export a PNG view of a given GDS-II or DEF file. This is controlled by `TAKE_LAYOUT_SCROT`. | +| `run_klayout` | | Streams the back-up final GDSII, 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 `//results/klayout/` . | +| `scrot_klayout` | | Export a PNG view of a given GDSII or DEF file. This is controlled by `TAKE_LAYOUT_SCROT`. | | | `[-log ]` | Output log file. | | | `[-layout ]` | 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`. | +| `run_klayout_drc` | | Runs KLayout DRC on a given GDSII file. This is controlled by `RUN_KLAYOUT_DRC`. | | | `[-gds ]` | The input GDS file, the default is `::env(CURRENT_GDS)`. | | | `[-stage ]` | The output stage using the DRC, the default is `magic`. The `magic` implies that the drc was run on the default GDS which is produced by magic. | -| `run_klayout_gds_xor` | | Runs Klayout XOR on 2 GDS-IIs. This is controlled by `RUN_KLAYOUT_XOR` and `KLAYOUT_XOR_GDS` and `KLAYOUT_XOR_XML`. | -| | `[-layout1 ]` | The input GDS file, the default is the magic generated GDS-II under `/results/magic/.gds`. | -| | `[-layout2 ]` | The input GDS file, the default is the klayout generated GDS-II under `/results/klayout/.gds`. | +| `run_klayout_gds_xor` | | Runs KLayout XOR on 2 GDSIIs. This is controlled by `RUN_KLAYOUT_XOR` and `KLAYOUT_XOR_GDS` and `KLAYOUT_XOR_XML`. | +| | `[-layout1 ]` | The input GDS file, the default is the magic generated GDSII under `/results/magic/.gds`. | +| | `[-layout2 ]` | The input GDS file, the default is the klayout generated GDSII under `/results/klayout/.gds`. | | | `[-output_gds ]` | The output GDS file with the xor result, the default under `/results/klayout/.xor.gds`. | | | `[-output_xml ]` | The output XML file with the xor result, the default under `/results/klayout/.xor.xml`. | -| `open_in_klayout` | | Opens a design in the Klayout GUI with MERGED_LEF for the cell/macro definitions. Useful as it works around Klayout's LEF import peculiarities. | +| `open_in_klayout` | | Opens a design in the KLayout GUI with MERGED_LEF for the cell/macro definitions. Useful as it works around KLayout's LEF import peculiarities. | | | `[-layout ]` | The input DEF file, the default is `::env(CURRENT_DEF)`. | ## LVS Commands @@ -343,22 +338,22 @@ Most of the following commands' implementation exists in these files: [deflef][1 | `find_all ` | | Print a sorted list of *.ext files that are found in the current run directory. | -[0]: ./../../scripts/tcl_commands/all.tcl -[1]: ./../../scripts/tcl_commands/checkers.tcl -[2]: ./../../scripts/tcl_commands/cts.tcl -[3]: ./../../scripts/tcl_commands/floorplan.tcl -[4]: ./../../scripts/tcl_commands/init_design.tcl -[5]: ./../../scripts/tcl_commands/lvs.tcl -[6]: ./../../scripts/tcl_commands/magic.tcl -[7]: ./../../scripts/tcl_commands/placement.tcl -[8]: ./../../scripts/tcl_commands/routing.tcl -[9]: ./../../scripts/tcl_commands/synthesis.tcl -[10]: ./../../scripts/utils/deflef_utils.tcl -[11]: ./../../scripts/utils/fake_display_buffer.tcl -[12]: ./../../scripts/utils/utils.tcl -[13]: ./../../docs/source/configuration.md +[0]: ./../../../scripts/tcl_commands/all.tcl +[1]: ./../../../scripts/tcl_commands/checkers.tcl +[2]: ./../../../scripts/tcl_commands/cts.tcl +[3]: ./../../../scripts/tcl_commands/floorplan.tcl +[4]: ./../../../scripts/tcl_commands/init_design.tcl +[5]: ./../../../scripts/tcl_commands/lvs.tcl +[6]: ./../../../scripts/tcl_commands/magic.tcl +[7]: ./../../../scripts/tcl_commands/placement.tcl +[8]: ./../../../scripts/tcl_commands/routing.tcl +[9]: ./../../../scripts/tcl_commands/synthesis.tcl +[10]: ./../../../scripts/utils/deflef_utils.tcl +[11]: ./../../../scripts/utils/fake_display_buffer.tcl +[12]: ./../../../scripts/utils/utils.tcl +[13]: ./configuration.md [14]: https://github.com/The-OpenROAD-Project/openlane/blob/master/designs/spm/pin_order.cfg -[15]: ./chip_integration.md -[16]: ./advanced_power_grid_control.md -[17]: ./../../scripts/tcl_commands/klayout.tcl -[18]: ./../../scripts/tcl_commands/cvc.tcl +[15]: ../usage/chip_integration.md +[16]: ../usage/advanced_power_grid_control.md +[17]: ./../../../scripts/tcl_commands/klayout.tcl +[18]: ./../../../scripts/tcl_commands/cvc.tcl diff --git a/docs/source/advanced_power_grid_control.md b/docs/source/usage/advanced_power_grid_control.md similarity index 99% rename from docs/source/advanced_power_grid_control.md rename to docs/source/usage/advanced_power_grid_control.md index 1dedd96ce..62b5ae9c9 100644 --- a/docs/source/advanced_power_grid_control.md +++ b/docs/source/usage/advanced_power_grid_control.md @@ -10,7 +10,7 @@ An example utilizing the controls and logic provided in this documentation is [c > **Note**: When we say "your configurations" in this documentation we are refering to the `config.json` or `config.tcl` for that specific block. -## Chip Level: +## Chip Level According to the current methodology of [OpenLane Chip Integration][0], the process goes as follows: 1. Hardening the hard/internal macros. @@ -19,7 +19,7 @@ According to the current methodology of [OpenLane Chip Integration][0], the proc Therefore at the top level typically you only have the core block. All you need to do in that step is to verify that the power pads are in the middle of each padframe side, and then add this line to your interactive script: `power_routing` After legalization and before signal routing. However, this only supports a single power domain. Otherwise, you need to manually connect the power pads to the core ring of your core module. -## Core Level: +## Core Level Let's clarify here, before delving into details, that with each hierarchy level you lose one routing metal layer. For example, in the skywater pdk the metal stack has 5 layers, thus for the core level you can use all layers up to met5; however, if you have another macro inside your core, that macro can only use up to met4, and so forth. diff --git a/docs/source/chip_integration.md b/docs/source/usage/chip_integration.md similarity index 94% rename from docs/source/chip_integration.md rename to docs/source/usage/chip_integration.md index 6347139e1..03b7f18c3 100644 --- a/docs/source/chip_integration.md +++ b/docs/source/usage/chip_integration.md @@ -59,8 +59,8 @@ You need to set ***all environment variables mentioned in [Hardening the Core](# The following inputs are provided to produce the final GDSII: 1. Padframe cfg file (provided by the user or generated by padring). [Here][6] is an example. Or a hardened chip_io.gds and chip_io.lef following [this][4]. -2. Hardened lef & GDS-II for the core module, generated [here](#hardening-the-core) -3. Top level netlist instantiating pads and core module (Could be provided by the user or generated by [topModuleGen][7]) +2. Hardened lef & GDSII for the core module, generated [here](#hardening-the-core) +3. Top level netlist instantiating pads and core module (Could be provided by the user or generated by topModuleGen) [The interactive script for the IOs][4] does the following: - Sources configurations. @@ -69,7 +69,7 @@ The following inputs are provided to produce the final GDSII: - Uses odbpy/padringer.py to generate the padframe. - Adds the obstructions to the core area, and removes core nets and pins. - Routes. -- Streams out the GDS-II and the LEFv view. +- Streams out the GDSII and the LEFv view. Given these inputs the following [interactive script][5] script. Mainly, it does the following steps: - Runs the top level netlist through yosys. @@ -85,11 +85,11 @@ Given these inputs the following [interactive script][5] script. Mainly, it does ## Power_routing -### Macros: +### Macros This is discussed in detail [here][8]. -### Core: +### Core It should have an `stdcell` section that includes a `core_ring` on met4 and met5. It should use met5 and met4 for the straps, and met1 for the rails. Thus, make sure to add these to your config file: @@ -119,7 +119,7 @@ You can automate the power routing process in the core and macro level by readin When you use the `power_routing` command in the chip interactive script, the power pads will be connected to the core ring, and thus the whole chip would be powered. -## General Notes: +## General Notes [This][2] includes more guidance on how to create an interactive script. @@ -127,14 +127,13 @@ When you use the `power_routing` command in the chip interactive script, the pow [This][1] has a description for all OpenLane commands. -[0]: ./configuration.md -[1]: ./openlane_commands.md -[2]: ./advanced_readme.md +[0]: ../reference/configuration.md +[1]: ../reference/openlane_commands.md +[2]: ../reference/interactive_mode.md [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 diff --git a/docs/source/building_the_pdk.md b/docs/source/usage/custom_pdk_builds.md similarity index 98% rename from docs/source/building_the_pdk.md rename to docs/source/usage/custom_pdk_builds.md index 2dc2be7a8..d568048d8 100644 --- a/docs/source/building_the_pdk.md +++ b/docs/source/usage/custom_pdk_builds.md @@ -1,4 +1,4 @@ -# Building the PDK +# Custom-Building PDKs The pre-built version of the sky130 PDK variants included with OpenLane includes the following standard cell libraries: * sky130_fd_io * sky130_fd_pr diff --git a/docs/source/designs.md b/docs/source/usage/designs.md similarity index 91% rename from docs/source/designs.md rename to docs/source/usage/designs.md index 51f94b846..76261d2b6 100644 --- a/docs/source/designs.md +++ b/docs/source/usage/designs.md @@ -1,4 +1,4 @@ -# The OpenLane Designs Folder +# Adding Your Designs To add a new design, the following command creates a configuration file for your design: ```bash @@ -15,8 +15,8 @@ This will create the following directory structure: designs/ ├── config.json (or config.tcl) ``` -In the configuration file (`config.json`), you should edit the required variables and the optional variables, if needed. Further information about the variables can be found [here](../configuration/README.md). -> Note: config.json/config.tcl is a global configuration for all PDKs and SCLs. For more information about design configuration files, including how to set up PDK/SCL-specific variables, please see [this file](../docs/source/configuration_files.md). +In the configuration file (`config.json`), you should edit the required variables and the optional variables, if needed. Further information about the variables can be found [here](../reference/configuration.md). +> Note: config.json/config.tcl is a global configuration for all PDKs and SCLs. For more information about design configuration files, including how to set up PDK/SCL-specific variables, please see [this file](../reference/configuration_files.md). It is recommended to place the design's verilog files in a `src` directory inside the design's folder as following: diff --git a/regression_results/README.md b/docs/source/usage/exploration_script.md similarity index 95% rename from regression_results/README.md rename to docs/source/usage/exploration_script.md index 52fadfa5e..40e9c0342 100644 --- a/regression_results/README.md +++ b/docs/source/usage/exploration_script.md @@ -1,8 +1,4 @@ # Regression & Exploration - - - - ## Overview OpenLane provides `run_designs.py`, a script that can do multiple runs in a parallel using different configurations. A run consists of a set of designs and a configuration file that contains the configuration values. It is useful to explore the design implementation using different configurations to figure out the best one(s). For examples, check the [Usage](#usage) section. @@ -10,7 +6,7 @@ Also, it can be used for testing the flow by running the flow against several de ``` python3 run_designs.py --tag test --threads 3 spm xtea des aes256 ``` -## Default Test Set Results: +## Default Test Set Results You can view the results of the run against some designs (more [here](#usage)) against any of the 5 sky130 standard cell libraries through these sheets: @@ -24,7 +20,7 @@ You can view the results of the run against some designs (more [here](#usage)) a ## Usage -- The list of flags that could be used with run_designs.py is described here [Command line arguments](#command-line-arguments). Check [columns_defintions.md][21] for more details on the reported configuration parameters. +- The list of flags that could be used with run_designs.py is described here [Command line arguments](#command-line-arguments). Check [columns_defintions.md](../reference/datapoint_definitions.md) for more details on the reported configuration parameters. The script can be used in two ways @@ -34,7 +30,7 @@ The script can be used in two ways python3 run_designs.py --threads 4 spm xtea PPU APU ``` - You can run the default test set consisting of all designs under [./designs](../designs/) through running the following command along with any of the flags: + You can run the default test set consisting of all designs under [designs](../../../designs/) through running the following command along with any of the flags: ```bash python3 run_design.py --defaultTestSet @@ -118,6 +114,4 @@ The script can be used in two ways ## Command line arguments -`python3 ./run_designs.py --help` - -[21]: ./datapoint_definitions.md +`python3 ./run_designs.py --help` \ No newline at end of file diff --git a/docs/source/hardening_macros.md b/docs/source/usage/hardening_macros.md similarity index 92% rename from docs/source/hardening_macros.md rename to docs/source/usage/hardening_macros.md index c6aee4834..5a2d541f1 100644 --- a/docs/source/hardening_macros.md +++ b/docs/source/usage/hardening_macros.md @@ -1,12 +1,11 @@ # Hardening Macros - -Using openlane, you can produce a GDSII from an RTL for macros, and then use these macros to create your chip. Check [this][4] for more details about chip integration. +Using OpenLane, you can produce a GDSII from an RTL for macros, and then use these macros to create your chip. Check [this][4] for more details about chip integration. In this document we will go through the hardening steps and discuss in some detail what considerations should be made when hardening your macro. > **NOTE:** For all the configurations mentioned in this documentation and any other openlane configurations, you can use the exploration script `run_designs.py` to find the optimal value for each configuration for your design. Read more [here][6]. -## Base Requirements: +## Base Requirements You should start by setting the basic configuration file for your design. Check [this][5] for how to add your new design. @@ -125,7 +124,7 @@ You can read more about those configurations [here][0]. Placement is done in three steps: Global Placement, Optimizations, and Detailed Placement. -### Global Placement: +### Global Placement For Global Placement, the most important value would be `PL_TARGET_DENSITY` which should be easy to set. @@ -135,17 +134,17 @@ For Global Placement, the most important value would be `PL_TARGET_DENSITY` whic Other values to be considered are `PL_BASIC_PLACEMENT` and `PL_SKIP_INITIAL_PLACEMENT`, you can read more about those [here][0]. -### Optimizations: +### Optimizations For this step we rely on Resizer and OpenPhySyn. -#### Resizer optimizations: +#### Resizer optimizations The only optimization we use from resizer is the wire length optimization which is used to reduce the antenna violations. This is disabled by default since the diode insertion strategies should cover that purpose. However, you can enable that by setting `PL_RESIZER_OVERBUFFER` to `1` and then determine the maximum wire length by setting this value `MAX_WIRE_LENGTH`. -### Detailed Placement: +### Detailed Placement The only value to consider here is the `DPL_CELL_PADDING` which is usually selected for each (PDK,STD_CELL_LIBRARY) and should mostly be left as is. However, typically for the skywater libraries the value should be 4~6. @@ -194,11 +193,11 @@ The configurations here were selected based on a large design test set and the c Finally, the flow ends with physical verification. This begins by streaming out the GDS followed by running DRC, LVS, and Antenna checks on the design. Then, it produces a final summary report in csv format to summarize all the reports. -You can control whether the magic DRC should be done on GDS-II or on LEF/DEF abstract views. We recommend using GDS-II on macros while using LEF/DEF on the chip level. This should speed up the run process and still give results as accurate as possible. This is controlled by `MAGIC_DRC_USE_GDS`. +You can control whether the magic DRC should be done on GDSII or on LEF/DEF abstract views. We recommend using GDSII on macros while using LEF/DEF on the chip level. This should speed up the run process and still give results as accurate as possible. This is controlled by `MAGIC_DRC_USE_GDS`. You can run Antenna Checks using OpenROAD ARC or magic. This is controlled by `USE_ARC_ANTENNA_CHECK`. The magic antenna checker was more reliable at the time of writing this documentation but it comes with a huge runtime trade-off and the accuracy gain is not significant enough to accept that tradeoff; thus, the default is OpenROAD's ARC. -You can control whether LVS should be run down to the device level or the cell level based on the type of the extraction. If you perform extraction on GDS-II then it's going to be down to the device/transistor level, otherwise using the LEF/DEF views then it's going to be down to the cell/block level. This is controlloed by `MAGIC_EXT_USE_GDS`. +You can control whether LVS should be run down to the device level or the cell level based on the type of the extraction. If you perform extraction on GDSII then it's going to be down to the device/transistor level, otherwise using the LEF/DEF views then it's going to be down to the cell/block level. This is controlloed by `MAGIC_EXT_USE_GDS`. You can enable LEC on the different netlists by setting `LEC_ENABLE` to one, which should run logic verification after writing each intermediate netlist. @@ -206,21 +205,21 @@ A final summary report is produced by default as `/reports/metrics.csv A final manufacturability report is produced by default as `/reports/manufacturability_report.csv`, this report contains the magic DRC, the LVS, and the antenna violations summaries. -The final GDS-II file can be found under `/results/final/gds`. +The final GDSII file can be found under `/results/final/gds`. 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. -[0]: ./../../docs/source/configuration.md -[1]: ./openlane_commands.md -[2]: ./advanced_readme.md +[0]: ../reference/configuration.md +[1]: ../reference/openlane_commands.md +[2]: ../reference/interactive_mode.md [3]: https://github.com/The-OpenROAD-Project/OpenROAD/blob/master/src/pdn/doc/PDN.md [4]: ./chip_integration.md -[5]: ./../../docs/source/designs.md -[6]: ./../../regression_results/README.md +[5]: ./designs.md +[6]: ./exploration_script.md [7]: https://github.com/The-OpenROAD-Project/openlane/blob/master/designs/spm/pin_order.cfg -[8]: ./pdk_structure.md +[8]: ../for_developers/pdk_structure.md [9]: ./advanced_power_grid_control.md -[10]: ./../../regression_results/datapoint_definitions.md -[11]: ./../../scripts/base.sdc +[10]: ../reference/datapoint_definitions.md +[11]: ./../../../scripts/base.sdc diff --git a/docs/source/usage.rst b/docs/source/usage/index.rst similarity index 70% rename from docs/source/usage.rst rename to docs/source/usage/index.rst index 606138300..915dafebf 100644 --- a/docs/source/usage.rst +++ b/docs/source/usage/index.rst @@ -3,7 +3,10 @@ Using OpenLane .. toctree:: :glob: + designs + exploration_script hardening_macros chip_integration advanced_power_grid_control + custom_pdk_builds \ No newline at end of file diff --git a/index.rst b/index.rst deleted file mode 100644 index 749e6157f..000000000 --- a/index.rst +++ /dev/null @@ -1,14 +0,0 @@ -OpenLane -########### - -OpenLane is an automated RTL to GDSII flow based on several components including OpenROAD, Yosys, Magic, Netgen, CVC, SPEF-Extractor, CU-GR, Klayout and a number of custom scripts for design exploration and optimization. The flow performs full ASIC implementation steps from RTL all the way down to GDSII. - -.. toctree:: - :glob: - - docs/source/getting_started - docs/source/usage - docs/source/for_developers - docs/source/reference - AUTHORS - diff --git a/scripts/klayout/open_design_cmd.py b/scripts/klayout/open_design_cmd.py index 6abebf86a..69ccf3dce 100644 --- a/scripts/klayout/open_design_cmd.py +++ b/scripts/klayout/open_design_cmd.py @@ -36,7 +36,7 @@ @click.argument("input_def") def open_design(input_lef, pdk_root, pdk, input_def): """ - Opens a design in Klayout. + Opens a design in KLayout. """ dir = os.path.dirname(__file__) klayout_script_path = os.path.join(dir, "open_design.py") diff --git a/scripts/report/report.py b/scripts/report/report.py index f24cf4b88..2588cd3fd 100755 --- a/scripts/report/report.py +++ b/scripts/report/report.py @@ -500,7 +500,7 @@ def re_get_last_capture(rx, string): # Not really sure why we do this magic_violations = (magic_violations_raw + 3) // 4 - # Klayout DRC Violations + # KLayout DRC Violations klayout_drc = Artifact(rp, "reports", "signoff", "magic.lydrc", True) klayout_drc_content = klayout_drc.get_content() diff --git a/scripts/tcl_commands/README.md b/scripts/tcl_commands/README.md index 8d56a955d..9c09092ba 100644 --- a/scripts/tcl_commands/README.md +++ b/scripts/tcl_commands/README.md @@ -1,7 +1,7 @@ # OpenLane Package ------------------- -## Commands: +## Commands Refer to this [README](../../docs/source/openlane_commands.md) diff --git a/scripts/tcl_commands/klayout.tcl b/scripts/tcl_commands/klayout.tcl index 7bdaf013a..deba26121 100755 --- a/scripts/tcl_commands/klayout.tcl +++ b/scripts/tcl_commands/klayout.tcl @@ -17,7 +17,7 @@ proc run_klayout {args} { increment_index set log [index_file $::env(signoff_logs)/gdsii-klayout.log] TIMER::timer_start - puts_info "Streaming out GDS-II with Klayout (log: [relpath . $log])..." + puts_info "Streaming out GDSII with KLayout (log: [relpath . $log])..." set gds_files_in "" if { [info exist ::env(EXTRA_GDS_FILES)] } { set gds_files_in $::env(EXTRA_GDS_FILES) @@ -58,10 +58,10 @@ proc run_klayout {args} { exec echo "[TIMER::get_runtime]" | python3 $::env(SCRIPTS_DIR)/write_runtime.py "gdsii - klayout" scrot_klayout -layout $::env(signoff_results)/$::env(DESIGN_NAME).gds -log $::env(signoff_logs)/screenshot.klayout.log } elseif { $::env(PRIMARY_SIGNOFF_TOOL) != "klayout" } { - puts_warn "::env(KLAYOUT_TECH) is not defined for the current PDK. So, GDS-II streaming out using Klayout will be skipped." + puts_warn "::env(KLAYOUT_TECH) is not defined for the current PDK. So, GDSII streaming out using KLayout will be skipped." puts_warn "This warning can be turned off by setting ::env(RUN_KLAYOUT) to 0, or defining a tech file." } else { - puts_err "::env(KLAYOUT_TECH) is not defined for the current PDK, however Klayout is set as the primary signoff tool. This is a critical error." + puts_err "::env(KLAYOUT_TECH) is not defined for the current PDK, however KLayout is set as the primary signoff tool. This is a critical error." flow_fail } @@ -81,17 +81,17 @@ proc scrot_klayout {args} { increment_index TIMER::timer_start set log [index_file $arg_values(-log)] - puts_info "Creating a screenshot using Klayout (log: [relpath . $log])..." + puts_info "Creating a screenshot using KLayout (log: [relpath . $log])..." try_catch bash $::env(SCRIPTS_DIR)/klayout/scrotLayout.sh $::env(KLAYOUT_TECH) $arg_values(-layout) |& tee $::env(TERMINAL_OUTPUT) $log puts_info "Screenshot taken." TIMER::timer_stop exec echo "[TIMER::get_runtime]" | python3 $::env(SCRIPTS_DIR)/write_runtime.py "screenshot - klayout" } elseif { $::env(PRIMARY_SIGNOFF_TOOL) != "klayout" } { - puts_warn "::env(KLAYOUT_DRC_TECH_SCRIPT) is not defined for the current PDK. So, GDS-II streaming out using Klayout will be skipped." + puts_warn "::env(KLAYOUT_DRC_TECH_SCRIPT) is not defined for the current PDK. So, GDSII streaming out using KLayout will be skipped." puts_warn "This warning can be turned off by setting ::env(RUN_KLAYOUT_DRC) to 0, or designating a tech file." } else { - puts_err "::env(KLAYOUT_DRC_TECH_SCRIPT) is not defined for the current PDK, however Klayout is set as the primary signoff tool. This is a critical error." + puts_err "::env(KLAYOUT_DRC_TECH_SCRIPT) is not defined for the current PDK, however KLayout is set as the primary signoff tool. This is a critical error." flow_fail } } @@ -112,18 +112,18 @@ proc run_klayout_drc {args} { increment_index TIMER::timer_start set log [index_file $::env(signoff_logs)/$arg_values(-stage).drc.log] - puts_info "Running DRC on the layout using Klayout (log: [relpath . $log])..." + puts_info "Running DRC on the layout using KLayout (log: [relpath . $log])..." try_catch bash $::env(SCRIPTS_DIR)/klayout/run_drc.sh $::env(KLAYOUT_DRC_TECH_SCRIPT) $arg_values(-gds) $arg_values(-gds).lydrc |& tee $::env(TERMINAL_OUTPUT) $log file copy -force $arg_values(-gds).lydrc [index_file $::env(signoff_reports)/$arg_values(-stage).lydrc] - puts_info "Klayout DRC Complete" + puts_info "KLayout DRC Complete" TIMER::timer_stop exec echo "[TIMER::get_runtime]" | python3 $::env(SCRIPTS_DIR)/write_runtime.py "drc - klayout" } elseif { $::env(PRIMARY_SIGNOFF_TOOL) != "klayout" } { - puts_warn "::env(KLAYOUT_DRC_TECH_SCRIPT) is not defined or doesn't exist for the current PDK. So, GDS-II streaming out using Klayout will be skipped." + puts_warn "::env(KLAYOUT_DRC_TECH_SCRIPT) is not defined or doesn't exist for the current PDK. So, GDSII streaming out using KLayout will be skipped." puts_warn "This warning can be turned off by setting ::env(RUN_KLAYOUT_DRC) to 0, or designating a tech file." } else { - puts_err "::env(KLAYOUT_DRC_TECH_SCRIPT) is not defined or doesn't exist for the current PDK, however Klayout is set as the primary signoff tool. This is a critical error." + puts_err "::env(KLAYOUT_DRC_TECH_SCRIPT) is not defined or doesn't exist for the current PDK, however KLayout is set as the primary signoff tool. This is a critical error." flow_fail } } @@ -146,7 +146,7 @@ proc run_klayout_gds_xor {args} { increment_index TIMER::timer_start set log [index_file $::env(signoff_logs)/xor.log] - puts_info "Running XOR on the layouts using Klayout (log: [relpath . $log])..." + puts_info "Running XOR on the layouts using KLayout (log: [relpath . $log])..." if { $::env(KLAYOUT_XOR_GDS) } { try_catch bash $::env(SCRIPTS_DIR)/klayout/xor.sh \ diff --git a/scripts/tcl_commands/magic.tcl b/scripts/tcl_commands/magic.tcl index 893bb9ac5..bd166bd81 100755 --- a/scripts/tcl_commands/magic.tcl +++ b/scripts/tcl_commands/magic.tcl @@ -20,7 +20,7 @@ proc run_magic {args} { # |---------------- 6. TAPE-OUT ---------------------| # |----------------------------------------------------| set log [index_file $::env(signoff_logs)/gdsii.log] - puts_info "Streaming out GDS-II with Magic (log: [relpath . $log])..." + puts_info "Streaming out GDSII with Magic (log: [relpath . $log])..." # the following MAGTYPE better be mag for clean GDS generation # use load -dereference to ignore it later if needed @@ -101,7 +101,7 @@ proc run_magic_drc {args} { -o $::env(drc_prefix).tcl \ $::env(drc_prefix).rpt - puts_info "Converting Magic DRC Violations to Klayout XML Database..." + puts_info "Converting Magic DRC Violations to KLayout XML Database..." try_catch $::env(OPENROAD_BIN) -python $::env(SCRIPTS_DIR)/drc_rosetta.py magic to_tr\ -o $::env(drc_prefix).tr \ $::env(drc_prefix).rpt