index.md

Caravel User Project

Table of Contents

• Overview
• Quickstart
• Caravel Integration
  • Repo Integration
  • Verilog Integration
  • GPIO Configuration
  • Layout Integration
• Running Full Chip Simulation
• User Project Wrapper Requirements
• Hardening the User Project using OpenLane
• Running Timing Analysis on Existing Projects
• Checklist for Open-MPW Submission

Overview

This repository contains a sample user project for the Caravel chip user space. It includes a simple counter demonstrating how to use Caravel's utilities such as IO pads, logic analyzer probes, and the Wishbone port. The repository also follows the recommended structure for open-mpw shuttle projects.

Prerequisites

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

Quickstart

Starting Your Project

1. Create a new repository based on the caravel_user_project template. Ensure your repo is public and includes a README.

   • Follow this link to create your repository.

   • Clone the repository using:

     git clone <your github repo URL>

2. Set up your local environment:

   cd <project_name>
   make setup

   This command installs:

   • caravel_lite
   • Management core for simulation
   • OpenLane for design hardening
   • PDK
   • Timing scripts

3. Start hardening your design:

   • For hardening, provide an RTL Verilog model of your design to OpenLane.

   • Create a subdirectory for each macro in your project under the openlane/ directory with OpenLane configuration files.

     make <module_name>

   Refer to Hardening the User Project using OpenLane for examples.

4. Integrate modules into the user_project_wrapper:

   • Update 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 with your module(s):

     make user_project_wrapper

5. Run cocotb simulation on your design:

   • Update rtl/gl/gl+sdf files in verilog/includes/includes.<rtl/gl/gl+sdf>.caravel_user_project.

   • Run gen_gpio_defaults.py script to generate caravel_core.v.

   • Run RTL tests:

     make cocotb-verify-all-rtl

   • For GL simulation:

     make cocotb-verify-all-gl

   • To add cocotb tests, refer to Adding cocotb test.

6. Run opensta on your design:

   • Extract parasitics for user_project_wrapper and its macros:

     make extract-parasitics

   • Create a spef mapping file:

     make create-spef-mapping

   • Run opensta:

     make caravel-sta

Note

To update timing scripts, run make setup-timing-scripts.

7. Run the precheck locally:

   make precheck
   make run-precheck

8. You're done! Submit your project at Efabless Open Shuttle Program.

GPIO Configuration

Specify the power-on default configuration for each GPIO in Caravel in verilog/rtl/user_defines.v. GPIO[5] to GPIO[37] require configuration, while GPIO[0] to GPIO[4] are preset and cannot be changed.

Layout Integration

The Caravel layout includes an empty golden wrapper in the user space. Provide a valid user_project_wrapper GDS file. Your hardened user_project_wrapper will be integrated into the Caravel layout during tapeout.

Ensure your hardened user_project_wrapper meets the requirements in User Project Wrapper Requirements.

Running Full Chip Simulation

Refer to ReadTheDocs for adding cocotb tests.

1. Install the simulation environment:

   make setup-cocotb

2. Run RTL simulation:

   make cocotb-verify-<test_name>-rtl

3. After physical implementation, run full gate-level simulations to verify your design.

   make cocotb-verify-<test_name>-gl

User Project Wrapper Requirements

Your hardened user_project_wrapper must match the golden user_project_wrapper in:

• Area (2.920um x 3.520um)
• Top module name "user_project_wrapper"
• Pin Placement
• Pin Sizes
• Core Rings Width and Offset
• PDN Vertical and Horizontal Straps Width

You can change the PDN Vertical and Horizontal Pitch & Offset.

We run an XOR check between your hardened user_project_wrapper GDS and the golden wrapper GDS as part of the mpw-precheck tool.

Hardening the User Project using OpenLane

OpenLane Installation

Install OpenLane with:

make openlane

For more detailed instructions, refer to the ReadTheDocs.

Hardening Options

There are three options for hardening the user project macro using OpenLane:

1. Option 1: Harden the user macro(s) first, then insert it into the user project wrapper with no standard cells at the top level.

   

   Example: caravel_user_project

2. Option 2: Flatten the user macro(s) with the user_project_wrapper.

   

3. Option 3: Place multiple macros in the wrapper along with standard cells at the top level.

   

   Example: clear

For more details, refer to the Knowledgebase article.

Running OpenLane

For this project, we chose the first option: harden the user macro first, then insert it into the user project wrapper without standard cells at the top level.

To reproduce this process, run:

# DO NOT cd into openlane

# Harden user_proj_example
make user_proj_example

# Harden user_project_wrapper
make user_project_wrapper

For more information, refer to the OpenLane Documentation.

Running Transistor Level LVS

To pass precheck, a custom LVS configuration file (lvs_config.json) is needed for your design. The configuration file should include:

Required variables:

• TOP_SOURCE: Top source cell name.
• TOP_LAYOUT: Top layout cell name.
• LAYOUT_FILE: Layout GDS data file.
• LVS_SPICE_FILES: List of spice files.
• LVS_VERILOG_FILES: List of Verilog files (child modules should be listed before parent modules).

Optional variables:

• INCLUDE_CONFIGS: List of configuration files to read recursively.
• EXTRACT_FLATGLOB: List of cell names to flatten before extraction.
• EXTRACT_ABSTRACT: List of cells to extract as abstract devices.
• LVS_FLATTEN: List of cells to flatten before comparing.
• LVS_NOFLATTEN: List of cells not to flatten in case of a mismatch.
• LVS_IGNORE: List of cells to ignore during LVS.

Note

Missing files and undefined variables result in fatal errors.

Running MPW Precheck Locally

Install the mpw-precheck by running:

make precheck

Run the precheck with:

make run-precheck

To disable LVS/Soft/ERC connection checks:

DISABLE_LVS=1 make run-precheck

Running Timing Analysis on Existing Projects

Update the Makefile for your project:

make setup-timing-scripts

Run timing analysis:

make extract-parasitics

make create-spef-mapping

make caravel-sta

A summary of timing results is provided at the end.

Checklist for Shuttle Submission

• ✔️ The project repo follows the directory structure in this repo.
• ✔️ Top level macro is named user_project_wrapper.
• ✔️ Full Chip Simulation passes for RTL and GL.
• ✔️ Hardened Macros are LVS and DRC clean.
• ✔️ Contains a gate-level netlist for user_project_wrapper at verilog/gl/user_project_wrapper.v.
• ✔️ Hardened user_project_wrapper matches the pin order.
• ✔️ Matches the fixed wrapper configuration.
• ✔️ Design passes the mpw-precheck.