blob: e756a3f720a0aef91d526f30161042ace0ee51ef [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>
174
Marwan Abbas073ecab2022-04-03 14:52:46 +0200175 # use volare to download the pdk
Marwan Abbas70e891d2022-04-07 17:19:12 +0200176 # To change the default pdk version you can export OPEN_PDKS_COMMIT=<pdk_commit>
Marwan Abbasfab39d92022-04-06 22:39:21 +0200177 make pdk-with-volare
manarabdelatyd0e7afb2021-04-22 00:21:13 +0200178
manarabdelatyd8dd0102021-04-30 08:40:52 +0200179Running Full Chip Simulation
180============================
181
182First, you will need to install the simulation environment, by
183
184.. code:: bash
185
186 make simenv
187
188This will pull a docker image with the needed tools installed.
189
Manar4ec8cba2021-10-04 10:26:10 -0500190Then, run the RTL simulation by
manarabdelatyd0e7afb2021-04-22 00:21:13 +0200191
192.. code:: bash
193
194 export PDK_ROOT=<pdk-installation-path>
Manar4ec8cba2021-10-04 10:26:10 -0500195 # Run RTL simulation on IO ports testbench, make verify-io_ports
Marwan Abbas0914d042022-04-06 19:06:34 +0200196 make verify-<testbench-name>-rtl
manarabdelatyd0e7afb2021-04-22 00:21:13 +0200197
Manar4ec8cba2021-10-04 10:26:10 -0500198Once 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.
199
200Run the gate-level simulation by:
201
202.. code:: bash
203
204 export PDK_ROOT=<pdk-installation-path>
Manar4ec8cba2021-10-04 10:26:10 -0500205 # Run RTL simulation on IO ports testbench, make verify-io_ports
Marwan Abbas0914d042022-04-06 19:06:34 +0200206 make verify-<testbench-name>-gl
Manar4ec8cba2021-10-04 10:26:10 -0500207
208
209This sample project comes with four example testbenches to test the IO port connection, wishbone interface, and logic analyzer. The test-benches are under the
210`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 +0200211simulation environment and the available testbenches for this sample
Manarffaf9842021-04-30 22:55:37 +0200212project, refer to `README <https://github.com/efabless/caravel_user_project/blob/main/verilog/dv/README.md>`__.
Mohamed Kassem6f2fcd22021-04-19 10:14:19 -0700213
Manar4ec8cba2021-10-04 10:26:10 -0500214
215User Project Wrapper Requirements
216=================================
217
218Your 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:
219
220- Area ``(2.920um x 3.520um)``
221- Top module name ``"user_project_wrapper"``
222- Pin Placement
223- Pin Sizes
224- Core Rings Width and Offset
225- PDN Vertical and Horizontal Straps Width
226
227
228.. raw:: html
229
230 <p align="center">
231 <img src="./_static/empty.png" width="40%" height="40%">
232 </p>
233
Marwan Abbasca9b6922022-01-26 20:27:03 +0200234You are allowed to change the following if you need to:
Manar4ec8cba2021-10-04 10:26:10 -0500235
236- PDN Vertical and Horizontal Pitch & Offset
237
238.. raw:: html
239
240 <p align="center">
241 <img src="./_static/pitch.png" width="30%" height="30%">
242 </p>
243
244To 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.
245
246
247Hardening the User Project using OpenLane
248==========================================
249
250OpenLane Installation
251---------------------
Mohamed Kassem6f2fcd22021-04-19 10:14:19 -0700252
manarabdelatyd8dd0102021-04-30 08:40:52 +0200253You will need to install openlane by running the following
manarabdelatyd0e7afb2021-04-22 00:21:13 +0200254
255.. code:: bash
256
manarabdelaty0218c0f2021-04-29 18:31:49 +0200257 export OPENLANE_ROOT=<openlane-installation-path>
manarabdelatyfbd955f2021-09-20 11:59:53 +0200258
259 # you can optionally specify the openlane tag to use
260 # by running: export OPENLANE_TAG=<openlane-tag>
261 # if you do not set the tag, it defaults to the last verfied tag tested for this project
262
manarabdelaty0218c0f2021-04-29 18:31:49 +0200263 make openlane
manarabdelatyd0e7afb2021-04-22 00:21:13 +0200264
manarabdelatyfbd955f2021-09-20 11:59:53 +0200265For detailed instructions on the openlane and the pdk installation refer
manarabdelatyd0e7afb2021-04-22 00:21:13 +0200266to
Manar4ec8cba2021-10-04 10:26:10 -0500267`README <https://github.com/The-OpenROAD-Project/OpenLane#setting-up-openlane>`__.
268
269Hardening Options
270-----------------
Mohamed Kassem6f2fcd22021-04-19 10:14:19 -0700271
manarabdelatyfbd955f2021-09-20 11:59:53 +0200272There are three options for hardening the user project macro using
Mohamed Kassem6f2fcd22021-04-19 10:14:19 -0700273openlane:
274
Manar4ec8cba2021-10-04 10:26:10 -0500275+--------------------------------------------------------------+--------------------------------------------+--------------------------------------------+
276| Option 1 | Option 2 | Option 3 |
277+--------------------------------------------------------------+--------------------------------------------+--------------------------------------------+
278| Hardening the user macro(s) first, then inserting it in the | Flattening the user macro(s) with the | Placing multiple macros in the wrapper |
279| user project wrapper with no standard cells on the top level | user_project_wrapper | along with standard cells on the top level |
280+==============================================================+============================================+============================================+
281| |pic1| | |pic2| | |pic3| |
282| | | |
283+--------------------------------------------------------------+--------------------------------------------+--------------------------------------------+
284| ex: |link1| | | ex: |link2| |
285+--------------------------------------------------------------+--------------------------------------------+--------------------------------------------+
Mohamed Kassem6f2fcd22021-04-19 10:14:19 -0700286
Manar4ec8cba2021-10-04 10:26:10 -0500287.. |link1| replace:: `caravel_user_project <https://github.com/efabless/caravel_user_project>`__
288
289.. |link2| replace:: `caravel_ibex <https://github.com/efabless/caravel_ibex>`__
290
291
292.. |pic1| image:: ./_static/option1.png
293 :width: 48%
294
295.. |pic2| image:: ./_static/option2.png
296 :width: 140%
297
298.. |pic3| image:: ./_static/option3.png
299 :width: 72%
300
301For more details on hardening macros using openlane, refer to `README <https://github.com/The-OpenROAD-Project/OpenLane/blob/master/docs/source/hardening_macros.md>`__.
302
303
304Running OpenLane
305-----------------
Mohamed Kassem6f2fcd22021-04-19 10:14:19 -0700306
307For this sample project, we went for the first option where the user
308macro is hardened first, then it is inserted in the user project
manarabdelatyfbd955f2021-09-20 11:59:53 +0200309wrapper without having any standard cells on the top level.
Mohamed Kassem6f2fcd22021-04-19 10:14:19 -0700310
311.. raw:: html
312
313 <p align="center">
Manar4ec8cba2021-10-04 10:26:10 -0500314 <img src="./_static/wrapper.png" width="30%" height="30%">
Mohamed Kassem6f2fcd22021-04-19 10:14:19 -0700315 </p>
316
manarabdelatyd0e7afb2021-04-22 00:21:13 +0200317.. raw:: html
318
319 </p>
Manar4ec8cba2021-10-04 10:26:10 -0500320
Mohamed Kassem6f2fcd22021-04-19 10:14:19 -0700321To reproduce hardening this project, run the following:
322
323.. code:: bash
324
Marwan Abbasfa8d7ec2022-02-03 09:50:05 -0800325 # DO NOT cd into openlane
326
manarabdelaty0218c0f2021-04-29 18:31:49 +0200327 # Run openlane to harden user_proj_example
328 make user_proj_example
329 # Run openlane to harden user_project_wrapper
330 make user_project_wrapper
331
332
Manar4ec8cba2021-10-04 10:26:10 -0500333For more information on the openlane flow, check `README <https://github.com/The-OpenROAD-Project/OpenLane#readme>`__.
334
Manarf088db12021-09-20 12:13:04 +0200335Running MPW Precheck Locally
manarabdelaty0218c0f2021-04-29 18:31:49 +0200336=================================
337
Manar4ec8cba2021-10-04 10:26:10 -0500338You can install the `mpw-precheck <https://github.com/efabless/mpw_precheck>`__ by running
manarabdelaty0218c0f2021-04-29 18:31:49 +0200339
340.. code:: bash
341
342 # By default, this install the precheck in your home directory
343 # To change the installtion path, run "export PRECHECK_ROOT=<precheck installation path>"
344 make precheck
345
346This will clone the precheck repo and pull the latest precheck docker image.
347
348
349Then, you can run the precheck by running
350
351.. code:: bash
352
353 make run-precheck
354
355This will run all the precheck checks on your project and will produce the logs under the ``checks`` directory.
356
357
358Other Miscellaneous Targets
359============================
360
361The 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.
362
Manarf088db12021-09-20 12:13:04 +0200363Run ``make help`` to display available targets.
manarabdelaty0218c0f2021-04-29 18:31:49 +0200364
manarabdelaty0c03d602021-09-20 11:42:16 +0200365Run lvs on the mag view,
manarabdelaty0218c0f2021-04-29 18:31:49 +0200366
367.. code:: bash
368
369 make lvs-<macro_name>
370
371Run lvs on the gds,
372
373.. code:: bash
374
375 make lvs-gds-<macro_name>
376
377Run lvs on the maglef,
378
379.. code:: bash
380
381 make lvs-maglef-<macro_name>
382
383Run drc using magic,
384
385.. code:: bash
386
387 make drc-<macro_name>
388
389Run antenna check using magic,
390
391.. code:: bash
392
393 make antenna-<macro_name>
394
395Run XOR check,
396
397.. code:: bash
398
399 make xor-wrapper
Marwan Abbasfa8d7ec2022-02-03 09:50:05 -0800400
401
manarabdelaty0218c0f2021-04-29 18:31:49 +0200402
Mohamed Kassem6f2fcd22021-04-19 10:14:19 -0700403
404Checklist for Open-MPW Submission
405=================================
406
Manarf088db12021-09-20 12:13:04 +0200407- ✔️ The project repo adheres to the same directory structure in this
Mohamed Kassem6f2fcd22021-04-19 10:14:19 -0700408 repo.
Manarf088db12021-09-20 12:13:04 +0200409- ✔️ The project repo contain info.yaml at the project root.
410- ✔️ Top level macro is named ``user_project_wrapper``.
411- ✔️ Full Chip Simulation passes for RTL and GL (gate-level)
412- ✔️ The hardened Macros are LVS and DRC clean
Jeff DiCorpo9e950432021-10-24 10:09:39 -0700413- ✔️ The project contains a gate-level netlist for ``user_project_wrapper`` at verilog/gl/user_project_wrapper.v
Manarf088db12021-09-20 12:13:04 +0200414- ✔️ The hardened ``user_project_wrapper`` adheres to the same pin
Mohamed Kassem6f2fcd22021-04-19 10:14:19 -0700415 order specified at
416 `pin\_order <https://github.com/efabless/caravel/blob/master/openlane/user_project_wrapper_empty/pin_order.cfg>`__
Manarf088db12021-09-20 12:13:04 +0200417- ✔️ 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>`__
418- ✔️ XOR check passes with zero total difference.
419- ✔️ Openlane summary reports are retained under ./signoff/
420- ✔️ The design passes the `mpw-precheck <https://github.com/efabless/mpw_precheck>`__
Mohamed Kassem6f2fcd22021-04-19 10:14:19 -0700421
422.. |License| image:: https://img.shields.io/badge/License-Apache%202.0-blue.svg
423 :target: https://opensource.org/licenses/Apache-2.0
manarabdelatyd0e7afb2021-04-22 00:21:13 +0200424.. |User CI| image:: https://github.com/efabless/caravel_project_example/actions/workflows/user_project_ci.yml/badge.svg
425 :target: https://github.com/efabless/caravel_project_example/actions/workflows/user_project_ci.yml
426.. |Caravel Build| image:: https://github.com/efabless/caravel_project_example/actions/workflows/caravel_build.yml/badge.svg
Mohamed Kassem9ae1f072021-04-23 12:19:31 -0700427 :target: https://github.com/efabless/caravel_project_example/actions/workflows/caravel_build.yml