Mohamed Kassem | 49a4ff6 | 2020-10-14 04:56:27 -0700 | [diff] [blame] | 1 | # CIIC Harness |
shalan | 0d14e6e | 2020-08-31 16:50:48 +0200 | [diff] [blame] | 2 | |
| 3 | A template SoC for Google SKY130 free shuttles. It is still WIP. The current SoC architecture is given below. |
| 4 | |
| 5 | <p align=”center”> |
Mohamed Shalan | 12a9a1d | 2020-09-01 18:03:17 +0200 | [diff] [blame] | 6 | <img src="/doc/ciic_harness.png" width="75%" height="75%"> |
shalan | 0d14e6e | 2020-08-31 16:50:48 +0200 | [diff] [blame] | 7 | </p> |
| 8 | |
Ahmed Ghazy | 0893d01 | 2020-12-05 23:30:25 +0200 | [diff] [blame] | 9 | |
agorararmard | 7d6fadb | 2020-11-25 20:23:20 +0200 | [diff] [blame] | 10 | ## Getting Started: |
| 11 | |
Ahmed Ghazy | 0893d01 | 2020-12-05 23:30:25 +0200 | [diff] [blame] | 12 | * For information on tooling and versioning, please refer to [this][1]. |
| 13 | |
agorararmard | 7d6fadb | 2020-11-25 20:23:20 +0200 | [diff] [blame] | 14 | Start by cloning the repo and uncompressing the files. |
| 15 | ```bash |
| 16 | git clone https://github.com/efabless/caravel.git |
| 17 | cd caravel |
| 18 | make uncompress |
| 19 | ``` |
| 20 | |
agorararmard | d4a2d6f | 2020-12-01 19:21:51 +0200 | [diff] [blame] | 21 | Then 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 | |
agorararmard | 63e5672 | 2020-12-09 19:57:30 +0200 | [diff] [blame^] | 24 | > \* 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. |
agorararmard | d4a2d6f | 2020-12-01 19:21:51 +0200 | [diff] [blame] | 25 | |
agorararmard | 212cd82 | 2020-11-26 22:40:17 +0200 | [diff] [blame] | 26 | Install the required version of the PDK by running the following commands: |
| 27 | |
| 28 | ```bash |
| 29 | export PDK_ROOT=<The place where you want to install the pdk> |
| 30 | make pdk |
| 31 | ``` |
| 32 | |
agorararmard | 7d6fadb | 2020-11-25 20:23:20 +0200 | [diff] [blame] | 33 | Then, 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 |
agorararmard | da92aef | 2020-12-04 23:56:37 +0200 | [diff] [blame] | 37 | - You could only use openlane:rc5 |
| 38 | - Make sure you have the commit hashes provided here inside the [Makefile](./Makefile) |
agorararmard | dc723a6 | 2020-11-26 20:00:29 +0200 | [diff] [blame] | 39 | ## Aboard Caravel: |
agorararmard | dc723a6 | 2020-11-26 20:00:29 +0200 | [diff] [blame] | 40 | |
agorararmard | e2bdaef | 2020-11-27 16:43:22 +0200 | [diff] [blame] | 41 | Your 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. |
agorararmard | dc723a6 | 2020-11-26 20:00:29 +0200 | [diff] [blame] | 42 | |
| 43 | If you will use OpenLANE to harden your design, go through the instructions in this [README.md][0]. |
| 44 | |
agorararmard | 0cd21c9 | 2020-12-09 17:02:18 +0200 | [diff] [blame] | 45 | You 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 | |
agorararmard | e2bdaef | 2020-11-27 16:43:22 +0200 | [diff] [blame] | 49 | Then, you will need to put your design aboard the Caravel chip. Make sure you have the following: |
agorararmard | dc723a6 | 2020-11-26 20:00:29 +0200 | [diff] [blame] | 50 | |
agorararmard | 3741dfc | 2020-12-01 18:04:37 +0200 | [diff] [blame] | 51 | - [Magic VLSI Layout Tool](http://opencircuitdesign.com/magic/index.html) installed on your machine. We may provide a Dockerized version later.\* |
agorararmard | e2bdaef | 2020-11-27 16:43:22 +0200 | [diff] [blame] | 52 | - You have your user_project_wrapper.gds under `./gds/` in the Caravel directory. |
agorararmard | dc723a6 | 2020-11-26 20:00:29 +0200 | [diff] [blame] | 53 | |
agorararmard | 065a942 | 2020-12-05 00:24:07 +0200 | [diff] [blame] | 54 | > \* **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. |
agorararmard | 3741dfc | 2020-12-01 18:04:37 +0200 | [diff] [blame] | 55 | |
agorararmard | dc723a6 | 2020-11-26 20:00:29 +0200 | [diff] [blame] | 56 | Run the following command: |
| 57 | |
| 58 | ```bash |
agorararmard | 212cd82 | 2020-11-26 22:40:17 +0200 | [diff] [blame] | 59 | export PDK_ROOT=<The place where the installed pdk resides. The same PDK_ROOT used in the pdk installation step> |
agorararmard | dc723a6 | 2020-11-26 20:00:29 +0200 | [diff] [blame] | 60 | make |
| 61 | ``` |
| 62 | |
agorararmard | ba078c3 | 2020-12-08 22:26:06 +0200 | [diff] [blame] | 63 | This 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. |
agorararmard | dc723a6 | 2020-11-26 20:00:29 +0200 | [diff] [blame] | 64 | |
agorararmard | 065a942 | 2020-12-05 00:24:07 +0200 | [diff] [blame] | 65 | ## Running Make using OpenLANE Magic |
agorararmard | 3741dfc | 2020-12-01 18:04:37 +0200 | [diff] [blame] | 66 | |
| 67 | To use the magic installed inside Openlane to complete the final GDS streaming out step, export the following: |
| 68 | |
| 69 | ```bash |
| 70 | export PDK_ROOT=<The location where the pdk is installed> |
| 71 | export OPENLANE_ROOT=<the absolute path to the openlane directory cloned or to be cloned> |
| 72 | export IMAGE_NAME=<the openlane image name installed on your machine. Preferably openlane:rc5> |
| 73 | export CARAVEL_PATH=$(pwd) |
| 74 | ``` |
| 75 | |
| 76 | Then, mount the docker: |
| 77 | |
| 78 | ```bash |
| 79 | docker 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 | |
| 82 | Finally, once inside the docker run the following commands: |
| 83 | ```bash |
| 84 | cd $CARAVEL_PATH |
| 85 | make |
| 86 | exit |
| 87 | ``` |
| 88 | |
agorararmard | ba078c3 | 2020-12-08 22:26:06 +0200 | [diff] [blame] | 89 | This 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. |
agorararmard | 3741dfc | 2020-12-01 18:04:37 +0200 | [diff] [blame] | 90 | |
agorararmard | da92aef | 2020-12-04 23:56:37 +0200 | [diff] [blame] | 91 | ## 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 | |
shalan | 0d14e6e | 2020-08-31 16:50:48 +0200 | [diff] [blame] | 105 | ## Managment SoC |
thesourcerer8 | 0a6a447 | 2020-10-20 13:31:24 +0200 | [diff] [blame] | 106 | The managment SoC runs firmware that can be used to: |
agorararmard | dc723a6 | 2020-11-26 20:00:29 +0200 | [diff] [blame] | 107 | - 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 |
shalan | 0d14e6e | 2020-08-31 16:50:48 +0200 | [diff] [blame] | 110 | |
Mohamed Shalan | 4f75616 | 2020-11-18 15:25:22 +0200 | [diff] [blame] | 111 | The memory map of the management SoC can be found [here](verilog/rtl/README) |
shalan | 0d14e6e | 2020-08-31 16:50:48 +0200 | [diff] [blame] | 112 | |
agorararmard | dc723a6 | 2020-11-26 20:00:29 +0200 | [diff] [blame] | 113 | ## User Project Area |
Mohamed Shalan | 4f75616 | 2020-11-18 15:25:22 +0200 | [diff] [blame] | 114 | This 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. |
agorararmard | dc723a6 | 2020-11-26 20:00:29 +0200 | [diff] [blame] | 115 | The repository contains a [sample user project](/verilog/rtl/user_proj_example.v) that contains a binary 32-bit up counter. </br> |
shalan | 0d14e6e | 2020-08-31 16:50:48 +0200 | [diff] [blame] | 116 | |
| 117 | <p align=”center”> |
Mohamed Shalan | 49fc489 | 2020-08-31 16:56:48 +0200 | [diff] [blame] | 118 | <img src="/doc/counter_32.png" width="50%" height="50%"> |
shalan | 0d14e6e | 2020-08-31 16:50:48 +0200 | [diff] [blame] | 119 | </p> |
| 120 | |
| 121 | The 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: |
agorararmard | dc723a6 | 2020-11-26 20:00:29 +0200 | [diff] [blame] | 122 | 1. 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). |
| 123 | 2. 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). |
| 124 | 3. 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 Ghazy | 0893d01 | 2020-12-05 23:30:25 +0200 | [diff] [blame] | 127 | [1]: mpw-one-a.md |