A comprehensive, self-contained learning and development environment for RISC-V system simulation. Build, run, and analyze bare-metal RISC-V applications across multiple simulation platforms.
- Multi-platform: Run the same bare-metal code on QEMU, Spike, gem5 (SE + FS), and Renode
- Single-core and multi-core (SMP): Configurable hart count (1 to 8+)
- RISC-V Vector Extension (RVV 1.0): Progressive vector workloads with VLEN-agnostic code
- Multi-processor (AMP): YAML-configured heterogeneous clusters on gem5 Full System (scalar and/or RVV cores, L1/L2, scratchpads, shared SRAM, UART/CLINT/PLIC)
- CMake + CTest: Modern build system with presets and comprehensive testing
- Test-Driven Development: TDD approach with automated validation
- Devcontainer: Fully reproducible development environment
- CI/CD: Automated builds, simulation runs, and validation
Current Phase: Phase 3 - Cross-Platform Support (Spike) ✅ COMPLETE
Next Phase: Phase 4 - Multi-Core SMP Support
- ✅ Phase 0: Design & Setup (comprehensive documentation)
- ✅ Phase 1: CMake build system, CTest framework, toolchain setup scripts, CI integration
- ✅ Phase 2: Single-core bare-metal application (TDD, UART driver, CSR access, 7 tests, CI green)
- ✅ Phase 3: Spike cross-platform support (HTIF driver, 8 Spike tests, CI simulation, cross-validation)
- 🔜 Phase 4: Multi-Core SMP support (2-8 harts, spinlocks, barriers)
See ROADMAP.md for detailed milestones and PHASE2_SUMMARY.md for Phase 2 details.
| Document | Description |
|---|---|
| ROADMAP.md | ⭐ Implementation roadmap with phased milestones |
| BUILD.md | ⭐ Build system setup and usage guide |
| claude.md | AI assistant context and development guidelines |
| .cursorrules | Cursor-specific development rules |
| Document | Description |
|---|---|
| 00 - Project Overview | High-level vision, goals, repository structure, and phased roadmap |
| 01 - Platform Assessment | Comprehensive evaluation of RISC-V simulation/emulation platforms (QEMU, Spike, gem5, Renode, etc.) |
| 02 - Bare-Metal Application | Application architecture: boot sequence, HAL, UART/HTIF drivers, CSR access, and module design |
| 03 - Platform Configurations | Single-core, multi-core SMP, and multi-processor AMP configuration designs |
| gem5 AMP README | YAML AMP topology, caches, buses, peripherals |
| 04 - RVV Vector Extension | RVV 1.0 learning plan: concepts, instruction categories, progressive workloads, and LMUL exploration |
| 05 - Build System | Build system design (now implemented with CMake) |
| 06 - CI/CD Pipeline | GitHub Actions workflows for build, simulation, lint, and gem5 |
Use the devcontainer (recommended) or install manually:
# Using devcontainer (VS Code / Codespaces)
# Just open the project -- the container has everything pre-installed.
# Manual setup
./scripts/setup-toolchain.sh # Install RISC-V GCC toolchain
./scripts/setup-simulators.sh # Install QEMU + Spike
# Verify environment
./scripts/verify-environment.sh# Configure with a preset (see CMakePresets.json)
cmake --preset default # QEMU single-core
# Build
cmake --build build/default
# Test (when Phase 2 is complete)
ctest --test-dir build/default --output-on-failurecmake --list-presets # List all presets
# Common presets:
cmake --preset default # QEMU single-core
cmake --preset qemu-smp # QEMU 4-hart SMP
cmake --preset qemu-rvv-256 # QEMU with RVV (VLEN=256)
cmake --preset spike # Spike ISA simulator
cmake --preset gem5-fs # gem5 Full System
cmake --preset gem5-amp # gem5 AMP (2-cluster heterogeneous)
cmake --preset renode # RenodeSee BUILD.md for detailed build instructions.
| Platform | Type | RVV | Multi-Core | Cycle-Accurate | CI | Phase |
|---|---|---|---|---|---|---|
| QEMU | DBT Emulator | Yes | Yes (SMP) | No | ✅ Yes | 2-5 |
| Spike | Functional ISA Sim | Yes | Yes (SMP) | No | ✅ Yes | 3 |
| gem5 SE | Micro-arch Sim (Syscall Emulation) | Partial | Yes (SMP) | Yes | On merge | 6 |
| gem5 FS | Micro-arch Sim (Full System) | Partial | Yes (SMP+AMP) | Yes | On merge | 6, 8 |
| Renode | Functional Emulator | Limited | Yes (SMP+AMP) | No | Planned | 7 |
| Configuration | ISA String | Description |
|---|---|---|
| Minimal | rv64imac |
Integer + Atomic + Compressed |
| Standard | rv64gc |
Full general-purpose (= rv64imafdc) |
| Vector | rv64gcv |
General-purpose + Vector 1.0 |
Apache License 2.0. See LICENSE for details.