blob: 1467d4cfa106894b49ee99b7e600f6dab3a6db86 [file] [log] [blame]
NohealthyBBQ2f6ba082022-08-16 11:21:05 -04001.. 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 Analog User Project
22===========================
23
24|License| |User CI| |Caravan Build|
25
26Table of contents
27=================
28
29- `Overview <#overview>`__
30- `Install Caravel <#install-caravel>`__
31- `Caravel Integration <#caravel-integration>`__
32
33 - `User Project: Power on Reset <#user-project-power-on-reset>`_
34 - `Verilog Integration <#verilog-integration>`__
35
36- `Running Full Chip Simulation <#running-full-chip-simulation>`__
37- `Analog Design Flow <#analog-design-flow>`__
38- `Other Miscellaneous Targets <#other-miscellaneous-targets>`_
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 caravan chip (analog version of `caravel <https://github.com/efabless/caravel.git>`__) user space. The user project is a simple power-on-reset that showcases how to make use of caravan's user space utilities like IO pads, logic analyzer probes, and wishbone port. The repo also demonstrates the recommended structure for the open-mpw **analog** projects.
46
47Install Caravel
48===============
49
50To setup caravel, run the following:
51
52.. code:: bash
53
54 # By default, CARAVEL_ROOT is set to $(pwd)/caravel
55 # If you want to install caravel at a different location, run "export CARAVEL_ROOT=<caravel-path>"
56 # Disable submodule installation if needed by, run "export SUBMODULE=0"
57
58 git clone https://github.com/efabless/caravel_user_project_analog.git
59 cd caravel_user_project_analog
60 make install
61
62To update the installed caravel to the latest, run:
63
64.. code:: bash
65
66 make update_caravel
67
68To remove caravel, run
69
70.. code:: bash
71
72 make uninstall
73
74By default
75`caravel-lite <https://github.com/efabless/caravel-lite.git>`__ is
76installed. To install the full version of caravel, run this prior to
77calling make install.
78
79.. code:: bash
80
81 export CARAVEL_LITE=0
82
83Caravel Integration
84=====================
85
86
87User Project: Power on Reset
88----------------------------
89
90This is an example user analog project which breaks out the power-on-reset
91circuit used by the management SoC for power-up behavior so that the circuit
92input and output can be independently controlled and measured.
93
94The power-on-reset circuit itself is a simple, non-temperature-compensated
95analog delay calibrated to 15ms under nominal conditions, with a Schmitt
96trigger inverter to provide hysteresis around the trigger point to provide
97a clean output reset signal.
98
99The circuit provides a single high-voltage (3.3V domain) sense-inverted reset
100signal "porb_h" and complementary low-voltage (1.8V domain) reset signals
101"por_l" and "porb_l".
102
103The only input to the circuit is the 3.3V domain power supply itself.
104
105
106Verilog Integration
107-------------------
108
109You need to create a wrapper around your macro that adheres to the
110template at
111`user\_analog_project\_wrapper <https://github.com/efabless/caravel/blob/master/verilog/rtl/__user_analog_project_wrapper.v>`__.
112The wrapper top module must be named ``user_analog_project_wrapper`` and must
113have the same input and output ports as the analog wrapper template. The wrapper gives access to the
114user space utilities provided by caravel like IO ports, logic analyzer
115probes, and wishbone bus connection to the management SoC.
116
117The verilog modules instantiated in the wrapper module should represent
118the analog project; they need not be more than empty blocks, but it is
119encouraged to write a simple behavioral description of the analog circuit
120in standard verilog, using real-valued wires when necessary. This allows
121the whole system to be run in a verilog testbench and verify the connectivity
122to the padframe and management SoC, even if the testbench C code does nothing
123more than set the mode of each GPIO pin. The example top-level verilog code
124emulates the behavior of the power-on-reset delay after applying a valid
125power supply to the circuit.
126
127
128Building the PDK
129================
130
131For more information about volare click `here <https://github.com/efabless/volare>`__
132
133.. code:: bash
134
135 # set PDK_ROOT to the path you wish to use for the pdk
136 export PDK_ROOT=<pdk-installation-path
137
138 # use volare to download the pdk
139 # To change the default pdk version you can export OPEN_PDKS_COMMIT=<pdk_commit>
140 make pdk-with-volare
141
142
143
144Running Full Chip Simulation
145============================
146
147First, you will need to install the simulation environment, by
148
149.. code:: bash
150
151 make simenv
152
153This will pull a docker image with the needed tools installed.
154
155To install the simulation environment locally, refer to `README <https://github.com/efabless/caravel_user_project_analog/blob/main/verilog/dv/README.md>`__
156
157Then, run the RTL and GL simulation by
158
159.. code:: bash
160
161 export PDK_ROOT=<pdk-installation-path>
162 export CARAVEL_ROOT=$(pwd)/caravel
163 # specify simulation mode: RTL/GL
164 export SIM=RTL
165 # Run the mprj_por testbench, make verify-mprj_por
166 make verify-<testbench-name>
167
168The verilog test-benches are under this directory
169`verilog/dv <https://github.com/efabless/caravel_user_project_analog/tree/main/verilog/dv>`__.
170
171
172Analog Design Flow
173===================
174
175The example project uses a very simple analog design flow with schematics
176made with xschem, simulation done using ngspice, layout done with magic,
177and LVS verification done with netgen. Sources for the power-on-reset
178circuit are in the "xschem/" directory, which also includes a schematic
179representing the wrapper with all of its ports, for use in a testbench
180circuit. There are several testbenches in the example, starting from
181tests of the component devices to a full test of the completed project
182inside the wrapper.
183
184There is no automation in this project; the schematic and layout were
185done by hand, including both the power-on-reset block and the power and
186signal routing to the pins on the wrapper.
187
188The power-on-reset circuit itself is simple and is not compensated for
189temperature or voltage variation. When the power supply reaches a
190sufficient level, the voltage divider sets the gate voltage on an nFET
191device to draw a current of nominally 240nA. The testbench
192"threshold_test_tb.spice" does a DC sweep to find the gate voltage that
193produces this value. Next, a cascaded current mirror divides down the
194current by a factor of (roughly) 400. The testbench current_test.spice
195checks the current division value. Finally, the output ~600pA from the
196end of the current mirror is accumulated on a capacitor until the value
197trips the input of the 3.3V Schmitt trigger buffer from the
198sky130_fd_sd_hvl library. The capacitor is sized to peg the nominal
199time to trigger at 15ms. The schematic "example_por_tb.sch" sets up
200the testbench for this timing test.
201
202The output of the Schmitt trigger buffer becomes the high-voltage
203output, and is input to a standard buffer and inverter used as
204level shifters from the 3.3V domain to the 1.8V domain, producing
205complementary low-voltage outputs.
206
207The user project is formed from two power-on-reset circuits, one of
208which is connected to the user area VDDA1 power supply, and the other
209of which is connected to one of the analog I/O pads, used as a power
210supply input and connected to its voltage ESD clamp circuit. The
2113.3V domain outputs are connected directly to GPIO pads through the
212ESD (150 ohm series) connection. The 1.8V domain outputs are connected
213to GPIO pads through the usual I/O connections, with the corresponding
214user output enable (sense inverted) held low to keep the output always
215active.
216
217The C code testbench is in "verilog/dv/mprj_por/mprj_por.c" and only
218sets the GPIO pins used to the correct state (user output function).
219The POR circuit outputs are monitored by the testbench verilog file
220"mprj_por_tb.v" which will fail if the connections are wrong or if
221the behavioral POR verilog does not work as intended.
222
223Note that to properly test this circuit, the GPIO pins have to be
224configured for output to be seen and measured, implying that the
225management SoC power supply must be stable and the C program running
226off of the SPI flash before the user area power supplies are raised.
227
228**NOTE**
229
230 When running spice extraction on the user_analog_project_wrapper layout, it is recommended to use `ext2spice short resistor`.
231 This is to preserve all the different port names in the extracted netlist. In case you have two ports that are electrically shorted
232 in the layout, the `short resistor` option will tell magic not to merge the two shorted ports instead it adds zero-ohm ideal resistors
233 between the net names so that they can be kept as separate nets.
234
235
236Running Open-MPW Precheck Locally
237=================================
238
239You can install the precheck by running
240
241.. code:: bash
242
243 # By default, this install the precheck in your home directory
244 # To change the installtion path, run "export PRECHECK_ROOT=<precheck installation path>"
245 make precheck
246
247This will clone the precheck repo and pull the latest precheck docker image.
248
249
250Then, you can run the precheck by running
251Specify CARAVEL_ROOT before running any of the following,
252
253.. code:: bash
254
255 # export CARAVEL_ROOT=$(pwd)/caravel
256 export CARAVEL_ROOT=<path-to-caravel>
257 make run-precheck
258
259This will run all the precheck checks on your project and will retain the logs under the ``checks`` directory.
260
261Other Miscellaneous Targets
262============================
263
264The makefile provides a number of useful that targets that can run compress, uncompress, and run XOR checks on your design.
265
266Compress gds files and any file larger than 100MB (GH file size limit),
267
268.. code:: bash
269
270 make compress
271
272Uncompress files,
273
274.. code:: bash
275
276 make uncompress
277
278
279Specify ``CARAVEL_ROOT`` before running any of the following,
280
281.. code:: bash
282
283 # export CARAVEL_ROOT=$(pwd)/caravel
284 export CARAVEL_ROOT=<path-to-caravel>
285
286Run XOR check,
287
288.. code:: bash
289
290 make xor-analog-wrapper
291
292Checklist for Open-MPW Submission
293=================================
294
295
296|:heavy_check_mark:| The project repo adheres to the same directory structure in this repo.
297
298|:heavy_check_mark:| The project repo contain info.yaml at the project root.
299
300|:heavy_check_mark:| Top level macro is named ``user_analog_project_wrapper``.
301
302|:heavy_check_mark:| Full Chip Simulation passes for RTL and GL (gate-level)
303
304|:heavy_check_mark:| The project contains a spice netlist for the ``user_analog_project_wrapper`` at netgen/user_analog_project_wrapper.spice
305
306|:heavy_check_mark:| The hardened Macros are LVS and DRC clean
307
308|:heavy_check_mark:| The ``user_analog_project_wrapper`` adheres to empty wrapper template order specified at `user_analog_project_wrapper_empty <https://github.com/efabless/caravel/blob/master/mag/user_analog_project_wrapper_empty.mag>`__
309
310|:heavy_check_mark:| XOR check passes with zero total difference.
311
312|:heavy_check_mark:| Open-MPW-Precheck tool runs successfully.
313
314
315.. |License| image:: https://img.shields.io/badge/License-Apache%202.0-blue.svg
316 :target: https://opensource.org/licenses/Apache-2.0
317.. |User CI| image:: https://github.com/efabless/caravel_user_project_analog/actions/workflows/user_project_ci.yml/badge.svg
318 :target: https://github.com/efabless/caravel_user_project_analog/actions/workflows/user_project_ci.yml
319.. |Caravan Build| image:: https://github.com/efabless/caravel_user_project_analog/actions/workflows/caravan_build.yml/badge.svg
320 :target: https://github.com/efabless/caravel_user_project_analog/actions/workflows/caravan_build.yml