RVVM - The RISC-V Virtual Machine

RVVM is a virtual machine / emulator for RISC-V guests, which emphasizes on performance, security, lean code and portability. It already runs a lot of guest operating systems, including Linux, Haiku, FreeBSD, OpenBSD, etc. It also aims to run RISC-V applications on a foreign-arch host without full OS guest & isolation (Userland emulation).

Main features

• Fully spec-compliant rv64imafdcb instruction set, Zkr/Zicbom/Zicboz/Sstc extensions
• Tracing JIT with x86_64, ARM64, RISC-V backends - Faster than QEMU TCG
• Working OpenSBI & U-Boot, Linux, FreeBSD, OpenBSD, Haiku guests
• Framebuffer display, HID mouse & keyboard, UART terminal
• NVMe storage drives, TRIM support (Deallocate space on host), fast multi-threaded IO
• Networking userland stack (Works on any host OS)
• VFIO PCIe passthrough (For GPUs, etc)
• Kernel-level isolation to prevent and contain vulnerability exploitation
• Library API (librvvm) for machine/userland emulation, implementing new devices
• Userland emulation (WIP)
• Shadow pagetable acceleration (WIP)
• See wiki page for full list of features

📦 Installing

🛠 Building

Currently builds using GNU Make (recommended) or CMake and is extremely portable.

git clone https://github.com/LekKit/RVVM
cd RVVM
make
cd release.linux.x86_64
./rvvm_x86_64 -h

Alternatively, you can use CMake:

git clone https://github.com/LekKit/RVVM
cd RVVM
cmake -S. -Bbuild
cmake --build build --target all
cd build
./rvvm -h

See the wiki page for advanced build manual like cross-compilation.

🚀 Running

Example: Launches a dual-core VM with 2 GiB of RAM, 1280x720 display.

Runs OpenSBI + U-Boot firmware, EFI guest from drive.img. Forwards host 127.0.0.1:2022 into guest SSH port.

rvvm fw_payload.bin -i drive.img -m 2G -smp 2 -res 1280x720 -portfwd tcp/127.0.0.1:2022=22

Argument explanation:

[fw_payload.bin]    Initial M-mode firmware, OpenSBI + U-Boot in this case
-i  drive.img       Attach preferred storage image (Currently as NVMe)
-m 2G               Memory amount (may be suffixed by k/M/G), default 256M
-smp 2              Amount of cores, single-core machine by default
-res 1280x720       Set display(s) resolution
-portfwd 8080=80    Port forwarding (Extended: tcp/127.0.0.1:8080=80)
 . . .
-rv32               Enable 32-bit RISC-V, 64-bit by default
-v                  Verbose mode
-h                  Extended help

See wiki page for recommended guest firmware/images and full argument explanation.

⚖️ License

The librvvm library is licensed under non-viral MPL 2.0 license.

If you wish to use librvvm as a component of a larger, non-GPL compliant project (permissive, etc), you are free
to do so in any form (Static linkage, binary distribution, modules) as long as you comply with the MPL 2.0 license.

The RVVM Manager and Linux userland emulator (rvvm and rvvm-user) binaries are licensed under the GPL 3.0
license, since they are intended for end-users. All the heavy lifting is done by librvvm anyways.

Source file headers should be gradually fixed to reflect this.

🎉 Contributions

	Achievements	Working on
LekKit	RVVM API & infrastructure RV64IMAFDC interpreter, MMU/IRQs/Priv/etc RVJIT Compiler, X86/RISC-V backends NVMe, RTL8169, VFIO, many tiny devices Userspace network Rework of PCIe, PLIC, etc	Networking, Userspace emulation COW blk-dedup image format New CPU features & JIT optimizations
cerg2010cerg2010	Important fixes, RV64 groundwork, FPU Initial PLIC & PCI, PS2 HID, ATA, OC Ethernet ARM/ARM64 RVJIT backends	Testing, Assistance
Mr0maks	Initial C/M/Zicsr extensions, initial UART, VM debugger ARM32 mul/div JIT intrinsics	-
0xCatPKG	Userspace network & API improvements Extended testing & portability fixes	HD Audio
X547	Haiku GUI, I2C HID, Userland API assistance	Guest Haiku support, UserlandVM
iyzsong	OpenBSD & PLIC fixes, Chardev API
nebulka1	Relative input mode

🔍 TODO

• Implement Svpbmt, Svnapot extensions
• Sparse block image format with compression/deduplication
• Suspend/resume to file, VM migration
• Linux userspace binary emulation (WIP)
• USB3.0 XHCI, USB passthrough
• Sound (HD Audio or else)
• More RVJIT optimizations, shared caches
• FPU JIT (Complicated AF to make a conformant one)
• Vector extensions
• Other peripherals from real boards (VisionFive 2: GPIO, SPI, flash...)
• RISC-V APLIC, PCIe MSI Interrupts
• Virtio devices (For better QEMU interoperability; VirGL via Virtio-GPU)
• Free page reporting via virtio-balloon
• A lot more...
• KVM hypervisor? Alternative CPU engines?

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