/--===============------\
      ______     __    | |⎺⎺⎺⎺⎺⎺⎺⎺⎺⎺⎺⎺⎺⎺⎺|     |
     |  _ \ \   / /    | |               |     |
     | |_) \ \ / /     | |   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, with a focus on efficiency and readability.

Features:

• Fast interpreter for executing the RV32 ISA
• Comprehensive support for RV32I and M, A, C extensions
• Partial support for the F extension
• Memory-efficient design
• Built-in ELF loader
• Implementation of commonly used newlib system calls
• Experimental SDL-based display/event system calls for running video games
• Support for remote GDB debugging

rv32emu relies on certain third-party packages for full functionality and access to all its features. To ensure proper operation, the target system should have the SDL2 library installed.

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

Install RISCOF.

python3 -m pip install git+https://github.com/riscv/riscof

Build the emulator.

make

Run sample RV32I[M] programs:

make check

Run Doom, the classical video game, via rv32emu:

make doom

The build script will then download data file for Doom automatically. When Doom is loaded and run, an SDL2-based window ought to appear.

If RV32F support is enabled (turned on by default), Quake demo program can be launched via:

make quake

The usage and limitations of Doom and Quake demo are listed in docs/demo.md.

RISCOF - RISC-V Compatibility Framework is a python based framework which enables testing of RISC-V target against a golden reference model.

The RISC-V Architectural Tests, also known as riscv-arch-test, provides the fundamental set of tests that can be used to confirm that the behavior of the risc-v model adheres to the RISC-V standards while executing certain applications. (not intended to replace thorough design verification)

There are reference signatures that generated by the formal RISC-V model RISC-V SAIL in the Executable and Linkable Format (ELF) files. ELF files that have multiple testing instructions, data, and signatures, like cadd-01.elf. The specific data places that must be written by the testing model (this emulator) throughout the test are known as test signatures. The test signatures will be written after it has been completed, and they will be compared to the reference signature. When both signatures exactly match, the test is successful.

RISC-V GNU Compiler Toolchain should be prepared in advance. You can obtain prebuilt GNU toolchain for riscv32-elf via Automated Nightly Release. Then, run the following command:

make arch-test

Users of macOS might need to install sdiff first.

brew install diffutils

To run the tests for specific extension, set the environmental variable RISCV_DEVICE to one of I, M, C, Zifencei, privilege.

make arch-test RISCV_DEVICE=I

Current progress of this emulator in riscv-arch-test (RV32):

• Passed Tests
  • I: Base Integer Instruction Set
  • M: Standard Extension for Integer Multiplication and Division
  • C: Standard Extension for Compressed Instruction
  • Zifencei: Instruction-Fetch Fence
  • privilege: RISCV Privileged Specification
• Unsupported tests (runnable but incomplete)
  • F Standard Extension for Single-Precision Floating-Point

Detail in riscv-arch-test:

• RISCOF document
• riscv-arch-test repository
• RISC-V Architectural Testing Framework
• RISC-V Architecture Test Format Specification

rv32emu is configurable, and you can override the below variable(s) to fit your expectations:

• ENABLE_EXT_M: Standard Extension for Integer Multiplication and Division
• ENABLE_EXT_A: Standard Extension for Atomic Instructions
• ENABLE_EXT_C: Standard Extension for Compressed Instructions (RV32C.F excluded)
• ENABLE_EXT_F: Standard Extension for Single-Precision Floating Point Instructions
• ENABLE_Zicsr: Control and Status Register (CSR)
• ENABLE_Zifencei: Instruction-Fetch Fence
• ENABLE_GDBSTUB : GDB remote debugging support
• ENABLE_SDL : Experimental Display and Event System Calls

e.g., run make ENABLE_EXT_F=0 for the build without floating-point support.

rv32emu is permitted to operate as gdbstub in an experimental manner since it supports a limited number of GDB Remote Serial Protocol (GDBRSP). You must first build the emulator and set ENABLE_GDBSTUB to 1 in the Makefile in order to activate this feature. After that, you might execute it using the command below.

build/rv32emu --gdbstub <binary>

The <binary> should be the ELF file in RISC-V 32 bit format. Additionally, it is advised that you compile programs with the -g option in order to produce debug information in your ELF files.

You can run riscv-gdb if the emulator starts up correctly without an error. It takes two GDB commands to connect to the emulator after giving GDB the supported architecture of the emulator and any debugging symbols it may have.

$ riscv32-unknown-elf-gdb
(gdb) file <binary>
(gdb) target remote :1234

Congratulate yourself if riscv-gdb does not produce an error message. Now that the GDB command line is available, you can communicate with rv32emu.

If an option --dump-registers [filename] is specified, the emulator outputs registers as JSON format. This can be used for tests using the emulator, such as compiler tests.

You can use the option with --quiet to use the output directly.

# Read the register x10 (a0).
$ build/rv32emu --dump-registers - out.elf --quiet | jq .x10

See CONTRIBUTING.md for contribution guidelines.

In rv32emu repository, there are some prebuilt ELF files for testing purpose.

• aes.elf : See tests/aes.c
• captcha.elf : See tests/captcha.c
• cc.elf : See tests/cc
• chacha20.elf : See tests/chacha20
• coremark.elf : See eembc/coremark [RV32M]
• dhrystone.elf : See rv8-bench
• doom.elf : See sysprog21/doom_riscv [RV32M]
• ieee754.elf : See tests/ieee754.c [RV32F]
• jit-bf.elf : See ezaki-k/xkon_beta
• lena.elf: See tests/lena.c
• line.elf : See tests/line.c [RV32M]
• maj2random.elf : See tests/maj2random.c [RV32F]
• mandelbrot.elf : See tests/mandelbrot.c
• nqueens.elf : See tests/nqueens.c
• nyancat.elf : See tests/nyancat.c
• pi.elf : See tests/pi.c [RV32M]
• qrcode.elf : See tests/qrcode.c
• quake.elf : See sysprog21/quake-embedded [RV32F]
• readelf.elf : See tests/readelf
• richards.elf : See tests/richards.c
• rvsim.elf : See tests/rvsim.c
• scimark2.elf : See tests/scimark2 [RV32MF]
• stream.elf : See tests/stream [RV32MF]

• Writing a simple RISC-V emulator in plain C
• Writing a RISC-V Emulator in Rust
• Juraj's RISC-V note
• libriscv: RISC-V userspace emulator library
• GUI-VP: RISC-V based Virtual Prototype (VP) for graphical application development
• LupV: an education-friendly RISC-V based system emulator
• yutongshen/RISC-V-Simulator
• mini-rv32ima / video: Writing a Really Tiny RISC-V Emulator
• RVVM

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.