This page describes the steps necessary to get Fedora for RISC-V running, either on emulated or real hardware.
Obtain a disk image
Tested images
These images have undergone some testing and thus are more likely to work without issues. If you are not sure which image to choose, go with one of these.
Download using virt-builder
This is the recommended way to obtain disk images.
Before you can start using virt-builder
for this task, a one-time setup is necessary:
$ mkdir -p ~/.config/virt-builder/repos.d/ $ cat <<EOF >~/.config/virt-builder/repos.d/fedora-riscv.conf [fedora-riscv] uri=https://dl.fedoraproject.org/pub/alt/risc-v/repo/virt-builder-images/images/index EOF
With that out of the way, you can get a list of available RISC-V templates with:
$ virt-builder --list | grep riscv64 fedora-rawhide-developer-20191123.n.0 riscv64 Fedora® Rawhide Developer 20191123.n.0 fedora-rawhide-minimal-20191123.n.1 riscv64 Fedora® Rawhide Minimal 20191123.n.1
Then tell virt-builder
to build a custom disk image based on one of the templates:
$ virt-builder \ --arch riscv64 \ --size 20G \ --format raw \ --output Fedora-Developer-Rawhide-20191123.n.0-sda.raw \ fedora-rawhide-developer-20191123.n.0 [ 3.6] Downloading: https://dl.fedoraproject.org/pub/alt/risc-v/repo/virt-builder-images/images/Fedora-Developer-Rawhide-20191123.n.0-sda.raw.xz [ 6.1] Planning how to build this image [ 6.1] Uncompressing [ 32.8] Opening the new disk [ 38.4] Setting a random seed [ 38.4] Setting the machine ID in /etc/machine-id [ 38.4] Setting passwords virt-builder: Setting random password of root to 5PegnZtGMP47bXnw [ 39.9] Finishing off Output file: Fedora-Developer-Rawhide-20191123.n.0-sda.raw Output size: 20.0G Output format: raw Total usable space: 19.7G Free space: 14.7G (75%)
virt-builder
has reasonable defaults, such as generating a random root password for you, but if you want more control you can pass additional arguments to customize the image further: for example, using --format qcow2
will cause the output image to be in QCOW2 format. See virt-builder --help
for more information.
In addition to the disk image, a firmware image (which has to be downloaded separately) is needed as well. To find out the download URL, use:
$ virt-builder --arch riscv64 --notes fedora-rawhide-developer-20191123.n.0 | grep fw_payload https://dl.fedoraproject.org/pub/alt/risc-v/repo/virt-builder-images/images/Fedora-Developer-Rawhide-20191123.n.0-fw_payload-uboot-qemu-virt-smode.elf https://dl.fedoraproject.org/pub/alt/risc-v/repo/virt-builder-images/images/Fedora-Developer-Rawhide-20191123.n.0-fw_payload-uboot-qemu-virt-smode.elf.CHECKSUM
Then download it using your favorite HTTP client, for example:
$ wget https://dl.fedoraproject.org/pub/alt/risc-v/repo/virt-builder-images/images/Fedora-Developer-Rawhide-20191123.n.0-fw_payload-uboot-qemu-virt-smode.elf
Download manually
If using virt-builder
is not an option, you can download disk images manually from: https://dl.fedoraproject.org/pub/alt/risc-v/repo/virt-builder-images/images/
Download Fedora-Developer-Rawhide-*.raw.xz
as well as the matching Fedora-Developer-Rawhide-*-fw_payload-uboot-qemu-virt-smode.elf
.
Nightly builds
You can find them here: http://fedora.riscv.rocks/koji/tasks?state=closed&view=flat&method=createAppliance&order=-id
Select the most recent (top) build and download Fedora-Developer-Rawhide-*.raw.xz
.
These disk images differ from the ones above in that:
- the firmware is inside the disk image, in the
/boot
directory; - they are completely untested.
Prepare the disk image
These steps are only necessary if you haven't used virt-builder
.
Uncompress the image
Whether you have downloaded a tested image or a nightly build, you'll need to uncompress it before it can be used:
$ unxz Fedora-Developer-Rawhide-*.raw.xz
Optional: expand the disk image
You might want to expand the disk image before setting up the VM. Here is one example:
$ truncate -r Fedora-Developer-Rawhide-*.raw expanded.raw $ truncate -s 40G expanded.raw $ virt-resize -v -x --expand /dev/sda4 Fedora-Developer-Rawhide-*.raw expanded.raw $ virt-filesystems --long -h --all -a expanded.raw $ virt-df -h -a expanded.raw
The resulting disk image will work with QEMU as well as TinyEMU. Make sure you use expanded.raw
instead of Fedora-Developer-Rawhide-*.raw
when booting the guest.
Optional: create an overlay
You can also create qcow2
disk image with raw
Fedora disk as backing one. This way Fedora raw
is unmodified and all changes are written to qcow2
layer. You will need to install libguestfs-tools-c
.
$ qemu-img create -f qcow2 -F raw -b Fedora-Developer-Rawhide-*.raw overlay.qcow2 20G $ virt-resize -v -x --expand /dev/sda4 Fedora-Developer-Rawhide-*.raw overlay.qcow2 $ virt-filesystems --long -h --all -a overlay.qcow2
The resulting disk image will only work with QEMU. Make sure you use overlay.qcow2
instead of Fedora-Developer-Rawhide-*.raw
when booting the guest.
Optional: set the hostname before booting
If you want to change hostname before the first boot, install libguestfs-tools-c
and then run:
$ virt-customize -a Fedora-Developer-Rawhide-*.raw --hostname fedora-riscv-mymagicbox
Nightly builds only: extracting firmware (OpenSBI)
Fedora/RISC-V does not support BLS (Boot Loader Specification - more details).
Disk images contain a /boot
directory from where you can copy out the firmware.
This is only necessary for nightly builds, since for tested images these files are provided as separate downloads alongside the image.
Example session:
$ guestfish \ add Fedora-Developer-Rawhide-*.raw : \ run : \ mount /dev/sda1 / : \ ls /opensbi/unstable fw_jump.elf fw_payload-5.2.0-0.rc7.git0.1.0.riscv64.fc31.riscv64.elf fw_payload-uboot-qemu-virt-smode.elf $ guestfish \ add Fedora-Developer-Rawhide-*.raw : run : mount /dev/sda1 / : \ download /opensbi/unstable/fw_payload-uboot-qemu-virt-smode.elf fw_payload-uboot-qemu-virt-smode.elf
You can also use guestmount
or QEMU/NBD to mount disk image. Examples:
$ mkdir a $ guestmount -a $PWD/Fedora-Developer-Rawhide-*.raw -m /dev/sda1 $PWD/a $ cp a/opensbi/unstable/fw_payload-uboot-qemu-virt-smode.elf . $ guestunmount $PWD/a
$ sudo modprobe nbd max_part=8 $ sudo qemu-nbd -f raw --connect=/dev/nbd1 $PWD/Fedora-Developer-Rawhide-*.raw $ sudo fdisk -l /dev/nbd1 Disk /dev/nbd1: 7.5 GiB, 8053063680 bytes, 15728640 sectors Units: sectors of 1 * 512 = 512 bytes Sector size (logical/physical): 512 bytes / 512 bytes I/O size (minimum/optimal): 512 bytes / 512 bytes Disklabel type: gpt Disk identifier: F0F4268F-1B73-46FF-BABA-D87F075DCCA5 Device Start End Sectors Size Type /dev/nbd1p1 2048 15001599 14999552 7.2G Linux filesystem $ sudo mount /dev/nbd1p1 a $ sudo cp a/opensbi/unstable/fw_payload-uboot-qemu-virt-smode.elf . $ sudo umount a $ sudo qemu-nbd --disconnect /dev/nbd1
Note NBD is highly useful if you need to run fdisk
, e2fsck
(e.g. after VM crash and filesystem lock up), resize2fs
. It might be beneficial to look into nbdkit
and nbd
packages.
Boot the image on virtual hardware
There are several options for booting the image on virtual hardware once you've prepared it following the steps above.
Boot with libvirt
Detailed instructions how to install libvirt: https://docs.fedoraproject.org/en-US/quick-docs/getting-started-with-virtualization/
Quick instructions for libvirt installation (tested on Fedora 30):
# dnf group install --with-optional virtualization # systemctl enable --now libvirtd
When running RISC-V guests, it's usually a good idea to use the very latest versions of QEMU, libvirt and virt-manager: the virt-preview
repository offers just that for Fedora users. To enable it, simply run:
# dnf copr enable @virtmaint-sig/virt-preview
and update your system.
The steps below assume you have copied both the disk image and the firmware into /var/lib/libvirt/images
: this is the location where libvirt usually expects to find disk images, so while using a different location might work it's a good idea to do this and reduce the possibility of issues caused by filesystem permissions and such.
Assuming you have QEMU ≥ 4.0.0, libvirt ≥ 5.3.0 and virt-manager ≥ 2.2.0, the installation will be as simple as:
# virt-install \ --name fedora-riscv \ --arch riscv64 \ --vcpus 8 \ --memory 2048 \ --os-variant fedora30 \ --boot kernel=/var/lib/libvirt/images/Fedora-Developer-Rawhide-*-fw_payload-uboot-qemu-virt-smode.elf \ --import --disk path=/var/lib/libvirt/images/Fedora-Developer-Rawhide-*.raw \ --network network=default \ --graphics none
If you are stuck with older software (QEMU ≥ 2.12.0, libvirt ≥ 4.7.0), then you're going to need a more verbose command line:
# virt-install \ --name fedora-riscv \ --arch riscv64 \ --machine virt \ --vcpus 8 \ --memory 2048 \ --os-variant fedora30 \ --boot kernel=/var/lib/libvirt/images/Fedora-Developer-Rawhide-*-fw_payload-uboot-qemu-virt-smode.elf \ --import --disk path=/var/lib/libvirt/images/Fedora-Developer-Rawhide-*.raw,bus=virtio \ --network network=default,model=virtio \ --rng device=/dev/urandom,model=virtio \ --channel name=org.qemu.guest_agent.0 \ --graphics none
Additionally, when using older software components you won't get PCI support, and so enabling graphics will not be possible.
Either one of the commands above will automatically boot you into the console. If you don't want that add --noautoconsole
option. You can later use virsh
tool to manage your VM and get to console.
A quick reference of virsh
commands:
virsh list --all
- list all VMs and their statesvirsh console <name>
- connect to serial console (remember:Escape character is ^]
)virsh shutdown <name>
- power down VM (see above for more details)virsh start <name>
- power up VMvirsh undefine <name>
- remove VMvirsh net-list
- list network (useful for the next command)virsh net-dhcp-leases <network_name>
- list DHCP leases,<network_name>
most likely will bedefault
. This is useful when you want to get IPv4 and SSH to the VM.virsh domifaddr <name>
- alternative for the above two commands, only shows IPv4 for one VMvirsh reset <name>
- hard reset VMvirsh destroy <name>
hard power down of VM
If you want to use ssh user@virtualMachine
you can setup libvirt NSS module. See: https://wiki.libvirt.org/page/NSS_module
You might want also to setup logging for serial console (in case kernel panics or something else).
For this we will be using two commands: virsh edit <name>
(modifying VM XML) and virsh dumpxml <name>
(dump VM XML for backup). You need to modify <serial>
node by adding <log file='/var/log/libvirt/qemu/fedora-riscv-mymagicbox.serial.log'/>
. Then power down and power up the VM.
Alternatively you can use --serial log.file=/.../whatever.serial.log
with virt-install
command.
Boot under QEMU
You will get the best results if your QEMU version is 4.0.0 or newer, but any version since 2.12.0 will work.
$ qemu-system-riscv64 \ -nographic \ -machine virt \ -smp 8 \ -m 2G \ -kernel Fedora-Developer-Rawhide-*-fw_payload-uboot-qemu-virt-smode.elf \ -object rng-random,filename=/dev/urandom,id=rng0 \ -device virtio-rng-device,rng=rng0 \ -device virtio-blk-device,drive=hd0 \ -drive file=Fedora-Developer-Rawhide-*.raw,format=raw,id=hd0 \ -device virtio-net-device,netdev=usernet \ -netdev user,id=usernet,hostfwd=tcp::10000-:22
Once machine is booted you can connect via SSH:
$ ssh -p 10000 -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no -o PreferredAuthentications=password -o PubkeyAuthentication=no root@localhost
Boot under TinyEMU (RISCVEMU)
Note (2019 March 10): This is not supported anymore until TinyEMU is updated to support external initrd file. Please, use QEMU or libvirt/QEMU.
RISCVEMU recently (2018-09-23) was renamed to TinyEMU (https://bellard.org/tinyemu/).
TinyEMU allow booting Fedora disk images in TUI and GUI modes. You can experiment using JSLinux (no need to download/compile/etc) here: https://bellard.org/jslinux/
Below are instructions how to boot Fedora into X11/Fluxbox GUI mode.
Step 1. Compile TinyEMU:
wget https://bellard.org/tinyemu/tinyemu-2018-09-23.tar.gz tar xvf tinyemu-2018-09-23.tar.gz cd tinyemu-2018-09-23 make
Step 2. Setup for booting Fedora:
mkdir fedora cd fedora cp ../temu . # Download pre-built BBL with embedded kernel wget https://bellard.org/jslinux/bbl64-4.15.bin # Create configuration file for TinyEMU cat <<EOF > root-riscv64.cfg /* VM configuration file */ { version: 1, machine: "riscv64", memory_size: 1400, bios: "bbl64-4.15.bin", cmdline: "loglevel=3 console=tty0 root=/dev/vda rw TZ=${TZ}", drive0: { file: "Fedora-Developer-Rawhide-*-sda1.raw" }, eth0: { driver: "user" }, display0: { device: "simplefb", width: 1920, height: 1080, }, input_device: "virtio", } EOF # Download disk image and unpack in the same directory
Step 3. Boot it.
./temu -rw root-riscv64.cfg
We need to use -rw
if we want our changes to persist in disk image. Otherwise disk image will be loaded as read-only and all changes will not persist after reboot.
Boot the image on physical hardware
Install on the HiFive Unleashed SD card
These are instructions for the HiFive Unleashed board.
The disk image (above) is partitioned, but usually we need an unpartitioned ("naked") filesystem. There are several ways to get this, but the easiest is:
$ guestfish \ add Fedora-Developer-Rawhide-*-sda.raw : \ run : \ download /dev/sda1 Fedora-Developer-Rawhide-*-sda1.raw
This creates a naked ext4 filesystem called *-sda1.raw
. The naked ext4 filesystem can be copied over the second partition of the SD card.
You can also build a custom bbl+kernel+initramfs to boot directly into the SD card using these sources.
Install on the HiFive Unleashed using NBD server
Look at https://github.com/rwmjones/fedora-riscv-kernel in the sifive_u540
branch. This is quite complex to set up so it's best to ask on the #fedora-riscv
IRC channel.
Install Fedora GNOME Desktop on SiFive HiFive Unleashed + Microsemi HiFive Unleashed Expansion board
Detailed instructions are provided by Atish Patra from Western Digital Corporation (WDC). See their GitHub page for details and pictures: https://github.com/westerndigitalcorporation/RISC-V-Linux
So far two GPUs are confirmed to be working: Radeon HD 6450 and Radeon HD 5450.
Use the image
Once the system is booted, login as root
with riscv
as password.
X11 with Fluxbox can be started using: startx /usr/bin/startfluxbox
. The disk image also includes awesome and i3 for testing. Dillo is available as a basic web browser (no javascript support) and pcmanfm as file manager.
To gracefully shutdown just type poweroff
into console.
If you want more information being displayed during boot, remove quiet
from the append
line in /boot/extlinux/extlinux.conf
.