1Getting Started
2===============
3
4OpenROAD is divided into a number of tools that are orchestrated
5together to achieve RTL-to-GDS. As of the current implementation, the
6flow is divided into two stages:
7
81. Logic Synthesis: is performed by `yosys`_.
92. Floorplanning through Detailed Routing: are performed by `OpenROAD App`_.
10
11In order to integrate the flow steps, `OpenROAD-flow-scripts`_ repository includes
12the necessary scripts to build and test the flow.
13
14Prerequisites
15-------------
16
17Before proceeding to the next step:
181. Install `Docker`_ on your machine, OR
192. Check that build dependencies for all tools are installed on your machine.
20   During initial Setup or if you have installed on a new machine, run this script:
21   run ./etc/DependencyInstaller.sh
22
23Get the tools
24-------------
25
26There are currently two options to get OpenROAD tools.
27
28Option 1: build from sources using Docker
29~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
30
31Clone and Build
32+++++++++++++++
33
34.. code-block:: shell
35
36   $ git clone --recursive https://github.com/The-OpenROAD-Project/OpenROAD-flow-scripts
37   $ cd OpenROAD-flow-scripts
38   $ ./build_openroad.sh
39
40Verify Installation
41+++++++++++++++++++
42
43The binaries should be available on your ``$PATH`` after setting up the
44environment.
45
46.. code-block:: shell
47
48   $ docker run -it -u $(id -u ${USER}):$(id -g ${USER}) -v $(pwd)/flow/platforms:/OpenROAD-flow-scripts/flow/platforms:ro openroad/flow-scripts
49   [inside docker] $ source ./setup_env.sh
50   [inside docker] $ yosys -help
51   [inside docker] $ openroad -help
52   [inside docker] $ cd flow
53   [inside docker] $ make
54   [inside docker] $ exit
55
56Option 2: Build from sources locally
57~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
58
59Clone and Build
60+++++++++++++++
61
62.. code-block:: shell
63
64   $ git clone --recursive https://github.com/The-OpenROAD-Project/OpenROAD-flow-scripts
65   $ cd OpenROAD-flow-scripts
66   $ ./build_openroad.sh --local
67
68Verify Installation
69+++++++++++++++++++
70
71The binaries should be available on your ``$PATH`` after setting up the
72environment.
73
74.. code-block:: shell
75
76   $ source ./setup_env.sh
77   $ yosys -help
78   $ openroad -help
79   $ exit
80
81Designs
82-------
83
84Sample design configurations are available in the ``designs`` directory.
85You can select a design using either of the following methods:
86
871. The flow `Makefile`_ contains a list of sample design configurations at
88the top of the file.  Uncomment the respective line to select the design
892. Specify the design using the shell environment, e.g.
90``make DESIGN_CONFIG=./designs/nangate45/swerv/config.mk`` or
91``export DESIGN_CONFIG=./designs/nangate45/swerv/config.mk ; make``
92
93By default, the simple design gcd is selected. We recommend implementing
94this design first to validate your flow and tool setup.
95
96Adding a New Design
97~~~~~~~~~~~~~~~~~~~
98
99To add a new design, we recommend looking at the included designs for
100examples of how to set one up.
101
102Platforms
103---------
104
105OpenROAD-flow-scripts supports Verilog to GDS for the following open platforms:
106Nangate45 / FreePDK45
107
108These platforms have a permissive license which allows us to
109redistribute the PDK and OpenROAD platform-specific files. The platform
110files and license(s) are located in ``platforms/{platform}``.
111
112OpenROAD-flow-scripts also supports the following commercial platforms: TSMC65LP /
113GF14 (in progress)
114
115The PDKs and platform-specific files for these kits cannot be provided
116due to NDA restrictions. However, if you are able to access these
117platforms, you can create the necessary platform-specific files
118yourself.
119
120Once the platform is setup. Create a new design configuration with
121information about the design. See sample configurations in the
122``design`` directory.
123
124Adding a New Platform
125~~~~~~~~~~~~~~~~~~~~~
126
127At this time, we recommend looking at the `Nangate45`_ as an example of
128how to set up a new platform for OpenROAD-flow-scripts.
129
130Implement the Design
131--------------------
132
133Run ``make`` to perform Verilog to GDS. The final output will be located
134at ``flow/results/{platform}/{design_name}/6_final.gds``
135
136Miscellaneous
137-------------
138
139tiny-tests - easy to add, single concern, single Verilog file
140~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
141
142The tiny-tests are have been designed with two design goals in mind:
143
1441. It should be trivial to add a new test: simply add a tiny standalone
145   Verilog file to ``OpenROAD-flow-scripts/flow/designs/src/tiny-tests``
1462. Each test should be as small and as standalone as possible and be a
147   single concern test.
148
149To run a test:
150
151.. code-block:: shell
152
153   make DESIGN_NAME=SmallPinCount DESIGN_CONFIG=`pwd`/designs/tiny-tests.mk
154
155nangate45 smoke-test harness for top level Verilog designs
156~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
157
1581. Drop your Verilog files into designs/src/harness
1592. Start the workflow:
160
161.. code-block:: shell
162
163   make DESIGN_NAME=TopLevelName DESIGN_CONFIG=`pwd`/designs/harness.mk
164
165
166.. note::
167   TIP! Start with a small tiny submodule in your design with few pins
168
169.. _`yosys`: https://github.com/The-OpenROAD-Project/yosys
170.. _`releases page on GitHub`: https://github.com/The-OpenROAD-Project/OpenROAD-flow-scripts/releases
171.. _`OpenROAD App`: https://github.com/The-OpenROAD-Project/OpenROAD
172.. _`OpenROAD-flow-scripts`: https://github.com/The-OpenROAD-Project/OpenROAD-flow-scripts
173.. _`yosys Dockerfile`: https://github.com/The-OpenROAD-Project/yosys/blob/master/Dockerfile
174.. _`DependencyInstaller.sh`: https://github.com/The-OpenROAD-Project/OpenROAD/blob/master/etc/DependencyInstaller.sh
175.. _`Docker`: https://docs.docker.com/engine/install
176.. _`Makefile`: https://github.com/The-OpenROAD-Project/OpenROAD-flow-scripts/blob/master/flow/Makefile
177.. _`Nangate45`: https://github.com/The-OpenROAD-Project/OpenROAD-flow-scripts/tree/master/flow/platforms/nangate45
178