RV32I bare-metal emulator

A C++20/CMake command-line emulator for statically linked, bare-metal RV32I ELF programs.

Quick start

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j
ctest --test-dir build --output-on-failure
./build/riscv-emu path/to/program.elf --trace

Build the assembly examples (requires a RISC-V cross toolchain, optional):

sh examples/build.sh
./build/riscv-emu examples/build/hello.elf

CLI

riscv-emu <elf> [--max-instructions N] [--ram-size SIZE] [--trace]

• --max-instructions N (-n): stop after N instructions (default 10000000).
• --ram-size SIZE: RAM capacity; decimal, 0x-hex, K/M/G suffixes (default 16M).
• --trace: print PC: raw disassembly per instruction to stdout.
• UART bytes are printed to stdout; final statistics always print.
• Exit status: 0 for --help; 1 for load failure or any halt/trap (including ECALL/EBREAK, which stop execution by design); 2 for instruction-limit exit.

Runtime contract

• Static ELF32 little-endian RISC-V (ET_EXEC, EM_RISCV), PT_LOAD segments mapped at p_paddr with BSS zero-fill; entry = ELF entry point.
• RAM at 0x80000000 (default 16 MiB, configurable); UART TX byte at 0x10000000.
• Byte store to UART transmits; byte load returns 0; wider MMIO traps.
• ECALL/EBREAK halt with a reported trap (no guest handler yet).
• Single-threaded, no CSRs, no floating-point/atomics/compressed/M-extension.

See docs/ for the ISA list, memory map, CLI details, limitations, and compatibility matrix.