Quick start for caravel_user_project

Dependencies

Docker: Linux || Windows || Mac with Intel Chip || Mac with M1 Chip
Python 3.6+ with PIP

Starting your project

To start the project you first need to create a new repository based on the caravel_user_project template and make sure your repo is public and includes a README.
- Follow https://github.com/efabless/caravel_user_project/generate to create a new repository.
- Clone the reposity using the following command:
```
git clone <your github repo URL>
```

To setup your local environment run:

cd <project_name> # project_name is the name of your repo

mkdir dependencies

export OPENLANE_ROOT=$(pwd)/dependencies/openlane_src # you need to export this whenever you start a new shell

export PDK_ROOT=$(pwd)/dependencies/pdks # you need to export this whenever you start a new shell

# export the PDK variant depending on your shuttle, if you don't know leave it to the default

# for sky130 MPW shuttles....
export PDK=sky130B

# for the GFMPW shuttles...
export PDK=gf180mcuC

make setup

This command will setup your environment by installing the following:
- caravel_lite (a lite version of caravel)
- management core for simulation
- openlane to harden your design
- pdk

Now you can start hardening your design
- To start hardening you project you need - RTL verilog model for your design for OpenLane to harden - A subdirectory for each macro in your project under openlane/ directory, each subdirectory should include openlane configuration files for the macro
```
make <module_name>
```
  For an example of hardening a project please refer to user_project_example
Integrate modules into the user_project_wrapper
- Change the environment variables VERILOG_FILES_BLACKBOX, EXTRA_LEFS and EXTRA_GDS_FILES in openlane/user_project_wrapper/config.tcl to point to your module
- Instantiate your module(s) in verilog/rtl/user_project_wrapper.v
- Harden the user_project_wrapper including your module(s), using this command:
```
make user_project_wrapper
```

Run simulation on your design

You need to include your rtl/gl/gl+sdf files in verilog/includes/includes.<rtl/gl/gl+sdf>.caravel_user_project

NOTE: You shouldn’t include the files inside the verilog code

# you can then run RTL simulations using
make verify-<testbench-name>-rtl

# OR GL simulation using
make verify-<testbench-name>-gl

# OR for GL+SDF simulation using
# sdf annotated simulation is slow
make verify-<testbench-name>-gl-sdf

# for example
make verify-io_ports-rtl

Run cocotb simulation on your design
- You need to include your rtl/gl/gl+sdf files in verilog/includes/includes.<rtl/gl/gl+sdf>.caravel_user_project
- To make sure the cocotb flow works, run the following commands for testing the counter example
  # RTL tests make cocotb-verify-rtl # OR GL simulation using make cocotb-verify-gl
- To run cocotb tests on your design, Follow the steps below
  - Add cocotb tests under verilog/dv/cocotb follow steps at Adding_cocotb_test
  - Run cocotb tests using caravel_cocotb command steps at Running_cocotb_tests
Run opensta on your design
- Extract spefs for user_project_wrapper and macros inside it:
```
make extract-parasitics
```
- Create spef mapping file that maps instance names to spef files:
```
make create-spef-mapping
```
- Run opensta:
```
make caravel-sta
```
Run the precheck locally
```
make precheck
make run-precheck
```
You are done! now go to https://efabless.com/open_shuttle_program/ to submit your project!