blob: 5a4ed668c45ffd078709b705722851d840139cef [file] [log] [blame] [view]
Mohamed Kassem49a4ff62020-10-14 04:56:27 -07001# CIIC Harness
shalan0d14e6e2020-08-31 16:50:48 +02002
3A template SoC for Google SKY130 free shuttles. It is still WIP. The current SoC architecture is given below.
4
5<p align=”center”>
Mohamed Shalan12a9a1d2020-09-01 18:03:17 +02006<img src="/doc/ciic_harness.png" width="75%" height="75%">
shalan0d14e6e2020-08-31 16:50:48 +02007</p>
8
Ahmed Ghazy0893d012020-12-05 23:30:25 +02009
agorararmard7d6fadb2020-11-25 20:23:20 +020010## Getting Started:
11
Ahmed Ghazy0893d012020-12-05 23:30:25 +020012* For information on tooling and versioning, please refer to [this][1].
13
agorararmard7d6fadb2020-11-25 20:23:20 +020014Start by cloning the repo and uncompressing the files.
15```bash
16git clone https://github.com/efabless/caravel.git
17cd caravel
18make uncompress
19```
20
agorararmardd4a2d6f2020-12-01 19:21:51 +020021Then you need to install the open_pdks prerequisite:
22 - [Magic VLSI Layout Tool](http://opencircuitdesign.com/magic/index.html) is needed to run open_pdks -- version >= 8.3.60*
23
agorararmard63e56722020-12-09 19:57:30 +020024 > \* Note: You can avoid the need for the magic prerequisite by using the openlane docker to do the installation step in open_pdks. This could be done by cloning [openlane](https://github.com/efabless/openlane/tree/master) and running this [script](https://github.com/efabless/openlane/blob/master/travisCI/travisBuild.sh) in the openlane root directrory.
agorararmardd4a2d6f2020-12-01 19:21:51 +020025
agorararmard212cd822020-11-26 22:40:17 +020026Install the required version of the PDK by running the following commands:
27
28```bash
29export PDK_ROOT=<The place where you want to install the pdk>
30make pdk
31```
32
agorararmard7d6fadb2020-11-25 20:23:20 +020033Then, you can learn more about the caravel chip by watching these video:
34- Caravel User Project Features -- https://youtu.be/zJhnmilXGPo
35- Aboard Caravel -- How to put your design on Caravel? -- https://youtu.be/9QV8SDelURk
36- Things to Clarify About Caravel -- What versions to use with Caravel? -- https://youtu.be/-LZ522mxXMw
agorararmardda92aef2020-12-04 23:56:37 +020037 - You could only use openlane:rc5
38 - Make sure you have the commit hashes provided here inside the [Makefile](./Makefile)
agorararmarddc723a62020-11-26 20:00:29 +020039## Aboard Caravel:
agorararmarddc723a62020-11-26 20:00:29 +020040
agorararmarde2bdaef2020-11-27 16:43:22 +020041Your area is the full user_project_wrapper, so feel free to add your project there or create a differnt macro and harden it seperately then insert it into the user_project_wrapper. For example, if your design is analog or you're using a different tool other than OpenLANE.
agorararmarddc723a62020-11-26 20:00:29 +020042
43If you will use OpenLANE to harden your design, go through the instructions in this [README.md][0].
44
agorararmard0cd21c92020-12-09 17:02:18 +020045You must copy your synthesized gate-level-netlist for `user_project_wrapper` to `verilog/gl/` and overwrite `user_project_wrapper.v`. Otherwise, you can point to it in [info.yaml](info.yaml).
46
47> Note: If you're using openlane to harden your design, you should find the synthesized gate-level-netlist here: `openlane/user_project_wrapper/runs/user_project_wrapper/results/synthesis/user_project_wrapper.synthesis.v`.
48
agorararmarde2bdaef2020-11-27 16:43:22 +020049Then, you will need to put your design aboard the Caravel chip. Make sure you have the following:
agorararmarddc723a62020-11-26 20:00:29 +020050
agorararmard3741dfc2020-12-01 18:04:37 +020051- [Magic VLSI Layout Tool](http://opencircuitdesign.com/magic/index.html) installed on your machine. We may provide a Dockerized version later.\*
agorararmarde2bdaef2020-11-27 16:43:22 +020052- You have your user_project_wrapper.gds under `./gds/` in the Caravel directory.
agorararmarddc723a62020-11-26 20:00:29 +020053
agorararmard065a9422020-12-05 00:24:07 +020054 > \* **Note:** You can avoid the need for the magic prerequisite by using the openlane docker to run the make step. This [section](#running-make-using-openlane-magic) shows how.
agorararmard3741dfc2020-12-01 18:04:37 +020055
agorararmarddc723a62020-11-26 20:00:29 +020056Run the following command:
57
58```bash
agorararmard212cd822020-11-26 22:40:17 +020059export PDK_ROOT=<The place where the installed pdk resides. The same PDK_ROOT used in the pdk installation step>
agorararmarddc723a62020-11-26 20:00:29 +020060make
61```
62
agorararmardba078c32020-12-08 22:26:06 +020063This should merge the GDSes using magic and you'll end up with your version of `./gds/caravel.gds`. You should expect ~100 magic DRC violations with the current "development" state of caravel.
agorararmarddc723a62020-11-26 20:00:29 +020064
agorararmard065a9422020-12-05 00:24:07 +020065## Running Make using OpenLANE Magic
agorararmard3741dfc2020-12-01 18:04:37 +020066
67To use the magic installed inside Openlane to complete the final GDS streaming out step, export the following:
68
69```bash
70export PDK_ROOT=<The location where the pdk is installed>
71export OPENLANE_ROOT=<the absolute path to the openlane directory cloned or to be cloned>
72export IMAGE_NAME=<the openlane image name installed on your machine. Preferably openlane:rc5>
73export CARAVEL_PATH=$(pwd)
74```
75
76Then, mount the docker:
77
78```bash
79docker run -it -v $CARAVEL_PATH:$CARAVEL_PATH -v $OPENLANE_ROOT:/openLANE_flow -v $PDK_ROOT:$PDK_ROOT -e CARAVEL_PATH=$CARAVEL_PATH -e PDK_ROOT=$PDK_ROOT -u $(id -u $USER):$(id -g $USER) $IMAGE_NAME
80```
81
82Finally, once inside the docker run the following commands:
83```bash
84cd $CARAVEL_PATH
85make
86exit
87```
88
agorararmardba078c32020-12-08 22:26:06 +020089This should merge the GDSes using magic and you'll end up with your version of `./gds/caravel.gds`. You should expect ~100 magic DRC violations with the current "development" state of caravel.
agorararmard3741dfc2020-12-01 18:04:37 +020090
agorararmardda92aef2020-12-04 23:56:37 +020091## Required Directory Structure
92
93- ./gds/ : includes all the gds files used or produced from the project.
94- ./def/ : includes all the def files used or produced from the project.
95- ./lef/ : includes all the lef files used or produced from the project.
96- ./mag/ : includes all the mag files used or produced from the project.
97- ./maglef/ : includes all the maglef files used or produced from the project.
98- ./spi/lvs/ : includes all the maglef files used or produced from the project.
99- ./verilog/dv/ : includes all the simulation test benches and how to run them.
100- ./verilog/gl/ : includes all the synthesized/elaborated netlists.
101- ./verilog/rtl/ : includes all the Verilog RTLs and source files.
102- ./openlane/`<macro>`/ : includes all configuration files used to run openlane on your project.
103- info.yaml: includes all the info required in [this example](info.yaml). Please make sure that you are pointing to an elaborated caravel netlist as well as a synthesized gate-level-netlist for the user_project_wrapper
104
shalan0d14e6e2020-08-31 16:50:48 +0200105## Managment SoC
thesourcerer80a6a4472020-10-20 13:31:24 +0200106The managment SoC runs firmware that can be used to:
agorararmarddc723a62020-11-26 20:00:29 +0200107- Configure User Project I/O pads
108- Observe and control User Project signals (through on-chip logic analyzer probes)
109- Control the User Project power supply
shalan0d14e6e2020-08-31 16:50:48 +0200110
Mohamed Shalan4f756162020-11-18 15:25:22 +0200111The memory map of the management SoC can be found [here](verilog/rtl/README)
shalan0d14e6e2020-08-31 16:50:48 +0200112
agorararmarddc723a62020-11-26 20:00:29 +0200113## User Project Area
Mohamed Shalan4f756162020-11-18 15:25:22 +0200114This is the user space. It has limited silicon area (TBD, about 3.1mm x 3.8mm) as well as a fixed number of I/O pads (37) and power pads (10). See [the Caravel premliminary datasheet](doc/caravel_datasheet.pdf) for details.
agorararmarddc723a62020-11-26 20:00:29 +0200115The repository contains a [sample user project](/verilog/rtl/user_proj_example.v) that contains a binary 32-bit up counter. </br>
shalan0d14e6e2020-08-31 16:50:48 +0200116
117<p align=”center”>
Mohamed Shalan49fc4892020-08-31 16:56:48 +0200118<img src="/doc/counter_32.png" width="50%" height="50%">
shalan0d14e6e2020-08-31 16:50:48 +0200119</p>
120
121The firmware running on the Management Area SoC, configures the I/O pads used by the counter and uses the logic probes to observe/control the counter. Three firmware examples are provided:
agorararmarddc723a62020-11-26 20:00:29 +02001221. Configure the User Project I/O pads as o/p. Observe the counter value in the testbench: [IO_Ports Test](verilog/dv/caravel/user_proj_example/io_ports).
1232. Configure the User Project I/O pads as o/p. Use the Chip LA to load the counter and observe the o/p till it reaches 500: [LA_Test1](verilog/dv/caravel/user_proj_example/la_test1).
1243. Configure the User Project I/O pads as o/p. Use the Chip LA to control the clock source and reset signals and observe the counter value for five clock cylcles: [LA_Test2](verilog/dv/caravel/user_proj_example/la_test2).
125
126[0]: openlane/README.md
Ahmed Ghazy0893d012020-12-05 23:30:25 +0200127[1]: mpw-one-a.md