[Docs]: WIP how to run documentation -- rev. 1
diff --git a/README.md b/README.md index cffca22..3e002ed 100644 --- a/README.md +++ b/README.md
@@ -20,23 +20,52 @@ - 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 +## Aboard Caravel: +### Versions: +- [OpenLANE](https://github.com/efabless/openlane) rc4 or rc5. +- latest [Skywater-pdk](https://github.com/google/skywater-pdk). + - sky130_fd_sc_hd + - sky130_fd_sc_hvl + - sky130_fd_io +- latest [open_pdks](https://github.com/RTimothyEdwards/open_pdks). + +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. + +If you will use OpenLANE to harden your design, go through the instructions in this [README.md][0]. + +Then, you will need to put your design aboard the Caravel chip. In the Caravel directory, make sure you have the following: + +- Magic installed on your machine. We may provide a Dockerized version later. +- You have your user_project_wrapper.gds under `./gds/` directory. + +Run the following command: + +```bash +export PDK_ROOT=<The place where the installed pdk resides> +make +``` + +This should merge the GDSes using magic and you'll end up with your version of `./gds/caravel.gds`. + ## Managment SoC The managment SoC runs firmware that can be used to: -- Configure Mega Project I/O pads -- Observe and control Mega Project signals (through on-chip logic analyzer probes) -- Control the Mega Project power supply +- 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) -## Mega Project Area +## 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 mega project](/verilog/rtl/user_proj_example.v) that contains a binary 32-bit up counter. </br> +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 Mega 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 Mega 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 Mega 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). +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
diff --git a/openlane/DFFRAM/README.md b/openlane/DFFRAM/README.md new file mode 100644 index 0000000..639fc5a --- /dev/null +++ b/openlane/DFFRAM/README.md
@@ -0,0 +1,3 @@ +# DFFRAM + +This DFFRAM is adobted from https://github.com/shalan/DFFRAM
diff --git a/openlane/README.md b/openlane/README.md new file mode 100644 index 0000000..1fd14e9 --- /dev/null +++ b/openlane/README.md
@@ -0,0 +1,86 @@ +# Using OpenLANE to Harden Your Design: + +You can utilize the Makefile existing here in this directory to do that. + +But, first you need to specify 3 things: +```bash +export IMAGE_NAME=openlane:<the openlane tag/version you are using> +export PDK_ROOT=<The location where the pdk is installed> +export OPENLANE_ROOT=<the absolute path to the cloned openlane directory> +``` + +Then, you have two options: +1. Create a macro for your design and harden it, then insert it into user_project_wrapper. + +2. Flatten your design with the user_project_wrapper and harden them as one. + + +**NOTE:** The OpenLANE documentation should cover everything you might need to create your design. You can find that [here](https://github.com/efabless/openlane/blob/master/README.md). + +## Option 1: + +This could be done by creating a directory for your design here in this directory, and adding a configuration file for it under the same directory. You can follow the instructions given [here](https://github.com/efabless/openlane#adding-a-design) to generate an initial configuration file for your design, or you can start with the following: + +```tcl +set script_dir [file dirname [file normalize [info script]]] + +set ::env(DESIGN_NAME) <Your Design Name> + +set ::env(VERILOG_FILES) "$script_dir/../../verilog/rtl/<Your RTL.v>" + +set ::env(CLOCK_PORT) <Clock port name if it exists> +set ::env(CLOCK_PERIOD) <Desired clock period> +``` + +Then you can add them as you see fit to get the desired DRC/LVS clean outcome. + +After that, run the following command: +```bash +make <your design directory name> +``` + +Then, follow the instructions given in Option 2. + +## Option 2: + +1. Add your design to the RTL of the [user_project_wrapper](../verilog/rtl/user_project_wrapper.v). + +2. Modify the configuration file [here](./user_project_wrapper/config.tcl) to include any extra files you may need. Make sure to change these accordingly: +```tcl +set ::env(CLOCK_NET) "mprj.clk" + + +set ::env(VERILOG_FILES) "\ + $script_dir/../../verilog/rtl/defines.v \ + $script_dir/../../verilog/rtl/user_project_wrapper.v" + +set ::env(VERILOG_FILES_BLACKBOX) "\ + $script_dir/../../verilog/rtl/defines.v \ + $script_dir/../../verilog/rtl/user_proj_example.v" + +set ::env(EXTRA_LEFS) "\ + $script_dir/../../lef/user_proj_example.lef" + +set ::env(EXTRA_GDS_FILES) "\ + $script_dir/../../gds/user_proj_example.gds" +``` +**NOTE:** Don't change the size or the pin order! + +3. Remove this line `add_macro_placement mprj 1150 1700 N` from the interactive script [here](./user_project_wrapper/config.tcl) and replace it with the placement for your macro instances. Or, remove it entirely if you have no macros, along with this line `manual_macro_placement f`. + +4. Run your design through the flow: `make user_project_wrapper` + +5. Re-iterate until you have what you want. + +6. Go back to the main [README.md](../README.md) and continue the process of boarding the chip. + + +## Extra Pointers: + + +- The OpenLANE documentation should cover everything you might need to create your design. You can find that [here](https://github.com/efabless/openlane/blob/master/README.md). +- The OpenLANE [FAQs](https://github.com/efabless/openlane/wiki) can guide through your troubles. +- [Here](https://github.com/efabless/openlane/blob/master/configuration/README.md) you can find all the configurations and how to use them. +- [Here](https://github.com/efabless/openlane/blob/master/doc/advanced_readme.md) you can learn how to write an interactive script. +- [Here](https://github.com/efabless/openlane/blob/master/doc/OpenLANE_commands.md) you can find a full documentation for all OpenLANE commands. +- [This documentation](https://github.com/efabless/openlane/blob/master/regression_results/README.md) describes how to use the exploration script to achieve an LVS/DRC clean design.