| ___ ____ ___ ____ _ ____ ____ ___ |
| / \ | \ / _]| \ | | / || \ / _] |
| | || o ) [_ | _ || | | o || _ | / [_ |
| | O || _/ _]| | || |___ | || | || _] |
| | || | | [_ | | || || _ || | || [_ |
| \___/ |__| |_____||__|__||_____||__|__||__|__||_____| ver 0.981 |
| |
| |
| ## Table of contents |
| - [Overview](#overview) |
| - [Getting started](#getting-started) |
| - [Clonning OpenLane](#clonning-openlane) |
| - [Building OpenLane](#building-openlane) |
| - [Running the flow](#running-the-flow) |
| - [Adding a design](#adding-a-design) |
| - [Command line arguments](#command-line-arguments) |
| - [The Flow](#the-flow) |
| - [Flow output](#flow-output) |
| - [Flow configuration](#flow-configuration) |
| - [Interactive Mode](#interactive-mode) |
| - [Regression](#regression) |
| - [Overview](#overview) |
| - [Usage](#usage) |
| - [Output](#output) |
| - [Command line arguments](#command-line-arguments) |
| - [Chip Integration](#chip-integration) |
| |
| ## Overview |
| |
| |
| OpenLane is an automated RTL to GDSII flow based on OpenRoad EDA tools configured for the SkyWater PDK. |
| The flow performs ASIC implementation steps from RTL all the way down to GDSII. |
| |
| |
| <b>NOTICE: </b> |
| <i>This software contains confidential information from SkyWater Technology Foundry. This software is provided to partners of Efabless Corporation through license agreement with SkyWater Technology Foundry Inc.</i> |
| <i>You must have an appropriate confidentiality and license aggrement with SkyWater Technology Foundry Inc in order to access and use this software.</i> |
| |
| |
| ## Getting started |
| |
| ### Clonning OpenLane |
| |
| First install git lfs follow [these instructions]. Which is being used by pdk submodule [20] |
| |
| Then clone the repo: |
| |
| ``` |
| git clone https://vault.efabless.com/foss/openroad.git openlane |
| ``` |
| |
| Then pull the pdk submodule (without it's git history avoiding it's huge size): |
| |
| ``` |
| cd openlane |
| git submodule update --init |
| ``` |
| |
| ### Building OpenLane |
| |
| Before running the flow, you need to build tools used by the flow. OpenLane uses the following tools: |
| - RTL Synthesis & Technology Mapping: [yosys + abc][4] |
| - Static Timing Analysis: [OpenSTA][8] |
| - Floor Planning: [verilog2def][5] (a part of [resizer][15]), [ioPlacer][6], [pdn][16] and [tapcell][7] |
| - Placement: [RePLace][9] (Global) and [OpenDP][10] (Detailed) |
| - Clock Tree Synthesis: [TritonCTS][11] |
| - Fill Insertion: [addspacers][18] |
| - Routing: [FastRoute][12] (Global) and [TritonRoute][13] (Detailed) |
| - GDSII Streaming out: [Magic][14] |
| |
| The [following instructions][1] walk you through the process of using docker containers to build the needed tools then integrate them into OpenLane flow. |
| |
| ### Running the flow |
| |
| After building the docker image, issue the following command to open the docker container: |
| |
| ```bash |
| docker run -it openlane:latest |
| ``` |
| The docker container will open in the directory of the openlane flow. |
| |
| You can also issue the following command from the project root, to ensure that the output files persist after exiting the container: |
| |
| |
| ```bash |
| docker run -itv $(pwd):/openLANE_flow openlane:latest |
| ``` |
| |
| **Note: this will mirror the openlane directory inside the container.** |
| |
| |
| Then, you can test the flow using one of the provided designs (spm: Serial-Parallel Adder) by running: |
| |
| ```bash |
| ./flow.tcl -design spm |
| ``` |
| |
| ### Adding a design |
| |
| To add a new design, the following command creates a configuration file for your design: |
| |
| ```bash |
| ./flow.tcl -design <design_name> -init_design_config |
| ``` |
| |
| This will create the following directory structure: |
| |
| ```bash |
| designs/<design_name> |
| ├── config.tcl |
| ``` |
| In the configuration file, you should edit the required variables and the optional variables, if needed. Further information about the variables can be found [here][2] |
| |
| It is recommended to place the design's verilog files in a `src` directory inside the design's folder as following: |
| |
| ```bash |
| designs/<design_name> |
| ├── config.tcl |
| ├── src |
| │ ├── design.v |
| ``` |
| |
| Optionally, you can specify the configuration file name (without the extension) by using: |
| |
| ```bash |
| ./flow.tcl -design <design_name> -init_design_config -tag <config_name> |
| ``` |
| |
| After adding the design, you can specify the design name using a `-design` argument: |
| |
| ```bash |
| ./flow.tcl -design <design_name> |
| ``` |
| |
| Finally, you can specify the configuration file (belonging to that design) the flow should use: |
| |
| ```bash |
| ./flow.tcl -design <design_name> -config <config_name> |
| ``` |
| |
| |
| ## Command line arguments |
| |
| The following are arguments that can be passed to `flow.tcl` |
| |
| <table> |
| <tr> |
| <th width="196"> |
| Argument |
| </th> |
| <th > |
| Description |
| </th> |
| </tr> |
| <tr> |
| <td align="center"> |
| <code>-design</code> <br> (Required) |
| </td> |
| <td align="justify"> |
| Specifies the design folder. A design folder should contain a config.tcl definig the design parameters. <br> If the folder is not found, ./designs directory is searched |
| </td> |
| </tr> |
| <tr> |
| <td align="center"> |
| <code>-config <name></code> <br> (Optional) |
| </td> |
| <td align="justify"> |
| Specifies the design's configuration file for while running the flow. <br> For example, to run the flow using <code>designs/spm/config2.tcl</code> <br> Use run <code>./flow.tcl -design spm -config config2.tcl</code> <br> By default <code>config.tcl</code> is used. |
| </td> |
| </tr> |
| <tr> |
| </tr> |
| <td align="center"> |
| <code>-tag <name></code> <br> (Optional) |
| </td> |
| <td align="justify"> |
| Specifies a <code>name</code> for a specific run. If the tag is not specified, a timestamp is generated for identification of that run. <br> Can Specify the configuration file name in case of using <code>-init_design_config</code> |
| </td> |
| </tr> |
| <tr> |
| </tr> |
| <td align="center"> |
| <code>-init_design_config </code> <br> (Optional) |
| </td> |
| <td td align="justify"> |
| Creates a tcl configuration file for a design. <code>-tag <name></code> can be added to rename the config file to <code><name>.tcl</code> |
| </td> |
| </tr> |
| <tr> |
| </tr> |
| <td align="center"> |
| <code>-overwrite</code> <br> (Optional) |
| </td> |
| <td align="justify"> |
| Flag to overwirte an existing run with the same tag |
| </td> |
| </tr> |
| <tr> |
| </tr> |
| <td align="center"> |
| <code>-interactive</code> <br> (Optional) |
| </td> |
| <td align="justify"> |
| Flag to run openlane flow in interactive mode |
| </td> |
| </tr> |
| <tr> |
| </tr> |
| <td align="center"> |
| <code>-file <file_path></code> <br> (Optional) |
| </td> |
| <td align="justify"> |
| Passes a script of interactive commands in interactive mode |
| </td> |
| </tr> |
| </table> |
| |
| ## The Flow |
| |
| OpenLane flow consists of several stages. Each stage may consist of multiple sub-stages. OpenLane can run either interactively (the designer executes the flow steps one by one) or non-interactively (default; running all the flow steps one after another). The following diagram illustrates the flow steps: |
| |
| <table> |
| <tr> |
| <td width=1800 align="middle"><img src="./doc/flow.png" height="40%"></td> |
| </tr> |
| </table> |
| <sub>(1) designs/design/runs/tag/results/synthesis/design.synthesis.v</sub><br> |
| <sub>(2) designs/design/runs/tag/results/floorplan/design.floorplan.def</sub><br> |
| <sub>(3) designs/design/runs/tag/results/placement/design.placement.def</sub><br> |
| <sub>(4) designs/design/runs/tag/results/cts/design.cts.def</sub><br> |
| <sub>(5) designs/design/runs/tag/results/routing/design.routing.def</sub><br> |
| <sub>(6) designs/design/runs/tag/results/magic/design.magic.gds</sub><br> |
| |
| |
| |
| 1. **Synthesis** |
| 1. `yosys` - Performs RTL synthesis |
| 2. `abc` - Performs technology mapping |
| 3. `OpenSTA` - Pefroms static timing analysis on the resulting netlist to generate timing reports |
| 2. **Floorplan and PDN** |
| 1. `verilog2def` - 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. `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 |
| 6. **GDSII Generation** |
| 1. `magic` - Streams out the final GDSII layout file from the routed def |
| |
| <sub>* addspacers is run just before routing to insert fill cells </sub> |
| |
| ### Flow output |
| |
| After running a design, a directory called `runs` is created inside that design folder. Each run is placed under that directory. |
| A run is either named after `-tag` or named with a timestamp of that run. |
| A run folder contains: |
| |
| 1. The run configuration |
| 2. Four directories. Inside each, there is a folder per stage of the flow |
| 1. `logs` - Runtime log of each tool. Can be useful in case of a crash. |
| 2. `reports` - Reports generated by some of the tools. (i.e. synthesis report, timing report, etc...) |
| 3. `results` - Final files created by completing a stage. Can either be `.def` or `.v` or `.gds`. |
| 4. `tmp` - Files created by substages. |
| |
| The resulting directory tree is as follows: |
| |
| ``` |
| designs/spm |
| ├── config.tcl |
| ├── runs |
| │ ├── <tag> |
| │ │ ├── config.tcl |
| │ │ ├── logs |
| │ │ │ ├── cts |
| │ │ │ ├── floorplan |
| │ │ │ ├── magic |
| │ │ │ ├── placement |
| │ │ │ ├── routing |
| │ │ │ └── synthesis |
| │ │ ├── reports |
| │ │ │ ├── cts |
| │ │ │ ├── floorplan |
| │ │ │ ├── magic |
| │ │ │ ├── placement |
| │ │ │ ├── routing |
| │ │ │ └── synthesis |
| │ │ ├── results |
| │ │ │ ├── cts |
| │ │ │ ├── floorplan |
| │ │ │ ├── magic |
| │ │ │ ├── placement |
| │ │ │ ├── routing |
| │ │ │ └── synthesis |
| │ │ └── tmp |
| │ │ ├── cts |
| │ │ ├── floorplan |
| │ │ ├── magic |
| │ │ ├── placement |
| │ │ ├── routing |
| │ │ └── synthesis |
| ``` |
| |
| ### Flow configuration |
| |
| OpenLane requires some environment variables to be defined. These variables are split into three main categories: |
| |
| 1. PDK specific |
| 2. Flow specific |
| 3. Design specific |
| |
| - A PDK should define at least one variant for the PDK. A common configuration file for all PDK variants is located in: |
| |
| ``` |
| ./pdks/<pdk>/common_config.tcl |
| ``` |
| |
| - Sometimes the PDK comes with several Standard Cell Libraries or Metal Stacks. Each is considered as a PDK variant. A variant configuration file defines extra variables specific to the variant. It may also override variables in the common PDK configuration file which is located in: |
| |
| ``` |
| ./pdks/<pdk>/<variant>/config.tcl |
| ``` |
| |
| - 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: |
| |
| ``` |
| ./designs/<design>/config.tcl |
| ``` |
| |
| A list of all available variables can be found [here][17]. |
| |
| |
| ### Interactive Mode |
| You may run the flow interactively by using the `-interactive` option: |
| |
| ``` |
| ./flow.tcl -interactive |
| ``` |
| |
| A tcl shell will be opened where you must first source the openlane package: |
| ``` |
| % package require openlane 0.9 |
| ``` |
| |
| Then, you should be able to run the following commands: |
| |
| 1. `prep -design <design> -tag <tag> -config <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` |
| 4. `run_placement` |
| 5. `run_cts` |
| 6. `run_routing` |
| 7. `run_magic` |
| |
| The above commands can also be written in a file and passed to `flow.tcl`: |
| |
| ``` |
| ./flow.tcl -interactive -file <file> |
| ``` |
| |
| Note 1: Currently, configuration variables have higher priority over the above commands so if `RUN_MAGIC` is 0, command `run_magic` will have no effect. |
| |
| Note 2: Currently, all these commands must be run in sequence and none should be omitted. |
| |
| |
| ## Regression |
| |
| ### 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. |
| |
| Also, it can be used for testing the flow by running the flow against several designs using their best configurations. For example the following has two runs: spm and xtea using their default configuration files `config.tcl.` : |
| ``` |
| python3 run_designs.py --designs spm xtea des aes256 raven_soc --tag test --threads 3 |
| ``` |
| |
| ### Usage |
| |
| The script can be used in two ways |
| |
| 1. Running one or more designs. |
| ``` |
| python3 run_designs.py --designs spm xtea PPU APU |
| ``` |
| |
| 2. An exploration run that generates configuration files of all possible combinations of the passed regression file and runs them on the provided designs. |
| ``` |
| python3 run_designs.py --designs spm xtea --regression ./scripts/config/regression.config |
| ``` |
| These parameters must be provided in the file passed to `--regression`. Any file can be used. The file used above is just an example |
| ``` |
| adjustment_factor=(0.1 0.15) |
| utilization=(40 50) |
| density=(0.4) |
| synth_strategy=(1 3) |
| pdn_v_pitch=("153.6") |
| pdn_h_pitch=("153.18") |
| aspect_ratio=(1) |
| max_fanout=(5) |
| |
| extra=" |
| set ::env(PDK_VARIANT) efs8hd |
| " |
| ``` |
| In addition, `extra` is appended to every configuration file generated. So it is used to add some configurations specific to this regression run. |
| |
| **Important Note:** *If you are going to launch two or more separate regression runs that include same design(s), make sure to set different tags for them using the `--tag` option.* |
| |
| ### Output |
| - In addition to files produced inside `designs/<design>/runs/config_<tag>_<number>` for each run on a design, three files are produced: |
| 1. `logs/<tag>_<timestamp>.log` A log file that describes start and stopping time of a given run. |
| 2. `logs/<tag>_<timestamp>.rpt` A report file that provides a summary of each run. The summary contains some metrics and the configuration of that run |
| 3. `logs/<tag>_<timestamp>_best.rpt` A report file that selects the best configuration per design based on number of violations |
| |
| ### Command line arguments |
| <table> |
| <tr> |
| <th> |
| Argument |
| </th> |
| <th > |
| Description |
| </th> |
| </tr> |
| <tr> |
| <td align="center"> |
| <code>--designs design1 design2 design3 ...</code> <br> (Required) |
| </td> |
| <td align="justify"> |
| Specifies the designs to run. Similar to the argument of <code>./flow.tcl -design</code> |
| </td> |
| </tr> |
| <tr> |
| </tr> |
| <td align="center"> |
| <code>--regression <file> </code> <br> (Optional) |
| </td> |
| <td align="justify"> |
| Creates configuration files using the parameters in <code><file></code> and runs the configuration files on each design <br> |
| The generated configuration files are based on the default config file in each design <code>designs/<design>/config.tcl</code> and the passed parameters in <code><file></code> |
| </td> |
| </tr> |
| <tr> |
| <td align="center"> |
| <code>--tag <name></code> <br> (Optional) |
| </td> |
| <td align="justify"> |
| Appends a tag to the log files in <code>logs/</code> and the generated configuration files when passing <code>--regression</code> <br> Default value: <code>regression</code> |
| </td> |
| </tr> |
| <tr> |
| </tr> |
| <td align="center"> |
| <code>--threads <number></code> <br> (Optional) |
| </td> |
| <td align="justify"> |
| Number of threads <br> Default value: <code>5</code> |
| </td> |
| </tr> |
| <tr> |
| </tr> |
| <td align="center"> |
| <code>--config <config></code> <br> (Optional) |
| </td> |
| <td align="justify"> |
| Defines the configuration file to be used in NON regression mode<br> Default value: <code>config</code> |
| </td> |
| </tr> |
| </table> |
| |
| ### Chip Integration |
| |
| Using openlane, you can produce a GDSII from a chip RTL. |
| |
| For example, striVe: |
| |
| <table> |
| <tr> |
| <td width=1800 align="middle"><img src="./doc/striVe.jpeg" height="30%"></td> |
| </tr> |
| |
| </table> |
| |
| The current methodology involves first hardenning the modules inside the chip as macros, then use these macros to generate the chip GDSII. |
| |
| The following inputs are provided to produce striVe GDSII: |
| |
| 1. Padframe def file |
| 2. Padframe cfg file |
| 3. Hardened lefs for striVe's inner modules |
| 4. Top level netlist instantiating pads and inner modules |
| 5. Core def with inner modules (placed?) |
| |
| Given these inputs the following [interactive script][19] script. Mainly, it does the following steps: |
| - Parse the padframe cfg file to get the diearea and input it to the floorplanner |
| - Combine the pads lef, macros lefs and tech lef in one lef file |
| - Run the top level netlist through yosys (as a sanity check?) |
| - Running `chip_floorplan` which first generates a floorplan using `verilog2def` followed by removing PINS section and cleaning NETS section in the generated def file |
| - Replace the components of the floorplan def file with placed components from padframe def file and core def file |
| - Finally route the design and generate a GDSII file of the routed design |
| |
| [1]: ./docker_build/README.md |
| [2]: ./configuration/README.md |
| [3]: ./doc/flow.png |
| [4]: https://github.com/YosysHQ/yosys |
| [5]: https://github.com/The-OpenROAD-Project/Resizer#verilog-to-def |
| [6]: https://github.com/The-OpenROAD-Project/ioPlacer/ |
| [7]: https://github.com/The-OpenROAD-Project/tapcell |
| [8]: https://github.com/The-OpenROAD-Project/OpenSTA |
| [9]: https://github.com/The-OpenROAD-Project/RePlAce |
| [10]: https://github.com/The-OpenROAD-Project/OpenDP |
| [11]: https://github.com/The-OpenROAD-Project/TritonCTS |
| [12]: https://github.com/The-OpenROAD-Project/FastRoute4-lefdef |
| [13]: https://github.com/The-OpenROAD-Project/TritonRoute |
| [14]: https://github.com/RTimothyEdwards/magic |
| [15]: https://github.com/The-OpenROAD-Project/Resizer |
| [16]: https://github.com/The-OpenROAD-Project/pdn/ |
| [17]: ./configuration/README.md |
| [18]: https://github.com/RTimothyEdwards/qflow/blob/master/src/addspacers.c |
| [19]: ./designs/striVe_toplevel/toplevel.tcl |
| [20]: https://github.com/git-lfs/git-lfs/wiki/Installation |
