blob: c30c74af7f8a2cf8d327e7f7606fe0105e535e64 [file] [log] [blame] [view]
manarabdelatyf2b6ea22021-04-20 19:07:40 +02001<!---
2# SPDX-FileCopyrightText: 2020 Efabless Corporation
3#
4# Licensed under the Apache License, Version 2.0 (the "License");
5# you may not use this file except in compliance with the License.
6# You may obtain a copy of the License at
7#
8# http://www.apache.org/licenses/LICENSE-2.0
9#
10# Unless required by applicable law or agreed to in writing, software
11# distributed under the License is distributed on an "AS IS" BASIS,
12# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13# See the License for the specific language governing permissions and
14# limitations under the License.
15#
16# SPDX-License-Identifier: Apache-2.0
17-->
18
19# Caravel User Project
20[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) [![UPRJ_CI](https://github.com/efabless/caravel_project_example/actions/workflows/user_project_ci.yml/badge.svg)](https://github.com/efabless/caravel_project_example/actions/workflows/user_project_ci.yml) [![Caravel Build](https://github.com/efabless/caravel_project_example/actions/workflows/caravel_build.yml/badge.svg)](https://github.com/efabless/caravel_project_example/actions/workflows/caravel_build.yml)
21
22# Table of contents
23- [Overview](#overview)
24- [Install Caravel](#install-caravel)
25- [Caravel Integration](#caravel-integration)
26 - [Repo Integration](#repo-integration)
27 - [Verilog Integration](#verilog-integration)
28- [Running Full Chip Simulation](#running-full-chip-simulation)
29- [Hardening the User Project Macro using Openlane](#hardening-the-user-project-macro-using-openlane)
30- [Checklist for Open-MPW Submission](#checklist-for-open-mpw-submission)
31
32# Overview
33
34This repo contains a sample user project that utilizes the [caravel](https://github.com/efabless/caravel.git) chip user space. The user project is a simple counter that showcases how to make use of [caravel's](https://github.com/efabless/caravel.git) user space utilities like IO pads, logic analyzer probes, and wishbone port. The repo also demonstrates the recommended structure for the open-mpw shuttle projects.
35
36# Install Caravel
37
38To setup caravel, run the following:
39
40```bash
41# By default, CARAVEL_ROOT is set to $(pwd)/caravel
42# If you want to install caravel at a different location, run "export CARAVEL_ROOT=<caravel-path>"
43# Disable submodule installation if needed by, run "export SUBMODULE=0"
44
45make install
46```
47
48To update the installed caravel to the latest, run:
49
50```bash
51 make update_caravel
52```
53
54To remove caravel, run
55```bash
56make uninstall
57```
58
59By default [caravel-lite](https://github.com/efabless/caravel-lite.git) is installed. To install the full version of caravel, run this prior to calling make install.
60```bash
61export CARAVEL_LITE=0
62```
63
64# Caravel Integration
65
66## Repo Integration
67
68Caravel files are kept separate from the user project by having caravel as submodule. The submodule commit should point to the latest of caravel/caravel-lite master. The following files should have a symbolic link to [caravel's](https://github.com/efabless/caravel.git) corresponding files:
69
70- [Openlane Makefile](openlane/Makefile): This provides an easier way for running openlane to harden your macros. Refer to
71[Hardening the User Project Macro using Openlane](#hardening-the-user-project-macro-using-openlane). Also, the makefile retains the openlane summary reports under the signoff directory.
72
73- [Pin order](openlane/user_project_wrapper/pin_order.cfg) file for the user wrapper: The hardened user project wrapper macro must have the same pin order specified in caravel's repo. Failing to adhere to the same order will fail the gds integration of the macro with caravel's back-end.
74
75The symbolic links are automatically set when you run `make install`.
76
77## Verilog Integration
78
79You need to create a wrapper around your macro that adheres to the template at [user_project_wrapper](caravel/verilog/rtl/__user_project_wrapper.v). The wrapper top module must be named `user_project_wrapper` and must have the same input and output ports. The wrapper gives access to the user space utilities provided by caravel like IO ports, logic analyzer probes, and wishbone bus connection to the management SoC.
80
81For this sample project, the user macro makes use of:
82
83- The IO ports for displaying the count register values on the IO pads.
84
85- The LA probes for supplying an optional reset and clock signals and for setting an initial value for the count register.
86
87- The wishbeone port for reading/writing the count value through the management SoC.
88
89Refer to [user_project_wrapper](verilog/rtl/user_project_wrapper.v) for more information.
90
91<p align=”center”>
92<img src="docs/source/_static/counter_32.png" width="50%" height="10%">
93</p>
94
95# Running Full Chip Simulation
96
97First, you will need to install the simulation environment, by
98
99```bash
100make simenv
101```
102
103This will pull a docker image with the needed tools installed.
104
105Then, you will need to build the pdk to obtain the verilog views.
106
107```bash
Jeff DiCorpof7e47a62021-04-21 12:37:41 -0700108# set PDK_ROOT to the path you wish to use for the pdk
manarabdelatyf2b6ea22021-04-20 19:07:40 +0200109export PDK_ROOT=<pdk-installation-path>
Jeff DiCorpof7e47a62021-04-21 12:37:41 -0700110
Jeff DiCorpo7177a7c2021-04-21 12:39:46 -0700111# you can optionally specify skywater-pdk and open-pdks commit used
Jeff DiCorpof7e47a62021-04-21 12:37:41 -0700112# by setting and exporting SKYWATER_COMMIT and OPEN_PDKS_COMMIT
113# if you do not set them, they default to the last verfied commits tested for this project
114
manarabdelatyf2b6ea22021-04-20 19:07:40 +0200115make pdk
116```
117
118Then, run the RTL and GL simulation by
119
120```bash
121export PDK_ROOT=<pdk-installation-path>
122export CARAVEL_ROOT=$(pwd)/caravel
123# specify simulation mode: RTL/GL
124export SIM=RTL
125# Run IO ports testbench, make verify-io_ports
126make verify-<dv-pattern>
127```
128
129The verilog test-benches are under this directory [verilog/dv](verilog/dv). For more information on setting up the simulation environment and the available testbenches for this sample project, refer to [README](verilog/dv/README.md).
130
131# Hardening the User Project Macro using Openlane
132
133First, you will need to install the pdk by
134
135```bash
Jeff DiCorpof7e47a62021-04-21 12:37:41 -0700136# set PDK_ROOT to the path you wish to use for the pdk
manarabdelatyf2b6ea22021-04-20 19:07:40 +0200137export PDK_ROOT=<pdk-installation-path>
Jeff DiCorpof7e47a62021-04-21 12:37:41 -0700138
Jeff DiCorpo7177a7c2021-04-21 12:39:46 -0700139# you can optionally specify skywater-pdk and open-pdks commit used
Jeff DiCorpof7e47a62021-04-21 12:37:41 -0700140# by setting and exporting SKYWATER_COMMIT and OPEN_PDKS_COMMIT
141# if you do not set them, they default to the last verfied commits tested for this project
142
manarabdelatyf2b6ea22021-04-20 19:07:40 +0200143make pdk
144```
145
146Then, you will need to install openlane by
147
148```bash
149export OPENLANE_ROOT=<openlane-installation-path>
150export OPENLANE_TAG=v0.12
151make openlane
152```
153
154For detailed instructions on how to install openlane and the pdk refer to [README](https://github.com/efabless/openlane/blob/master/README.md).
155
156
157There are two options for hardening the user project macro using openlane:
158
1591. Hardening the user macro, then embedding it in the wrapper
1602. Flattening the user macro with the wrapper.
161
Matt Vennd4860ee2021-04-20 21:32:16 +0200162For more details on this, refer to this [README](https://github.com/efabless/caravel/blob/master/openlane/README.rst).
manarabdelatyf2b6ea22021-04-20 19:07:40 +0200163
164For this sample project, we went for the first option where the user macro is hardened first, then it is inserted in the user project wrapper.
165
166<p align=”center”>
167<img src="docs/source/_static/wrapper.png" width="30%" height="5%">
168</p>
169
170To reproduce hardening this project, run the following:
171
172```bash
173export OPENLANE_TAG=v0.12
174# Run openlane to harden user_proj_example
175make user_proj_example
176# Run openlane to harden user_project_wrapper
177make user_project_wrapper
178```
179
180# Checklist for Open-MPW Submission
181
182- [x] The project repo adheres to the same directory structure in this repo.
183- [x] The project repo contain info.yaml at the project root.
184- [x] Top level macro is named `user_project_wrapper`.
185- [x] Full Chip Simulation passes for RTL and GL (gate-level)
186- [x] The hardened Macros are LVS and DRC clean
187- [x] The hardened `user_project_wrapper` adheres to the same pin order specified at [pin_order](https://github.com/efabless/caravel/blob/master/openlane/user_project_wrapper_empty/pin_order.cfg)
188- [x] XOR check passes with zero total difference.
189- [x] Openlane summary reports are retained under ./signoff/<macro-name>