This repository contains a starting point for integrating a Chisel project into the Caravel harness using Librelane.

To use Chisel you need to have a JDK (up ti 21) and sbt installed. See Chisel Setup.

It includes a Chisel top-level module (CaravelTop) containing a simple GCD calculator which is connected to the Caravel's wishbone bus and GPIOs. The verilog for the CaravelTop module is generated by running:

make chisel-generate

To work with caravel, you will have to install the cf-cli tool and fetch dependencies using:

pip install chipfoundry-cli
cf setup

The Chisel top-level is hardened separately as a macro which is placed into the Caravel user_project_wrapper. The configuration files for both are located in the openlane/ directory. They are hardened using the following commands:

cf harden CaravelTop
cf harden user_project_wrapper

The Chisel modules can be tested in Scala by calling:

make chisel-test

An integration test for the whole Caravel system can be run using cocotb. An example test case is included, which uses the GCD component and checks its output in verilog/dv/cocotb/user_proj_tests/gcd_example_test. To run this test, execute the following command:

cf verify --all

The remaining documentation is a general guide from the Caravel user project template.

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.