232 lines
7.9 KiB
Markdown
232 lines
7.9 KiB
Markdown
<div align="center">
|
|
|
|
<img src="https://umsousercontent.com/lib_lnlnuhLgkYnZdkSC/hj0vk05j0kemus1i.png" alt="ChipFoundry Logo" height="140" />
|
|
|
|
[](https://git.io/typing-svg)
|
|
|
|
[](https://opensource.org/licenses/Apache-2.0)
|
|
[](https://platform.chipfoundry.io/marketplace)
|
|
|
|
</div>
|
|
|
|
## Table of Contents
|
|
- [Overview](#overview)
|
|
- [Documentation & Resources](#documentation--resources)
|
|
- [Prerequisites](#prerequisites)
|
|
- [Project Structure](#project-structure)
|
|
- [Starting Your Project](#starting-your-project)
|
|
- [Development Flow](#development-flow)
|
|
- [GPIO Configuration](#gpio-configuration)
|
|
- [Local Precheck](#local-precheck)
|
|
- [Checklist for Shuttle Submission](#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](https://github.com/chipfoundry/caravel/blob/main/docs/caravel_datasheet_2.pdf)**: Detailed electrical and physical specifications of the Caravel harness.
|
|
* **[Caravel Technical Reference Manual (TRM)](https://github.com/chipfoundry/caravel/blob/main/docs/caravel_datasheet_2_register_TRM_r2.pdf)**: Complete register maps and programming guides for the management SoC.
|
|
* **[ChipFoundry Marketplace](https://platform.chipfoundry.io/marketplace)**: Access additional IP blocks, EDA tools, and shuttle services.
|
|
|
|
---
|
|
|
|
## Prerequisites
|
|
Ensure your environment meets the following requirements:
|
|
|
|
1. **Docker** [Linux](https://docs.docker.com/desktop/setup/install/linux/ubuntu/) | [Windows](https://docs.docker.com/desktop/setup/install/windows-install/) | [Mac](https://docs.docker.com/desktop/setup/install/mac-install/)
|
|
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:
|
|
|
|
```bash
|
|
git clone <your-github-repo-URL>
|
|
pip install chipfoundry-cli
|
|
cd <project_name>
|
|
```
|
|
|
|
### 2. Project Initialization
|
|
|
|
> [!IMPORTANT]
|
|
> Run this first! Initialize your project configuration:
|
|
|
|
```bash
|
|
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):
|
|
|
|
```bash
|
|
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`.
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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):**
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
cf verify <test_name>
|
|
```
|
|
|
|
Run Gate-Level (GL) Simulation:
|
|
|
|
```bash
|
|
cf verify <test_name> --sim gl
|
|
```
|
|
|
|
Run all tests:
|
|
|
|
```bash
|
|
cf verify --all
|
|
```
|
|
|
|
#### 2. Static Timing Analysis (STA)
|
|
Verify that your design meets timing constraints using OpenSTA:
|
|
|
|
```bash
|
|
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:**
|
|
```bash
|
|
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.
|
|
|
|
```bash
|
|
cf precheck
|
|
```
|
|
|
|
You can also run specific checks or disable LVS:
|
|
|
|
```bash
|
|
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.
|