Files

T

imple c7b19e8744 Seed RISC-V core roadmap and project contracts

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.

2026-04-28 11:11:38 +02:00

3.1 KiB

Raw Blame History

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.

3.1 KiB Raw Blame History