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

## Table of contents
- [Overview](#overview)
- [Getting started](#getting-started)
    - [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)
- [Regression](#regression)
    - [Overview](#overview)
    - [Usage](#usage)
    - [Command line arguments](#command-line-arguments)

# 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. 

## Getting started

### 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][6] and [tapcell][7] 
- Placement: [RePLace][9] (Global) and [OpenDP][10] (Detailed)
- Clock Tree Synthesis: [TritonCTS][11]
- 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 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>
```

_**NOTE: The design name should be named after the design's top level module.**_

## 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 name to run through the flow. It should be the same name as the design folder name and all named after the design's top level module. <br> For example, to run <code>designs/XYZ/</code> use <code>-design XYZ</code><br>
        </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>
</table>

## The Flow

OpenLane flow consists of several stages. Each stage may consist of multiple sub-stages. The following diagram illustrates the flow:

<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 plced comoponents
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. Magic
    1. `magic` - Streams out a GDSII of the final routed def

### 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 created by completeing 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
    ```
    
    - A variant configuration file should define extra variables specific to that variant. It may also override vairables 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 initiallized 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][16]. 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][16].

## Regression

### Overview
- OpenLane provides `run_designs.py`, a script that can do multiple runs in a parallel. A run consists of a design and a configuration file for the given design. For example the following 
has two runs: spm and xtea using their default configuration file `config.tcl.`:

    ```
    python3 run_designs.py --designs spm xtea --tag test --threads 8
    ```

- It can also do "regression" on the designs provided to the script. By providing a file that defines a predefined list of variables 
`run_designs.py` generates all possible combinations of configuration files per designs and runs the flow on each one of them.

- 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 conatins 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

### Usage

The script can be used in two ways

1. Running one or more designs.
    ```
    python3 run_designs.py --designs spm xtea ...
    ```
    
2. A regression 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) scs8ms
    "
    ```
    In addition, `extra` is appended to every configuration file generated. So it is used to add some configurations sepecfic 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.**

### 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.
        </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/<design>/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>


[1]: ./docker_build
[2]: ./designs
[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/Resizer#verilog-to-def
[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/RTimothyEdwards/magic
[16]: ./designs/README.md