RISC-V RV32I[MAC] emulator with ELF support

rv32emu is an instruction set architecture (ISA) emulator implementing the 32 bit RISC-V processor model.

Build and Verify

rv32emu relies on some 3rd party packages to be fully usable and to provide you full access to all of its features. You need to have a working SDL2 library on your target system.

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

Build the emulator.

make

Run sample RV32I[MA] programs:

make check

Run Doom, the classical video game, via rv32emu:

make demo

The build script will then download data file for Doom automatically. SDL2 based window should appear when Doom is loaded and executed.

riscv-arch-test

The RISC-V Architectural Tests, riscv-arch-test, is the basic set of tests that can ensure the risc-v model's behavior that matches RISC-V specifications while implementing specific software.(not a substitute for rigorous design verification)

There are reference signatures that generated by the formal RISC-V model RISC-V SAIL and the Executable and Linkable Format(ELF) files. The ELF files such as cadd-01.elf that contain several testing instructions, data, and signatures. The test signatures are the specific data locations that need to be written by testing model(this emulator) during the test. Once the test is executed, the test signatures will be written and compared to the reference signature. The test will pass if both signatures exactly match.

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

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

To run a specific test case,set both RISCV_DEVICE and RISCV_TEST.For example:

make arch-test RISCV_DEVICE=M RISCV_TEST=div-01

The details about the setup environment variables can be found in the RISC-V Architectural Testing Framework, 5.1 Setup environment variables.

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
- Zifencei: Instruction-Fetch Fence
Failed Tests
- C: Standard Extension for Compressed Instruction
  - cebreak
- privilege: RISCV Privileged Specification
  - 2 system calls
    - ebreak
    - ecall
  - 5 misaligned CB-type instructions
    - misalign-beq
    - misalign-bge
    - misalign-bgeu
    - misalign-blt
    - misalign-bltu
  - 1 misaligned CL-type instructions
    - misalign-lw
  - 1 misaligned CS-type instructions
    - misalign-sw
Unsupported tests
- F Standard Extension for Single-Precision Floating-Point

Detail in riscv-arch-test:

Customization

rv32emu is configurable, and you can modify Makefile to fit your expectations:

ENABLE_RV32M: Standard Extension for Integer Multiplication and Division
ENABLE_RV32A: Standard Extension for Atomic Instructions
ENABLE_RV32C: Standard Extension for Compressed Instructions (RV32C.F excluded)
Zicsr: Control and Status Register (CSR)
Zifencei: Instruction-Fetch Fence

Add -D to enable and -U to disable the specific ISA extensions.

Reference

libriscv: RISC-V userspace emulator library

License