1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
|
# Richard CPU
**RV64GCZicsr_Zifencei** Five-Stage In-Order Pipelined Processor SoC
Written in SystemVerilog, simulated with Verilator, targeting official riscv-arch-test compliance.
## Features
- **ISA**: RV64IMAFDC + Zicsr + Zifencei (RV64GC)
- **Pipeline**: 5-stage in-order single-issue (IF → ID → EX → MEM → WB)
- **Privilege Levels**: M / S / U tri-mode
- **Virtual Memory**: Sv39 (MMU with TLB + Hardware PTW)
- **Cache**: I-Cache 4KB + D-Cache 4KB (AXI4-Full Burst refill)
- **Bus**: AXI4-Full (Cache) + AXI4-Lite (Peripherals) + auto bridge
- **Peripherals**: CLINT / PLIC / UART 16550 / GPIO / SRAM Controller
- **Debug**: JTAG Debug Transport Module (reserved)
- **FPGA**: Xilinx / Gowin synthesis support (reserved)
## Quick Start
### Dependencies
- [Verilator](https://verilator.org) ≥ 5.0
- CMake ≥ 3.20
- C++17 compiler (GCC / Clang)
- [riscv64-unknown-elf-gcc](https://github.com/riscv-collab/riscv-gnu-toolchain) (software compilation, optional)
- [uv](https://docs.astral.sh/uv/) (ACT4 Python tooling)
- [podman](https://podman.io/) (riscv-unified-db runtime)
- [sail_riscv_sim 0.10](https://github.com/riscv/sail-riscv/releases/tag/0.10) (reference model for ACT4)
- [GTKWave](http://gtkwave.sourceforge.net/) (waveform viewer, optional)
### Build Simulation
```bash
# Configure (enable waveform tracing)
cmake -B build -DENABLE_TRACE=ON
# Compile
cmake --build build -j$(nproc)
# Run all tests
ctest --test-dir build --output-on-failure
```
### Build Bare-Metal Programs
```bash
cmake -B build_sw -DBUILD_SW=ON \
-DCMAKE_TOOLCHAIN_FILE=tools/toolchain-riscv64.cmake
cmake --build build_sw -j$(nproc)
```
### Run Compliance Tests
```bash
# Initialize riscv-arch-test submodule
git submodule update --init --recursive
# Sync ACT4 python dependencies
cd sw/riscv-arch-test && uv sync --frozen && cd ../..
# Run strict full implemented suite (reference signature compare enabled)
python3 scripts/run_compliance.py --suite rv64full --max-cycles 200000 --require-reference
```
Verified strict suites (all pass):
- `rv64i`
- `rv64im`
- `rv64ia`
- `rv64ic`
- `rv64if`
- `rv64id`
- `rv64priv`
- `rv64full` (aggregate)
### View Waveforms
```bash
./scripts/wave_view.sh # Open latest waveform
./scripts/wave_view.sh waves/soc.vcd # Open specific file
```
## Documentation
| Document | Description |
|---|---|
| [docs/architecture.md](docs/architecture.md) | Microarchitecture design (pipeline, privilege levels, MMU, FPU, cache, bus) |
| [docs/memory_map.md](docs/memory_map.md) | Physical address space and peripheral register layout |
| [docs/isa_support.md](docs/isa_support.md) | ISA instruction implementation status matrix |
| [docs/pipeline_diagram.md](docs/pipeline_diagram.md) | Pipeline timing, inter-stage registers, forwarding/hazards |
## Project Structure
```
richard-cpu/
├── CMakeLists.txt # Top-level build
├── rtl/ # SystemVerilog RTL
│ ├── core/ # CPU core (pipeline stages + functional units)
│ │ ├── include/ # Global packages (rv64_pkg, csr_pkg)
│ │ ├── mmu/ # MMU (TLB + PTW)
│ │ ├── fpu/ # FPU (F/D extensions)
│ │ └── debug/ # Debug DTM (reserved)
│ ├── cache/ # I-Cache + D-Cache
│ ├── bus/ # AXI4 interconnect + AXI4-Lite bridge
│ ├── perips/ # Peripherals (CLINT/PLIC/UART/GPIO/SRAM)
│ └── soc/ # SoC top-level integration
├── tb/ # Verilator simulation testbench
│ ├── common/ # Common infrastructure
│ ├── unit/ # Unit tests
│ ├── core/ # Core integration tests
│ ├── soc/ # SoC-level simulation
│ └── compliance/ # riscv-arch-test runner
├── sw/ # Software
│ ├── common/ # Startup code + linker script
│ ├── baremetal/ # Bare-metal test programs
│ └── riscv-arch-test/ # Official compliance tests (git submodule)
├── fpga/ # FPGA synthesis
│ ├── xilinx/ # Artix-7 top-level + constraints + Tcl
│ └── gowin/ # (reserved)
├── scripts/ # Helper scripts
├── tools/ # CMake toolchain files
└── docs/ # Design documentation
```
## Roadmap
| Phase | Milestone |
|---|---|
| P1 | RV64I five-stage pipeline + hazard handling (Done) |
| P2 | CSR + M/S/U privilege levels + Trap (Done) |
| P3 | MMU (TLB + PTW) |
| P4 | Cache + AXI4-Full Burst |
| P5 | Peripherals + AXI4-Lite bridge + SoC integration |
| P6 | Pass riscv-arch-test (In Progress: strict suites above all pass) |
| P7 | M/F/D/A/C extensions + FPGA bring-up |
## License
[GPLv3](LICENSE)
|
