Skip to content

Commit fd7138d

Browse files
MummanajagadeeshMummanajagadeesh
committed
docs: add full project README
1 parent 8fd1b92 commit fd7138d

1 file changed

Lines changed: 194 additions & 6 deletions

File tree

‎README.md‎

Lines changed: 194 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,198 @@
1-
# Caravel User Project
1+
# FIR Accelerator Caravel SoC
22

3-
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) [![UPRJ_CI](https://github.com/efabless/caravel_project_example/actions/workflows/user_project_ci.yml/badge.svg)](https://github.com/efabless/caravel_project_example/actions/workflows/user_project_ci.yml) [![Caravel Build](https://github.com/efabless/caravel_project_example/actions/workflows/caravel_build.yml/badge.svg)](https://github.com/efabless/caravel_project_example/actions/workflows/caravel_build.yml)
3+
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
44

5-
| :exclamation: Important Note |
6-
|-----------------------------------------|
5+
A mixed-signal signal processing SoC implemented as a Caravel user project on the SkyWater SKY130A 130nm open-source PDK. The design implements a complete digital signal processing pipeline — CIC decimation → FIR filtering → PWM DAC output — controlled via the Caravel RISC-V management core over Wishbone.
76

8-
## Please fill in your project documentation in this README.md file
7+
## Table of Contents
98

10-
Refer to [README](docs/source/index.md) for this sample project documentation.
9+
- [Overview](#overview)
10+
- [Architecture](#architecture)
11+
- [Register Map](#register-map)
12+
- [Directory Structure](#directory-structure)
13+
- [Quickstart](#quickstart)
14+
- [Hardening](#hardening)
15+
- [Signoff Results](#signoff-results)
16+
- [Checklist](#checklist)
17+
18+
## Overview
19+
20+
This project implements a programmable digital FIR filter accelerator SoC inside the Caravel user project wrapper. The RISC-V management core programs filter coefficients, decimation ratio, and control flags via a Wishbone CSR block. A 1-bit bitstream input (from GPIO or internal LFSR test source) passes through a CIC decimation filter, an 8-tap FIR filter, and a PWM DAC to produce an analog-approximated output on GPIO[9].
21+
22+
Intended as a foundation for a future mixed-signal tapeout with a first-order Σ∆ modulator frontend (analog block, Phase 2).
23+
24+
## Architecture
25+
26+
```
27+
GPIO[8] ──────────────────────┐
28+
├──► [Bitstream MUX] ──► [CIC Decimator] ──► [FIR Filter] ──► [PWM DAC] ──► GPIO[9]
29+
LFSR (use_lfsr=1) ────────────┘ ▲ ▲ ▲ ▲
30+
│ │ │ │
31+
[Wishbone CSR] ◄──────────────────────────────────────────────────┘
32+
▲
33+
Caravel RISC-V Management Core (Wishbone)
34+
```
35+
36+
### Blocks
37+
38+
| Block | File | Description |
39+
|---|---|---|
40+
| `wb_csr` | `rtl/digital/wishbone_csr/wb_csr.v` | Wishbone CSR — register-mapped control and status |
41+
| `cic_decimator` | `rtl/digital/cic/cic_decimator.v` | 3-stage CIC decimation filter, OSR=8/16/32/64 |
42+
| `fir_filter` | `rtl/digital/fir/fir_filter.v` | 8-tap direct-form I FIR, Q1.15, runtime-programmable coefficients |
43+
| `pwm_dac` | `rtl/digital/pwm_dac/pwm_dac.v` | 8-bit first-order delta-sigma PWM DAC |
44+
| `lfsr` | `rtl/digital/lfsr/lfsr.v` | 16-bit Galois LFSR — internal test bitstream source |
45+
46+
## Register Map
47+
48+
Base address: `0x3000_0000` (Wishbone)
49+
50+
| Offset | Name | Bits | Description |
51+
|---|---|---|---|
52+
| 0x00 | CTRL | [0]=enable, [1]=bypass_fir, [2]=bypass_cic, [3]=soft_rst, [4]=use_lfsr | Control register |
53+
| 0x04 | OSR | [6:0] | CIC decimation ratio (8/16/32/64) |
54+
| 0x08 | COEFF_ADDR | [2:0] | FIR tap index to write (0–7) |
55+
| 0x0C | COEFF_DATA | [15:0] | FIR coefficient in Q1.15 format — write triggers load |
56+
| 0x10 | STATUS | [0]=data_valid, [1]=overflow | Read-only status |
57+
| 0x14 | PWM_DATA | [7:0] | Direct PWM value (bypass_fir mode) |
58+
59+
### GPIO
60+
61+
| GPIO | Direction | Function |
62+
|---|---|---|
63+
| GPIO[8] | Input | Bitstream input (Σ∆ modulator / external) |
64+
| GPIO[9] | Output | PWM DAC output |
65+
66+
## Directory Structure
67+
68+
```
69+
rtl/
70+
├── digital/
71+
│ ├── cic/ — CIC decimation filter
72+
│ ├── fir/ — FIR filter
73+
│ ├── lfsr/ — LFSR test source
74+
│ ├── pwm_dac/ — PWM DAC
75+
│ └── wishbone_csr/ — Wishbone CSR block
76+
└── analog/ — Σ∆ modulator (Phase 2, planned)
77+
sim/digital/ — Testbenches (Icarus Verilog)
78+
verilog/rtl/ — Caravel top-level wrapper
79+
openlane/wrapped_filter/— OpenLane hardening config and SDC
80+
signoff/ — DRC, LVS, timing reports
81+
xschem/ — Analog schematic (Phase 2, planned)
82+
analog/magic/ — Analog layout (Phase 2, planned)
83+
docs/ — Documentation
84+
```
85+
86+
## Quickstart
87+
88+
### Prerequisites
89+
90+
- Docker
91+
- Python 3.8+
92+
- `volare` (`pip3 install volare`)
93+
94+
### Setup
95+
96+
```bash
97+
git clone https://github.com/Mummanajagadeesh/fir-accel-caravel-soc.git
98+
cd fir-accel-caravel-soc
99+
100+
export PDK_ROOT=~/pdks
101+
export PDK=sky130A
102+
export OPENLANE_ROOT=~/OpenLane
103+
export CARAVEL_ROOT=$(pwd)/caravel
104+
export UPRJ_ROOT=$(pwd)
105+
106+
make setup
107+
```
108+
109+
### RTL Simulation
110+
111+
```bash
112+
# Simulate individual blocks
113+
iverilog -o sim/digital/pwm_dac_sim \
114+
rtl/digital/pwm_dac/pwm_dac.v sim/digital/tb_pwm_dac.v && \
115+
vvp sim/digital/pwm_dac_sim
116+
117+
iverilog -o sim/digital/cic_sim \
118+
rtl/digital/cic/cic_decimator.v sim/digital/tb_cic.v && \
119+
vvp sim/digital/cic_sim
120+
121+
iverilog -o sim/digital/fir_sim \
122+
rtl/digital/fir/fir_filter.v sim/digital/tb_fir.v && \
123+
vvp sim/digital/fir_sim
124+
125+
# Integration smoke test
126+
iverilog -o sim/digital/top_sim \
127+
verilog/rtl/user_project_wrapper.v \
128+
rtl/digital/wishbone_csr/wb_csr.v \
129+
rtl/digital/cic/cic_decimator.v \
130+
rtl/digital/fir/fir_filter.v \
131+
rtl/digital/pwm_dac/pwm_dac.v \
132+
rtl/digital/lfsr/lfsr.v \
133+
sim/digital/tb_top.v && \
134+
vvp sim/digital/top_sim
135+
```
136+
137+
## Hardening
138+
139+
```bash
140+
cd openlane
141+
142+
# Harden user project (RTL → GDS)
143+
make wrapped_filter \
144+
OPENLANE_ROOT=$OPENLANE_ROOT \
145+
PDK_ROOT=$PDK_ROOT \
146+
PDK=sky130A \
147+
CARAVEL_ROOT=$CARAVEL_ROOT \
148+
UPRJ_ROOT=$UPRJ_ROOT
149+
```
150+
151+
Flow runs synthesis (Yosys), floorplan, placement, CTS, routing, and signoff (Magic DRC + LVS + OpenSTA) inside the OpenLane Docker container (`efabless/openlane:2023.07.19-1`).
152+
153+
## Signoff Results
154+
155+
| Check | Result |
156+
|---|---|
157+
| Magic DRC | **0 violations** |
158+
| LVS | **Clean** (18,329 nets) |
159+
| Setup violations | None |
160+
| Hold violations | None |
161+
| Antenna violations | 2 (non-critical) |
162+
| GDS size | 95 MB |
163+
| Die area | 2920 × 3520 µm |
164+
| Standard cell library | `sky130_fd_sc_hd` |
165+
| Clock period | 25 ns (40 MHz) |
166+
167+
## Future Work
168+
169+
- **Phase 2 — Analog frontend**: First-order Σ∆ modulator in Sky130 full-custom layout (Xschem schematic → Magic layout → NGSpice post-layout verification)
170+
- Gate-level simulation with Caravel cocotb infrastructure
171+
- Efabless chipIgnite shuttle submission
172+
173+
## Tools
174+
175+
| Tool | Version |
176+
|---|---|
177+
| OpenLane | 1.0.2 (superstable) |
178+
| Sky130A PDK | `78b7bc32` |
179+
| Icarus Verilog | 11.0 |
180+
| NGSpice | 36 |
181+
| Magic VLSI | 8.3.105 |
182+
| Docker image | `efabless/openlane:2023.07.19-1` |
183+
184+
## License
185+
186+
[Apache License 2.0](LICENSE)
187+
188+
## Checklist for Shuttle Submission
189+
190+
- ✔️ Top level macro named `user_project_wrapper`
191+
- ✔️ Hardened macro is DRC clean (Magic DRC: 0 violations)
192+
- ✔️ Hardened macro is LVS clean (18,329 nets)
193+
- ✔️ No setup or hold violations at typical corner
194+
- ✔️ Pin order matches Caravel wrapper specification
195+
- ✔️ RTL simulations pass for all blocks
196+
- ⬜ Gate-level simulation (cocotb)
197+
- ⬜ Full mpw-precheck pass
198+
- ⬜ Analog frontend (Phase 2)

0 commit comments

Comments
 (0)