quickstart.rst

Quick start for caravel_user_project

Dependencies

• Docker: Linux || Windows || Mac with Intel Chip || Mac with M1 Chip

---

Starting your project

1. To start the project you need to first create an empty Git project on Github and make sure your repo is public and includes a README

2. Open your Terminal. Create an empty folder to use as your Caravel workspace, and navigate to it.

   # Create a directory and call it anything you want
   mkdir -p caravel_tutorial
   
   # navigate into the directory
   cd caravel_tutorial

3. Clone caravel_user_project and setup the git environment as follows

   # Make sure that "caravel_example" matches the empty github repo name in step 1
   git clone -b mpw-5c https://github.com/efabless/caravel_user_project caravel_example
   cd caravel_example
   git remote rename origin upstream
   
   # You need to put your empty github repo URL from step 1
   git remote add origin <your github repo URL>
   
   # Create a new branch, you can name it anything
   git checkout -b <my_branch>
   git push -u origin <my_branch>

4. Now that your git environment is setup, it's time to setup your local environment by running.

   # make sure to change <directory_name> with the directory you created in step 2
   # in this case it is caravel_tutorial
   export OPENLANE_ROOT=~/<directory_name>/openlane # you need to export this whenever you start a new shell
   
   export PDK_ROOT=~/<directory_name>/pdks # you need to export this whenever you start a new shell
   
   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

5. 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

6. 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

7. 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
     
     # for example
     make verify-io_ports-rtl

8. Run the precheck locally

   make precheck
   make run-precheck

9. You are done! now go to www.efabless.com to submit your project!