xref: /cloud-hypervisor/docs/riscv.md (revision 226ecf47bb608d52367de61236fb8ad37b871ca2) 
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## Known limitations
84
85- Direct kernel boot only
86- `64-bit Linux` guest OS only
87- For more details, see
88  [here](https://github.com/cloud-hypervisor/cloud-hypervisor/issues/6978).
89