Add README from 3cpu-512w-nobuff-wrapped. 4e60cd8416751ad0bf38814006a930c58a6f0468
diff --git a/README.md b/README.md index 15727b1..ce11d9b 100644 --- a/README.md +++ b/README.md
@@ -1,149 +1,177 @@ -<!--- -# SPDX-FileCopyrightText: 2020 Efabless Corporation -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -# -# SPDX-License-Identifier: Apache-2.0 ---> -# CIIC Harness +# Softshell -A template SoC for Google SKY130 free shuttles. It is still WIP. The current SoC architecture is given below. +Multicore RISC-V MCU for developing software defined peripherals. This design +is targetted for the first Google-sponsored MPW shuttle Nov/Dec 2020. -<p align="center"> -<img src="/doc/ciic_harness.png" width="75%" height="75%"> -</p> +## Configuration +### CPU / Private Peripheral Configuration +- 3 x 50 MHz picorv32 cores +- 32 word private "core coupled" memory for stack +- 32-bit private GPIO peripheral +- "flexio" custom instruction (high speed configurable 2/4/8-bit shift register) -## Getting Started: +### Shared Peripherals +- Round-robin arbiter +- 512 word (2KB) shared memory +- XIP QSPI flash controller +- UART +- Pinmux crossbar -* For information on tooling and versioning, please refer to [this][1]. +## Memory Map -Start by cloning the repo and uncompressing the files. -```bash -git clone https://github.com/efabless/caravel.git -cd caravel -make uncompress +### CPU Private +``` +// Local memory (for stack, etc). +parameter CCM_ADDR_MASK = 32'hffff_0000; +parameter CCM_BASE_ADDR = 32'h0000_0000; + +// Local GPIO peripheral. +parameter GPIO_ADDR_MASK = 32'hffff_0000; +parameter GPIO_BASE_ADDR = 32'h2000_0000; + +// Access to the shared peripheral space. +parameter SHARED_ADDR_MASK = 32'hff00_0000; +parameter SHARED_BASE_ADDR = 32'h3000_0000; ``` -Then you need to install the open_pdks prerequisite: - - [Magic VLSI Layout Tool](http://opencircuitdesign.com/magic/index.html) is needed to run open_pdks -- version >= 8.3.60* +### Shared +``` +// Softshell base address (used for filtering addresses from Caravel). +parameter SOFTSHELL_MASK = 32'hff00_0000; +parameter SOFTSHELL_ADDR = 32'h3000_0000; - > \* 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 following the instructions given there to use the Makefile. +// Slave base addresses. +parameter SHARED_RAM_MASK = 32'hfff0_0000; +parameter SHARED_RAM_ADDR = 32'h3000_0000; -Install the required version of the PDK by running the following commands: +parameter SHARED_FLASH_MASK = 32'hfff0_0000; +parameter SHARED_FLASH_ADDR = 32'h3040_0000; -```bash -export PDK_ROOT=<The place where you want to install the pdk> -make pdk +parameter FLASH_CONFIG_MASK = 32'hffff_0000; +parameter FLASH_CONFIG_ADDR = 32'h3080_0000; +parameter PINMUX_ADDR_MASK = 32'hffff_0000; +parameter PINMUX_BASE_ADDR = 32'h3081_0000; +parameter UART0_ADDR_MASK = 32'hffff_0000; +parameter UART0_BASE_ADDR = 32'h3082_0000; ``` -Then, you can learn more about the caravel chip by watching these video: -- Caravel User Project Features -- https://youtu.be/zJhnmilXGPo -- Aboard Caravel -- How to put your design on Caravel? -- https://youtu.be/9QV8SDelURk -- Things to Clarify About Caravel -- What versions to use with Caravel? -- https://youtu.be/-LZ522mxXMw - - You could only use openlane:rc6 - - Make sure you have the commit hashes provided here inside the [Makefile](./Makefile) -## Aboard Caravel: +## Pins and Debug -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. +``` +User IOs +-------- +io[37:6] - Mapped to 32-bit pinmux (gpios, flexio, uart) +io[8] - Flash CSB (muxable to Caravel passthru for programming) +io[9] - Flash CLK (muxable to Caravel passthru for programming) +io[10] - Flash DIO0 (muxable to Caravel passthru for programming) +io[11] - Flash DIO1 (muxable to Caravel passthru for programming) +io[12] - Flash DIO2 +io[13] - Flash DIO3 -If you will use OpenLANE to harden your design, go through the instructions in this [README.md][0]. +Wishbone Access from Caravel +---------------------------- +Access to entire shared memory space (RAM, XIP Flash, etc) -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). +Debug from Caravel +------------------ +la_data_in[0] - Wishbone reset (also resets CPUs) +la_data_in[1] - CPU0 reset +la_data_in[2] - CPU1 reset +la_data_in[3] - CPU2 reset (if implemented) +la_data_in[4] - CPU3 reset (if implemented) -> Note: If you're using openlane to harden your design, this should happen automatically. +la_data_out[31:0] - GPIO out +la_data_out[63:32] - GPIO in -Then, you will need to put your design aboard the Caravel chip. Make sure you have the following: - -- [Magic VLSI Layout Tool](http://opencircuitdesign.com/magic/index.html) installed on your machine. We may provide a Dockerized version later.\* -- You have your user_project_wrapper.gds under `./gds/` in the Caravel directory. - - > \* **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. - -Run the following command: - -```bash -export PDK_ROOT=<The place where the installed pdk resides. The same PDK_ROOT used in the pdk installation step> -make +Note: CPU resets are not synchronized while the wishbone reset is. ``` -This should merge the GDSes using magic and you'll end up with your version of `./gds/caravel.gds`. You should expect ~90 magic DRC violations with the current "development" state of caravel. +## Verification -## Running Make using OpenLANE Magic +The `softshell_top` and `user_proj_example` modules are verified using the +same testbench. -To use the magic installed inside Openlane to complete the final GDS streaming out step, export the following: +It performs these basic tests: +- Memory read/write tests from Caravel SoC wishbone interface. +- Memory tests from Softshell CPU 0. +- GPIO in / out tests from Softshell CPU 0. +- Flexio tests. +- Flash XIP execution. -```bash -export PDK_ROOT=<The location where the pdk is installed> -export OPENLANE_ROOT=<the absolute path to the openlane directory cloned or to be cloned> -export IMAGE_NAME=<the openlane image name installed on your machine. Preferably openlane:rc6> -export CARAVEL_PATH=$(pwd) -``` +Testing execution from each CPU is a manual process requiring manually editing +the linker script, flash memory load address, and which CPU is released from +reset in the test bench. Not holding unused CPUs in reset will cause the X's +to propagate everywhere in GL sims. -Then, mount the docker: +1. Build the picorv32 toolchain and install at `/opt/riscv32ic/bin`. We only + need the `riscv32ic` mach. +2. Configure `PDK_ROOT`. +3. Run the testbench. + ``` + # For behavioral sims. + cd verilog/rtl/softshell/dv && make clean; make -```bash -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 -``` + # For GL (this will take a long time). + cd verilog/rtl/softshell/dv && make clean; make GL=1 + ``` -Finally, once inside the docker run the following commands: -```bash -cd $CARAVEL_PATH -make -exit -``` +There are plans to do a full top level Caravel testbench soon. -This should merge the GDSes using magic and you'll end up with your version of `./gds/caravel.gds`. You should expect ~90 magic DRC violations with the current "development" state of caravel. +## Building +Due to the limited timeline, this design is built with two different versions +of openlane / PDKs. You'll need to have both `mpw-one-a` and `mpw-one-b` +available on your machine to do a full build. -## IMPORTANT: +### Softshell `user_proj_example` and Wrapper `user_project_wrapper` Macros -Please make sure to run `make compress` before commiting anything to your repository. Avoid having 2 versions of the gds/user_project_wrapper.gds or gds/caravel.gds one compressed and the other not compressed. +Requires `mpw-one-a` openlane and PDK. To make the routing work harder, it's +preferred to edit the openlane `tritonRoute.param` file and add +`drouteEndIterNum:${ROUTING_OPT_ITERS}` which we later set to try harder during +wrapper routing. -## Required Directory Structure +1. Configure `OPENLANE_ROOT` and `PDK_ROOT` to point to `mpw-one-a` versions. +2. Harden the macro, this will take 8 - 12 hours on a modern 12 core machine. + ``` + cd openlane && make user_proj_example + ``` +3. Review the `final_summary_report.csv` file. Expect LVS errors only on the + output pins of the macro (pin mismatches) and a few antenna violations. + There should be zero DRC errors, if you get some you will need to rerun to + get a different seed (or manually edit the GDS). Manually review the + log files to confirm that the antenna ratios are reasonable and that any LVS + errors are safe (pin mismatches are generally safe, compare the GL netlist + and spice extracted netlist to confirm). +3. Copy the results from the run folder into the appropriate locations. This is + done primarily so it's easy to switch between run snapshots to compare. + ``` + cd openlane/user_proj_example && ./copy_results.sh runs/<result tag> + ``` +4. Harden the wrapper macro. + ``` + cd openlane && make user_project_wrapper + ``` +5. Review the `final_summary_report.csv` file to confirm 0 DRC/LVS/antenna + violations. -- ./gds/ : includes all the gds files used or produced from the project. -- ./def/ : includes all the def files used or produced from the project. -- ./lef/ : includes all the lef files used or produced from the project. -- ./mag/ : includes all the mag files used or produced from the project. -- ./maglef/ : includes all the maglef files used or produced from the project. -- ./spi/lvs/ : includes all the maglef files used or produced from the project. -- ./verilog/dv/ : includes all the simulation test benches and how to run them. -- ./verilog/gl/ : includes all the synthesized/elaborated netlists. -- ./verilog/rtl/ : includes all the Verilog RTLs and source files. -- ./openlane/`<macro>`/ : includes all configuration files used to run openlane on your project. -- 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 +### Top Level Caravel -## Managment SoC -The managment SoC runs firmware that can be used to: -- Configure User Project I/O pads -- Observe and control User Project signals (through on-chip logic analyzer probes) -- Control the User Project power supply +Requires `mpw-one-b` openlane and PDK. Probably not strictly necessary but +safest to use what eFabless will use. -The memory map of the management SoC can be found [here](verilog/rtl/README) +1. Configure `OPENLANE_ROOT` and `PDK_ROOT` to point to `mpw-one-b` versions. +2. Extract and build the final caravel gds. + ``` + make uncompress && make ship + ``` +3. Check results, and recompress. This will take a while since we use `xz` + compression. + ``` + make compress + ``` -## User Project Area -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. -The repository contains a [sample user project](/verilog/rtl/user_proj_example.v) that contains a binary 32-bit up counter. </br> +## Caravel Top Level Wrapper Details -<p align="center"> -<img src="/doc/counter_32.png" width="50%" height="50%"> -</p> - -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: -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). -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). -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). - -[0]: openlane/README.md -[1]: mpw-one-b.md +The top level wrapper for this project is the Caravel harness. See +[Caravel Readme](README_caravel.md) for more information.
diff --git a/README_caravel.md b/README_caravel.md new file mode 100644 index 0000000..15727b1 --- /dev/null +++ b/README_caravel.md
@@ -0,0 +1,149 @@ +<!--- +# SPDX-FileCopyrightText: 2020 Efabless Corporation +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# +# SPDX-License-Identifier: Apache-2.0 +--> +# CIIC Harness + +A template SoC for Google SKY130 free shuttles. It is still WIP. The current SoC architecture is given below. + +<p align="center"> +<img src="/doc/ciic_harness.png" width="75%" height="75%"> +</p> + + +## Getting Started: + +* For information on tooling and versioning, please refer to [this][1]. + +Start by cloning the repo and uncompressing the files. +```bash +git clone https://github.com/efabless/caravel.git +cd caravel +make uncompress +``` + +Then you need to install the open_pdks prerequisite: + - [Magic VLSI Layout Tool](http://opencircuitdesign.com/magic/index.html) is needed to run open_pdks -- version >= 8.3.60* + + > \* 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 following the instructions given there to use the Makefile. + +Install the required version of the PDK by running the following commands: + +```bash +export PDK_ROOT=<The place where you want to install the pdk> +make pdk +``` + +Then, you can learn more about the caravel chip by watching these video: +- Caravel User Project Features -- https://youtu.be/zJhnmilXGPo +- Aboard Caravel -- How to put your design on Caravel? -- https://youtu.be/9QV8SDelURk +- Things to Clarify About Caravel -- What versions to use with Caravel? -- https://youtu.be/-LZ522mxXMw + - You could only use openlane:rc6 + - Make sure you have the commit hashes provided here inside the [Makefile](./Makefile) +## Aboard Caravel: + +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. + +If you will use OpenLANE to harden your design, go through the instructions in this [README.md][0]. + +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). + +> Note: If you're using openlane to harden your design, this should happen automatically. + +Then, you will need to put your design aboard the Caravel chip. Make sure you have the following: + +- [Magic VLSI Layout Tool](http://opencircuitdesign.com/magic/index.html) installed on your machine. We may provide a Dockerized version later.\* +- You have your user_project_wrapper.gds under `./gds/` in the Caravel directory. + + > \* **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. + +Run the following command: + +```bash +export PDK_ROOT=<The place where the installed pdk resides. The same PDK_ROOT used in the pdk installation step> +make +``` + +This should merge the GDSes using magic and you'll end up with your version of `./gds/caravel.gds`. You should expect ~90 magic DRC violations with the current "development" state of caravel. + +## Running Make using OpenLANE Magic + +To use the magic installed inside Openlane to complete the final GDS streaming out step, export the following: + +```bash +export PDK_ROOT=<The location where the pdk is installed> +export OPENLANE_ROOT=<the absolute path to the openlane directory cloned or to be cloned> +export IMAGE_NAME=<the openlane image name installed on your machine. Preferably openlane:rc6> +export CARAVEL_PATH=$(pwd) +``` + +Then, mount the docker: + +```bash +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 +``` + +Finally, once inside the docker run the following commands: +```bash +cd $CARAVEL_PATH +make +exit +``` + +This should merge the GDSes using magic and you'll end up with your version of `./gds/caravel.gds`. You should expect ~90 magic DRC violations with the current "development" state of caravel. + + +## IMPORTANT: + +Please make sure to run `make compress` before commiting anything to your repository. Avoid having 2 versions of the gds/user_project_wrapper.gds or gds/caravel.gds one compressed and the other not compressed. + +## Required Directory Structure + +- ./gds/ : includes all the gds files used or produced from the project. +- ./def/ : includes all the def files used or produced from the project. +- ./lef/ : includes all the lef files used or produced from the project. +- ./mag/ : includes all the mag files used or produced from the project. +- ./maglef/ : includes all the maglef files used or produced from the project. +- ./spi/lvs/ : includes all the maglef files used or produced from the project. +- ./verilog/dv/ : includes all the simulation test benches and how to run them. +- ./verilog/gl/ : includes all the synthesized/elaborated netlists. +- ./verilog/rtl/ : includes all the Verilog RTLs and source files. +- ./openlane/`<macro>`/ : includes all configuration files used to run openlane on your project. +- 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 + +## Managment SoC +The managment SoC runs firmware that can be used to: +- Configure User Project I/O pads +- Observe and control User Project signals (through on-chip logic analyzer probes) +- Control the User Project power supply + +The memory map of the management SoC can be found [here](verilog/rtl/README) + +## User Project Area +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. +The repository contains a [sample user project](/verilog/rtl/user_proj_example.v) that contains a binary 32-bit up counter. </br> + +<p align="center"> +<img src="/doc/counter_32.png" width="50%" height="50%"> +</p> + +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: +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). +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). +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). + +[0]: openlane/README.md +[1]: mpw-one-b.md