Table of Contents

• Overview
• Documentation & Resources
• Prerequisites
• Project Structure
• Starting Your Project
• Development Flow
• GPIO Configuration
• Local Precheck
• Checklist for Shuttle Submission

Overview

This repository contains a user project designed for integration into the Caravel chip user space. Use it as a template for integrating custom RTL with Caravel's system-on-chip (SoC) utilities, including:

• IO Pads: Configurable general-purpose input/output.
• Logic Analyzer Probes: 128 signals for non-intrusive hardware debugging.
• Wishbone Port: A 32-bit standard bus interface for communication between the RISC-V management core and your custom hardware.

---

Documentation & Resources

For detailed hardware specifications and register maps, refer to the following official documents:

• Caravel Datasheet: Detailed electrical and physical specifications of the Caravel harness.
• Caravel Technical Reference Manual (TRM): Complete register maps and programming guides for the management SoC.
• ChipFoundry Marketplace: Access additional IP blocks, EDA tools, and shuttle services.

---

Prerequisites

Ensure your environment meets the following requirements:

1. Docker Linux | Windows | Mac
2. Python 3.8+ with pip.
3. Git: For repository management.

---

Project Structure

A successful Caravel project requires a specific directory layout for the automated tools to function:

Directory	Description
openlane/	Configuration files for hardening macros and the wrapper.
verilog/rtl/	Source Verilog code for the project.
verilog/gl/	Gate-level netlists (generated after hardening).
verilog/dv/	Design Verification (cocotb and Verilog testbenches).
gds/	Final GDSII binary files for fabrication.
lef/	Library Exchange Format files for the macros.

---

Starting Your Project

1. Repository Setup

Create a new repository based on the caravel_user_project template and clone it to your local machine:

git clone <your-github-repo-URL>
pip install chipfoundry-cli
cd <project_name>

2. Project Initialization

Important

Run this first! Initialize your project configuration:

cf init

This creates .cf/project.json with project metadata. This must be run before any other commands (cf setup, cf gpio-config, cf harden, cf precheck, cf verify).

3. Environment Setup

Install the ChipFoundry CLI tool and set up the local environment (PDKs, OpenLane, and Caravel lite):

cf setup

The cf setup command installs:

• Caravel Lite: The Caravel SoC template.
• Management Core: RISC-V management area required for simulation.
• OpenLane: The RTL-to-GDS hardening flow.
• PDK: Skywater 130nm process design kit.
• Timing Scripts: For Static Timing Analysis (STA).

---

Development Flow

Hardening the Design

Hardening is the process of synthesizing your RTL and performing Place & Route (P&R) to create a GDSII layout.

Macro Hardening

Create a subdirectory for each custom macro under openlane/ containing your config.tcl.

cf harden --list         # List detected configurations
cf harden <macro_name>   # Harden a specific macro

Integration

Instantiate your module(s) in verilog/rtl/user_project_wrapper.v.

Update openlane/user_project_wrapper/config.json environment variables (VERILOG_FILES_BLACKBOX, EXTRA_LEFS, EXTRA_GDS_FILES) to point to your new macros.

Wrapper Hardening

Finalize the top-level user project:

cf harden user_project_wrapper

Verification

1. Simulation

We use cocotb for functional verification. Ensure your file lists are updated in verilog/includes/.

Configure GPIO settings first (required before verification):

cf gpio-config

This interactive command will:

• Configure all GPIO pins interactively
• Automatically update verilog/rtl/user_defines.v
• Automatically run gen_gpio_defaults.py to generate GPIO defaults for simulation

GPIO configuration is required before running any verification tests.

Run RTL Simulation:

cf verify <test_name>

Run Gate-Level (GL) Simulation:

cf verify <test_name> --sim gl

Run all tests:

cf verify --all

2. Static Timing Analysis (STA)

Verify that your design meets timing constraints using OpenSTA:

make extract-parasitics
make create-spef-mapping
make caravel-sta

Note

Run make setup-timing-scripts if you need to update the STA environment.

---

GPIO Configuration

Configure the power-on default configuration for each GPIO using the interactive CLI tool.

Use the GPIO configuration command:

cf gpio-config

This command will:

• Present an interactive form for configuring GPIO pins 5-37 (GPIO 0-4 are fixed system pins)
• Show available GPIO modes with descriptions
• Allow selection by number, partial key, or full mode name
• Save configuration to .cf/project.json (as hex values)
• Automatically update verilog/rtl/user_defines.v with the new configuration
• Automatically run gen_gpio_defaults.py to generate GPIO defaults for simulation (if Caravel is installed)

GPIO Pin Information:

• GPIO[0] to GPIO[4]: Preset system pins (do not change).
• GPIO[5] to GPIO[37]: User-configurable pins.

Available GPIO Modes:

• Management modes: mgmt_input_nopull, mgmt_input_pulldown, mgmt_input_pullup, mgmt_output, mgmt_bidirectional, mgmt_analog
• User modes: user_input_nopull, user_input_pulldown, user_input_pullup, user_output, user_bidirectional, user_output_monitored, user_analog

Note

GPIO configuration is required before running cf precheck or cf verify. Invalid modes cannot be saved - all GPIOs must have valid configurations.

---

Local Precheck

Before submitting your design for fabrication, run the local precheck to ensure it complies with all shuttle requirements:

Important

GPIO configuration is required before running precheck. Make sure you've run cf gpio-config first.

cf precheck

You can also run specific checks or disable LVS:

cf precheck --disable-lvs                    # Skip LVS check
cf precheck --checks license --checks makefile  # Run specific checks only

---

Checklist for Shuttle Submission

• Top-level macro is named user_project_wrapper.
• Full Chip Simulation passes for both RTL and GL.
• Hardened Macros are LVS and DRC clean.
• user_project_wrapper matches the required pin order/template.
• Design passes the local cf precheck.
• Documentation (this README) is updated with project-specific details.