qemu-system-riscv64

Boot a kernel emulating riscv64 architecture

$ qemu-system-riscv64 [[-M|-machine]] virt -bios none -kernel [kernel.elf] -nographic

$ qemu-system-riscv64 [[-M|-machine]] help

$ <Ctrl a><x>

qemu-system-riscv64 [options] [disk_image]

Examples:
qemu-system-riscv64 -M virt -cpu rv64gc -smp 4 -m 2G -kernel path/to/Image -initrd path/to/rootfs.cpio.gz -append "root=/dev/ram console=ttyS0" -nographic
qemu-system-riscv64 -M virt -bios path/to/opensbi.bin -kernel path/to/boot/u-boot.bin -hda path/to/disk.qcow2 -nographic

-M
    Specifies the emulated machine type (e.g., virt for a generic virtual machine, sifive_u for SiFive Unmatched).

-cpu
    Sets the emulated CPU type (e.g., rv64gc for a common 64-bit core with general purpose and compressed extensions, rv64imafdc_zicsr_zifencei for a more specific configuration).

-kernel
    Loads a Linux kernel image or U-Boot binary into the virtual machine's memory.

-initrd
    Specifies an initial RAM disk (initrd) image to be loaded by the kernel.

-append
    Passes command-line arguments to the guest kernel.

-smp
    Sets the number of virtual CPUs to emulate.

-m
    Allocates the specified amount of RAM to the virtual machine (e.g., 1G, 512M).

-hda , -hdb , etc.
    Attaches a virtual hard disk image (e.g., raw, qcow2). More general disk attachment is done via -drive.

-drive
    Configures a disk drive, allowing more detailed settings for interface, bus, and file format.

-nic [,options]
    Configures a virtual network interface card. Common types include user (user-mode networking, NAT) and bridge (requires host bridge setup).

-nographic
    Disables graphical output, redirecting serial console output to the host's standard output/error.

-curses
    Uses the ncurses library to provide a text-based console, allowing interactive use without a graphical display.

-bios
    Specifies a custom BIOS or firmware image to use (e.g., OpenSBI, UEFI firmware for RISC-V).

-serial [,options]
    Redirects serial port output. Can be used to connect to a pipe, file, or TCP socket for debugging.

-gdb
    Starts a GDB remote debugging server on the specified TCP port, allowing remote debugging of the guest.

-device [,property=value,...]
    Adds a specific virtual device to the machine, allowing fine-grained control over hardware components.

qemu-system-riscv64 is a specific QEMU executable designed to emulate a full RISC-V 64-bit system. QEMU (Quick Emulator) is a generic and open-source machine emulator and virtualizer. When invoked as qemu-system-riscv64, it creates a virtual RISC-V 64-bit machine, including a CPU, memory, and various peripheral devices like network cards, storage controllers, and graphics adapters.

This command is invaluable for developers working on RISC-V operating systems, firmware, or applications, allowing them to test and debug their code without needing physical RISC-V hardware. It supports booting various operating systems (e.g., Linux, FreeBSD, OpenBSD) or running bare-metal applications. While QEMU can use hardware virtualization (like KVM) for x86 guests on x86 hosts, for RISC-V emulation on non-RISC-V hosts, it performs full software emulation, which is slower but provides full control and portability.

Due to pure software emulation for RISC-V on non-RISC-V hosts, performance can be significantly slower than native execution or hardware-assisted virtualization. Configuring the correct machine type (-M) and CPU (-cpu) is crucial for compatibility with the guest operating system or firmware. Many RISC-V setups require specific firmware (like OpenSBI or U-Boot) to properly boot operating systems, which must be provided via -bios or -kernel depending on the boot chain. Debugging complex boot issues or driver problems within the emulated environment can be challenging.

When booting an operating system like Linux, you often need to chain-load components. For RISC-V, this typically involves using a small firmware like OpenSBI (Supervisor Binary Interface) provided via -bios, which then loads U-Boot (Universal Bootloader) or a Linux kernel directly. U-Boot itself might then load the Linux kernel and an initrd. The -kernel and -initrd options are convenience wrappers for directly loading a kernel/initrd, bypassing the need for a full bootloader if your kernel is compatible.

The -nic option provides flexible networking. user mode creates a NAT (Network Address Translation) setup, isolating the guest network from the host's, which is simple but limits direct inbound connections. bridge mode connects the guest's virtual network card directly to a host bridge, allowing the guest to appear as a peer on the host's network, requiring more advanced host network configuration.

While qemu-system-riscv64 uses disk images, creating and managing these images is typically done with the qemu-img utility. This separate command can create new images (e.g., qcow2 format), convert between formats, resize existing images, and check their integrity. It's an indispensable companion tool for preparing virtual disk environments.

QEMU was initially developed by Fabrice Bellard and released in 2003. Support for the RISC-V architecture was integrated into QEMU as the ISA matured and gained prominence, particularly starting around the mid-2010s. This integration involved adding specific machine models, CPU instruction set emulation, and peripheral devices tailored to the RISC-V specification. The continuous development of qemu-system-riscv64 reflects the rapid evolution of the RISC-V ecosystem, with ongoing updates to support new ISA extensions and hardware implementations, making it an essential tool for RISC-V software development and research.

qemu-system-x86_64(1), qemu-img(1), qemu-nbd(8), kvm(7)