blob: 9bcf7414ea713cd87c8b3b40fa3a609bc4358ea8 [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 Abbasfab39d92022-04-06 22:39:21 +0200174
175 # set the OPENLANE_ROOT to the openlane installation path
176 export OPENLANE_ROOT=<openlane-installation-path>
manarabdelatyd0e7afb2021-04-22 00:21:13 +0200177
Marwan Abbas073ecab2022-04-03 14:52:46 +0200178 # use volare to download the pdk
Marwan Abbasfab39d92022-04-06 22:39:21 +0200179 make pdk-with-volare
manarabdelatyd0e7afb2021-04-22 00:21:13 +0200180
manarabdelatyd8dd0102021-04-30 08:40:52 +0200181Running Full Chip Simulation
182============================
183
184First, you will need to install the simulation environment, by
185
186.. code:: bash
187
188 make simenv
189
190This will pull a docker image with the needed tools installed.
191
Manar4ec8cba2021-10-04 10:26:10 -0500192Then, run the RTL simulation by
manarabdelatyd0e7afb2021-04-22 00:21:13 +0200193
194.. code:: bash
195
196 export PDK_ROOT=<pdk-installation-path>
Manar4ec8cba2021-10-04 10:26:10 -0500197 # Run RTL simulation on IO ports testbench, make verify-io_ports
Marwan Abbas0914d042022-04-06 19:06:34 +0200198 make verify-<testbench-name>-rtl
manarabdelatyd0e7afb2021-04-22 00:21:13 +0200199
Manar4ec8cba2021-10-04 10:26:10 -0500200Once 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.
201
202Run the gate-level simulation by:
203
204.. code:: bash
205
206 export PDK_ROOT=<pdk-installation-path>
Manar4ec8cba2021-10-04 10:26:10 -0500207 # Run RTL simulation on IO ports testbench, make verify-io_ports
Marwan Abbas0914d042022-04-06 19:06:34 +0200208 make verify-<testbench-name>-gl
Manar4ec8cba2021-10-04 10:26:10 -0500209
210
211This sample project comes with four example testbenches to test the IO port connection, wishbone interface, and logic analyzer. The test-benches are under the
212`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 +0200213simulation environment and the available testbenches for this sample
Manarffaf9842021-04-30 22:55:37 +0200214project, refer to `README <https://github.com/efabless/caravel_user_project/blob/main/verilog/dv/README.md>`__.
Mohamed Kassem6f2fcd22021-04-19 10:14:19 -0700215
Manar4ec8cba2021-10-04 10:26:10 -0500216
217User Project Wrapper Requirements
218=================================
219
220Your 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:
221
222- Area ``(2.920um x 3.520um)``
223- Top module name ``"user_project_wrapper"``
224- Pin Placement
225- Pin Sizes
226- Core Rings Width and Offset
227- PDN Vertical and Horizontal Straps Width
228
229
230.. raw:: html
231
232 <p align="center">
233 <img src="./_static/empty.png" width="40%" height="40%">
234 </p>
235
Marwan Abbasca9b6922022-01-26 20:27:03 +0200236You are allowed to change the following if you need to:
Manar4ec8cba2021-10-04 10:26:10 -0500237
238- PDN Vertical and Horizontal Pitch & Offset
239
240.. raw:: html
241
242 <p align="center">
243 <img src="./_static/pitch.png" width="30%" height="30%">
244 </p>
245
246To 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.
247
248
249Hardening the User Project using OpenLane
250==========================================
251
252OpenLane Installation
253---------------------
Mohamed Kassem6f2fcd22021-04-19 10:14:19 -0700254
manarabdelatyd8dd0102021-04-30 08:40:52 +0200255You will need to install openlane by running the following
manarabdelatyd0e7afb2021-04-22 00:21:13 +0200256
257.. code:: bash
258
manarabdelaty0218c0f2021-04-29 18:31:49 +0200259 export OPENLANE_ROOT=<openlane-installation-path>
manarabdelatyfbd955f2021-09-20 11:59:53 +0200260
261 # you can optionally specify the openlane tag to use
262 # by running: export OPENLANE_TAG=<openlane-tag>
263 # if you do not set the tag, it defaults to the last verfied tag tested for this project
264
manarabdelaty0218c0f2021-04-29 18:31:49 +0200265 make openlane
manarabdelatyd0e7afb2021-04-22 00:21:13 +0200266
manarabdelatyfbd955f2021-09-20 11:59:53 +0200267For detailed instructions on the openlane and the pdk installation refer
manarabdelatyd0e7afb2021-04-22 00:21:13 +0200268to
Manar4ec8cba2021-10-04 10:26:10 -0500269`README <https://github.com/The-OpenROAD-Project/OpenLane#setting-up-openlane>`__.
270
271Hardening Options
272-----------------
Mohamed Kassem6f2fcd22021-04-19 10:14:19 -0700273
manarabdelatyfbd955f2021-09-20 11:59:53 +0200274There are three options for hardening the user project macro using
Mohamed Kassem6f2fcd22021-04-19 10:14:19 -0700275openlane:
276
Manar4ec8cba2021-10-04 10:26:10 -0500277+--------------------------------------------------------------+--------------------------------------------+--------------------------------------------+
278| Option 1 | Option 2 | Option 3 |
279+--------------------------------------------------------------+--------------------------------------------+--------------------------------------------+
280| Hardening the user macro(s) first, then inserting it in the | Flattening the user macro(s) with the | Placing multiple macros in the wrapper |
281| user project wrapper with no standard cells on the top level | user_project_wrapper | along with standard cells on the top level |
282+==============================================================+============================================+============================================+
283| |pic1| | |pic2| | |pic3| |
284| | | |
285+--------------------------------------------------------------+--------------------------------------------+--------------------------------------------+
286| ex: |link1| | | ex: |link2| |
287+--------------------------------------------------------------+--------------------------------------------+--------------------------------------------+
Mohamed Kassem6f2fcd22021-04-19 10:14:19 -0700288
Manar4ec8cba2021-10-04 10:26:10 -0500289.. |link1| replace:: `caravel_user_project <https://github.com/efabless/caravel_user_project>`__
290
291.. |link2| replace:: `caravel_ibex <https://github.com/efabless/caravel_ibex>`__
292
293
294.. |pic1| image:: ./_static/option1.png
295 :width: 48%
296
297.. |pic2| image:: ./_static/option2.png
298 :width: 140%
299
300.. |pic3| image:: ./_static/option3.png
301 :width: 72%
302
303For more details on hardening macros using openlane, refer to `README <https://github.com/The-OpenROAD-Project/OpenLane/blob/master/docs/source/hardening_macros.md>`__.
304
305
306Running OpenLane
307-----------------
Mohamed Kassem6f2fcd22021-04-19 10:14:19 -0700308
309For this sample project, we went for the first option where the user
310macro is hardened first, then it is inserted in the user project
manarabdelatyfbd955f2021-09-20 11:59:53 +0200311wrapper without having any standard cells on the top level.
Mohamed Kassem6f2fcd22021-04-19 10:14:19 -0700312
313.. raw:: html
314
315 <p align="center">
Manar4ec8cba2021-10-04 10:26:10 -0500316 <img src="./_static/wrapper.png" width="30%" height="30%">
Mohamed Kassem6f2fcd22021-04-19 10:14:19 -0700317 </p>
318
manarabdelatyd0e7afb2021-04-22 00:21:13 +0200319.. raw:: html
320
321 </p>
Manar4ec8cba2021-10-04 10:26:10 -0500322
Mohamed Kassem6f2fcd22021-04-19 10:14:19 -0700323To reproduce hardening this project, run the following:
324
325.. code:: bash
326
Marwan Abbasfa8d7ec2022-02-03 09:50:05 -0800327 # DO NOT cd into openlane
328
manarabdelaty0218c0f2021-04-29 18:31:49 +0200329 # Run openlane to harden user_proj_example
330 make user_proj_example
331 # Run openlane to harden user_project_wrapper
332 make user_project_wrapper
333
334
Manar4ec8cba2021-10-04 10:26:10 -0500335For more information on the openlane flow, check `README <https://github.com/The-OpenROAD-Project/OpenLane#readme>`__.
336
Manarf088db12021-09-20 12:13:04 +0200337Running MPW Precheck Locally
manarabdelaty0218c0f2021-04-29 18:31:49 +0200338=================================
339
Manar4ec8cba2021-10-04 10:26:10 -0500340You can install the `mpw-precheck <https://github.com/efabless/mpw_precheck>`__ by running
manarabdelaty0218c0f2021-04-29 18:31:49 +0200341
342.. code:: bash
343
344 # By default, this install the precheck in your home directory
345 # To change the installtion path, run "export PRECHECK_ROOT=<precheck installation path>"
346 make precheck
347
348This will clone the precheck repo and pull the latest precheck docker image.
349
350
351Then, you can run the precheck by running
352
353.. code:: bash
354
355 make run-precheck
356
357This will run all the precheck checks on your project and will produce the logs under the ``checks`` directory.
358
359
360Other Miscellaneous Targets
361============================
362
363The 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.
364
Manarf088db12021-09-20 12:13:04 +0200365Run ``make help`` to display available targets.
manarabdelaty0218c0f2021-04-29 18:31:49 +0200366
manarabdelaty0c03d602021-09-20 11:42:16 +0200367Run lvs on the mag view,
manarabdelaty0218c0f2021-04-29 18:31:49 +0200368
369.. code:: bash
370
371 make lvs-<macro_name>
372
373Run lvs on the gds,
374
375.. code:: bash
376
377 make lvs-gds-<macro_name>
378
379Run lvs on the maglef,
380
381.. code:: bash
382
383 make lvs-maglef-<macro_name>
384
385Run drc using magic,
386
387.. code:: bash
388
389 make drc-<macro_name>
390
391Run antenna check using magic,
392
393.. code:: bash
394
395 make antenna-<macro_name>
396
397Run XOR check,
398
399.. code:: bash
400
401 make xor-wrapper
Marwan Abbasfa8d7ec2022-02-03 09:50:05 -0800402
403
manarabdelaty0218c0f2021-04-29 18:31:49 +0200404
Mohamed Kassem6f2fcd22021-04-19 10:14:19 -0700405
406Checklist for Open-MPW Submission
407=================================
408
Manarf088db12021-09-20 12:13:04 +0200409- ✔️ The project repo adheres to the same directory structure in this
Mohamed Kassem6f2fcd22021-04-19 10:14:19 -0700410 repo.
Manarf088db12021-09-20 12:13:04 +0200411- ✔️ The project repo contain info.yaml at the project root.
412- ✔️ Top level macro is named ``user_project_wrapper``.
413- ✔️ Full Chip Simulation passes for RTL and GL (gate-level)
414- ✔️ The hardened Macros are LVS and DRC clean
Jeff DiCorpo9e950432021-10-24 10:09:39 -0700415- ✔️ The project contains a gate-level netlist for ``user_project_wrapper`` at verilog/gl/user_project_wrapper.v
Manarf088db12021-09-20 12:13:04 +0200416- ✔️ The hardened ``user_project_wrapper`` adheres to the same pin
Mohamed Kassem6f2fcd22021-04-19 10:14:19 -0700417 order specified at
418 `pin\_order <https://github.com/efabless/caravel/blob/master/openlane/user_project_wrapper_empty/pin_order.cfg>`__
Manarf088db12021-09-20 12:13:04 +0200419- ✔️ 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>`__
420- ✔️ XOR check passes with zero total difference.
421- ✔️ Openlane summary reports are retained under ./signoff/
422- ✔️ The design passes the `mpw-precheck <https://github.com/efabless/mpw_precheck>`__
Mohamed Kassem6f2fcd22021-04-19 10:14:19 -0700423
424.. |License| image:: https://img.shields.io/badge/License-Apache%202.0-blue.svg
425 :target: https://opensource.org/licenses/Apache-2.0
manarabdelatyd0e7afb2021-04-22 00:21:13 +0200426.. |User CI| image:: https://github.com/efabless/caravel_project_example/actions/workflows/user_project_ci.yml/badge.svg
427 :target: https://github.com/efabless/caravel_project_example/actions/workflows/user_project_ci.yml
428.. |Caravel Build| image:: https://github.com/efabless/caravel_project_example/actions/workflows/caravel_build.yml/badge.svg
Mohamed Kassem9ae1f072021-04-23 12:19:31 -0700429 :target: https://github.com/efabless/caravel_project_example/actions/workflows/caravel_build.yml