From Fedora Project Wiki
(Use IP address for link until we can fix certificate issues.)
m (Added info about where to get virt-builder)
(19 intermediate revisions by 4 users not shown)
Line 1: Line 1:
= Download the latest disk image =
This page describes the steps necessary to get Fedora for RISC-V running, either on emulated or real hardware.


<!-- http://fedora-riscv.tranquillity.se/koji/tasks?state=closed&view=flat&method=createAppliance&order=-id -->
= Obtain a disk image =
Go [http://185.97.32.145/koji/tasks?state=closed&view=flat&method=createAppliance&order=-id to this link for the nightly builds] and select the most recent (top) build.  Look for the <code>-sda.raw.xz</code> file and download it.  It will usually be quite large, around 200-300 MB.


Uncompress it:
== 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.
 
To install <code>virt-builder</code>, run <code>dnf install libguestfs-tools-c</code>.
 
Before you can start using <code>virt-builder</code> for this task, a one-time setup is necessary:


<pre>
<pre>
$ unxz Fedora-Developer-Rawhide-xxxx.n.0-sda.raw.xz
$ 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
</pre>
</pre>


== Root password ==
With that out of the way, you can get a list of available RISC-V templates with:


<code>riscv</code>
<pre>
$ 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
</pre>


= Boot under TinyEMU (RISCVEMU) =
Then tell <code>virt-builder</code> to build a custom disk image based on one of the templates:
 
<pre>
$ 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%)
</pre>


RISCVEMU recently (2018-09-23) was renamed to TinyEMU (https://bellard.org/tinyemu/).
<code>virt-builder</code> 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 <code>--format qcow2</code> will cause the output image to be in QCOW2 format. See <code>virt-builder --help</code> for more information.


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/
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:


Below are instructions how to boot Fedora into X11/Fluxbox GUI mode.
<pre>
$ 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
</pre>


'''Step 1'''. Compile TinyEMU:
Then download it using your favorite HTTP client, for example:


<pre>
<pre>
wget https://bellard.org/tinyemu/tinyemu-2018-09-23.tar.gz
$ 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
tar xvf tinyemu-2018-09-23.tar.gz
cd tinyemu-2018-09-23
make
</pre>
</pre>


'''Step 2'''. Setup for booting Fedora:
=== Download manually ===
<pre>
 
mkdir fedora
If using <code>virt-builder</code> is not an option, you can download disk images manually from: https://dl.fedoraproject.org/pub/alt/risc-v/repo/virt-builder-images/images/
cd fedora
 
cp ../temu .
Download <code>Fedora-Developer-Rawhide-*.raw.xz</code> as well as the matching <code>Fedora-Developer-Rawhide-*-fw_payload-uboot-qemu-virt-smode.elf</code>.
 
== 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 <code>Fedora-Developer-Rawhide-*.raw.xz</code>.
 
These disk images differ from the ones above in that:
* the firmware is inside the disk image, in the <code>/boot</code> directory;
* they are completely untested.
 
= Prepare the disk image =
 
These steps are only necessary if you haven't used <code>virt-builder</code>.


# Download pre-built BBL with embedded kernel
== Uncompress the image ==
wget https://bellard.org/jslinux/bbl64-4.15.bin


# Create configuration file for TinyEMU
Whether you have downloaded a tested image or a nightly build, you'll need to uncompress it before it can be used:
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/vda1 rw TZ=${TZ}",
    drive0: { file: "Fedora-Developer-Rawhide-xxxx.n.0-sda.raw" },
    eth0: { driver: "user" },
    display0: {
        device: "simplefb",
        width: 1920,
        height: 1080,
    },
    input_device: "virtio",
}
EOF


# Download disk image and unpack in the same directory
<pre>
$ unxz Fedora-Developer-Rawhide-*.raw.xz
</pre>
</pre>


'''Step 3'''. Boot it.
== Optional: expand the disk image ==
 
You might want to expand the disk image before setting up the VM. Here is one example:
 
<pre>
<pre>
./temu -rw root-riscv64.cfg
$ 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
</pre>
</pre>


We need to use <code>-rw</code> 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.
The resulting disk image will work with QEMU as well as TinyEMU. Make sure you use <code>expanded.raw</code> instead of <code>Fedora-Developer-Rawhide-*.raw</code> when booting the guest.
 
== Optional: create an overlay ==


Once the system is booted login as <code>root</code> with <code>riscv</code> as password. Finally start X11 with Fluxbox: <code>startx /usr/bin/startfluxbox</code>. To gratefully shutdown just type <code>poweroff</code> into console.
You can also create <code>qcow2</code> disk image with <code>raw</code> Fedora disk as backing one. This way Fedora <code>raw</code> is unmodified and all changes are written to <code>qcow2</code> layer. You will need to install <code>libguestfs-tools-c</code>.


The disk image also incl. awesome and i3 for testing. Dillo is available as a basic web browser (no javascript support) and pcmanfm as file manager.
<pre>
$ 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
</pre>


= Boot under qemu =
The resulting disk image will only work with QEMU. Make sure you use <code>overlay.qcow2</code> instead of <code>Fedora-Developer-Rawhide-*.raw</code> when booting the guest.


You will need a very recent version of qemu.  If in doubt, compile from upstream qemu sources.
== Optional: set the hostname before booting ==


Get [https://fedorapeople.org/groups/risc-v/disk-images/bbl bbl from here] or [https://github.com/rwmjones/fedora-riscv-kernel compile it from source].
If you want to change hostname before the first boot, install <code>libguestfs-tools-c</code> and then run:


<pre>
<pre>
qemu-system-riscv64 \
$ virt-customize -a Fedora-Developer-Rawhide-*.raw --hostname fedora-riscv-mymagicbox
    -nographic \
    -machine virt \
    -smp 4 \
    -m 2G \
    -kernel bbl \
    -object rng-random,filename=/dev/urandom,id=rng0 \
    -device virtio-rng-device,rng=rng0 \
    -append "console=ttyS0 ro root=/dev/vda1" \
    -device virtio-blk-device,drive=hd0 \
    -drive file=Fedora-Developer-Rawhide-xxxx.n.0-sda.raw,format=raw,id=hd0 \
    -device virtio-net-device,netdev=usernet \
    -netdev user,id=usernet,hostfwd=tcp::10000-:22
</pre>
</pre>


You can also create <code>qcow2</code> disk image with <code>raw</code> Fedora disk as backing one. This way Fedora <code>raw</code> is unmodified and all changes are written to <code>qcow2</code> layer. You will need to install <code>libguestfs-tools-c</code>.
== Nightly builds only: extracting firmware (OpenSBI) ==
 
Fedora/RISC-V does not support BLS (Boot Loader Specification - [https://fedoraproject.org/wiki/Changes/BootLoaderSpecByDefault more details]).
 
Disk images contain a <code>/boot</code> 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:


<pre>
<pre>
qemu-img create -f qcow2 -F raw -b Fedora-Developer-Rawhide-xxxx.n.0-sda.raw tmp.qcow2 20G
$ guestfish \
virt-resize -v -x --expand /dev/sda1 Fedora-Developer-Rawhide-xxxx.n.0-sda.raw tmp.qcow2
  add Fedora-Developer-Rawhide-*.raw : \
virt-filesystems --long -h --all -a tmp.qcow2
  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
</pre>
</pre>


Then modify above QEMU invocation by changing <code>-drive</code> option to:
You can also use <code>guestmount</code> or QEMU/NBD to mount disk image. Examples:
<pre>
<pre>
-drive file=tmp.qcow2,id=hd0
$ 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
</pre>
</pre>


You can use up to <code>-smp 8</code>, which is helpful for building large projects.
<pre>
$ 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


Once machine is booted you can connect via SSH:
Device      Start      End  Sectors  Size Type
<pre>
/dev/nbd1p1  2048 15001599 14999552  7.2G Linux filesystem
ssh -p 10000 -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no root@localhost
$ 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
</pre>
</pre>


= Boot with libvirt =
Note NBD is highly useful if you need to run <code>fdisk</code>,  <code>e2fsck</code> (e.g. after VM crash and filesystem lock up), <code>resize2fs</code>. It might be beneficial to look into <code>nbdkit</code> and <code>nbd</code> 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/
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 29):
Quick instructions for libvirt installation (tested on Fedora 30):
 
<pre>
<pre>
dnf group install --with-optional virtualization
# dnf group install --with-optional virtualization
systemctl start libvirtd
# systemctl enable --now libvirtd
systemctl enable libvirtd
</pre>
</pre>


Needs <b>libvirt &ge; 4.7.0</b> which is the first version with upstream RISC-V support. This is available in Fedora 29. You should be able to boot the disk image using a command similar to this:
When running RISC-V guests, it's usually a good idea to use the very latest versions of QEMU, libvirt and virt-manager: the <code>virt-preview</code> repository offers just that for Fedora users. To enable it, simply run:


<pre>
<pre>
# virt-install \
# dnf copr enable @virtmaint-sig/virt-preview
    --name fedora-riscv \
    --arch riscv64 \
    --machine virt \
    --vcpus 4 \
    --memory 2048 \
    --import \
    --disk path=/var/lib/libvirt/images/Fedora-Developer-Rawhide-xxxx.n.0-sda.raw,bus=virtio \
    --boot kernel=/var/lib/libvirt/images/bbl,kernel_args="console=ttyS0 ro root=/dev/vda1" \
    --network network=default,model=virtio \
    --rng device=/dev/urandom,model=virtio \
    --graphics none
</pre>
</pre>


Note that will automatically boot you into the console. If you don't want that add <code>--noautoconsole</code> option. You can later use <code>virsh</code> tool to manage your VM and get to console.
and update your system.


You can use up to <code>--vcpus 8</code>, which is helpful for large projects.
The steps below assume you have copied both the disk image and the firmware into <code>/var/lib/libvirt/images</code>: 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 &ge; 4.0.0, libvirt &ge; 5.3.0 and virt-manager &ge; 2.2.0, the installation will be as simple as:
 
<pre>
# 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
</pre>


Add <code>--channel name=org.qemu.guest_agent.0</code> option if you want <code>virsh shutdown <name></code> to work. This requires <code>qemu-guest-agent</code> to be installed in disk image (available in Developer, GNOME and Minimal disk images starting Oct 15, 2018, but not in Nano disk images).
If you are stuck with older software (QEMU &ge; 2.12.0, libvirt &ge; 4.7.0), then you're going to need a more verbose command line:


If you want to change hostname before 1st boot install <code>libguestfs-tools-c</code> and then:
<pre>
<pre>
virt-customize -a Fedora-Developer-Rawhide-xxxx.n.0-sda.raw --hostname fedora-riscv-mymagicbox
# 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
</pre>
</pre>
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 <code>--noautoconsole</code> option. You can later use <code>virsh</code> tool to manage your VM and get to console.


A quick reference of <code>virsh</code> commands:
A quick reference of <code>virsh</code> commands:
Line 169: Line 263:
If you want to use <code>ssh user@virtualMachine</code> you can setup libvirt NSS module. See: https://wiki.libvirt.org/page/NSS_module
If you want to use <code>ssh user@virtualMachine</code> you can setup libvirt NSS module. See: https://wiki.libvirt.org/page/NSS_module


You might want to expand <code>raw</code> Fedora disk image before setting up VM. Here is one example:
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: <code>virsh edit <name></code> (modifying VM XML) and <code>virsh dumpxml <name></code> (dump VM XML for backup). You need to modify <code><serial></code> node by adding <code><log file='/var/log/libvirt/qemu/fedora-riscv-mymagicbox.serial.log'/></code>. Then power down and power up the VM.
 
Alternatively you can use <code>--serial log.file=/.../whatever.serial.log</code> with <code>virt-install</code> 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.
 
<pre>
$ 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
</pre>
 
Once machine is booted you can connect via SSH:
 
<pre>
$ ssh -p 10000 -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no -o PreferredAuthentications=password -o PubkeyAuthentication=no root@localhost
</pre>
 
== 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:
 
<pre>
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
</pre>
 
'''Step 2'''. Setup for booting Fedora:
 
<pre>
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
</pre>
 
'''Step 3'''. Boot it.


<pre>
<pre>
truncate -r Fedora-Developer-Rawhide-xxxx.n.0-sda.raw xxxx.n.0-sda.raw
./temu -rw root-riscv64.cfg
truncate -s 40G xxxx.n.0-sda.raw
virt-resize -v -x --expand /dev/sda1 Fedora-Developer-Rawhide-xxxx.n.0-sda.raw xxxx.n.0-sda.raw
virt-filesystems --long -h --all -a xxxx.n.0-sda.raw
virt-df -h -a xxxx.n.0-sda.raw
</pre>
</pre>


Then adjust <code>--disk path=</code> option in libvirt invocation.
We need to use <code>-rw</code> 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.


You might want also to setup logging for serial console (in case kernel panics or something else).
= Boot the image on physical hardware =
 
== Install on the HiFive Unleashed SD card ==
 
The disk image can be copied directly to an SD card and run on the [https://www.sifive.com/products/hifive-unleashed/ HiFive Unleashed board].
 
A good way to create the SD card is with this virt-builder command:


For this we will be using two commands: <code>virsh edit <name></code> (modifying VM XML) and <code>virsh dumpxml <name></code> (dump VM XML for backup). You need to modify <code><serial></code> node by adding <code><log file='/var/log/libvirt/qemu/fedora-riscv-mymagicbox.serial.log'/></code>. Then power down and power up the VM.
<pre>
sudo virt-builder \
    --source https://dl.fedoraproject.org/pub/alt/risc-v/repo/virt-builder-images/images/index \
    --no-check-signature \
    --arch riscv64 \
    --format raw \
    --hostname testing.example.com \
    --output /dev/sdXXX \
    --root-password password:riscv \
    fedora-rawhide-developer-20200108.n.0
</pre>


= Install on the HiFive Unleashed SD card =
== Install on the HiFive Unleashed using NBD server ==


These are instructions for the [https://www.sifive.com/products/hifive-unleashed/ HiFive Unleashed board].
You will need a separate machine on the same network which can act as an NBD server.  It can be any Linux machine with [https://github.com/qemu/qemu/blob/master/qemu-nbd.c qemu-nbd] or [https://github.com/libguestfs/nbdkit nbdkit] installed.


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:
You will first need to get it working on the SD card using the instructions in the previous section.


On the HiFive board, install <code>dracut-network</code> and <code>nbd</code>, and rebuild the initramfs with NBD support using these commands:
<pre>
<pre>
$ guestfish -a Fedora-Developer-Rawhide-xxxx.n.0-sda.raw \
dnf install dracut-network nbd
    run : download /dev/sda1 Fedora-Developer-Rawhide-xxxx.n.0-sda1.raw
dracut -m "nbd network base" -v --force
</pre>
</pre>


This creates a naked ext4 filesystem called <code>*-sda1.raw</code>.  The naked ext4 filesystem can be copied over the second partition of the SD card.
Shut down the HiFive board, remove the SD card, and copy the 4th partition from the SD card into a file or partition on the NBD server.


You can also build a custom bbl+kernel+initramfs to boot directly into the SD card using [https://github.com/rwmjones/fedora-riscv-kernel these sources].
You will need to change the UUID on this filesystem to a new random one (else it will conflict with the SD-card root filesystem), eg:
<pre>
tune2fs -U random /dev/VG/jive
</pre>


= Install on the HiFive Unleashed using NBD server =
Start up the NBD server (in this example using <code>qemu-nbd</code> with the 4th partition having been copied to <code>/dev/VG/jive</code> listening on port 10810):
<pre>
qemu-nbd -t -f raw -x "" -p 10810 /dev/VG/jive
</pre>
 
Place the SD card back in the HiFive board and boot it.  At this point you have still booted into the SD card's root filesystem (not NBD).  Go and edit <code>/boot/extlinux/extlinux.conf</code>.  To the <code>addappend</code> line you will need to set:
 
<pre>
root=UUID=...uuid... netroot=nbd:192.168.0.220:10810 rootfstype=ext4 ro rootdelay=5 ip=dhcp rootwait
</pre>


Look at https://github.com/rwmjones/fedora-riscv-kernel in the <code>sifive_u540</code> branchThis is quite complex to set up so it's best to ask on the <code>#fedora-riscv</code> IRC channel.
I would also advise removing <code>rhgb quiet</code> if they are presentNote you need to set <code>uuid</code> and the address and port number of the NBD server correctly.  Immediately reboot and it should come up with an NBD root.  Check the boot messages carefully to see whether it used the SD card or NBD root.


= Install Fedora GNOME Desktop on SiFive HiFive Unleashed + Microsemi HiFive Unleashed Expansion board =
== 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
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.
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 <code>root</code> with <code>riscv</code> as password.
X11 with Fluxbox can be started using: <code>startx /usr/bin/startfluxbox</code>. 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 <code>poweroff</code> into console.
If you want more information being displayed during boot, remove <code>quiet</code> from the <code>append</code> line in <code>/boot/extlinux/extlinux.conf</code>.

Revision as of 00:47, 30 April 2020

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.

To install virt-builder, run dnf install libguestfs-tools-c.

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 states
  • virsh 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 VM
  • virsh undefine <name> - remove VM
  • virsh net-list - list network (useful for the next command)
  • virsh net-dhcp-leases <network_name> - list DHCP leases, <network_name> most likely will be default. 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 VM
  • virsh reset <name> - hard reset VM
  • virsh 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

The disk image can be copied directly to an SD card and run on the HiFive Unleashed board.

A good way to create the SD card is with this virt-builder command:

sudo virt-builder \
    --source https://dl.fedoraproject.org/pub/alt/risc-v/repo/virt-builder-images/images/index \
    --no-check-signature \
    --arch riscv64 \
    --format raw \
    --hostname testing.example.com \
    --output /dev/sdXXX \
    --root-password password:riscv \
    fedora-rawhide-developer-20200108.n.0

Install on the HiFive Unleashed using NBD server

You will need a separate machine on the same network which can act as an NBD server. It can be any Linux machine with qemu-nbd or nbdkit installed.

You will first need to get it working on the SD card using the instructions in the previous section.

On the HiFive board, install dracut-network and nbd, and rebuild the initramfs with NBD support using these commands:

dnf install dracut-network nbd
dracut -m "nbd network base" -v --force

Shut down the HiFive board, remove the SD card, and copy the 4th partition from the SD card into a file or partition on the NBD server.

You will need to change the UUID on this filesystem to a new random one (else it will conflict with the SD-card root filesystem), eg:

tune2fs -U random /dev/VG/jive

Start up the NBD server (in this example using qemu-nbd with the 4th partition having been copied to /dev/VG/jive listening on port 10810):

qemu-nbd -t -f raw -x "" -p 10810 /dev/VG/jive

Place the SD card back in the HiFive board and boot it. At this point you have still booted into the SD card's root filesystem (not NBD). Go and edit /boot/extlinux/extlinux.conf. To the addappend line you will need to set:

root=UUID=...uuid... netroot=nbd:192.168.0.220:10810 rootfstype=ext4 ro rootdelay=5 ip=dhcp rootwait

I would also advise removing rhgb quiet if they are present. Note you need to set uuid and the address and port number of the NBD server correctly. Immediately reboot and it should come up with an NBD root. Check the boot messages carefully to see whether it used the SD card or NBD root.

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.