blob: 76f0c39ce1b1e7bbc02af3a87e0a23075d383afd [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
manarabdelatyd0e7afb2021-04-22 00:21:13 +020053Install Caravel
54===============
55
56To setup caravel, run the following:
57
58.. code:: bash
59
60 # By default, CARAVEL_ROOT is set to $(pwd)/caravel
61 # If you want to install caravel at a different location, run "export CARAVEL_ROOT=<caravel-path>"
62 # Disable submodule installation if needed by, run "export SUBMODULE=0"
Mohamed Kassem9ae1f072021-04-23 12:19:31 -070063
64 clone https://github.com/efabless/caravel_user_project.git
65 cd caravel_user_project
manarabdelatyd0e7afb2021-04-22 00:21:13 +020066 make install
67
68To update the installed caravel to the latest, run:
69
70.. code:: bash
71
72 make update_caravel
73
74To 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
97caravel/caravel-lite master. The following files should have a symbolic
98link to `caravel's <https://github.com/efabless/caravel.git>`__
99corresponding files:
Mohamed Kassem6f2fcd22021-04-19 10:14:19 -0700100
101- `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
104 Openlane <#hardening-the-user-project-macro-using-openlane>`__. Also,
105 the makefile retains the openlane summary reports under the signoff
106 directory.
Mohamed Kassem6f2fcd22021-04-19 10:14:19 -0700107
108- `Pin order <openlane/user_project_wrapper/pin_order.cfg>`__ file for
109 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
121`user\_project\_wrapper <caravel/verilog/rtl/__user_project_wrapper.v>`__.
122The wrapper top module must be named ``user_project_wrapper`` and must
123have the same input and output ports. The wrapper gives access to the
124user 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
134- The wishbeone port for reading/writing the count value through the
135 management SoC.
136
137Refer to `user\_project\_wrapper <verilog/rtl/user_project_wrapper.v>`__
138for 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
150Running Full Chip Simulation
151============================
152
manarabdelatyd0e7afb2021-04-22 00:21:13 +0200153First, you will need to install the simulation environment, by
154
155.. code:: bash
156
157 make simenv
158
159This will pull a docker image with the needed tools installed.
160
161Then, you will need to build the pdk to obtain the verilog views.
162
163.. code:: bash
164
165 # set PDK_ROOT to the path you wish to use for the pdk
166 export PDK_ROOT=<pdk-installation-path>
167
168 # you can optionally specify skywater-pdk and open-pdks commit used
169 # by setting and exporting SKYWATER_COMMIT and OPEN_PDKS_COMMIT
170 # if you do not set them, they default to the last verfied commits tested for this project
171
172 make pdk
173
174Then, run the RTL and GL simulation by
175
176.. code:: bash
177
178 export PDK_ROOT=<pdk-installation-path>
179 export CARAVEL_ROOT=$(pwd)/caravel
180 # specify simulation mode: RTL/GL
181 export SIM=RTL
182 # Run IO ports testbench, make verify-io_ports
183 make verify-<dv-pattern>
184
185The verilog test-benches are under this directory
186`verilog/dv <verilog/dv>`__. For more information on setting up the
187simulation environment and the available testbenches for this sample
188project, refer to `README <verilog/dv/README.md>`__.
Mohamed Kassem6f2fcd22021-04-19 10:14:19 -0700189
190Hardening the User Project Macro using Openlane
191===============================================
192
manarabdelatyd0e7afb2021-04-22 00:21:13 +0200193First, you will need to install the pdk by
194
195.. code:: bash
196
197 # set PDK_ROOT to the path you wish to use for the pdk
198 export PDK_ROOT=<pdk-installation-path>
199
200 # you can optionally specify skywater-pdk and open-pdks commit used
201 # by setting and exporting SKYWATER_COMMIT and OPEN_PDKS_COMMIT
202 # if you do not set them, they default to the last verfied commits tested for this project
203
204 make pdk
205
206Then, you will need to install openlane by
207
208.. code:: bash
209
210 export OPENLANE_ROOT=<openlane-installation-path>
211 export OPENLANE_TAG=v0.12
212 make openlane
213
214For detailed instructions on how to install openlane and the pdk refer
215to
Mohamed Kassem6f2fcd22021-04-19 10:14:19 -0700216`README <https://github.com/efabless/openlane/blob/master/README.md>`__.
217
218There are two options for hardening the user project macro using
219openlane:
220
2211. Hardening the user macro, then embedding it in the wrapper
2222. Flattening the user macro with the wrapper.
223
224For more details on this, refer to this
manarabdelatyd0e7afb2021-04-22 00:21:13 +0200225`README <https://github.com/efabless/caravel/blob/master/openlane/README.rst>`__.
Mohamed Kassem6f2fcd22021-04-19 10:14:19 -0700226
227For this sample project, we went for the first option where the user
228macro is hardened first, then it is inserted in the user project
229wrapper.
230
231.. raw:: html
232
233 <p align="center">
234 <img src="./_static/wrapper.png" width="50%" height="50%">
235 </p>
236
manarabdelatyd0e7afb2021-04-22 00:21:13 +0200237.. raw:: html
238
239 </p>
240
Mohamed Kassem6f2fcd22021-04-19 10:14:19 -0700241To reproduce hardening this project, run the following:
242
243.. code:: bash
244
245 export OPENLANE_TAG=v0.12
Mohamed Kassem6f2fcd22021-04-19 10:14:19 -0700246 # Run openlane to harden user_proj_example
247 make user_proj_example
248 # Run openlane to harden user_project_wrapper
249 make user_project_wrapper
250
251Checklist for Open-MPW Submission
252=================================
253
254- [x] The project repo adheres to the same directory structure in this
255 repo.
256- [x] The project repo contain info.yaml at the project root.
257- [x] Top level macro is named ``user_project_wrapper``.
258- [x] Full Chip Simulation passes for RTL and GL (gate-level)
259- [x] The hardened Macros are LVS and DRC clean
260- [x] The hardened ``user_project_wrapper`` adheres to the same pin
261 order specified at
262 `pin\_order <https://github.com/efabless/caravel/blob/master/openlane/user_project_wrapper_empty/pin_order.cfg>`__
263- [x] XOR check passes with zero total difference.
264- [x] Openlane summary reports are retained under ./signoff/
265
266.. |License| image:: https://img.shields.io/badge/License-Apache%202.0-blue.svg
267 :target: https://opensource.org/licenses/Apache-2.0
manarabdelatyd0e7afb2021-04-22 00:21:13 +0200268.. |User CI| image:: https://github.com/efabless/caravel_project_example/actions/workflows/user_project_ci.yml/badge.svg
269 :target: https://github.com/efabless/caravel_project_example/actions/workflows/user_project_ci.yml
270.. |Caravel Build| image:: https://github.com/efabless/caravel_project_example/actions/workflows/caravel_build.yml/badge.svg
Mohamed Kassem9ae1f072021-04-23 12:19:31 -0700271 :target: https://github.com/efabless/caravel_project_example/actions/workflows/caravel_build.yml