imple
c7b19e8744
Establish the repository as a documentation-first plan for a custom SystemVerilog RISC-V CPU targeting the Digilent Arty A7 100T. Add the initial README, roadmap, and contributor guidance that define the starting RV32IM direction, Vivado/RISC-V toolchain expectations, basic SystemVerilog conventions, and the phased path from an architecture contract toward a Linux-capable SoC. This commit intentionally contains planning and interface direction only; RTL, firmware, testbenches, and Vivado project files are left for later phases.
73 lines
3.1 KiB
Markdown
73 lines
3.1 KiB
Markdown
# CLAUDE.md
|
|
|
|
## Project Overview
|
|
|
|
This is a custom RISC-V RV32IM CPU core written in SystemVerilog, targeting the
|
|
Digilent Arty A7 100T (xc7a100tcsg324-1) with Vivado 2025.2.1.
|
|
|
|
The goal is incremental development from a single-cycle core to a Linux-capable SoC.
|
|
See ROADMAP.md for the full phased plan.
|
|
|
|
## Conventions
|
|
|
|
- Language: SystemVerilog (not Verilog). Use SV features: packages, structs, enums,
|
|
always_comb, always_ff, logic (not reg/wire).
|
|
- All inter-stage signals are defined as structs in `rtl/pkg/rv32_pkg.sv`. Always
|
|
import this package. When adding new functionality, extend the existing structs
|
|
rather than adding loose wires.
|
|
- Module naming: `rv32_<block>` (e.g., `rv32_alu`, `rv32_decode`, `rv32_regfile`).
|
|
- File naming: one module per file, filename matches module name.
|
|
- Testbenches: `tb/tb_<module>.sv`. Use Vivado simulator.
|
|
- Clock: single clock domain, active rising edge, signal named `clk`.
|
|
- Reset: synchronous active-high, signal named `rst`.
|
|
- BRAM init files: `mem/*.mem` in hex format, one 32-bit word per line.
|
|
- Firmware source: `fw/` directory. Built with riscv64-unknown-elf-gcc,
|
|
-march=rv32im -mabi=ilp32.
|
|
|
|
## Directory Structure
|
|
|
|
```
|
|
rtl/ — synthesizable source
|
|
pkg/ — packages (rv32_pkg.sv)
|
|
core/ — CPU core modules (ALU, decoder, regfile, datapath)
|
|
periph/ — peripherals (UART, timer, etc.)
|
|
top/ — top-level and SoC integration
|
|
tb/ — testbenches
|
|
mem/ — BRAM init files (.mem)
|
|
fw/ — firmware source (C, assembly, linker scripts)
|
|
constraints/ — Vivado XDC constraint files
|
|
docs/ — block diagrams, notes
|
|
```
|
|
|
|
## ISA Target
|
|
|
|
RV32IM base. Extensions added incrementally:
|
|
- Zicsr (CSR instructions) — Phase 9
|
|
- Zifencei (fence.i) — implemented as NOP until caches exist
|
|
- M-mode privileged — Phase 9
|
|
- S-mode + U-mode + Sv32 — Phase 14
|
|
|
|
## Key Design Decisions
|
|
|
|
- Single-cycle first, pipeline later (Phase 12). Stages are separated in the code
|
|
even without pipeline registers between them.
|
|
- Memory bus uses valid/ready handshake from day one, even though BRAM always
|
|
responds in one cycle. This is for future DRAM compatibility.
|
|
- M extension (multiply/divide) is in the ALU from the start to avoid rework.
|
|
- Harvard architecture (separate instruction and data memory) initially. Unified
|
|
memory when DRAM is added.
|
|
|
|
## When Helping With This Project
|
|
|
|
- Always check rv32_pkg.sv first to understand current struct definitions and enums.
|
|
- Reference the RISC-V ISA spec for instruction encoding and behavior.
|
|
- Prefer simulation-testable solutions. Every module should be verifiable standalone
|
|
before integration.
|
|
- Don't add Verilog-style code (reg, wire, always @). Use SV equivalents.
|
|
- When suggesting fixes, consider that the design is single-cycle — there are no
|
|
pipeline hazards yet.
|
|
- Vivado quirks: use (* dont_touch = "true" *) for signals that Vivado optimizes
|
|
away during debug. ILA/VIO probes need to be on nets that survive synthesis.
|
|
- The Arty A7 100T has: 101,440 logic cells, 4,860 Kbit BRAM, 240 DSP slices,
|
|
256MB DDR3L SDRAM, USB-UART bridge, 4 LEDs, 4 switches, 4 buttons.
|