RISCVBox: A high-performance RISC-V emulator, JIT-compiled in Rust

Welcome to the RISCVBox repository! It hosts the source code for the RISC-V box emulator—a rv32ima systems emulator enabling Linux boot by translating the environment to x86_64 assembly.

RISCVBox.Demo.mp4

Table of contents

• Features
• Building
• Usage
• Building RISC-V Linux
• Testing
• Supported Platforms
• License

Features

• RV32IMASU RISC-V frontend
• x86_64 JIT backend
• SV32 MMU
• ASID aware TLB
• Peripherals:
  • PLIC
  • CLINT
  • NS16550A
  • RAMFB
  • SYSCON

Building

First, install rustup, then clone this project:

git clone https://github.com/bane9/RISCVBox.git

Inside the repository, set the compiler to the nighly version

rustup override set nightly

Then build the project

cargo b --release

This repository holds prebuilt Linux and OpenSBI binaries you can test out. To run them, do the following

cargo r --release -- --bios linux/prebuilt/fw_jump.bin --kernel linux/prebuilt/Image

Usage

Usage: RISCVBox.exe [OPTIONS] --bios <BIOS>

Options:
  -b, --bios <BIOS>      Path to BIOS (firmware) image
  -k, --kernel <KERNEL>  Path to Linux kernel image [default: ]
  -m, --memory <MEMORY>  Memory size in MiB [default: 64]
      --nographic        Disable the graphical output (only output to console)
      --width <WIDTH>    Width of the graphical output in pixels [default: 800]
      --height <HEIGHT>  Height of the graphical output in pixels [default: 600]
  -s, --scale <SCALE>    Scale factor for the graphical output (1, 2, 4, 8, 16, 32) [default: 1]
  -h, --help             Print help
  -V, --version          Print version

To quickly exit the emulator in nographic mode, press LEFT-CTRL + A, then X (just like in QEMU).

Building RISC-V Linux

This reposotory provides Buildroot configuration files to enable building of the Linux kernel and OpenSBI bootloader with configuration that are compatible with this emulator.

To utilize them, do the following (Linux only):

sudo apt install -y git build-essential wget cpio unzip rsync bc libncurses5-dev screen bison file flex

cd linux
./build.sh

The bootloader (fw_jump.bin) and the kernel (Image) will end up in linux/output folder

Testing

The emulator provides unit testing for amd64 instruction generation as well for riscv-tests.

To run the instruction unit tests, do the following:

cargo test RISCVBox

If you wan't to utlize riscv-tests, you need to build them first:

First, init the riscv-test submodule

git submodule init riscv-tests

Then, install the riscv gnu toolchain:

Linux

sudo apt install cmake gcc-riscv32-unknown-elf

Mac

brew tap riscv-software-src/riscv
brew install riscv-tools cmake

Then, build the test via:

cmake -P misc/MakeTests.cmake

Finally, execute one of them like this:

cargo test --release test_rvi

The full list is: test_rvi test_rvm test_rva test_rvmi test_rvsi

Supported platforms

Platform	Compatible	Comments
Windows amd64	✅
Ubuntu amd64	✅
MacOS amd64	❌	Compiles, but MAP_FIXED seems to be unsupported on newer MacOS'

License

This repository is under GNU GPLv3 license.

The RISC-V trade name is a registered trade mark of RISC-V International.