diff options
Diffstat (limited to 'rv64cpu/README')
| -rw-r--r-- | rv64cpu/README | 141 |
1 files changed, 141 insertions, 0 deletions
diff --git a/rv64cpu/README b/rv64cpu/README new file mode 100644 index 0000000..a7e62a5 --- /dev/null +++ b/rv64cpu/README @@ -0,0 +1,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) |