Mohamed Kassem | 6f2fcd2 | 2021-04-19 10:14:19 -0700 | [diff] [blame] | 1 | .. raw:: html |
| 2 | |
| 3 | <!--- |
| 4 | # SPDX-FileCopyrightText: 2020 Efabless Corporation |
| 5 | # |
| 6 | # Licensed under the Apache License, Version 2.0 (the "License"); |
| 7 | # you may not use this file except in compliance with the License. |
| 8 | # You may obtain a copy of the License at |
| 9 | # |
| 10 | # http://www.apache.org/licenses/LICENSE-2.0 |
| 11 | # |
| 12 | # Unless required by applicable law or agreed to in writing, software |
| 13 | # distributed under the License is distributed on an "AS IS" BASIS, |
| 14 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| 15 | # See the License for the specific language governing permissions and |
| 16 | # limitations under the License. |
| 17 | # |
| 18 | # SPDX-License-Identifier: Apache-2.0 |
| 19 | --> |
| 20 | |
| 21 | Caravel User Project |
| 22 | ==================== |
| 23 | |
manarabdelaty | d0e7afb | 2021-04-22 00:21:13 +0200 | [diff] [blame] | 24 | |License| |User CI| |Caravel Build| |
Mohamed Kassem | 6f2fcd2 | 2021-04-19 10:14:19 -0700 | [diff] [blame] | 25 | |
| 26 | Table of contents |
| 27 | ================= |
| 28 | |
| 29 | - `Overview <#overview>`__ |
Jeff DiCorpo | 43dc6d9 | 2022-10-27 18:00:26 -0700 | [diff] [blame] | 30 | - `Quickstart <#quickstart>`__ |
Mohamed Kassem | 6f2fcd2 | 2021-04-19 10:14:19 -0700 | [diff] [blame] | 31 | - `Caravel Integration <#caravel-integration>`__ |
| 32 | |
| 33 | - `Repo Integration <#repo-integration>`__ |
| 34 | - `Verilog Integration <#verilog-integration>`__ |
Jeff DiCorpo | c26d59e | 2022-11-18 18:55:27 -0800 | [diff] [blame] | 35 | - `GPIO Configuration <#gpio-configuration>`__ |
Manar | 4ec8cba | 2021-10-04 10:26:10 -0500 | [diff] [blame] | 36 | - `Layout Integration <#layout-integration>`__ |
Mohamed Kassem | 6f2fcd2 | 2021-04-19 10:14:19 -0700 | [diff] [blame] | 37 | |
| 38 | - `Running Full Chip Simulation <#running-full-chip-simulation>`__ |
Manar | 4ec8cba | 2021-10-04 10:26:10 -0500 | [diff] [blame] | 39 | - `User Project Wrapper Requirements <#user-project-wrapper-requirements>`__ |
| 40 | - `Hardening the User Project using |
| 41 | Openlane <#hardening-the-user-project-using-openlane>`__ |
Jeff DiCorpo | d3f3d20 | 2022-11-18 23:39:01 -0800 | [diff] [blame^] | 42 | - `Running Timing Analysis on Existing Projects <#running-timing-analysis-on-existing-projects>`__ |
Mohamed Kassem | 6f2fcd2 | 2021-04-19 10:14:19 -0700 | [diff] [blame] | 43 | - `Checklist for Open-MPW |
| 44 | Submission <#checklist-for-open-mpw-submission>`__ |
| 45 | |
| 46 | Overview |
| 47 | ======== |
| 48 | |
| 49 | This repo contains a sample user project that utilizes the |
| 50 | `caravel <https://github.com/efabless/caravel.git>`__ chip user space. |
| 51 | The user project is a simple counter that showcases how to make use of |
| 52 | `caravel's <https://github.com/efabless/caravel.git>`__ user space |
| 53 | utilities like IO pads, logic analyzer probes, and wishbone port. The |
| 54 | repo also demonstrates the recommended structure for the open-mpw |
| 55 | shuttle projects. |
| 56 | |
manarabdelaty | d8dd010 | 2021-04-30 08:40:52 +0200 | [diff] [blame] | 57 | Prerequisites |
| 58 | ============= |
| 59 | |
Marwan Abbas | 0914d04 | 2022-04-06 19:06:34 +0200 | [diff] [blame] | 60 | - Docker: `Linux <https://hub.docker.com/search?q=&type=edition&offering=community&operating_system=linux&utm_source=docker&utm_medium=webreferral&utm_campaign=dd-smartbutton&utm_location=header>`_ || `Windows <https://desktop.docker.com/win/main/amd64/Docker%20Desktop%20Installer.exe?utm_source=docker&utm_medium=webreferral&utm_campaign=dd-smartbutton&utm_location=header>`_ || `Mac with Intel Chip <https://desktop.docker.com/mac/main/amd64/Docker.dmg?utm_source=docker&utm_medium=webreferral&utm_campaign=dd-smartbutton&utm_location=header>`_ || `Mac with M1 Chip <https://desktop.docker.com/mac/main/arm64/Docker.dmg?utm_source=docker&utm_medium=webreferral&utm_campaign=dd-smartbutton&utm_location=header>`_ |
| 61 | |
| 62 | - Python 3.6+ with PIP |
manarabdelaty | d8dd010 | 2021-04-30 08:40:52 +0200 | [diff] [blame] | 63 | |
Jeff DiCorpo | 43dc6d9 | 2022-10-27 18:00:26 -0700 | [diff] [blame] | 64 | |
| 65 | Quickstart |
| 66 | =========== |
| 67 | |
| 68 | --------------------- |
| 69 | Starting your project |
| 70 | --------------------- |
| 71 | |
| 72 | #. To start the project you first need to create a new repository based on the `caravel_user_project <https://github.com/efabless/caravel_user_project/>`_ template and make sure your repo is public and includes a README. |
| 73 | |
| 74 | * Follow https://github.com/efabless/caravel_user_project/generate to create a new repository. |
| 75 | * Clone the reposity using the following command: |
| 76 | |
Kareem Farid | f421b8e | 2022-11-15 18:38:45 +0000 | [diff] [blame] | 77 | .. code:: bash |
| 78 | |
| 79 | git clone <your github repo URL> |
Jeff DiCorpo | 43dc6d9 | 2022-10-27 18:00:26 -0700 | [diff] [blame] | 80 | |
| 81 | #. To setup your local environment run: |
| 82 | |
| 83 | .. code:: bash |
| 84 | |
| 85 | cd <project_name> # project_name is the name of your repo |
| 86 | |
| 87 | mkdir dependencies |
| 88 | |
| 89 | export OPENLANE_ROOT=$(pwd)/dependencies/openlane_src # you need to export this whenever you start a new shell |
| 90 | |
| 91 | export PDK_ROOT=$(pwd)/dependencies/pdks # you need to export this whenever you start a new shell |
| 92 | |
| 93 | # export the PDK variant depending on your shuttle, if you don't know leave it to the default |
Jeff DiCorpo | b764059 | 2022-10-27 18:31:04 -0700 | [diff] [blame] | 94 | |
| 95 | # for sky130 MPW shuttles.... |
Jeff DiCorpo | 43dc6d9 | 2022-10-27 18:00:26 -0700 | [diff] [blame] | 96 | export PDK=sky130B |
Jeff DiCorpo | b764059 | 2022-10-27 18:31:04 -0700 | [diff] [blame] | 97 | |
| 98 | # for the gf180 GFMPW shuttles... |
| 99 | export PDK=gf180mcuC |
| 100 | |
| 101 | |
Jeff DiCorpo | 43dc6d9 | 2022-10-27 18:00:26 -0700 | [diff] [blame] | 102 | |
| 103 | make setup |
| 104 | |
Kareem Farid | f421b8e | 2022-11-15 18:38:45 +0000 | [diff] [blame] | 105 | * This command will setup your environment by installing the following |
Jeff DiCorpo | 43dc6d9 | 2022-10-27 18:00:26 -0700 | [diff] [blame] | 106 | |
Kareem Farid | f421b8e | 2022-11-15 18:38:45 +0000 | [diff] [blame] | 107 | - caravel_lite (a lite version of caravel) |
| 108 | - management core for simulation |
| 109 | - openlane to harden your design |
| 110 | - pdk |
Jeff DiCorpo | 43dc6d9 | 2022-10-27 18:00:26 -0700 | [diff] [blame] | 111 | |
| 112 | |
| 113 | #. Now you can start hardening your design |
| 114 | |
| 115 | * To start hardening you project you need |
| 116 | - RTL verilog model for your design for OpenLane to harden |
| 117 | - A subdirectory for each macro in your project under ``openlane/`` directory, each subdirectory should include openlane configuration files for the macro |
| 118 | |
Kareem Farid | f421b8e | 2022-11-15 18:38:45 +0000 | [diff] [blame] | 119 | .. code:: bash |
Jeff DiCorpo | 43dc6d9 | 2022-10-27 18:00:26 -0700 | [diff] [blame] | 120 | |
Kareem Farid | f421b8e | 2022-11-15 18:38:45 +0000 | [diff] [blame] | 121 | make <module_name> |
| 122 | .. |
Jeff DiCorpo | 43dc6d9 | 2022-10-27 18:00:26 -0700 | [diff] [blame] | 123 | |
Kareem Farid | 128c525 | 2022-11-15 18:45:41 +0000 | [diff] [blame] | 124 | For an example of hardening a project please refer to `Hardening the User Project using OpenLane`_. . |
Jeff DiCorpo | 43dc6d9 | 2022-10-27 18:00:26 -0700 | [diff] [blame] | 125 | |
| 126 | #. Integrate modules into the user_project_wrapper |
| 127 | |
| 128 | * Change the environment variables ``VERILOG_FILES_BLACKBOX``, ``EXTRA_LEFS`` and ``EXTRA_GDS_FILES`` in ``openlane/user_project_wrapper/config.tcl`` to point to your module |
| 129 | * Instantiate your module(s) in ``verilog/rtl/user_project_wrapper.v`` |
| 130 | * Harden the user_project_wrapper including your module(s), using this command: |
| 131 | |
| 132 | .. code:: bash |
| 133 | |
| 134 | make user_project_wrapper |
| 135 | |
| 136 | #. Run simulation on your design |
| 137 | |
| 138 | * You need to include your rtl/gl/gl+sdf files in ``verilog/includes/includes.<rtl/gl/gl+sdf>.caravel_user_project`` |
| 139 | |
| 140 | **NOTE:** You shouldn't include the files inside the verilog code |
| 141 | |
| 142 | .. code:: bash |
| 143 | |
| 144 | # you can then run RTL simulations using |
| 145 | make verify-<testbench-name>-rtl |
| 146 | |
| 147 | # OR GL simulation using |
| 148 | make verify-<testbench-name>-gl |
| 149 | |
| 150 | # OR for GL+SDF simulation using |
| 151 | # sdf annotated simulation is slow |
| 152 | make verify-<testbench-name>-gl-sdf |
| 153 | |
| 154 | # for example |
| 155 | make verify-io_ports-rtl |
Kareem Farid | 1c1b894 | 2022-11-15 20:59:10 +0200 | [diff] [blame] | 156 | |
| 157 | #. Run opensta on your design |
| 158 | |
| 159 | * Extract spefs for ``user_project_wrapper`` and macros inside it: |
| 160 | |
| 161 | .. code:: bash |
| 162 | |
| 163 | make extract-parasitics |
| 164 | |
| 165 | * Create spef mapping file that maps instance names to spef files: |
| 166 | |
| 167 | .. code:: bash |
| 168 | |
| 169 | make create-spef-mapping |
| 170 | |
| 171 | * Run opensta: |
| 172 | |
| 173 | .. code:: bash |
| 174 | |
| 175 | make caravel-sta |
| 176 | |
| 177 | **NOTE:** To update timing scripts run ``make setup-timing-scripts`` |
Jeff DiCorpo | 43dc6d9 | 2022-10-27 18:00:26 -0700 | [diff] [blame] | 178 | |
| 179 | #. Run the precheck locally |
| 180 | |
| 181 | .. code:: bash |
| 182 | |
| 183 | make precheck |
| 184 | make run-precheck |
| 185 | |
| 186 | #. You are done! now go to https://efabless.com/open_shuttle_program/ to submit your project! |
| 187 | |
| 188 | |
Mohamed Kassem | 6f2fcd2 | 2021-04-19 10:14:19 -0700 | [diff] [blame] | 189 | Caravel Integration |
| 190 | =================== |
| 191 | |
Kareem Farid | e3b5c47 | 2022-11-15 16:35:21 +0000 | [diff] [blame] | 192 | ---------------- |
Mohamed Kassem | 6f2fcd2 | 2021-04-19 10:14:19 -0700 | [diff] [blame] | 193 | Repo Integration |
| 194 | ---------------- |
| 195 | |
| 196 | Caravel files are kept separate from the user project by having caravel |
manarabdelaty | d0e7afb | 2021-04-22 00:21:13 +0200 | [diff] [blame] | 197 | as submodule. The submodule commit should point to the latest of |
Manar | 4ec8cba | 2021-10-04 10:26:10 -0500 | [diff] [blame] | 198 | caravel/caravel-lite master/main branch. The following files should have a symbolic |
manarabdelaty | d0e7afb | 2021-04-22 00:21:13 +0200 | [diff] [blame] | 199 | link to `caravel's <https://github.com/efabless/caravel.git>`__ |
| 200 | corresponding files: |
Mohamed Kassem | 6f2fcd2 | 2021-04-19 10:14:19 -0700 | [diff] [blame] | 201 | |
manarabdelaty | 0c03d60 | 2021-09-20 11:42:16 +0200 | [diff] [blame] | 202 | - `Openlane Makefile <../../openlane/Makefile>`__: This provides an easier |
manarabdelaty | d0e7afb | 2021-04-22 00:21:13 +0200 | [diff] [blame] | 203 | way for running openlane to harden your macros. Refer to `Hardening |
| 204 | the User Project Macro using |
Marwan Abbas | ca9b692 | 2022-01-26 20:27:03 +0200 | [diff] [blame] | 205 | Openlane <#hardening-the-user-project-using-openlane>`__. Also, |
manarabdelaty | d0e7afb | 2021-04-22 00:21:13 +0200 | [diff] [blame] | 206 | the makefile retains the openlane summary reports under the signoff |
| 207 | directory. |
Mohamed Kassem | 6f2fcd2 | 2021-04-19 10:14:19 -0700 | [diff] [blame] | 208 | |
manarabdelaty | 0c03d60 | 2021-09-20 11:42:16 +0200 | [diff] [blame] | 209 | - `Pin order <../../openlane/user_project_wrapper/pin_order.cfg>`__ file for |
Mohamed Kassem | 6f2fcd2 | 2021-04-19 10:14:19 -0700 | [diff] [blame] | 210 | the user wrapper: The hardened user project wrapper macro must have |
| 211 | the same pin order specified in caravel's repo. Failing to adhere to |
| 212 | the same order will fail the gds integration of the macro with |
| 213 | caravel's back-end. |
| 214 | |
manarabdelaty | d0e7afb | 2021-04-22 00:21:13 +0200 | [diff] [blame] | 215 | The symbolic links are automatically set when you run ``make install``. |
Mohamed Kassem | 6f2fcd2 | 2021-04-19 10:14:19 -0700 | [diff] [blame] | 216 | |
Kareem Farid | e3b5c47 | 2022-11-15 16:35:21 +0000 | [diff] [blame] | 217 | ------------------- |
Mohamed Kassem | 6f2fcd2 | 2021-04-19 10:14:19 -0700 | [diff] [blame] | 218 | Verilog Integration |
| 219 | ------------------- |
| 220 | |
| 221 | You need to create a wrapper around your macro that adheres to the |
| 222 | template at |
Manar | f088db1 | 2021-09-20 12:13:04 +0200 | [diff] [blame] | 223 | `user\_project\_wrapper <https://github.com/efabless/caravel/blob/master/verilog/rtl/__user_project_wrapper.v>`__. |
Mohamed Kassem | 6f2fcd2 | 2021-04-19 10:14:19 -0700 | [diff] [blame] | 224 | The wrapper top module must be named ``user_project_wrapper`` and must |
Manar | f088db1 | 2021-09-20 12:13:04 +0200 | [diff] [blame] | 225 | have the same input and output ports as the golden wrapper `template <https://github.com/efabless/caravel/blob/master/verilog/rtl/__user_project_wrapper.v>`__. The wrapper gives access to the |
Mohamed Kassem | 6f2fcd2 | 2021-04-19 10:14:19 -0700 | [diff] [blame] | 226 | user space utilities provided by caravel like IO ports, logic analyzer |
| 227 | probes, and wishbone bus connection to the management SoC. |
| 228 | |
| 229 | For this sample project, the user macro makes use of: |
| 230 | |
| 231 | - The IO ports for displaying the count register values on the IO pads. |
| 232 | |
| 233 | - The LA probes for supplying an optional reset and clock signals and |
| 234 | for setting an initial value for the count register. |
| 235 | |
matt venn | 4acd8b7 | 2021-04-27 11:34:42 +0200 | [diff] [blame] | 236 | - The wishbone port for reading/writing the count value through the |
Mohamed Kassem | 6f2fcd2 | 2021-04-19 10:14:19 -0700 | [diff] [blame] | 237 | management SoC. |
| 238 | |
manarabdelaty | fbd955f | 2021-09-20 11:59:53 +0200 | [diff] [blame] | 239 | Refer to `user\_project\_wrapper <../../verilog/rtl/user_project_wrapper.v>`__ |
Mohamed Kassem | 6f2fcd2 | 2021-04-19 10:14:19 -0700 | [diff] [blame] | 240 | for more information. |
| 241 | |
| 242 | .. raw:: html |
| 243 | |
| 244 | <p align="center"> |
| 245 | <img src="./_static/counter_32.png" width="50%" height="50%"> |
| 246 | </p> |
manarabdelaty | d0e7afb | 2021-04-22 00:21:13 +0200 | [diff] [blame] | 247 | |
Mohamed Kassem | 6f2fcd2 | 2021-04-19 10:14:19 -0700 | [diff] [blame] | 248 | .. raw:: html |
| 249 | |
| 250 | </p> |
| 251 | |
Jeff DiCorpo | f90c9b4 | 2022-11-18 18:11:10 -0800 | [diff] [blame] | 252 | ------------------- |
| 253 | GPIO Configuration |
| 254 | ------------------- |
| 255 | |
| 256 | You are required to specify the power-on default configuration for each GPIO in Caravel. The default configuration provide the state the GPIO will come up on power up. The configuration can be changed by the management SoC during firmware execution. |
| 257 | |
| 258 | Configuration settings define whether the GPIO is configured to connect to the user project area or the managment SoC. They also determine whether IOs are inputs or outputs, digital or analog, as well as whether pull-up or pull-down resistors are configured for inputs. |
| 259 | |
| 260 | GPIOs are configured by assigning predefined values for each IO in the file `verilog/rtl/user_defines.v <https://github.com/efabless/caravel_user_project/blob/main/verilog/rtl/user_defines.v>`_ in your project. |
| 261 | |
Jeff DiCorpo | adbb331 | 2022-11-18 18:26:58 -0800 | [diff] [blame] | 262 | You need to assigned configuration values for GPIO[5] thru GPIO[37]. |
| 263 | |
| 264 | GPIO[0] thru GPIO[4] are preset and cannot be changed. |
Jeff DiCorpo | f90c9b4 | 2022-11-18 18:11:10 -0800 | [diff] [blame] | 265 | |
| 266 | The following values are redefined for assigning to GPIOs. |
| 267 | |
Jeff DiCorpo | 6ef5d79 | 2022-11-18 19:32:44 -0800 | [diff] [blame] | 268 | |
| 269 | - GPIO_MODE_MGMT_STD_INPUT_NOPULL |
| 270 | - GPIO_MODE_MGMT_STD_INPUT_PULLDOWN |
| 271 | - GPIO_MODE_MGMT_STD_INPUT_PULLUP |
| 272 | - GPIO_MODE_MGMT_STD_OUTPUT |
| 273 | - GPIO_MODE_MGMT_STD_BIDIRECTIONAL |
| 274 | - GPIO_MODE_MGMT_STD_ANALOG |
| 275 | |
| 276 | - GPIO_MODE_USER_STD_INPUT_NOPULL |
| 277 | - GPIO_MODE_USER_STD_INPUT_PULLDOWN |
| 278 | - GPIO_MODE_USER_STD_INPUT_PULLUP |
| 279 | - GPIO_MODE_USER_STD_OUTPUT |
| 280 | - GPIO_MODE_USER_STD_BIDIRECTIONAL |
| 281 | - GPIO_MODE_USER_STD_OUT_MONITORED |
| 282 | - GPIO_MODE_USER_STD_ANALOG |
| 283 | |
Jeff DiCorpo | f90c9b4 | 2022-11-18 18:11:10 -0800 | [diff] [blame] | 284 | |
Jeff DiCorpo | adbb331 | 2022-11-18 18:26:58 -0800 | [diff] [blame] | 285 | MPW_Prececk includes a check to confirm each GPIO is assigned a valid value. |
Manar | 4ec8cba | 2021-10-04 10:26:10 -0500 | [diff] [blame] | 286 | |
Kareem Farid | e3b5c47 | 2022-11-15 16:35:21 +0000 | [diff] [blame] | 287 | ------------------- |
Manar | 4ec8cba | 2021-10-04 10:26:10 -0500 | [diff] [blame] | 288 | Layout Integration |
| 289 | ------------------- |
| 290 | |
| 291 | The caravel layout is pre-designed with an empty golden wrapper in the user space. You only need to provide us with a valid ``user_project_wrapper`` GDS file. And, as part of the tapeout process, your hardened ``user_project_wrapper`` will be inserted into a vanilla caravel layout to get the final layout shipped for fabrication. |
| 292 | |
| 293 | .. raw:: html |
| 294 | |
| 295 | <p align="center"> |
| 296 | <img src="./_static/layout.png" width="80%" height="80%"> |
| 297 | </p> |
| 298 | |
| 299 | To make sure that this integration process goes smoothly without having any DRC or LVS issues, your hardened ``user_project_wrapper`` must adhere to a number of requirements listed at `User Project Wrapper Requirements <#user-project-wrapper-requirements>`__ . |
| 300 | |
| 301 | |
manarabdelaty | d8dd010 | 2021-04-30 08:40:52 +0200 | [diff] [blame] | 302 | Running Full Chip Simulation |
| 303 | ============================ |
| 304 | |
| 305 | First, you will need to install the simulation environment, by |
| 306 | |
| 307 | .. code:: bash |
| 308 | |
| 309 | make simenv |
| 310 | |
| 311 | This will pull a docker image with the needed tools installed. |
| 312 | |
Manar | 4ec8cba | 2021-10-04 10:26:10 -0500 | [diff] [blame] | 313 | Then, run the RTL simulation by |
manarabdelaty | d0e7afb | 2021-04-22 00:21:13 +0200 | [diff] [blame] | 314 | |
| 315 | .. code:: bash |
| 316 | |
| 317 | export PDK_ROOT=<pdk-installation-path> |
Marwan Abbas | 0914d04 | 2022-04-06 19:06:34 +0200 | [diff] [blame] | 318 | make verify-<testbench-name>-rtl |
Marwan Abbas | e631e37 | 2022-07-01 02:34:39 -0700 | [diff] [blame] | 319 | |
| 320 | # For example |
| 321 | make verify-io_ports-rtl |
manarabdelaty | d0e7afb | 2021-04-22 00:21:13 +0200 | [diff] [blame] | 322 | |
Manar | 4ec8cba | 2021-10-04 10:26:10 -0500 | [diff] [blame] | 323 | Once you have the physical implementation done and you have the gate-level netlists ready, it is crucial to run full gate-level simulations to make sure that your design works as intended after running the physical implementation. |
| 324 | |
| 325 | Run the gate-level simulation by: |
| 326 | |
| 327 | .. code:: bash |
| 328 | |
| 329 | export PDK_ROOT=<pdk-installation-path> |
Marwan Abbas | 0914d04 | 2022-04-06 19:06:34 +0200 | [diff] [blame] | 330 | make verify-<testbench-name>-gl |
Manar | 4ec8cba | 2021-10-04 10:26:10 -0500 | [diff] [blame] | 331 | |
Marwan Abbas | e631e37 | 2022-07-01 02:34:39 -0700 | [diff] [blame] | 332 | # For example |
| 333 | make verify-io_ports-gl |
| 334 | |
| 335 | To make sure that your design is timing clean, one way is running sdf annotated gate-level simulation |
| 336 | Run the sdf annotated gate-level simulation by: |
| 337 | |
| 338 | .. code:: bash |
| 339 | |
| 340 | export PDK_ROOT=<pdk-installation-path> |
| 341 | make verify-<testbench-name>-gl-sdf |
| 342 | |
| 343 | # For example |
| 344 | make verify-io_ports-gl-sdf |
Manar | 4ec8cba | 2021-10-04 10:26:10 -0500 | [diff] [blame] | 345 | |
| 346 | This sample project comes with four example testbenches to test the IO port connection, wishbone interface, and logic analyzer. The test-benches are under the |
| 347 | `verilog/dv <https://github.com/efabless/caravel_user_project/tree/main/verilog/dv>`__ directory. For more information on setting up the |
manarabdelaty | d0e7afb | 2021-04-22 00:21:13 +0200 | [diff] [blame] | 348 | simulation environment and the available testbenches for this sample |
Manar | ffaf984 | 2021-04-30 22:55:37 +0200 | [diff] [blame] | 349 | project, refer to `README <https://github.com/efabless/caravel_user_project/blob/main/verilog/dv/README.md>`__. |
Mohamed Kassem | 6f2fcd2 | 2021-04-19 10:14:19 -0700 | [diff] [blame] | 350 | |
Manar | 4ec8cba | 2021-10-04 10:26:10 -0500 | [diff] [blame] | 351 | |
| 352 | User Project Wrapper Requirements |
| 353 | ================================= |
| 354 | |
| 355 | Your hardened ``user_project_wrapper`` must match the `golden user_project_wrapper <https://github.com/efabless/caravel/blob/master/gds/user_project_wrapper_empty.gds.gz>`__ in the following: |
| 356 | |
| 357 | - Area ``(2.920um x 3.520um)`` |
| 358 | - Top module name ``"user_project_wrapper"`` |
| 359 | - Pin Placement |
| 360 | - Pin Sizes |
| 361 | - Core Rings Width and Offset |
| 362 | - PDN Vertical and Horizontal Straps Width |
| 363 | |
| 364 | |
| 365 | .. raw:: html |
| 366 | |
| 367 | <p align="center"> |
| 368 | <img src="./_static/empty.png" width="40%" height="40%"> |
| 369 | </p> |
| 370 | |
Marwan Abbas | ca9b692 | 2022-01-26 20:27:03 +0200 | [diff] [blame] | 371 | You are allowed to change the following if you need to: |
Manar | 4ec8cba | 2021-10-04 10:26:10 -0500 | [diff] [blame] | 372 | |
| 373 | - PDN Vertical and Horizontal Pitch & Offset |
| 374 | |
| 375 | .. raw:: html |
| 376 | |
| 377 | <p align="center"> |
| 378 | <img src="./_static/pitch.png" width="30%" height="30%"> |
| 379 | </p> |
| 380 | |
| 381 | To make sure that you adhere to these requirements, we run an exclusive-or (XOR) check between your hardened ``user_project_wrapper`` GDS and the golden wrapper GDS after processing both layouts to include only the boundary (pins and core rings). This check is done as part of the `mpw-precheck <https://github.com/efabless/mpw_precheck>`__ tool. |
| 382 | |
| 383 | |
| 384 | Hardening the User Project using OpenLane |
| 385 | ========================================== |
| 386 | |
Kareem Farid | e3b5c47 | 2022-11-15 16:35:21 +0000 | [diff] [blame] | 387 | --------------------- |
Manar | 4ec8cba | 2021-10-04 10:26:10 -0500 | [diff] [blame] | 388 | OpenLane Installation |
| 389 | --------------------- |
Mohamed Kassem | 6f2fcd2 | 2021-04-19 10:14:19 -0700 | [diff] [blame] | 390 | |
manarabdelaty | d8dd010 | 2021-04-30 08:40:52 +0200 | [diff] [blame] | 391 | You will need to install openlane by running the following |
manarabdelaty | d0e7afb | 2021-04-22 00:21:13 +0200 | [diff] [blame] | 392 | |
| 393 | .. code:: bash |
| 394 | |
manarabdelaty | 0218c0f | 2021-04-29 18:31:49 +0200 | [diff] [blame] | 395 | export OPENLANE_ROOT=<openlane-installation-path> |
manarabdelaty | fbd955f | 2021-09-20 11:59:53 +0200 | [diff] [blame] | 396 | |
| 397 | # you can optionally specify the openlane tag to use |
| 398 | # by running: export OPENLANE_TAG=<openlane-tag> |
| 399 | # if you do not set the tag, it defaults to the last verfied tag tested for this project |
| 400 | |
manarabdelaty | 0218c0f | 2021-04-29 18:31:49 +0200 | [diff] [blame] | 401 | make openlane |
manarabdelaty | d0e7afb | 2021-04-22 00:21:13 +0200 | [diff] [blame] | 402 | |
manarabdelaty | fbd955f | 2021-09-20 11:59:53 +0200 | [diff] [blame] | 403 | For detailed instructions on the openlane and the pdk installation refer |
manarabdelaty | d0e7afb | 2021-04-22 00:21:13 +0200 | [diff] [blame] | 404 | to |
Manar | 4ec8cba | 2021-10-04 10:26:10 -0500 | [diff] [blame] | 405 | `README <https://github.com/The-OpenROAD-Project/OpenLane#setting-up-openlane>`__. |
| 406 | |
Kareem Farid | e3b5c47 | 2022-11-15 16:35:21 +0000 | [diff] [blame] | 407 | ----------------- |
Manar | 4ec8cba | 2021-10-04 10:26:10 -0500 | [diff] [blame] | 408 | Hardening Options |
| 409 | ----------------- |
Mohamed Kassem | 6f2fcd2 | 2021-04-19 10:14:19 -0700 | [diff] [blame] | 410 | |
manarabdelaty | fbd955f | 2021-09-20 11:59:53 +0200 | [diff] [blame] | 411 | There are three options for hardening the user project macro using |
Mohamed Kassem | 6f2fcd2 | 2021-04-19 10:14:19 -0700 | [diff] [blame] | 412 | openlane: |
| 413 | |
Manar | 4ec8cba | 2021-10-04 10:26:10 -0500 | [diff] [blame] | 414 | +--------------------------------------------------------------+--------------------------------------------+--------------------------------------------+ |
| 415 | | Option 1 | Option 2 | Option 3 | |
| 416 | +--------------------------------------------------------------+--------------------------------------------+--------------------------------------------+ |
| 417 | | Hardening the user macro(s) first, then inserting it in the | Flattening the user macro(s) with the | Placing multiple macros in the wrapper | |
| 418 | | user project wrapper with no standard cells on the top level | user_project_wrapper | along with standard cells on the top level | |
| 419 | +==============================================================+============================================+============================================+ |
| 420 | | |pic1| | |pic2| | |pic3| | |
| 421 | | | | | |
| 422 | +--------------------------------------------------------------+--------------------------------------------+--------------------------------------------+ |
| 423 | | ex: |link1| | | ex: |link2| | |
| 424 | +--------------------------------------------------------------+--------------------------------------------+--------------------------------------------+ |
Mohamed Kassem | 6f2fcd2 | 2021-04-19 10:14:19 -0700 | [diff] [blame] | 425 | |
Manar | 4ec8cba | 2021-10-04 10:26:10 -0500 | [diff] [blame] | 426 | .. |link1| replace:: `caravel_user_project <https://github.com/efabless/caravel_user_project>`__ |
| 427 | |
| 428 | .. |link2| replace:: `caravel_ibex <https://github.com/efabless/caravel_ibex>`__ |
| 429 | |
| 430 | |
| 431 | .. |pic1| image:: ./_static/option1.png |
| 432 | :width: 48% |
| 433 | |
| 434 | .. |pic2| image:: ./_static/option2.png |
| 435 | :width: 140% |
| 436 | |
| 437 | .. |pic3| image:: ./_static/option3.png |
| 438 | :width: 72% |
| 439 | |
| 440 | For more details on hardening macros using openlane, refer to `README <https://github.com/The-OpenROAD-Project/OpenLane/blob/master/docs/source/hardening_macros.md>`__. |
| 441 | |
Kareem Farid | e3b5c47 | 2022-11-15 16:35:21 +0000 | [diff] [blame] | 442 | ----------------- |
Manar | 4ec8cba | 2021-10-04 10:26:10 -0500 | [diff] [blame] | 443 | Running OpenLane |
| 444 | ----------------- |
Mohamed Kassem | 6f2fcd2 | 2021-04-19 10:14:19 -0700 | [diff] [blame] | 445 | |
| 446 | For this sample project, we went for the first option where the user |
| 447 | macro is hardened first, then it is inserted in the user project |
manarabdelaty | fbd955f | 2021-09-20 11:59:53 +0200 | [diff] [blame] | 448 | wrapper without having any standard cells on the top level. |
Mohamed Kassem | 6f2fcd2 | 2021-04-19 10:14:19 -0700 | [diff] [blame] | 449 | |
| 450 | .. raw:: html |
| 451 | |
| 452 | <p align="center"> |
Manar | 4ec8cba | 2021-10-04 10:26:10 -0500 | [diff] [blame] | 453 | <img src="./_static/wrapper.png" width="30%" height="30%"> |
Mohamed Kassem | 6f2fcd2 | 2021-04-19 10:14:19 -0700 | [diff] [blame] | 454 | </p> |
| 455 | |
manarabdelaty | d0e7afb | 2021-04-22 00:21:13 +0200 | [diff] [blame] | 456 | .. raw:: html |
| 457 | |
| 458 | </p> |
Manar | 4ec8cba | 2021-10-04 10:26:10 -0500 | [diff] [blame] | 459 | |
Mohamed Kassem | 6f2fcd2 | 2021-04-19 10:14:19 -0700 | [diff] [blame] | 460 | To reproduce hardening this project, run the following: |
| 461 | |
| 462 | .. code:: bash |
| 463 | |
Marwan Abbas | fa8d7ec | 2022-02-03 09:50:05 -0800 | [diff] [blame] | 464 | # DO NOT cd into openlane |
| 465 | |
manarabdelaty | 0218c0f | 2021-04-29 18:31:49 +0200 | [diff] [blame] | 466 | # Run openlane to harden user_proj_example |
| 467 | make user_proj_example |
| 468 | # Run openlane to harden user_project_wrapper |
| 469 | make user_project_wrapper |
| 470 | |
| 471 | |
Manar | 4ec8cba | 2021-10-04 10:26:10 -0500 | [diff] [blame] | 472 | For more information on the openlane flow, check `README <https://github.com/The-OpenROAD-Project/OpenLane#readme>`__. |
| 473 | |
Manar | f088db1 | 2021-09-20 12:13:04 +0200 | [diff] [blame] | 474 | Running MPW Precheck Locally |
manarabdelaty | 0218c0f | 2021-04-29 18:31:49 +0200 | [diff] [blame] | 475 | ================================= |
| 476 | |
Manar | 4ec8cba | 2021-10-04 10:26:10 -0500 | [diff] [blame] | 477 | You can install the `mpw-precheck <https://github.com/efabless/mpw_precheck>`__ by running |
manarabdelaty | 0218c0f | 2021-04-29 18:31:49 +0200 | [diff] [blame] | 478 | |
| 479 | .. code:: bash |
| 480 | |
| 481 | # By default, this install the precheck in your home directory |
| 482 | # To change the installtion path, run "export PRECHECK_ROOT=<precheck installation path>" |
| 483 | make precheck |
| 484 | |
| 485 | This will clone the precheck repo and pull the latest precheck docker image. |
| 486 | |
| 487 | |
| 488 | Then, you can run the precheck by running |
| 489 | |
| 490 | .. code:: bash |
| 491 | |
| 492 | make run-precheck |
| 493 | |
| 494 | This will run all the precheck checks on your project and will produce the logs under the ``checks`` directory. |
| 495 | |
Jeff DiCorpo | d3f3d20 | 2022-11-18 23:39:01 -0800 | [diff] [blame^] | 496 | Running Timing Analysis on Existing Projects |
| 497 | ======================================================== |
| 498 | |
| 499 | Start by updating the Makefile for your project. Starting in the project root... |
| 500 | |
| 501 | .. code:: bash |
| 502 | |
| 503 | curl -k https://raw.githubusercontent.com/efabless/caravel_user_project/main/Makefile > Makefile |
| 504 | |
| 505 | make setup-timing-scripts |
| 506 | |
| 507 | make install |
| 508 | |
| 509 | make install_mcw |
| 510 | |
| 511 | |
| 512 | This will update Caravel design files and install the scripts for running timing. |
| 513 | |
| 514 | |
| 515 | Then, you can run then run timing by the following... |
| 516 | |
| 517 | .. code:: bash |
| 518 | |
| 519 | make extract-parasitics |
| 520 | |
| 521 | make create-spef-mapping |
| 522 | |
| 523 | make caravel-sta |
| 524 | |
| 525 | |
| 526 | A summary of timing results is provided at the end of the flow. |
| 527 | |
manarabdelaty | 0218c0f | 2021-04-29 18:31:49 +0200 | [diff] [blame] | 528 | |
| 529 | Other Miscellaneous Targets |
| 530 | ============================ |
| 531 | |
| 532 | The makefile provides a number of useful that targets that can run LVS, DRC, and XOR checks on your hardened design outside of openlane's flow. |
| 533 | |
Manar | f088db1 | 2021-09-20 12:13:04 +0200 | [diff] [blame] | 534 | Run ``make help`` to display available targets. |
manarabdelaty | 0218c0f | 2021-04-29 18:31:49 +0200 | [diff] [blame] | 535 | |
manarabdelaty | 0c03d60 | 2021-09-20 11:42:16 +0200 | [diff] [blame] | 536 | Run lvs on the mag view, |
manarabdelaty | 0218c0f | 2021-04-29 18:31:49 +0200 | [diff] [blame] | 537 | |
| 538 | .. code:: bash |
| 539 | |
| 540 | make lvs-<macro_name> |
| 541 | |
| 542 | Run lvs on the gds, |
| 543 | |
| 544 | .. code:: bash |
| 545 | |
| 546 | make lvs-gds-<macro_name> |
| 547 | |
| 548 | Run lvs on the maglef, |
| 549 | |
| 550 | .. code:: bash |
| 551 | |
| 552 | make lvs-maglef-<macro_name> |
| 553 | |
| 554 | Run drc using magic, |
| 555 | |
| 556 | .. code:: bash |
| 557 | |
| 558 | make drc-<macro_name> |
| 559 | |
| 560 | Run antenna check using magic, |
| 561 | |
| 562 | .. code:: bash |
| 563 | |
| 564 | make antenna-<macro_name> |
| 565 | |
| 566 | Run XOR check, |
| 567 | |
| 568 | .. code:: bash |
| 569 | |
| 570 | make xor-wrapper |
Marwan Abbas | fa8d7ec | 2022-02-03 09:50:05 -0800 | [diff] [blame] | 571 | |
| 572 | |
manarabdelaty | 0218c0f | 2021-04-29 18:31:49 +0200 | [diff] [blame] | 573 | |
Mohamed Kassem | 6f2fcd2 | 2021-04-19 10:14:19 -0700 | [diff] [blame] | 574 | |
| 575 | Checklist for Open-MPW Submission |
| 576 | ================================= |
| 577 | |
Manar | f088db1 | 2021-09-20 12:13:04 +0200 | [diff] [blame] | 578 | - ✔️ The project repo adheres to the same directory structure in this |
Mohamed Kassem | 6f2fcd2 | 2021-04-19 10:14:19 -0700 | [diff] [blame] | 579 | repo. |
Manar | f088db1 | 2021-09-20 12:13:04 +0200 | [diff] [blame] | 580 | - ✔️ The project repo contain info.yaml at the project root. |
| 581 | - ✔️ Top level macro is named ``user_project_wrapper``. |
| 582 | - ✔️ Full Chip Simulation passes for RTL and GL (gate-level) |
| 583 | - ✔️ The hardened Macros are LVS and DRC clean |
Jeff DiCorpo | 9e95043 | 2021-10-24 10:09:39 -0700 | [diff] [blame] | 584 | - ✔️ The project contains a gate-level netlist for ``user_project_wrapper`` at verilog/gl/user_project_wrapper.v |
Manar | f088db1 | 2021-09-20 12:13:04 +0200 | [diff] [blame] | 585 | - ✔️ The hardened ``user_project_wrapper`` adheres to the same pin |
Mohamed Kassem | 6f2fcd2 | 2021-04-19 10:14:19 -0700 | [diff] [blame] | 586 | order specified at |
| 587 | `pin\_order <https://github.com/efabless/caravel/blob/master/openlane/user_project_wrapper_empty/pin_order.cfg>`__ |
Manar | f088db1 | 2021-09-20 12:13:04 +0200 | [diff] [blame] | 588 | - ✔️ The hardened ``user_project_wrapper`` adheres to the fixed wrapper configuration specified at `fixed_wrapper_cfgs <https://github.com/efabless/caravel/blob/master/openlane/user_project_wrapper_empty/fixed_wrapper_cfgs.tcl>`__ |
| 589 | - ✔️ XOR check passes with zero total difference. |
| 590 | - ✔️ Openlane summary reports are retained under ./signoff/ |
| 591 | - ✔️ The design passes the `mpw-precheck <https://github.com/efabless/mpw_precheck>`__ |
Mohamed Kassem | 6f2fcd2 | 2021-04-19 10:14:19 -0700 | [diff] [blame] | 592 | |
| 593 | .. |License| image:: https://img.shields.io/badge/License-Apache%202.0-blue.svg |
| 594 | :target: https://opensource.org/licenses/Apache-2.0 |
manarabdelaty | d0e7afb | 2021-04-22 00:21:13 +0200 | [diff] [blame] | 595 | .. |User CI| image:: https://github.com/efabless/caravel_project_example/actions/workflows/user_project_ci.yml/badge.svg |
| 596 | :target: https://github.com/efabless/caravel_project_example/actions/workflows/user_project_ci.yml |
| 597 | .. |Caravel Build| image:: https://github.com/efabless/caravel_project_example/actions/workflows/caravel_build.yml/badge.svg |
Mohamed Kassem | 9ae1f07 | 2021-04-23 12:19:31 -0700 | [diff] [blame] | 598 | :target: https://github.com/efabless/caravel_project_example/actions/workflows/caravel_build.yml |