cloud-hypervisor/docs/riscv.md

How to build and test Cloud Hypervisor on riscv64

This document introduces how to build and test Cloud Hypervisor on riscv64. All instructions here are tested with Ubuntu 24.04.2 as the host OS.

Hardware requirements

• riscv64 servers (recommended) or development boards equipped with the AIA (Advance Interrupt Architecture) interrupt controller.

Getting started

We create a folder to build and run Cloud Hypervisor at $HOME/cloud-hypervisor

export CLOUDH=$HOME/cloud-hypervisor
mkdir $CLOUDH

Prerequisites

You need to install some prerequisite packages to build and test Cloud Hypervisor.

Tools

# Install rust tool chain
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
# Install the tools used for building guest kernel, EDK2 and converting guest disk
sudo apt-get update
sudo apt-get install git build-essential m4 bison flex uuid-dev qemu-utils

Building Cloud Hypervisor

pushd $CLOUDH
git clone https://github.com/cloud-hypervisor/cloud-hypervisor.git
cd cloud-hypervisor
cargo build
popd

Disk image

Download the Ubuntu cloud image and convert the image type.

pushd $CLOUDH
wget https://cloud-images.ubuntu.com/jammy/current/jammy-server-cloudimg-riscv64.img
qemu-img convert -p -f qcow2 -O raw jammy-server-cloudimg-riscv64.img jammy-server-cloudimg-riscv64.raw
popd

Direct-kernel booting

Building kernel

pushd $CLOUDH
git clone --depth 1 "https://github.com/cloud-hypervisor/linux.git" -b ch-6.12.8
cd linux
make ch_defconfig
make -j `nproc`
popd

Booting the guest VM

pushd $CLOUDH
sudo $CLOUDH/cloud-hypervisor/target/debug/cloud-hypervisor \
           --kernel $CLOUDH/linux/arch/riscv64/boot/Image \
           --disk path=jammy-server-cloudimg-riscv64.raw \
           --cmdline "console=hvc0 root=/dev/vda rw" \
           --cpus boot=1 \
           --memory size=1024M \
           --seccomp false \
           --log-file boot.log -vv
popd

Virtualized Development Setup

Since there are few RISC-V development boards on the market and not many details about the AIA interrupt controller featured in product listings, QEMU is a popular and viable choice for creating a RISC-V development environment. Below are the steps used to create a QEMU virtual machine that can be used for cloud-hypervisor RISC-V development:

Install Dependencies

sudo apt update
sudo apt install opensbi qemu-system-misc u-boot-qemu

Download and Build QEMU (>=v9.2.0)

Older versions of QEMU may not have support for the AIA interrupt controller.

wget https://download.qemu.org/qemu-10.0.0.tar.xz
tar xvJf qemu-10.0.0.tar.xz
cd qemu-10.0.0
./configure --target-list=riscv64-softmmu
make -j $(nproc)
sudo make install

Download Ubuntu Server Image

At the time of writing, the best results have been seen with the Ubuntu 24.10 (Oracular) server image. Ex:

wget https://cdimage.ubuntu.com/releases/oracular/release/ubuntu-24.10-preinstalled-server-riscv64.img.xz
xz -dk ubuntu-24.10-preinstalled-server-riscv64.img.xz

(Optional) Resize Disk

If you would like a larger disk, you can resize it now.

qemu-img resize -f raw <ubuntu-image> +5G

Boot VM

Note the inclusion of the AIA interrupt controller in the invocation.

qemu-system-riscv64 \
  -machine virt,aia=aplic-imsic \
  -nographic -m 1G -smp 8 \
  -kernel /usr/lib/u-boot/qemu-riscv64_smode/uboot.elf \
  -device virtio-rng-pci \
  -device virtio-net-device,netdev=eth0 -netdev user,id=eth0 \
  -drive file=<ubuntu-image>,format=raw,if=virtio

Install KVM Kernel Module Within VM

KVM is not enabled within the VM by default, so we must enable it manually.

sudo modprobe kvm

From this point, you can continue with the above steps from the beginning.

Sources

https://risc-v-getting-started-guide.readthedocs.io/en/latest/linux-qemu.html

https://canonical-ubuntu-boards.readthedocs-hosted.com/en/latest/how-to/qemu-riscv/#using-the-live-server-image

https://www.qemu.org/docs/master/specs/riscv-aia.html

Known limitations

• Direct kernel boot only
• 64-bit Linux guest OS only
• For more details, see here.