How to install Ubuntu on RISC-V HiFive boards

In this tutorial, we walk you through the process of installing Ubuntu on the RISC-V-based SiFive HiFive Unleashed and Unmatched boards.

The HiFive Unmatched is the first true RISC-V PC. With a 4-core CPU, 16 GiB of RAM, Gigabit Ethernet, four USB 3.0 ports, a mini-ITX form factor, and expansion capabilities for PCIe and NVMe, we can finally have a RISC-V computer as a daily driver.

The HiFive Unleashed is a discontinued RISC-V developer platform. It was the first RISC-V platform allowing to run Linux. It provides a quad-core CPU, 8 GiB of RAM and Gigabit Ethernet. Microsemi supplied an FPGA based expansion board HFU540-EXP which added PCI support.

Let’s start!

What you’ll learn

• How to install Ubuntu on the HiFive boards (Unmatched and Unleashed)
• How to configure the Unmatched to boot from an NVMe drive
• How to set up a basic desktop environment

What you’ll need

• A HiFive Unmatched or Unleashed board
• A micro SD card
• A power supply with a 24-pin connector
• A GPU (if planning to run a graphical interface)
• An M.2 NVMe SSD (if planning to use one, highly recommended)
• An M.2 Wi-Fi/Bluetooth adapter if desired

Even if planning to use an NVMe SSD long term, the SD card will be required as a first step. This way we can make use of the NVMe drive on the board to set up the SSD later.

Downloading the image for the HiFive Unmatched board

The Ubuntu 21.04 pre-installed Unmatched image can be downloaded and decompressed by running the following commands

wget https://cdimage.ubuntu.com/releases/21.04/release/ubuntu-21.04-preinstalled-server-riscv64+unmatched.img.xz
unxz ubuntu-21.04-preinstalled-server-riscv64+unmatched.img.xz

Downloading the image for the HiFive Unleashed board

wget 
https://cdimage.ubuntu.com/releases/21.04/release/ubuntu-21.04-preinstalled-server-riscv64+unleashed.img.xz
unxz ubuntu-21.04-preinstalled-server-riscv64+unleashed.img.xz

Flashing the Image Via Command Line

To flash the image to the SD card via the command line, run

dd if=</path/to/image.img> of=/dev/mmcblk0 bs=1M status=progress

This command assumes you have the SD card plugged into the SD card slot of the computer. If you are using a USB adapter it may appear as /dev/sdb or something similar instead of /dev/mmcblk0.

Flashing the Image With a GUI

If you are more comfortable using a GUI to flash the image to the SD card, there’s a tool for that! It’s called RPi Imager and it’s available from a few different places. Despite the name, it can be used to flash images on SD cards even if they’re not for a Raspberry Pi. On Ubuntu, you can install it by running

sudo snap install rpi-imager

It’s also available for download from the Raspberry Pi foundation. It runs on Linux, Windows, and MAC. To choose the recently decompressed image, click the “CHOOSE OS” Button and scroll down to “Use custom”. Select the Ubuntu 21.04 pre-installed Unmatched image, select the SD card in the “Storage” drop-down menu, and click “WRITE”.

Now that the image has been flashed to the SD card, you can insert it into the HiFive Unmatched or Unleashed and boot it up!

There are three ways to log into the boards:

• serial console
• a keyboard connected directly to the Unmatched with GPU output
• ssh

We strongly recommend connecting to the serial console when booting for the first time. The serial console shows the early boot messages that are displayed before the kernel is able to initialize the GPU and doesn’t require any extra configuration like ssh. Whichever method you choose to boot for the first time, please wait for cloud-init to finish running before attempting to log in. We’re working on that. If using serial console or GPU, cloud-init will print some output to stdout when it is finished running.

The default username/password is

username: ubuntu
password: ubuntu

Connecting to the Serial Console

The Getting Started Guide from HiFive explains how to connect to the serial console from a variety of different operating systems. If using an Ubuntu computer to monitor the serial output, connect that computer to the micro USB port next to the SD card slot on the Unmatched or Unleashed and run

sudo screen /dev/ttyUSB1 115200

Once you press the power button, boot output will start appearing in the screen session.

Logging in with USB Keyboard

Logging in with a USB keyboard requires a GPU to display the login screen. SiFive recommends an AMD RX-500 series, although many others are currently supported. Physically connect your GPU to the PCIe 16x slot on the motherboard and boot up. It’s that easy! The very early stages of the boot process will not appear on the screen with GPU output, so be patient. After the kernel is loaded into memory and can initialize the GPU, the boot output will appear on screen and eventually a login prompt will be presented.

Connecting via ssh

If the board is connected to the internet, it is possible to use ssh to log in. Power it up and wait a while for it to boot fully. Identify the IP address of the Unmatched and run the following to get a login prompt.

ssh <IP of Unmatched>

Using an NVMe drive with the Unmatched makes a huge difference in terms of performance and usability, so it is strongly recommended to use it if possible. SiFive recommends a Samsung 970 EVO Plus, but also Samsung 970 EVO (not plus) has been tested, and other ones should work, too. The easiest way to install Ubuntu on the NVMe drive is to boot from the SD card and use the M.2 connector on the Unmatched itself.

Once booted, download the Ubuntu image to the Unmatched and decompress it by running the command described in Step 2 as follows

wget http://cdimage.ubuntu.com/ubuntu/releases/21.04/release/ubuntu-21.04-preinstalled-server-riscv64+unmatched.img.xz
unxz /ubuntu-21.04-preinstalled-server-riscv64+unmatched.img.xz

Make sure the NVMe drive is present by running

ls -l /dev/nvme*

For example, the NVMe drive can appear as /dev/nvme0n1. Now flash the image to the NVMe by running

sudo dd if=/ubuntu-21.04-preinstalled-server-riscv64+unmatched.img of=/dev/nvme0n1 bs=1M status=progress

Congratulations! You now have Ubuntu installed on the NVMe drive of your HiFive Unmatched. However, there’s still one additional step. The Unmatched still needs an SD card present to boot, and there is a race condition that might cause it to mount the root filesystem on the SD card rather than the NVMe drive. To prevent this, mount the newly flashed NVMe drive and chroot into it by running

sudo mount /dev/nvme0n1p1 /mnt
sudo chroot /mnt

Use your favorite text editor to edit /etc/default/u-boot. Add the line

U_BOOT_ROOT="root=/dev/nvme0n1p1"

To apply these changes, run

u-boot-update

Exit the chroot environment by running exit, then reboot the system. It will now boot to your NVMe drive and you will have significant performance gains!

While not officially supported on the riscv64 architecture, the Ubuntu desktop shows a good performance on the Unmatched and Unleashed boards. With power off to the board, connect your GPU. Boot the system and get to a shell either through the serial console, ssh, or console with a mouse, keyboard, and GPU output. Install the graphical desktop software by running

sudo apt install mutter gnome-shell gnome-shell-extension-appindicator gnome-shell-extension-desktop-icons-ng gnome-shell-extension-prefs gnome-shell-extension-ubuntu-dock ubuntu-gnome-wallpapers gnome-terminal

If you would like a web browser, the recommended one is epiphany. It can be installed by running

sudo apt install epiphany-browser

You should now have your Hifive Unmatched or Unleashed set up just the way you want it! While it’s meant to be a development board, it’s capable of quite a lot more. We here at Canonical would love to see what you all do with your HiFive boards! Feel free to share your experience with Ubuntu running on the HiFive boards with the Ubuntu Community Team to help us improve!

• Installing Ubuntu on the HiFive Unmatched on Discourse
• You can discuss Ubuntu on RISC-V over at the Ubuntu Server forums
• Canonical enables Ubuntu on SiFive’s HiFive RISC-V boards Press Release
• Ubuntu 20.04 LTS images for HiFive Unleashed & QEMU VMs on SiFive Forums
• Additional information about Ubuntu on RISC-V