Michael Clark edited this page Oct 8, 2018 · 36 revisions


Welcome to the riscv-qemu wiki!


The RISC-V QEMU port implements the following specifications:

  • RISC-V Instruction Set Manual Volume I: User-Level ISA Version 2.2
  • RISC-V Instruction Set Manual Volume II: Privileged ISA Version 1.9.1
  • RISC-V Instruction Set Manual Volume II: Privileged ISA Version 1.10

The RISC-V QEMU port supports the following instruction set extensions:

  • RV32GC with Supervisor-mode and User-mode (RV32IMAFDCSU)
  • RV64GC with Supervisor-mode and User-mode (RV64IMAFDCSU)

The QEMU Wiki platform page for RISC-V is here:


The RISC-V QEMU port supports the following targets:

  • riscv32-softmmu (RV32 full-system emulator)
  • riscv64-softmmu (RV64 full-system emulator)
  • riscv32-linux-user (RV32 linux user-mode emulator)
  • riscv64-linux-user (RV64 linux user-mode emulator)


The RISC-V QEMU port supports the following hardware blocks and features:

  • HTIF Console (Host Target Interface)
  • SiFive CLINT (Core Local Interruptor) for Timer interrupts and IPIs
  • SiFive PLIC (Platform Level Interrupt Controller)
  • SiFive Test (Test Finisher) for exiting simulation
  • SiFive UART, PRCI, AON, PWM, QSPI support is partially implemented
  • VirtIO MMIO (GPEX PCI support will be added in a future patch)
  • Generic 16550A UART emulation using 'hw/char/serial.c'
  • MTTCG and SMP support (PLIC and CLINT) on the 'virt' machine


The RISC-V QEMU full system emulator supports 5 machines:

  • 'spike_v1.9.1'; CLINT, PLIC, HTIF console, config-string, Priv ISA v1.9.1
  • 'spike_v1.10'; CLINT, PLIC, HTIF console, device-tree, Priv ISA v1.10
  • 'sifive_e'; CLINT, PLIC, SiFive UART, HiFive1 compat, Priv ISA v1.10
  • 'sifive_u'; CLINT, PLIC, SiFive UART, device-tree, Priv ISA v1.10
  • 'virt'; CLINT, PLIC, 16550A UART, VirtIO, device-tree, Priv ISA v1.10

Build and Install

Building the full system emulator and the user mode emulator on Linux:

git clone --recursive https://github.com/riscv/riscv-qemu.git
cd riscv-qemu
./configure \
make -j$(nproc)
make install

Building the full system emulator on macOS or other platforms:

git clone --recursive https://github.com/riscv/riscv-qemu.git
cd riscv-qemu
./configure \
make -j$(nproc)
make install


Invoking the spike machine:

qemu-system-riscv64 -nographic -machine spike_v1.10 -kernel bbl-linux-4.15

Note: this depends on bbl configured with a linux kernel plus initramfs payload.

Invoking the sifive_e machine with a HiFive1 binary:

qemu-system-riscv32 -nographic -machine sifive_e -kernel freedom-e-sdk/software/hello/hello

Note: this depends on SiFive's freedom-e-sdk examples compiled for the HiFive1.

Invoking the virt machine with virtual disk and tun/tap networking:

qemu-system-riscv64 -nographic -machine virt -kernel bbl-linux-4.15 \
    -append "root=/dev/vda ro console=ttyS0" \
    -drive file=root.bin,format=raw,id=hd0 \
    -device virtio-blk-device,drive=hd0 \
    -netdev type=tap,script=qemu-ifup,downscript=qemu-ifdown,id=net0 \
    -device virtio-net-device,netdev=net0

Note: this depends on a filesystem in root.bin as well as qemu-ifup and qemu-ifdown scripts for your platform. The invoking user also requires privileges to create the tun/tap device.

Bare Metal Examples

riscv-probe contains several bare metal examples containing code and linker scripts that build binaries for all of the riscv-qemu machines (spike, sifive_e, sifive_u and virt) for both riscv32 and riscv64, and for the Arty A7 FPGA images of SiFive's E20 and E21 Standard Cores.

Linux Images

Here are instructions for building a busybox+dropbear root image for the virt machine:

Information on the most recent Fedora images for RISC-V:

Information on the most recent Debian images for RISC-V:

Below are instructions for building riscv-qemu, riscv-linux, and a root filesystem based on buildroot using SiFive's freedom-u-sdk:

Note: When building freedom-u-sdk, make sure to unset the RISCV environment variable because buildroot needs a specific version of riscv-gnu-toolchain which is included in the freedom-u-sdk.

unset RISCV
git clone --recursive https://github.com/sifive/freedom-u-sdk.git
cd freedom-u-sdk
make qemu


The RISC-V QEMU port development occurs in GitHub.

Stable Branches

The following are the main branches:

Feature Branches

Experimental feature branches are kept in individual repos. Please add branches here.

Issue Tracker

The RISC-V QEMU port uses the GitHub Issue Tracker:

Pull Requests

Changes to the RISC-V QEMU port should go through the RISC-V QEMU port tree.

Please make pull requests in GitHub to the following branches:

  • qemu-for-upstream (well-tested features and bug fixes with Signed-off-by and Reviewed-by tags)
  • qemu-for-testing (features still under development but ready for integration testing)

Conventional Linux-style merge rules apply i.e. the RISC-V QEMU port maintainers rebase queued changes to upstream QEMU master, and likewise RISC-V port contributors rebase their changes to the RISC-V QEMU for-testing and for-upstream queues.

Note: these branches are periodically rebased to track upstream, add review feedback and sign-off's required by upstream QEMU, and thus commit ids can change. These branches are where changes are staged/curated and tested before being submitted upstream. These working branches are provided as a courtesy. Consumers of the RISC-V port that wish to branch from stable commit ids should use the versioned backport branches, otherwise be prepared to cherry-pick changes.


This is a list of RISC-V QEMU Port Contributors:

  • Alex Suykov
  • Alistair Francis
  • Andreas Schwab
  • Antony Pavlov
  • Bastian Koppelmann
  • Bruce Hoult
  • Chih-Min Chao
  • Daire McNamara
  • Darius Rad
  • David Abdurachmanov
  • Hesham Almatary
  • Ivan Griffin
  • Jim Wilson
  • Kito Cheng
  • Michael Clark
  • Palmer Dabbelt
  • Richard Henderson
  • Sagar Karandikar
  • Shea Levy
  • Stefan O'Rear
Clone this wiki locally
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.