= Prerequistites =

To boot a RISC-V virtual machine you will need the following packages:

 * qemu-system-misc - QEMU is used to emulate a virtual RISC-V machine.
 * u-boot-qemu - U-Boot is the firmware implementing the UEFI API and loads GRUB.

{{{
sudo apt-get update
sudo apt-get install opensbi qemu-system-misc u-boot-qemu
}}}

'''For booting Ubuntu 22.04 (Jammy) or later images use u-boot-qemu from release Ubuntu 22.04 or later.'''

= Booting a preinstalled server image with QEMU =

A preinstalled server image can be downloaded from https://cdimage.ubuntu.com/releases/24.04/release/.

First unpack the image

{{{
xz -dk ubuntu-24.04-preinstalled-server-riscv64.img.xz
}}}
(Up to Ubuntu 22.04. use the image for the [[RISC-V/SiFive HiFive Unmatched|SiFive HiFive Unmatched]] board, e.g. 'ubuntu-22.04.3-preinstalled-server-riscv64+unmatched.img'.)

Optionally, if you want a larger disk, you can expand the disk (the filesystem will be automatically resized too).

{{{
qemu-img resize -f raw ubuntu-24.04-preinstalled-server-riscv64.img +5G
}}}

Next use u-boot-qemu to boot the virtual machine. A working example with all the options is:

{{{
qemu-system-riscv64 \
-machine virt -nographic -m 2048 -smp 4 \
-bios /usr/lib/riscv64-linux-gnu/opensbi/generic/fw_jump.bin \
-kernel /usr/lib/u-boot/qemu-riscv64_smode/uboot.elf \
-device virtio-net-device,netdev=eth0 -netdev user,id=eth0 \
-device virtio-rng-pci \
-drive file=ubuntu-24.04-preinstalled-server-riscv64.img,format=raw,if=virtio
}}}

The important options to use are:

 * QEMU's generic virtual platform is selected by `-machine virt`
 * The first stage firmware booted by QEMU is OpenSBI as specified by the `-bios` option. This option is not needed with QEMU 7.0 or higher. It cannot be used with KVM.
 * The second stage firmware U-Boot is loaded into memory via `-kernel /usr/lib/u-boot/qemu-riscv64_smode/uboot.elf`

One can use pass through networking, adjust memory (`-m`) & cpu counts (`-smp`) as needed.

Watch the serial console output and wait for cloud-init to complete. It will show a line with the text 'Cloud-init finished' like:

{{{
[   68.346028] cloud-init[703]: Cloud-init v. 22.2-0ubuntu1~20.04.3 finished at Thu, 22 Sep 2022 11:35:28 +0000. Datasource DataSourceNoCloud [seed=/var/lib/cloud/seed/nocloud-net][dsmode=net].  Up 68.26 seconds
}}}

Then login using `ubuntu:ubuntu`. See the cloud-init section below to further customise the first boot behaviour with cloud-init.

== cloud-init integration ==

The image has a fallback cloud-init datasource that configures sudo user `ubuntu` with password `ubuntu` and DHCP networking. You will be asked to change the password on first login.

The image has `CIDATA` partition which can be used as a valid datasource to adjust cloud-config metadata. If you wish to customize user password, networking information, add ssh keys, etc. Please mount `CIDATA` partition rename `meta-data` and `user-data` files and adjust them to taste. You can use network-info to configure networking if something more sophisticated than just DHCP is desired.

For example ssh keys, disabling interactive login, and so on. See https://cloudinit.readthedocs.io/en/latest

= Ubuntu installation of a RISC-V virtual machine using a server install image and QEMU =

== Overview ==

Starting with Ubuntu 22.04 a server install image for QEMU is available. This topic describes how to use the image for an installation on a virtual machine.

The Jammy release image is available at https://cdimage.ubuntu.com/releases/22.04.3/release/.

Daily build images are provided at https://cdimage.ubuntu.com/ubuntu-server/daily-live/current/.

A general overview of the installation process is available at https://ubuntu.com/tutorials/install-ubuntu-server.

Download the image either using your web browser or with

{{{
wget https://cdimage.ubuntu.com/ubuntu-server/daily-live/current/<release>-live-server-riscv64.img.gz 
}}}

== Installation ==

Extract the image.

{{{
gzip -d jammy-live-server-riscv64.img.gz
}}}


Create the disk image on which you will install Ubuntu. 16 GiB should be enough.

{{{
dd if=/dev/zero bs=1M of=disk count=1 seek=16383
}}}


Start the installer with:

{{{
/usr/bin/qemu-system-riscv64 -machine virt -m 4G -smp cpus=2 -nographic \
    -bios /usr/lib/riscv64-linux-gnu/opensbi/generic/fw_jump.bin \
    -kernel /usr/lib/u-boot/qemu-riscv64_smode/u-boot.bin \
    -netdev user,id=net0 \
    -device virtio-net-device,netdev=net0 \
    -drive file=noble-live-server-riscv64.img,format=raw,if=virtio \
    -drive file=disk,format=raw,if=virtio \
    -device virtio-rng-pci
}}}


Follow the installation steps in https://ubuntu.com/tutorials/install-ubuntu-server.

When rebooting we have to remove the installer image. Otherwise the installer will restart.

U-Boot gives you a 2 second time window to press the Enter key to reach the U-Boot console. In U-Boot’s console you can use the poweroff command to stop QEMU. Another option to exit QEMU is pressing keys CTRL-a followed by key x.

== Run Ubuntu ==

To run your installed Ubuntu image use

{{{
/usr/bin/qemu-system-riscv64 -machine virt -m 4G -smp cpus=2 -nographic \
    -bios /usr/lib/riscv64-linux-gnu/opensbi/generic/fw_jump.bin \
    -kernel /usr/lib/u-boot/qemu-riscv64_smode/u-boot.bin \
    -netdev user,id=net0 \
    -device virtio-net-device,netdev=net0 \
    -drive file=disk,format=raw,if=virtio \
    -device virtio-rng-pci
}}}

= Limitations =

In Ubuntu 22.04 the number of virtual CPUs is limited to 8 in QEMU and in the Linux kernel.