blob: 052fcf72392539d6d4b9f9c18c8621f7c2caf4f2 [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
58- Docker
59
manarabdelatyd0e7afb2021-04-22 00:21:13 +020060Install Caravel
61===============
62
63To setup caravel, run the following:
64
65.. code:: bash
Mohamed Kassem9ae1f072021-04-23 12:19:31 -070066
manarabdelaty0218c0f2021-04-29 18:31:49 +020067 git clone https://github.com/efabless/caravel_user_project.git
Mohamed Kassem9ae1f072021-04-23 12:19:31 -070068 cd caravel_user_project
Marwan Abbasca9b6922022-01-26 20:27:03 +020069
manarabdelatyd0e7afb2021-04-22 00:21:13 +020070 make install
71
manarabdelatyd0e7afb2021-04-22 00:21:13 +020072To remove caravel, run
73
74.. code:: bash
75
76 make uninstall
77
78By default
79`caravel-lite <https://github.com/efabless/caravel-lite.git>`__ is
80installed. To install the full version of caravel, run this prior to
81calling make install.
82
83.. code:: bash
84
85 export CARAVEL_LITE=0
86
Mohamed Kassem6f2fcd22021-04-19 10:14:19 -070087Caravel Integration
88===================
89
90Repo Integration
91----------------
92
93Caravel files are kept separate from the user project by having caravel
manarabdelatyd0e7afb2021-04-22 00:21:13 +020094as submodule. The submodule commit should point to the latest of
Manar4ec8cba2021-10-04 10:26:10 -050095caravel/caravel-lite master/main branch. The following files should have a symbolic
manarabdelatyd0e7afb2021-04-22 00:21:13 +020096link to `caravel's <https://github.com/efabless/caravel.git>`__
97corresponding files:
Mohamed Kassem6f2fcd22021-04-19 10:14:19 -070098
manarabdelaty0c03d602021-09-20 11:42:16 +020099- `Openlane Makefile <../../openlane/Makefile>`__: This provides an easier
manarabdelatyd0e7afb2021-04-22 00:21:13 +0200100 way for running openlane to harden your macros. Refer to `Hardening
101 the User Project Macro using
Marwan Abbasca9b6922022-01-26 20:27:03 +0200102 Openlane <#hardening-the-user-project-using-openlane>`__. Also,
manarabdelatyd0e7afb2021-04-22 00:21:13 +0200103 the makefile retains the openlane summary reports under the signoff
104 directory.
Mohamed Kassem6f2fcd22021-04-19 10:14:19 -0700105
manarabdelaty0c03d602021-09-20 11:42:16 +0200106- `Pin order <../../openlane/user_project_wrapper/pin_order.cfg>`__ file for
Mohamed Kassem6f2fcd22021-04-19 10:14:19 -0700107 the user wrapper: The hardened user project wrapper macro must have
108 the same pin order specified in caravel's repo. Failing to adhere to
109 the same order will fail the gds integration of the macro with
110 caravel's back-end.
111
manarabdelatyd0e7afb2021-04-22 00:21:13 +0200112The symbolic links are automatically set when you run ``make install``.
Mohamed Kassem6f2fcd22021-04-19 10:14:19 -0700113
114Verilog Integration
115-------------------
116
117You need to create a wrapper around your macro that adheres to the
118template at
Manarf088db12021-09-20 12:13:04 +0200119`user\_project\_wrapper <https://github.com/efabless/caravel/blob/master/verilog/rtl/__user_project_wrapper.v>`__.
Mohamed Kassem6f2fcd22021-04-19 10:14:19 -0700120The wrapper top module must be named ``user_project_wrapper`` and must
Manarf088db12021-09-20 12:13:04 +0200121have 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 -0700122user space utilities provided by caravel like IO ports, logic analyzer
123probes, and wishbone bus connection to the management SoC.
124
125For this sample project, the user macro makes use of:
126
127- The IO ports for displaying the count register values on the IO pads.
128
129- The LA probes for supplying an optional reset and clock signals and
130 for setting an initial value for the count register.
131
matt venn4acd8b72021-04-27 11:34:42 +0200132- The wishbone port for reading/writing the count value through the
Mohamed Kassem6f2fcd22021-04-19 10:14:19 -0700133 management SoC.
134
manarabdelatyfbd955f2021-09-20 11:59:53 +0200135Refer to `user\_project\_wrapper <../../verilog/rtl/user_project_wrapper.v>`__
Mohamed Kassem6f2fcd22021-04-19 10:14:19 -0700136for more information.
137
138.. raw:: html
139
140 <p align="center">
141 <img src="./_static/counter_32.png" width="50%" height="50%">
142 </p>
manarabdelatyd0e7afb2021-04-22 00:21:13 +0200143
Mohamed Kassem6f2fcd22021-04-19 10:14:19 -0700144.. raw:: html
145
146 </p>
147
Manar4ec8cba2021-10-04 10:26:10 -0500148
149Layout Integration
150-------------------
151
152The 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.
153
154.. raw:: html
155
156 <p align="center">
157 <img src="./_static/layout.png" width="80%" height="80%">
158 </p>
159
160To 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>`__ .
161
162
manarabdelatyd8dd0102021-04-30 08:40:52 +0200163Building the PDK
164================
Mohamed Kassem6f2fcd22021-04-19 10:14:19 -0700165
manarabdelatyd8dd0102021-04-30 08:40:52 +0200166Make sure you have `Magic VLSI Layout Tool <http://opencircuitdesign.com/magic/index.html>`__ installed on your machine before building the pdk.
Donne2c388a2022-02-03 18:14:12 +0000167The pdk build is tested with magic version ``8.3.265``.
manarabdelatyd0e7afb2021-04-22 00:21:13 +0200168
169.. code:: bash
170
171 # set PDK_ROOT to the path you wish to use for the pdk
172 export PDK_ROOT=<pdk-installation-path>
173
174 # you can optionally specify skywater-pdk and open-pdks commit used
175 # by setting and exporting SKYWATER_COMMIT and OPEN_PDKS_COMMIT
176 # if you do not set them, they default to the last verfied commits tested for this project
177
178 make pdk
179
manarabdelatyd8dd0102021-04-30 08:40:52 +0200180Running Full Chip Simulation
181============================
182
183First, you will need to install the simulation environment, by
184
185.. code:: bash
186
187 make simenv
188
189This will pull a docker image with the needed tools installed.
190
Manar4ec8cba2021-10-04 10:26:10 -0500191Then, run the RTL simulation by
manarabdelatyd0e7afb2021-04-22 00:21:13 +0200192
193.. code:: bash
194
195 export PDK_ROOT=<pdk-installation-path>
manarabdelatyd0e7afb2021-04-22 00:21:13 +0200196 # specify simulation mode: RTL/GL
197 export SIM=RTL
Manar4ec8cba2021-10-04 10:26:10 -0500198 # Run RTL simulation on IO ports testbench, make verify-io_ports
199 make verify-<testbench-name>
manarabdelatyd0e7afb2021-04-22 00:21:13 +0200200
Manar4ec8cba2021-10-04 10:26:10 -0500201Once 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.
202
203Run the gate-level simulation by:
204
205.. code:: bash
206
207 export PDK_ROOT=<pdk-installation-path>
Manar4ec8cba2021-10-04 10:26:10 -0500208 # specify simulation mode: RTL/GL
209 export SIM=GL
210 # Run RTL simulation on IO ports testbench, make verify-io_ports
211 make verify-<testbench-name>
212
213
214This sample project comes with four example testbenches to test the IO port connection, wishbone interface, and logic analyzer. The test-benches are under the
215`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 +0200216simulation environment and the available testbenches for this sample
Manarffaf9842021-04-30 22:55:37 +0200217project, refer to `README <https://github.com/efabless/caravel_user_project/blob/main/verilog/dv/README.md>`__.
Mohamed Kassem6f2fcd22021-04-19 10:14:19 -0700218
Manar4ec8cba2021-10-04 10:26:10 -0500219
220User Project Wrapper Requirements
221=================================
222
223Your 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:
224
225- Area ``(2.920um x 3.520um)``
226- Top module name ``"user_project_wrapper"``
227- Pin Placement
228- Pin Sizes
229- Core Rings Width and Offset
230- PDN Vertical and Horizontal Straps Width
231
232
233.. raw:: html
234
235 <p align="center">
236 <img src="./_static/empty.png" width="40%" height="40%">
237 </p>
238
Marwan Abbasca9b6922022-01-26 20:27:03 +0200239You are allowed to change the following if you need to:
Manar4ec8cba2021-10-04 10:26:10 -0500240
241- PDN Vertical and Horizontal Pitch & Offset
242
243.. raw:: html
244
245 <p align="center">
246 <img src="./_static/pitch.png" width="30%" height="30%">
247 </p>
248
249To 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.
250
251
252Hardening the User Project using OpenLane
253==========================================
254
255OpenLane Installation
256---------------------
Mohamed Kassem6f2fcd22021-04-19 10:14:19 -0700257
manarabdelatyd8dd0102021-04-30 08:40:52 +0200258You will need to install openlane by running the following
manarabdelatyd0e7afb2021-04-22 00:21:13 +0200259
260.. code:: bash
261
manarabdelaty0218c0f2021-04-29 18:31:49 +0200262 export OPENLANE_ROOT=<openlane-installation-path>
manarabdelatyfbd955f2021-09-20 11:59:53 +0200263
264 # you can optionally specify the openlane tag to use
265 # by running: export OPENLANE_TAG=<openlane-tag>
266 # if you do not set the tag, it defaults to the last verfied tag tested for this project
267
manarabdelaty0218c0f2021-04-29 18:31:49 +0200268 make openlane
manarabdelatyd0e7afb2021-04-22 00:21:13 +0200269
manarabdelatyfbd955f2021-09-20 11:59:53 +0200270For detailed instructions on the openlane and the pdk installation refer
manarabdelatyd0e7afb2021-04-22 00:21:13 +0200271to
Manar4ec8cba2021-10-04 10:26:10 -0500272`README <https://github.com/The-OpenROAD-Project/OpenLane#setting-up-openlane>`__.
273
274Hardening Options
275-----------------
Mohamed Kassem6f2fcd22021-04-19 10:14:19 -0700276
manarabdelatyfbd955f2021-09-20 11:59:53 +0200277There are three options for hardening the user project macro using
Mohamed Kassem6f2fcd22021-04-19 10:14:19 -0700278openlane:
279
Manar4ec8cba2021-10-04 10:26:10 -0500280+--------------------------------------------------------------+--------------------------------------------+--------------------------------------------+
281| Option 1 | Option 2 | Option 3 |
282+--------------------------------------------------------------+--------------------------------------------+--------------------------------------------+
283| Hardening the user macro(s) first, then inserting it in the | Flattening the user macro(s) with the | Placing multiple macros in the wrapper |
284| user project wrapper with no standard cells on the top level | user_project_wrapper | along with standard cells on the top level |
285+==============================================================+============================================+============================================+
286| |pic1| | |pic2| | |pic3| |
287| | | |
288+--------------------------------------------------------------+--------------------------------------------+--------------------------------------------+
289| ex: |link1| | | ex: |link2| |
290+--------------------------------------------------------------+--------------------------------------------+--------------------------------------------+
Mohamed Kassem6f2fcd22021-04-19 10:14:19 -0700291
Manar4ec8cba2021-10-04 10:26:10 -0500292.. |link1| replace:: `caravel_user_project <https://github.com/efabless/caravel_user_project>`__
293
294.. |link2| replace:: `caravel_ibex <https://github.com/efabless/caravel_ibex>`__
295
296
297.. |pic1| image:: ./_static/option1.png
298 :width: 48%
299
300.. |pic2| image:: ./_static/option2.png
301 :width: 140%
302
303.. |pic3| image:: ./_static/option3.png
304 :width: 72%
305
306For more details on hardening macros using openlane, refer to `README <https://github.com/The-OpenROAD-Project/OpenLane/blob/master/docs/source/hardening_macros.md>`__.
307
308
309Running OpenLane
310-----------------
Mohamed Kassem6f2fcd22021-04-19 10:14:19 -0700311
312For this sample project, we went for the first option where the user
313macro is hardened first, then it is inserted in the user project
manarabdelatyfbd955f2021-09-20 11:59:53 +0200314wrapper without having any standard cells on the top level.
Mohamed Kassem6f2fcd22021-04-19 10:14:19 -0700315
316.. raw:: html
317
318 <p align="center">
Manar4ec8cba2021-10-04 10:26:10 -0500319 <img src="./_static/wrapper.png" width="30%" height="30%">
Mohamed Kassem6f2fcd22021-04-19 10:14:19 -0700320 </p>
321
manarabdelatyd0e7afb2021-04-22 00:21:13 +0200322.. raw:: html
323
324 </p>
Manar4ec8cba2021-10-04 10:26:10 -0500325
Mohamed Kassem6f2fcd22021-04-19 10:14:19 -0700326To reproduce hardening this project, run the following:
327
328.. code:: bash
329
Marwan Abbasfa8d7ec2022-02-03 09:50:05 -0800330 # DO NOT cd into openlane
331
manarabdelaty0218c0f2021-04-29 18:31:49 +0200332 # Run openlane to harden user_proj_example
333 make user_proj_example
334 # Run openlane to harden user_project_wrapper
335 make user_project_wrapper
336
337
Manar4ec8cba2021-10-04 10:26:10 -0500338For more information on the openlane flow, check `README <https://github.com/The-OpenROAD-Project/OpenLane#readme>`__.
339
Manarf088db12021-09-20 12:13:04 +0200340Running MPW Precheck Locally
manarabdelaty0218c0f2021-04-29 18:31:49 +0200341=================================
342
Manar4ec8cba2021-10-04 10:26:10 -0500343You can install the `mpw-precheck <https://github.com/efabless/mpw_precheck>`__ by running
manarabdelaty0218c0f2021-04-29 18:31:49 +0200344
345.. code:: bash
346
347 # By default, this install the precheck in your home directory
348 # To change the installtion path, run "export PRECHECK_ROOT=<precheck installation path>"
349 make precheck
350
351This will clone the precheck repo and pull the latest precheck docker image.
352
353
354Then, you can run the precheck by running
355
356.. code:: bash
357
358 make run-precheck
359
360This will run all the precheck checks on your project and will produce the logs under the ``checks`` directory.
361
362
363Other Miscellaneous Targets
364============================
365
366The 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.
367
Manarf088db12021-09-20 12:13:04 +0200368Run ``make help`` to display available targets.
manarabdelaty0218c0f2021-04-29 18:31:49 +0200369
manarabdelaty0c03d602021-09-20 11:42:16 +0200370Run lvs on the mag view,
manarabdelaty0218c0f2021-04-29 18:31:49 +0200371
372.. code:: bash
373
374 make lvs-<macro_name>
375
376Run lvs on the gds,
377
378.. code:: bash
379
380 make lvs-gds-<macro_name>
381
382Run lvs on the maglef,
383
384.. code:: bash
385
386 make lvs-maglef-<macro_name>
387
388Run drc using magic,
389
390.. code:: bash
391
392 make drc-<macro_name>
393
394Run antenna check using magic,
395
396.. code:: bash
397
398 make antenna-<macro_name>
399
400Run XOR check,
401
402.. code:: bash
403
404 make xor-wrapper
Marwan Abbasfa8d7ec2022-02-03 09:50:05 -0800405
406
manarabdelaty0218c0f2021-04-29 18:31:49 +0200407
Mohamed Kassem6f2fcd22021-04-19 10:14:19 -0700408
409Checklist for Open-MPW Submission
410=================================
411
Manarf088db12021-09-20 12:13:04 +0200412- ✔️ The project repo adheres to the same directory structure in this
Mohamed Kassem6f2fcd22021-04-19 10:14:19 -0700413 repo.
Manarf088db12021-09-20 12:13:04 +0200414- ✔️ The project repo contain info.yaml at the project root.
415- ✔️ Top level macro is named ``user_project_wrapper``.
416- ✔️ Full Chip Simulation passes for RTL and GL (gate-level)
417- ✔️ The hardened Macros are LVS and DRC clean
Jeff DiCorpo9e950432021-10-24 10:09:39 -0700418- ✔️ The project contains a gate-level netlist for ``user_project_wrapper`` at verilog/gl/user_project_wrapper.v
Manarf088db12021-09-20 12:13:04 +0200419- ✔️ The hardened ``user_project_wrapper`` adheres to the same pin
Mohamed Kassem6f2fcd22021-04-19 10:14:19 -0700420 order specified at
421 `pin\_order <https://github.com/efabless/caravel/blob/master/openlane/user_project_wrapper_empty/pin_order.cfg>`__
Manarf088db12021-09-20 12:13:04 +0200422- ✔️ 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>`__
423- ✔️ XOR check passes with zero total difference.
424- ✔️ Openlane summary reports are retained under ./signoff/
425- ✔️ The design passes the `mpw-precheck <https://github.com/efabless/mpw_precheck>`__
Mohamed Kassem6f2fcd22021-04-19 10:14:19 -0700426
427.. |License| image:: https://img.shields.io/badge/License-Apache%202.0-blue.svg
428 :target: https://opensource.org/licenses/Apache-2.0
manarabdelatyd0e7afb2021-04-22 00:21:13 +0200429.. |User CI| image:: https://github.com/efabless/caravel_project_example/actions/workflows/user_project_ci.yml/badge.svg
430 :target: https://github.com/efabless/caravel_project_example/actions/workflows/user_project_ci.yml
431.. |Caravel Build| image:: https://github.com/efabless/caravel_project_example/actions/workflows/caravel_build.yml/badge.svg
Mohamed Kassem9ae1f072021-04-23 12:19:31 -0700432 :target: https://github.com/efabless/caravel_project_example/actions/workflows/caravel_build.yml