Home

RISC-V QEMU

Welcome to the riscv-qemu wiki!

Overview

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:

• https://wiki.qemu.org/Documentation/Platforms/RISCV

Targets

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)

Features

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

Machines

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 \
    --target-list=riscv64-softmmu,riscv32-softmmu,riscv64-linux-user,riscv32-linux-user
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 \
    --target-list=riscv64-softmmu,riscv32-softmmu
make -j$(nproc)
make install

Invocation

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.

• https://github.com/michaeljclark/riscv-probe

Linux Images

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

• https://github.com/michaeljclark/busybear-linux

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

• https://fedoraproject.org/wiki/Architectures/RISC-V

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

• https://wiki.debian.org/RISC-V

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

• https://github.com/sifive/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

Development

The RISC-V QEMU port development occurs in GitHub.

Stable Branches

The following are the main branches:

• https://github.com/riscv/riscv-qemu/tree/qemu-for-upstream - patches pending merge upstream
• https://github.com/riscv/riscv-qemu/tree/qemu-for-testing - patches accepted for testing
• https://github.com/riscv/riscv-qemu/tree/riscv-all - integration branch (upstream + test)
• https://github.com/riscv/riscv-qemu/tree/riscv-qemu-3.0 - QEMU 3.0 backport branch
• https://github.com/riscv/riscv-qemu/tree/riscv-qemu-2.12 - QEMU 2.12 backport branch

Feature Branches

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

• https://github.com/michaeljclark/riscv-qemu/tree/wip-riscv-tcg-backend - RISC-V TCG backend

Issue Tracker

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

• https://github.com/riscv/riscv-qemu/issues

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.

Contributors

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