1# How to build and test Cloud Hypervisor on riscv64 2 3This document introduces how to build and test Cloud Hypervisor on `riscv64`. 4All instructions here are tested with Ubuntu 24.04.2 as the host OS. 5 6## Hardware requirements 7 8- riscv64 servers (recommended) or development boards equipped with the AIA 9(Advance Interrupt Architecture) interrupt controller. 10 11## Getting started 12 13We create a folder to build and run Cloud Hypervisor at `$HOME/cloud-hypervisor` 14 15```console 16export CLOUDH=$HOME/cloud-hypervisor 17mkdir $CLOUDH 18``` 19 20## Prerequisites 21 22You need to install some prerequisite packages to build and test Cloud Hypervisor. 23 24### Tools 25 26```console 27# Install rust tool chain 28curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh 29# Install the tools used for building guest kernel, EDK2 and converting guest disk 30sudo apt-get update 31sudo apt-get install git build-essential m4 bison flex uuid-dev qemu-utils 32``` 33 34### Building Cloud Hypervisor 35 36```console 37pushd $CLOUDH 38git clone https://github.com/cloud-hypervisor/cloud-hypervisor.git 39cd cloud-hypervisor 40cargo build 41popd 42``` 43 44### Disk image 45 46Download the Ubuntu cloud image and convert the image type. 47 48```console 49pushd $CLOUDH 50wget https://cloud-images.ubuntu.com/jammy/current/jammy-server-cloudimg-riscv64.img 51qemu-img convert -p -f qcow2 -O raw jammy-server-cloudimg-riscv64.img jammy-server-cloudimg-riscv64.raw 52popd 53``` 54 55## Direct-kernel booting 56 57### Building kernel 58 59```console 60pushd $CLOUDH 61git clone --depth 1 "https://github.com/cloud-hypervisor/linux.git" -b ch-6.12.8 62cd linux 63make ch_defconfig 64make -j `nproc` 65popd 66``` 67 68### Booting the guest VM 69 70```console 71pushd $CLOUDH 72sudo $CLOUDH/cloud-hypervisor/target/debug/cloud-hypervisor \ 73 --kernel $CLOUDH/linux/arch/riscv64/boot/Image \ 74 --disk path=jammy-server-cloudimg-riscv64.raw \ 75 --cmdline "console=hvc0 root=/dev/vda rw" \ 76 --cpus boot=1 \ 77 --memory size=1024M \ 78 --seccomp false \ 79 --log-file boot.log -vv 80popd 81``` 82 83## Virtualized Development Setup 84 85Since there are few RISC-V development boards on the market and not 86many details about the AIA interrupt controller featured in product listings, 87QEMU is a popular and viable choice for creating a RISC-V development environment. 88Below are the steps used to create a QEMU virtual machine that can be used for 89cloud-hypervisor RISC-V development: 90 91### Install Dependencies 92 93```console 94sudo apt update 95sudo apt install opensbi qemu-system-misc u-boot-qemu 96``` 97 98### Download and Build QEMU (>=v9.2.0) 99 100Older versions of QEMU may not have support for the AIA 101interrupt controller. 102 103```console 104wget https://download.qemu.org/qemu-10.0.0.tar.xz 105tar xvJf qemu-10.0.0.tar.xz 106cd qemu-10.0.0 107./configure --target-list=riscv64-softmmu 108make -j $(nproc) 109sudo make install 110``` 111 112### Download Ubuntu Server Image 113 114At the time of writing, the best results have been seen with 115the Ubuntu 24.10 (Oracular) server image. Ex: 116 117```console 118wget https://cdimage.ubuntu.com/releases/oracular/release/ubuntu-24.10-preinstalled-server-riscv64.img.xz 119xz -dk ubuntu-24.10-preinstalled-server-riscv64.img.xz 120``` 121 122### (Optional) Resize Disk 123 124If you would like a larger disk, you can resize it now. 125 126```console 127qemu-img resize -f raw <ubuntu-image> +5G 128``` 129 130### Boot VM 131 132Note the inclusion of the AIA interrupt controller in the 133invocation. 134 135```console 136qemu-system-riscv64 \ 137 -machine virt,aia=aplic-imsic \ 138 -nographic -m 1G -smp 8 \ 139 -kernel /usr/lib/u-boot/qemu-riscv64_smode/uboot.elf \ 140 -device virtio-rng-pci \ 141 -device virtio-net-device,netdev=eth0 -netdev user,id=eth0 \ 142 -drive file=<ubuntu-image>,format=raw,if=virtio 143``` 144 145### Install KVM Kernel Module Within VM 146KVM is not enabled within the VM by default, so we must enable 147it manually. 148 149```console 150sudo modprobe kvm 151``` 152 153From this point, you can continue with the above steps from the beginning. 154 155### Sources 156 157https://risc-v-getting-started-guide.readthedocs.io/en/latest/linux-qemu.html 158 159https://canonical-ubuntu-boards.readthedocs-hosted.com/en/latest/how-to/qemu-riscv/#using-the-live-server-image 160 161https://www.qemu.org/docs/master/specs/riscv-aia.html 162 163## Known limitations 164 165- Direct kernel boot only 166- `64-bit Linux` guest OS only 167- For more details, see 168 [here](https://github.com/cloud-hypervisor/cloud-hypervisor/issues/6978). 169