GitPedia

Rv32emu

Compact and Efficient RISC-V RV32I[MAFC] emulator

From sysprog21·Updated June 12, 2026·View on GitHub·

`rv32emu` is an emulator for the 32 bit [RISC-V processor model](https://riscv.org/technical/specifications/) (RV32), faithfully implementing the RISC-V instruction set architecture (ISA). It serves as an exercise in modeling a modern RISC-based processor, demonstrating the device's operations without the complexities of a hardware implementation. The code is designed to be accessible and expandable, making it an ideal educational tool and starting point for customization. It is primarily writte... The project is written primarily in C, distributed under the MIT License license, first published in 2020. Key topics include: bare-metal, elf-parser, emulator, gdbstub, instruction-set-simulator.

Latest release: v1.2
January 31, 2026View Changelog →

RISC-V RV32I[MAFC] emulator

GitHub Actions

                       /--===============------\
      ______     __    | |⎺⎺⎺⎺⎺⎺⎺⎺⎺⎺⎺⎺⎺⎺⎺|     |
     |  _ \ \   / /    | |               |     |
     | |_) \ \ / /     | |   Emulator!   |     |
     |  _ < \ V /      | |               |     |
     |_| \_\ \_/       | |_______________|     |
      _________        |                   ::::|
     |___ /___ \       '======================='
       |_ \ __) |      //-'-'-'-'-'-'-'-'-'-'-\\
      ___) / __/      //_'_'_'_'_'_'_'_'_'_'_'_\\
     |____/_____|     [-------------------------]

rv32emu is an emulator for the 32 bit RISC-V processor model (RV32),
faithfully implementing the RISC-V instruction set architecture (ISA).
It serves as an exercise in modeling a modern RISC-based processor, demonstrating
the device's operations without the complexities of a hardware implementation.
The code is designed to be accessible and expandable, making it an ideal educational
tool and starting point for customization. It is primarily written in C99, utilizing
C11 atomics for memory management, with a focus on efficiency and readability.

Features:

  • Fast interpreter that faithfully executes the complete RV32 instruction set
  • Full coverage of RV32I / RV32E plus the M (integer multiply–divide), A (atomics), F (single-precision floating-point), C (compressed), and Zba/Zbb/Zbc/Zbs bit-manipulation extensions
  • Partial support for the V (vector) extension — decode plus partial execution at VLEN=128; opt-in via make config (select "V — Vector Extension")
  • Built-in ELF loader for user-mode emulation
  • Newlib-compatible system-call layer for standalone programs
  • Minimal system emulation capable of booting an RV32 Linux kernel and running user-space binaries
  • SDL-based display/event/audio system calls for running video games
  • WebAssembly build for user-mode and system emulation with SDL graphics and audio in modern browsers
  • Remote debugging through the GDB Remote Serial Protocol
  • Tiered JIT compilation for performance boost while maintaining a small footprint

Quick start

rv32emu relies on the SDL2 library and
SDL2_Mixer library for full
functionality:

  • macOS: brew install sdl2 sdl2_mixer
  • Ubuntu Linux / Debian: sudo apt install libsdl2-dev libsdl2-mixer-dev

Build and verify:

shell
$ make defconfig      # Apply default configuration
$ make                # Build rv32emu
$ make check          # Run tests

Run the included demos:

shell
$ make doom           # Doom (1993)
$ make quake          # Quake (requires RV32F, on by default)

For interactive build configuration, use make config. For predefined
configurations, Kconfig options, and tiered JIT compilation setup
(LLVM toolchain), see docs/build.md.

Online demo

A hosted WebAssembly build of rv32emu runs entirely in the browser, so
you can try it without building locally:

The landing page links to both modes, and each mode page has a navigation
button that switches directly to the other.

Documentation

TopicDocument
Build options, Kconfig, and tiered JIT setupdocs/build.md
System emulation: boot Linux, virtio block devices, bootargsdocs/system.md
WebAssembly build for the browserdocs/wasm.md
GDB remote debugging and register JSON dumpdocs/gdbstub.md
RISCOF / RISC-V architecture testsdocs/riscof.md
Benchmarks and continuous benchmarkingdocs/benchmark.md
Static analysis tools (rv_histogram, rv_profiler)docs/tools.md
Docker imagedocs/docker.md
Demo applications (Doom, Quake)docs/demo.md
Code generation and JIT internalsdocs/codegen.md
RISC-V instruction referencedocs/instruction.md
Newlib system callsdocs/syscall.md
Prebuilt binariesdocs/prebuilt.md
Base image preparationdocs/base-image.md

Contributing

See CONTRIBUTING.md for contribution guidelines.

Citation

Please see our VMIL'24 paper, available in the ACM digital library.

@inproceedings{ncku2024accelerate,
  title={Accelerate {RISC-V} Instruction Set Simulation by Tiered {JIT} Compilation},
  author={Chen, Yen-Fu and Chen, Meng-Hung and Huang, Ching-Chun and Tu, Chia-Heng},
  booktitle={Proceedings of the 16th ACM SIGPLAN International Workshop on Virtual Machines and Intermediate Languages},
  pages={12--22},
  year={2024}
}

License

rv32emu is available under a permissive MIT-style license.
Use of this source code is governed by a MIT license that can be found in the LICENSE file.

External sources

See docs/prebuilt.md.

Reference

Contributors

Showing top 12 contributors by commit count.

jserv

jserv

974 commits

ChinYikMing

ChinYikMing

164 commits

visitorckw

visitorckw

85 commits

qwe661234

qwe661234

66 commits

vacantron

vacantron

64 commits

eleanorLYJ

eleanorLYJ

46 commits

henrybear327

henrybear327

24 commits

RinHizakura

RinHizakura

19 commits

alanjian85

alanjian85

16 commits

Risheng1128

Risheng1128

13 commits

TheCloudlet

TheCloudlet

10 commits

2011eric

2011eric

9 commits

View all contributors on GitHub →

This article is auto-generated from sysprog21/rv32emu via the GitHub API.Last fetched: 6/16/2026