blob: 039dd9a9aebe8932f9d3a01ae79137159f81e837 [file] [log] [blame]
Mohamed Kassem6f2fcd22021-04-19 10:14:19 -07001.. 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
21Caravel User Project
22====================
23
manarabdelatyd0e7afb2021-04-22 00:21:13 +020024|License| |User CI| |Caravel Build|
Mohamed Kassem6f2fcd22021-04-19 10:14:19 -070025
26Table of contents
27=================
28
29- `Overview <#overview>`__
manarabdelatyd0e7afb2021-04-22 00:21:13 +020030- `Install Caravel <#install-caravel>`__
Mohamed Kassem6f2fcd22021-04-19 10:14:19 -070031- `Caravel Integration <#caravel-integration>`__
32
33 - `Repo Integration <#repo-integration>`__
34 - `Verilog Integration <#verilog-integration>`__
Manar4ec8cba2021-10-04 10:26:10 -050035 - `Layout Integration <#layout-integration>`__
Mohamed Kassem6f2fcd22021-04-19 10:14:19 -070036
37- `Running Full Chip Simulation <#running-full-chip-simulation>`__
Manar4ec8cba2021-10-04 10:26:10 -050038- `User Project Wrapper Requirements <#user-project-wrapper-requirements>`__
39- `Hardening the User Project using
40 Openlane <#hardening-the-user-project-using-openlane>`__
Mohamed Kassem6f2fcd22021-04-19 10:14:19 -070041- `Checklist for Open-MPW
42 Submission <#checklist-for-open-mpw-submission>`__
43
44Overview
45========
46
47This repo contains a sample user project that utilizes the
48`caravel <https://github.com/efabless/caravel.git>`__ chip user space.
49The user project is a simple counter that showcases how to make use of
50`caravel's <https://github.com/efabless/caravel.git>`__ user space
51utilities like IO pads, logic analyzer probes, and wishbone port. The
52repo also demonstrates the recommended structure for the open-mpw
53shuttle projects.
54
manarabdelatyd8dd0102021-04-30 08:40:52 +020055Prerequisites
56=============
57
Marwan Abbas0914d042022-04-06 19:06:34 +020058- 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>`_
59
60- Python 3.6+ with PIP
manarabdelatyd8dd0102021-04-30 08:40:52 +020061
manarabdelatyd0e7afb2021-04-22 00:21:13 +020062Install Caravel
63===============
64
65To setup caravel, run the following:
66
67.. code:: bash
Mohamed Kassem9ae1f072021-04-23 12:19:31 -070068
manarabdelaty0218c0f2021-04-29 18:31:49 +020069 git clone https://github.com/efabless/caravel_user_project.git
Mohamed Kassem9ae1f072021-04-23 12:19:31 -070070 cd caravel_user_project
Marwan Abbasca9b6922022-01-26 20:27:03 +020071
manarabdelatyd0e7afb2021-04-22 00:21:13 +020072 make install
73
manarabdelatyd0e7afb2021-04-22 00:21:13 +020074To remove caravel, run
75
76.. code:: bash
77
78 make uninstall
79
80By default
81`caravel-lite <https://github.com/efabless/caravel-lite.git>`__ is
82installed. To install the full version of caravel, run this prior to
83calling make install.
84
85.. code:: bash
86
87 export CARAVEL_LITE=0
88
Mohamed Kassem6f2fcd22021-04-19 10:14:19 -070089Caravel Integration
90===================
91
92Repo Integration
93----------------
94
95Caravel files are kept separate from the user project by having caravel
manarabdelatyd0e7afb2021-04-22 00:21:13 +020096as submodule. The submodule commit should point to the latest of
Manar4ec8cba2021-10-04 10:26:10 -050097caravel/caravel-lite master/main branch. The following files should have a symbolic
manarabdelatyd0e7afb2021-04-22 00:21:13 +020098link to `caravel's <https://github.com/efabless/caravel.git>`__
99corresponding files:
Mohamed Kassem6f2fcd22021-04-19 10:14:19 -0700100
manarabdelaty0c03d602021-09-20 11:42:16 +0200101- `Openlane Makefile <../../openlane/Makefile>`__: This provides an easier
manarabdelatyd0e7afb2021-04-22 00:21:13 +0200102 way for running openlane to harden your macros. Refer to `Hardening
103 the User Project Macro using
Marwan Abbasca9b6922022-01-26 20:27:03 +0200104 Openlane <#hardening-the-user-project-using-openlane>`__. Also,
manarabdelatyd0e7afb2021-04-22 00:21:13 +0200105 the makefile retains the openlane summary reports under the signoff
106 directory.
Mohamed Kassem6f2fcd22021-04-19 10:14:19 -0700107
manarabdelaty0c03d602021-09-20 11:42:16 +0200108- `Pin order <../../openlane/user_project_wrapper/pin_order.cfg>`__ file for
Mohamed Kassem6f2fcd22021-04-19 10:14:19 -0700109 the user wrapper: The hardened user project wrapper macro must have
110 the same pin order specified in caravel's repo. Failing to adhere to
111 the same order will fail the gds integration of the macro with
112 caravel's back-end.
113
manarabdelatyd0e7afb2021-04-22 00:21:13 +0200114The symbolic links are automatically set when you run ``make install``.
Mohamed Kassem6f2fcd22021-04-19 10:14:19 -0700115
116Verilog Integration
117-------------------
118
119You need to create a wrapper around your macro that adheres to the
120template at
Manarf088db12021-09-20 12:13:04 +0200121`user\_project\_wrapper <https://github.com/efabless/caravel/blob/master/verilog/rtl/__user_project_wrapper.v>`__.
Mohamed Kassem6f2fcd22021-04-19 10:14:19 -0700122The wrapper top module must be named ``user_project_wrapper`` and must
Manarf088db12021-09-20 12:13:04 +0200123have 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 Kassem6f2fcd22021-04-19 10:14:19 -0700124user space utilities provided by caravel like IO ports, logic analyzer
125probes, and wishbone bus connection to the management SoC.
126
127For this sample project, the user macro makes use of:
128
129- The IO ports for displaying the count register values on the IO pads.
130
131- The LA probes for supplying an optional reset and clock signals and
132 for setting an initial value for the count register.
133
matt venn4acd8b72021-04-27 11:34:42 +0200134- The wishbone port for reading/writing the count value through the
Mohamed Kassem6f2fcd22021-04-19 10:14:19 -0700135 management SoC.
136
manarabdelatyfbd955f2021-09-20 11:59:53 +0200137Refer to `user\_project\_wrapper <../../verilog/rtl/user_project_wrapper.v>`__
Mohamed Kassem6f2fcd22021-04-19 10:14:19 -0700138for more information.
139
140.. raw:: html
141
142 <p align="center">
143 <img src="./_static/counter_32.png" width="50%" height="50%">
144 </p>
manarabdelatyd0e7afb2021-04-22 00:21:13 +0200145
Mohamed Kassem6f2fcd22021-04-19 10:14:19 -0700146.. raw:: html
147
148 </p>
149
Manar4ec8cba2021-10-04 10:26:10 -0500150
151Layout Integration
152-------------------
153
154The 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.
155
156.. raw:: html
157
158 <p align="center">
159 <img src="./_static/layout.png" width="80%" height="80%">
160 </p>
161
162To 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>`__ .
163
164
manarabdelatyd8dd0102021-04-30 08:40:52 +0200165Building the PDK
166================
Mohamed Kassem6f2fcd22021-04-19 10:14:19 -0700167
Marwan Abbas073ecab2022-04-03 14:52:46 +0200168For more information about volare click `here <https://github.com/efabless/volare>`__
manarabdelatyd0e7afb2021-04-22 00:21:13 +0200169
170.. code:: bash
171
172 # set PDK_ROOT to the path you wish to use for the pdk
173 export PDK_ROOT=<pdk-installation-path>
Marwan Abbase55106c2022-07-01 11:06:37 +0200174
175 # set the PDK variant depending on your shuttle, if you don't know leave it as default
176 export PDK=sky130B
manarabdelatyd0e7afb2021-04-22 00:21:13 +0200177
Marwan Abbas073ecab2022-04-03 14:52:46 +0200178 # use volare to download the pdk
Marwan Abbas70e891d2022-04-07 17:19:12 +0200179 # To change the default pdk version you can export OPEN_PDKS_COMMIT=<pdk_commit>
Marwan Abbasfab39d92022-04-06 22:39:21 +0200180 make pdk-with-volare
manarabdelatyd0e7afb2021-04-22 00:21:13 +0200181
manarabdelatyd8dd0102021-04-30 08:40:52 +0200182Running Full Chip Simulation
183============================
184
185First, you will need to install the simulation environment, by
186
187.. code:: bash
188
189 make simenv
190
191This will pull a docker image with the needed tools installed.
192
Manar4ec8cba2021-10-04 10:26:10 -0500193Then, run the RTL simulation by
manarabdelatyd0e7afb2021-04-22 00:21:13 +0200194
195.. code:: bash
196
197 export PDK_ROOT=<pdk-installation-path>
Marwan Abbas0914d042022-04-06 19:06:34 +0200198 make verify-<testbench-name>-rtl
Marwan Abbase631e372022-07-01 02:34:39 -0700199
200 # For example
201 make verify-io_ports-rtl
manarabdelatyd0e7afb2021-04-22 00:21:13 +0200202
Manar4ec8cba2021-10-04 10:26:10 -0500203Once 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.
204
205Run the gate-level simulation by:
206
207.. code:: bash
208
209 export PDK_ROOT=<pdk-installation-path>
Marwan Abbas0914d042022-04-06 19:06:34 +0200210 make verify-<testbench-name>-gl
Manar4ec8cba2021-10-04 10:26:10 -0500211
Marwan Abbase631e372022-07-01 02:34:39 -0700212 # For example
213 make verify-io_ports-gl
214
215To make sure that your design is timing clean, one way is running sdf annotated gate-level simulation
216Run the sdf annotated gate-level simulation by:
217
218.. code:: bash
219
220 export PDK_ROOT=<pdk-installation-path>
221 make verify-<testbench-name>-gl-sdf
222
223 # For example
224 make verify-io_ports-gl-sdf
Manar4ec8cba2021-10-04 10:26:10 -0500225
226This sample project comes with four example testbenches to test the IO port connection, wishbone interface, and logic analyzer. The test-benches are under the
227`verilog/dv <https://github.com/efabless/caravel_user_project/tree/main/verilog/dv>`__ directory. For more information on setting up the
manarabdelatyd0e7afb2021-04-22 00:21:13 +0200228simulation environment and the available testbenches for this sample
Manarffaf9842021-04-30 22:55:37 +0200229project, refer to `README <https://github.com/efabless/caravel_user_project/blob/main/verilog/dv/README.md>`__.
Mohamed Kassem6f2fcd22021-04-19 10:14:19 -0700230
Manar4ec8cba2021-10-04 10:26:10 -0500231
232User Project Wrapper Requirements
233=================================
234
235Your 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:
236
237- Area ``(2.920um x 3.520um)``
238- Top module name ``"user_project_wrapper"``
239- Pin Placement
240- Pin Sizes
241- Core Rings Width and Offset
242- PDN Vertical and Horizontal Straps Width
243
244
245.. raw:: html
246
247 <p align="center">
248 <img src="./_static/empty.png" width="40%" height="40%">
249 </p>
250
Marwan Abbasca9b6922022-01-26 20:27:03 +0200251You are allowed to change the following if you need to:
Manar4ec8cba2021-10-04 10:26:10 -0500252
253- PDN Vertical and Horizontal Pitch & Offset
254
255.. raw:: html
256
257 <p align="center">
258 <img src="./_static/pitch.png" width="30%" height="30%">
259 </p>
260
261To 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.
262
263
264Hardening the User Project using OpenLane
265==========================================
266
267OpenLane Installation
268---------------------
Mohamed Kassem6f2fcd22021-04-19 10:14:19 -0700269
manarabdelatyd8dd0102021-04-30 08:40:52 +0200270You will need to install openlane by running the following
manarabdelatyd0e7afb2021-04-22 00:21:13 +0200271
272.. code:: bash
273
manarabdelaty0218c0f2021-04-29 18:31:49 +0200274 export OPENLANE_ROOT=<openlane-installation-path>
manarabdelatyfbd955f2021-09-20 11:59:53 +0200275
276 # you can optionally specify the openlane tag to use
277 # by running: export OPENLANE_TAG=<openlane-tag>
278 # if you do not set the tag, it defaults to the last verfied tag tested for this project
279
manarabdelaty0218c0f2021-04-29 18:31:49 +0200280 make openlane
manarabdelatyd0e7afb2021-04-22 00:21:13 +0200281
manarabdelatyfbd955f2021-09-20 11:59:53 +0200282For detailed instructions on the openlane and the pdk installation refer
manarabdelatyd0e7afb2021-04-22 00:21:13 +0200283to
Manar4ec8cba2021-10-04 10:26:10 -0500284`README <https://github.com/The-OpenROAD-Project/OpenLane#setting-up-openlane>`__.
285
286Hardening Options
287-----------------
Mohamed Kassem6f2fcd22021-04-19 10:14:19 -0700288
manarabdelatyfbd955f2021-09-20 11:59:53 +0200289There are three options for hardening the user project macro using
Mohamed Kassem6f2fcd22021-04-19 10:14:19 -0700290openlane:
291
Manar4ec8cba2021-10-04 10:26:10 -0500292+--------------------------------------------------------------+--------------------------------------------+--------------------------------------------+
293| Option 1 | Option 2 | Option 3 |
294+--------------------------------------------------------------+--------------------------------------------+--------------------------------------------+
295| Hardening the user macro(s) first, then inserting it in the | Flattening the user macro(s) with the | Placing multiple macros in the wrapper |
296| user project wrapper with no standard cells on the top level | user_project_wrapper | along with standard cells on the top level |
297+==============================================================+============================================+============================================+
298| |pic1| | |pic2| | |pic3| |
299| | | |
300+--------------------------------------------------------------+--------------------------------------------+--------------------------------------------+
301| ex: |link1| | | ex: |link2| |
302+--------------------------------------------------------------+--------------------------------------------+--------------------------------------------+
Mohamed Kassem6f2fcd22021-04-19 10:14:19 -0700303
Manar4ec8cba2021-10-04 10:26:10 -0500304.. |link1| replace:: `caravel_user_project <https://github.com/efabless/caravel_user_project>`__
305
306.. |link2| replace:: `caravel_ibex <https://github.com/efabless/caravel_ibex>`__
307
308
309.. |pic1| image:: ./_static/option1.png
310 :width: 48%
311
312.. |pic2| image:: ./_static/option2.png
313 :width: 140%
314
315.. |pic3| image:: ./_static/option3.png
316 :width: 72%
317
318For more details on hardening macros using openlane, refer to `README <https://github.com/The-OpenROAD-Project/OpenLane/blob/master/docs/source/hardening_macros.md>`__.
319
320
321Running OpenLane
322-----------------
Mohamed Kassem6f2fcd22021-04-19 10:14:19 -0700323
324For this sample project, we went for the first option where the user
325macro is hardened first, then it is inserted in the user project
manarabdelatyfbd955f2021-09-20 11:59:53 +0200326wrapper without having any standard cells on the top level.
Mohamed Kassem6f2fcd22021-04-19 10:14:19 -0700327
328.. raw:: html
329
330 <p align="center">
Manar4ec8cba2021-10-04 10:26:10 -0500331 <img src="./_static/wrapper.png" width="30%" height="30%">
Mohamed Kassem6f2fcd22021-04-19 10:14:19 -0700332 </p>
333
manarabdelatyd0e7afb2021-04-22 00:21:13 +0200334.. raw:: html
335
336 </p>
Manar4ec8cba2021-10-04 10:26:10 -0500337
Mohamed Kassem6f2fcd22021-04-19 10:14:19 -0700338To reproduce hardening this project, run the following:
339
340.. code:: bash
341
Marwan Abbasfa8d7ec2022-02-03 09:50:05 -0800342 # DO NOT cd into openlane
343
manarabdelaty0218c0f2021-04-29 18:31:49 +0200344 # Run openlane to harden user_proj_example
345 make user_proj_example
346 # Run openlane to harden user_project_wrapper
347 make user_project_wrapper
348
349
Manar4ec8cba2021-10-04 10:26:10 -0500350For more information on the openlane flow, check `README <https://github.com/The-OpenROAD-Project/OpenLane#readme>`__.
351
Manarf088db12021-09-20 12:13:04 +0200352Running MPW Precheck Locally
manarabdelaty0218c0f2021-04-29 18:31:49 +0200353=================================
354
Manar4ec8cba2021-10-04 10:26:10 -0500355You can install the `mpw-precheck <https://github.com/efabless/mpw_precheck>`__ by running
manarabdelaty0218c0f2021-04-29 18:31:49 +0200356
357.. code:: bash
358
359 # By default, this install the precheck in your home directory
360 # To change the installtion path, run "export PRECHECK_ROOT=<precheck installation path>"
361 make precheck
362
363This will clone the precheck repo and pull the latest precheck docker image.
364
365
366Then, you can run the precheck by running
367
368.. code:: bash
369
370 make run-precheck
371
372This will run all the precheck checks on your project and will produce the logs under the ``checks`` directory.
373
374
375Other Miscellaneous Targets
376============================
377
378The 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.
379
Manarf088db12021-09-20 12:13:04 +0200380Run ``make help`` to display available targets.
manarabdelaty0218c0f2021-04-29 18:31:49 +0200381
manarabdelaty0c03d602021-09-20 11:42:16 +0200382Run lvs on the mag view,
manarabdelaty0218c0f2021-04-29 18:31:49 +0200383
384.. code:: bash
385
386 make lvs-<macro_name>
387
388Run lvs on the gds,
389
390.. code:: bash
391
392 make lvs-gds-<macro_name>
393
394Run lvs on the maglef,
395
396.. code:: bash
397
398 make lvs-maglef-<macro_name>
399
400Run drc using magic,
401
402.. code:: bash
403
404 make drc-<macro_name>
405
406Run antenna check using magic,
407
408.. code:: bash
409
410 make antenna-<macro_name>
411
412Run XOR check,
413
414.. code:: bash
415
416 make xor-wrapper
Marwan Abbasfa8d7ec2022-02-03 09:50:05 -0800417
418
manarabdelaty0218c0f2021-04-29 18:31:49 +0200419
Mohamed Kassem6f2fcd22021-04-19 10:14:19 -0700420
421Checklist for Open-MPW Submission
422=================================
423
Manarf088db12021-09-20 12:13:04 +0200424- ✔️ The project repo adheres to the same directory structure in this
Mohamed Kassem6f2fcd22021-04-19 10:14:19 -0700425 repo.
Manarf088db12021-09-20 12:13:04 +0200426- ✔️ The project repo contain info.yaml at the project root.
427- ✔️ Top level macro is named ``user_project_wrapper``.
428- ✔️ Full Chip Simulation passes for RTL and GL (gate-level)
429- ✔️ The hardened Macros are LVS and DRC clean
Jeff DiCorpo9e950432021-10-24 10:09:39 -0700430- ✔️ The project contains a gate-level netlist for ``user_project_wrapper`` at verilog/gl/user_project_wrapper.v
Manarf088db12021-09-20 12:13:04 +0200431- ✔️ The hardened ``user_project_wrapper`` adheres to the same pin
Mohamed Kassem6f2fcd22021-04-19 10:14:19 -0700432 order specified at
433 `pin\_order <https://github.com/efabless/caravel/blob/master/openlane/user_project_wrapper_empty/pin_order.cfg>`__
Manarf088db12021-09-20 12:13:04 +0200434- ✔️ 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>`__
435- ✔️ XOR check passes with zero total difference.
436- ✔️ Openlane summary reports are retained under ./signoff/
437- ✔️ The design passes the `mpw-precheck <https://github.com/efabless/mpw_precheck>`__
Mohamed Kassem6f2fcd22021-04-19 10:14:19 -0700438
439.. |License| image:: https://img.shields.io/badge/License-Apache%202.0-blue.svg
440 :target: https://opensource.org/licenses/Apache-2.0
manarabdelatyd0e7afb2021-04-22 00:21:13 +0200441.. |User CI| image:: https://github.com/efabless/caravel_project_example/actions/workflows/user_project_ci.yml/badge.svg
442 :target: https://github.com/efabless/caravel_project_example/actions/workflows/user_project_ci.yml
443.. |Caravel Build| image:: https://github.com/efabless/caravel_project_example/actions/workflows/caravel_build.yml/badge.svg
Mohamed Kassem9ae1f072021-04-23 12:19:31 -0700444 :target: https://github.com/efabless/caravel_project_example/actions/workflows/caravel_build.yml