      ___   ____   ___  ____   _       ____  ____     ___
     /   \ |    \ /  _]|    \ | |     /    ||    \   /  _]
    |     ||  o  )  [_ |  _  || |    |  o  ||  _  | /  [_
    |  O  ||   _/    _]|  |  || |___ |     ||  |  ||    _]
    |     ||  | |   [_ |  |  ||     ||  _  ||  |  ||   [_
     \___/ |__| |_____||__|__||_____||__|__||__|__||_____| ver 0.95
     

## 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 &lt;name&gt;</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 &lt;name&gt;</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 &lt;name&gt;</code> can be added to rename the config file to <code>&lt;name&gt;.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 &lt;file_path&gt;</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 &lt;file&gt; </code> <br> (Optional)
        </td>
        <td align="justify">
            Creates configuration files using the parameters in <code>&lt;file&gt;</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/&lt;design&gt;/config.tcl</code> and the passed parameters in <code>&lt;file&gt;</code>
        </td>
    </tr>
    <tr>
        <td align="center">
            <code>--tag &lt;name&gt;</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 &lt;number&gt;</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 &lt;config&gt;</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