blob: fa3f806d801ec2593909075d8330429d9da3d887 [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>`__
35
36- `Running Full Chip Simulation <#running-full-chip-simulation>`__
37- `Hardening the User Project Macro using
38 Openlane <#hardening-the-user-project-macro-using-openlane>`__
39- `Checklist for Open-MPW
40 Submission <#checklist-for-open-mpw-submission>`__
41
42Overview
43========
44
45This repo contains a sample user project that utilizes the
46`caravel <https://github.com/efabless/caravel.git>`__ chip user space.
47The user project is a simple counter that showcases how to make use of
48`caravel's <https://github.com/efabless/caravel.git>`__ user space
49utilities like IO pads, logic analyzer probes, and wishbone port. The
50repo also demonstrates the recommended structure for the open-mpw
51shuttle projects.
52
manarabdelatyd8dd0102021-04-30 08:40:52 +020053Prerequisites
54=============
55
56- Docker
57
manarabdelatyd0e7afb2021-04-22 00:21:13 +020058Install Caravel
59===============
60
61To setup caravel, run the following:
62
63.. code:: bash
64
matt venn77f39732021-05-04 13:31:13 +020065 # If unset, CARAVEL_ROOT will be set to $(pwd)/caravel
manarabdelatyd0e7afb2021-04-22 00:21:13 +020066 # If you want to install caravel at a different location, run "export CARAVEL_ROOT=<caravel-path>"
matt venn77f39732021-05-04 13:31:13 +020067 export CARAVEL_ROOT=$(pwd)/caravel
68
manarabdelatyd0e7afb2021-04-22 00:21:13 +020069 # Disable submodule installation if needed by, run "export SUBMODULE=0"
Mohamed Kassem9ae1f072021-04-23 12:19:31 -070070
manarabdelaty0218c0f2021-04-29 18:31:49 +020071 git clone https://github.com/efabless/caravel_user_project.git
Mohamed Kassem9ae1f072021-04-23 12:19:31 -070072 cd caravel_user_project
manarabdelatyd0e7afb2021-04-22 00:21:13 +020073 make install
74
75To update the installed caravel to the latest, run:
76
77.. code:: bash
78
79 make update_caravel
80
81To remove caravel, run
82
83.. code:: bash
84
85 make uninstall
86
87By default
88`caravel-lite <https://github.com/efabless/caravel-lite.git>`__ is
89installed. To install the full version of caravel, run this prior to
90calling make install.
91
92.. code:: bash
93
94 export CARAVEL_LITE=0
95
Mohamed Kassem6f2fcd22021-04-19 10:14:19 -070096Caravel Integration
97===================
98
99Repo Integration
100----------------
101
102Caravel files are kept separate from the user project by having caravel
manarabdelatyd0e7afb2021-04-22 00:21:13 +0200103as submodule. The submodule commit should point to the latest of
104caravel/caravel-lite master. The following files should have a symbolic
105link to `caravel's <https://github.com/efabless/caravel.git>`__
106corresponding files:
Mohamed Kassem6f2fcd22021-04-19 10:14:19 -0700107
manarabdelaty0c03d602021-09-20 11:42:16 +0200108- `Openlane Makefile <../../openlane/Makefile>`__: This provides an easier
manarabdelatyd0e7afb2021-04-22 00:21:13 +0200109 way for running openlane to harden your macros. Refer to `Hardening
110 the User Project Macro using
111 Openlane <#hardening-the-user-project-macro-using-openlane>`__. Also,
112 the makefile retains the openlane summary reports under the signoff
113 directory.
Mohamed Kassem6f2fcd22021-04-19 10:14:19 -0700114
manarabdelaty0c03d602021-09-20 11:42:16 +0200115- `Pin order <../../openlane/user_project_wrapper/pin_order.cfg>`__ file for
Mohamed Kassem6f2fcd22021-04-19 10:14:19 -0700116 the user wrapper: The hardened user project wrapper macro must have
117 the same pin order specified in caravel's repo. Failing to adhere to
118 the same order will fail the gds integration of the macro with
119 caravel's back-end.
120
manarabdelatyd0e7afb2021-04-22 00:21:13 +0200121The symbolic links are automatically set when you run ``make install``.
Mohamed Kassem6f2fcd22021-04-19 10:14:19 -0700122
123Verilog Integration
124-------------------
125
126You need to create a wrapper around your macro that adheres to the
127template at
Manarf088db12021-09-20 12:13:04 +0200128`user\_project\_wrapper <https://github.com/efabless/caravel/blob/master/verilog/rtl/__user_project_wrapper.v>`__.
Mohamed Kassem6f2fcd22021-04-19 10:14:19 -0700129The wrapper top module must be named ``user_project_wrapper`` and must
Manarf088db12021-09-20 12:13:04 +0200130have 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 -0700131user space utilities provided by caravel like IO ports, logic analyzer
132probes, and wishbone bus connection to the management SoC.
133
134For this sample project, the user macro makes use of:
135
136- The IO ports for displaying the count register values on the IO pads.
137
138- The LA probes for supplying an optional reset and clock signals and
139 for setting an initial value for the count register.
140
matt venn4acd8b72021-04-27 11:34:42 +0200141- The wishbone port for reading/writing the count value through the
Mohamed Kassem6f2fcd22021-04-19 10:14:19 -0700142 management SoC.
143
manarabdelatyfbd955f2021-09-20 11:59:53 +0200144Refer to `user\_project\_wrapper <../../verilog/rtl/user_project_wrapper.v>`__
Mohamed Kassem6f2fcd22021-04-19 10:14:19 -0700145for more information.
146
147.. raw:: html
148
149 <p align="center">
150 <img src="./_static/counter_32.png" width="50%" height="50%">
151 </p>
manarabdelatyd0e7afb2021-04-22 00:21:13 +0200152
Mohamed Kassem6f2fcd22021-04-19 10:14:19 -0700153.. raw:: html
154
155 </p>
156
manarabdelatyd8dd0102021-04-30 08:40:52 +0200157Building the PDK
158================
Mohamed Kassem6f2fcd22021-04-19 10:14:19 -0700159
manarabdelatyd8dd0102021-04-30 08:40:52 +0200160You have two options for building the pdk:
manarabdelatyd0e7afb2021-04-22 00:21:13 +0200161
manarabdelatyd8dd0102021-04-30 08:40:52 +0200162- Build the pdk natively.
manarabdelatyd0e7afb2021-04-22 00:21:13 +0200163
manarabdelatyd8dd0102021-04-30 08:40:52 +0200164Make sure you have `Magic VLSI Layout Tool <http://opencircuitdesign.com/magic/index.html>`__ installed on your machine before building the pdk.
manarabdelaty5f512a22021-09-20 13:20:57 +0200165The pdk build is tested with magic version `8.3.209`.
manarabdelatyd0e7afb2021-04-22 00:21:13 +0200166
167.. code:: bash
168
169 # set PDK_ROOT to the path you wish to use for the pdk
170 export PDK_ROOT=<pdk-installation-path>
171
172 # you can optionally specify skywater-pdk and open-pdks commit used
173 # by setting and exporting SKYWATER_COMMIT and OPEN_PDKS_COMMIT
174 # if you do not set them, they default to the last verfied commits tested for this project
175
176 make pdk
177
manarabdelatyd8dd0102021-04-30 08:40:52 +0200178- Build the pdk using openlane's docker image which has magic installed.
179
180.. code:: bash
181
182 # set PDK_ROOT to the path you wish to use for the pdk
183 export PDK_ROOT=<pdk-installation-path>
184
185 # you can optionally specify skywater-pdk and open-pdks commit used
186 # by setting and exporting SKYWATER_COMMIT and OPEN_PDKS_COMMIT
187 # if you do not set them, they default to the last verfied commits tested for this project
188
189 make pdk-nonnative
190
191Running Full Chip Simulation
192============================
193
194First, you will need to install the simulation environment, by
195
196.. code:: bash
197
198 make simenv
199
200This will pull a docker image with the needed tools installed.
201
manarabdelatyd0e7afb2021-04-22 00:21:13 +0200202Then, run the RTL and GL simulation by
203
204.. code:: bash
205
206 export PDK_ROOT=<pdk-installation-path>
207 export CARAVEL_ROOT=$(pwd)/caravel
208 # specify simulation mode: RTL/GL
209 export SIM=RTL
210 # Run IO ports testbench, make verify-io_ports
211 make verify-<dv-pattern>
212
213The verilog test-benches are under this directory
Manarffaf9842021-04-30 22:55:37 +0200214`verilog/dv <https://github.com/efabless/caravel_user_project/tree/main/verilog/dv>`__. For more information on setting up the
manarabdelatyd0e7afb2021-04-22 00:21:13 +0200215simulation environment and the available testbenches for this sample
Manarffaf9842021-04-30 22:55:37 +0200216project, refer to `README <https://github.com/efabless/caravel_user_project/blob/main/verilog/dv/README.md>`__.
Mohamed Kassem6f2fcd22021-04-19 10:14:19 -0700217
218Hardening the User Project Macro using Openlane
219===============================================
220
manarabdelatyd8dd0102021-04-30 08:40:52 +0200221You will need to install openlane by running the following
manarabdelatyd0e7afb2021-04-22 00:21:13 +0200222
223.. code:: bash
224
manarabdelaty0218c0f2021-04-29 18:31:49 +0200225 export OPENLANE_ROOT=<openlane-installation-path>
manarabdelatyfbd955f2021-09-20 11:59:53 +0200226
227 # you can optionally specify the openlane tag to use
228 # by running: export OPENLANE_TAG=<openlane-tag>
229 # if you do not set the tag, it defaults to the last verfied tag tested for this project
230
manarabdelaty0218c0f2021-04-29 18:31:49 +0200231 make openlane
manarabdelatyd0e7afb2021-04-22 00:21:13 +0200232
manarabdelatyfbd955f2021-09-20 11:59:53 +0200233For detailed instructions on the openlane and the pdk installation refer
manarabdelatyd0e7afb2021-04-22 00:21:13 +0200234to
Mohamed Kassem6f2fcd22021-04-19 10:14:19 -0700235`README <https://github.com/efabless/openlane/blob/master/README.md>`__.
236
manarabdelatyfbd955f2021-09-20 11:59:53 +0200237There are three options for hardening the user project macro using
Mohamed Kassem6f2fcd22021-04-19 10:14:19 -0700238openlane:
239
2401. Hardening the user macro, then embedding it in the wrapper
2412. Flattening the user macro with the wrapper.
manarabdelatyfbd955f2021-09-20 11:59:53 +02002423. Placing multiple macros in the wrapper along with standard cells on the top level.
Mohamed Kassem6f2fcd22021-04-19 10:14:19 -0700243
manarabdelatyfbd955f2021-09-20 11:59:53 +0200244For more details on hardening the user project macro using openlane, refer to `README <https://github.com/efabless/caravel/blob/master/openlane/README.rst>`__.
Mohamed Kassem6f2fcd22021-04-19 10:14:19 -0700245
246For this sample project, we went for the first option where the user
247macro is hardened first, then it is inserted in the user project
manarabdelatyfbd955f2021-09-20 11:59:53 +0200248wrapper without having any standard cells on the top level.
Mohamed Kassem6f2fcd22021-04-19 10:14:19 -0700249
250.. raw:: html
251
252 <p align="center">
253 <img src="./_static/wrapper.png" width="50%" height="50%">
254 </p>
255
manarabdelatyd0e7afb2021-04-22 00:21:13 +0200256.. raw:: html
257
258 </p>
259
Mohamed Kassem6f2fcd22021-04-19 10:14:19 -0700260To reproduce hardening this project, run the following:
261
262.. code:: bash
263
manarabdelaty0218c0f2021-04-29 18:31:49 +0200264 # Run openlane to harden user_proj_example
265 make user_proj_example
266 # Run openlane to harden user_project_wrapper
267 make user_project_wrapper
268
269
Manarf088db12021-09-20 12:13:04 +0200270Running MPW Precheck Locally
manarabdelaty0218c0f2021-04-29 18:31:49 +0200271=================================
272
273You can install the precheck by running
274
275.. code:: bash
276
277 # By default, this install the precheck in your home directory
278 # To change the installtion path, run "export PRECHECK_ROOT=<precheck installation path>"
279 make precheck
280
281This will clone the precheck repo and pull the latest precheck docker image.
282
283
284Then, you can run the precheck by running
manarabdelatyd8dd0102021-04-30 08:40:52 +0200285Specify CARAVEL_ROOT before running any of the following,
manarabdelaty0218c0f2021-04-29 18:31:49 +0200286
287.. code:: bash
288
manarabdelatyd8dd0102021-04-30 08:40:52 +0200289 # export CARAVEL_ROOT=$(pwd)/caravel
290 export CARAVEL_ROOT=<path-to-caravel>
manarabdelaty0218c0f2021-04-29 18:31:49 +0200291 make run-precheck
292
293This will run all the precheck checks on your project and will produce the logs under the ``checks`` directory.
294
295
296Other Miscellaneous Targets
297============================
298
299The 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.
300
Manarf088db12021-09-20 12:13:04 +0200301Run ``make help`` to display available targets.
manarabdelaty0218c0f2021-04-29 18:31:49 +0200302
303Specify CARAVEL_ROOT before running any of the following,
304
305.. code:: bash
manarabdelatyd8dd0102021-04-30 08:40:52 +0200306
307 # export CARAVEL_ROOT=$(pwd)/caravel
manarabdelaty0218c0f2021-04-29 18:31:49 +0200308 export CARAVEL_ROOT=<path-to-caravel>
309
manarabdelaty0c03d602021-09-20 11:42:16 +0200310Run lvs on the mag view,
manarabdelaty0218c0f2021-04-29 18:31:49 +0200311
312.. code:: bash
313
314 make lvs-<macro_name>
315
316Run lvs on the gds,
317
318.. code:: bash
319
320 make lvs-gds-<macro_name>
321
322Run lvs on the maglef,
323
324.. code:: bash
325
326 make lvs-maglef-<macro_name>
327
328Run drc using magic,
329
330.. code:: bash
331
332 make drc-<macro_name>
333
334Run antenna check using magic,
335
336.. code:: bash
337
338 make antenna-<macro_name>
339
340Run XOR check,
341
342.. code:: bash
343
344 make xor-wrapper
345
Mohamed Kassem6f2fcd22021-04-19 10:14:19 -0700346
347Checklist for Open-MPW Submission
348=================================
349
Manarf088db12021-09-20 12:13:04 +0200350- ✔️ The project repo adheres to the same directory structure in this
Mohamed Kassem6f2fcd22021-04-19 10:14:19 -0700351 repo.
Manarf088db12021-09-20 12:13:04 +0200352- ✔️ The project repo contain info.yaml at the project root.
353- ✔️ Top level macro is named ``user_project_wrapper``.
354- ✔️ Full Chip Simulation passes for RTL and GL (gate-level)
355- ✔️ The hardened Macros are LVS and DRC clean
356- ✔️ The hardened ``user_project_wrapper`` adheres to the same pin
Mohamed Kassem6f2fcd22021-04-19 10:14:19 -0700357 order specified at
358 `pin\_order <https://github.com/efabless/caravel/blob/master/openlane/user_project_wrapper_empty/pin_order.cfg>`__
Manarf088db12021-09-20 12:13:04 +0200359- ✔️ 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>`__
360- ✔️ XOR check passes with zero total difference.
361- ✔️ Openlane summary reports are retained under ./signoff/
362- ✔️ The design passes the `mpw-precheck <https://github.com/efabless/mpw_precheck>`__
Mohamed Kassem6f2fcd22021-04-19 10:14:19 -0700363
364.. |License| image:: https://img.shields.io/badge/License-Apache%202.0-blue.svg
365 :target: https://opensource.org/licenses/Apache-2.0
manarabdelatyd0e7afb2021-04-22 00:21:13 +0200366.. |User CI| image:: https://github.com/efabless/caravel_project_example/actions/workflows/user_project_ci.yml/badge.svg
367 :target: https://github.com/efabless/caravel_project_example/actions/workflows/user_project_ci.yml
368.. |Caravel Build| image:: https://github.com/efabless/caravel_project_example/actions/workflows/caravel_build.yml/badge.svg
Mohamed Kassem9ae1f072021-04-23 12:19:31 -0700369 :target: https://github.com/efabless/caravel_project_example/actions/workflows/caravel_build.yml