Installing Ubuntu 21.04 on the HiFive Unmatched

Tutorials
1

ⓘ This tutorial originally appeared on William Wilson’s (jawn-smith) blog and was contributed and modified here with permission.

The HiFive Unmatched is the first true RISC-V PC. With a 4-core CPU, 16GB 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. Click here for more information about Ubuntu and RISC-V

What You’ll Learn

  • How to install Ubuntu on the HiFive Unmatched
  • 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
  • A micro SD card (one should ship with the Unmatched)
  • A power supply with a 24-pin connector
  • A mini-ITX case
  • 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

Preparing the Board

Duration: varies

If you have a case, then go ahead and put the board in. I think a RISC-V board deserves an open source case, so I designed one!

unmatched_case

Unfortunately, a thermistor is currently broken in my 3D printer, so I have been unable to print and test it. Once that is resolved I will add the design files and .stl files to the original blog post along with instructions for how to assemble it. I hope to have that posted by mid-June.

Preparing the SD Card

Duration: 10:00

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 Unmatched to set up the SSD later. 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

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.

Note: be very careful about the “of” argument in the previous command. If the wrong disk is used, you may lose your data.

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”.

RPI imager
use_custom

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

Booting for the First Time

Duration: 2:00

There are three ways to log into the Unmatched: serial console, a keyboard connected directly to the Unmatched with GPU output, and ssh. I 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 and run

sudo screen /dev/ttyUSB1 115200

Once the power button is pressed, 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. I have tried a few different AMD graphics cards and they have all worked. 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 Unmatched 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

ssh <IP of Unmatched>

to get a login prompt.

Installing Ubuntu to an NVMe drive

Duration: 10:00

Using an NVMe drive with the Unmatched makes a huge difference in performance and usability. It takes a little effort to get it working but trust me that it’s worth it. SiFive recommends a Samsung 970 EVO Plus. I used a Samsung 970 EVO (not plus) and it works great. 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

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*

On my board the NVMe drive appears 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 a catch. 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

Note: the previous chroot command will only work if using a riscv64 computer to execute it. That is one reason why this tutorial suggests using the M.2 drive on the Unmatched to set up the NVMe drive

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!

Setting up a Desktop Environment

Duration: 10:00

While not officially supported on the riscv64 architecture, the Ubuntu desktop seems to work really well on the Unmatched. 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, I recommend epiphany. It can be installed by running

sudo apt install epiphany

That’s all!

Duration: 2:00

You should now have your Hifive Unmatched 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 Unmatched boards! If you have a project or anything else you want to share about your experience with the Unmatched, reach out to the Ubuntu Community Team and we’ll get something going!

4 Likes
2

Hi jawn-smith, thank you so much for this guide!

I followed the steps and I was able to boot Ubuntu 21.04 on my SiFive Unmatched from the nvme!

However, I have a couple of questions:

  1. the rootfs is loaded from the nvme, but the boot partition is still loaded from the sdcard (see foto attached). Is it normal?
    photo_2021-06-04_15-10-50

  2. The SiFive Unmatched still requires the sdcard for loading the u-boot at startup. Is it possible to install to install the u-boot in a way that the sd card is not needed anymore (e.g., changing the dip switch also) ?

Thank you again!

1 Like
3

Glad people are using the guide!

  1. It’s totally fine for /boot/efi to be still mounted on the SD card, as the rest of the boot partition (most importantly /boot/extlinux/) is still on the NVME.
  1. The need for the SD card to be present is actually part of the board’s firmware rather than u-boot itself, so unfortunately an SD card will be required.
    EDIT: I stand corrected, it is actually possible to flash bootloaders into EEPROM and set the DIP switches to boot from EEPROM. If there’s some interest in how to do that I’d be happy to do a write-up.
4

I really need it ! I will greatly appreciate anything about it.
And thank you for the tutorial: clear and easy to use.

Thank you again.

1 Like
5

Alright it seems there’s some interest so I’ll work out the details and post a write-up. I have to get focal booting on it first but then I’ll make that my next RISC-V project.

6

Nice. I will follow this thread with great interest.
Thank you to share your work like it.

1 Like
7

Thank you for the great tutorial!

In Gnome I get an white square mouse pointer if I hover over the desktop. If I hover over a window, to close it, it becomes an arrow. When I open a gnome terminal the window will not focus and it will not accept keyboard input.
Does anyone know what the problem is and how to fix this?

8

Any chance you’re using an Nvidia graphics card? If so Wayland is probably causing issues. You can disable it by editing /etc/gdm3/custom.conf and uncommenting the line #WaylandEnable=false

9

I am using a AMD Radeon Pro WX 3100. I will try your suggestion tomorrow to if this solves the problem

10

Thanks @jawn-smith, it solved the problem and everything seems to work fine now.

1 Like
11

@jawn-smith Gnome DISKS application is installed on Ubuntu Desktop by default, that can be used to “restore .img.xz image” onto sd-card. Without using rpi-imager, which is well quite unrelated.

Have you considered just using the “Disks” application in your guide?

12

I suppose that couldn’t hurt to add. Personally I just always use dd but wanted to throw a GUI option in there for people who wanted it.

14

I followed the steps to write out the image to NVMe, mounting partition 1 on it and then updating the u-boot config on this, but it continues to just boot from MMC. I’m guessing I must have missed a step, unless the firmware scans NVMe and MMC and should be prioritising the former. Initial boot output:

Device 0: unknown device
starting USB...
Bus xhci_pci: Register 4000840 NbrPorts 4
Starting the controller
USB XHCI 1.00
scanning bus xhci_pci for devices... 4 USB Device(s) found
       scanning usb for storage devices... 0 Storage Device(s) found

Device 0: unknown device
switch to partitions #0, OK
mmc0 is current device
Scanning mmc 0:1...
Found /boot/extlinux/extlinux.conf
Retrieving file: /boot/extlinux/extlinux.conf
1255 bytes read in 6 ms (204.1 KiB/s)
U-Boot menu
1:      Ubuntu 21.04 5.11.0-1012-generic
2:      Ubuntu 21.04 5.11.0-1012-generic (rescue target)
3:      Ubuntu 21.04 5.11.0-1007-generic
4:      Ubuntu 21.04 5.11.0-1007-generic (rescue target)
Enter choice: 1:        Ubuntu 21.04 5.11.0-1012-generic
Retrieving file: /boot/initrd.img-5.11.0-1012-generic

Note that prior to writing out the image to NVMe, I’d done a dist-upgrade while booted from MMC, hence the additional kernel version being shown in the boot menu.

15

Interesting, it seems u-boot is not scanning the NVMe as expected. When I boot I see

Device 0: Vendor: 0x144d Rev: 2B2QEXE7 Prod: S5H9NS0NB63499E
        Type: Hard Disk
        Capacity: 953869.7 MB = 931.5 GB (1953525168 x 512)
... is now current device
Scanning nvme 0:1...

First: a temporary workaround: While booted with the MMC as rootfs, do the same u-boot-update steps on that filesystem. That is, edit /etc/default/u-boot and add U_BOOT_ROOT="root=/dev/nvme0n1p1". Then run u-boot-update. This is the same as what you did while in the chroot environment on the NVMe, only now you will do it without the chroot, on the MMC.

Now to gather a little more info. Could you provide the following?

  • Brand and model of your NVMe drive
  • u-boot version number
16

Many thanks! The temporary workaround seems to have done the trick, although it still took a look time to read from MMC initially.

The SSD is a Samsung 970EVOPlus 1TB.

U-Boot SPL 2021.01+dfsg-3ubuntu9 (Apr 21 2021 - 17:05:00 +0000).

17

Sorry it’s taken so long to get back to you. Before we try dropping to a u-boot shell for debugging can you try an impish indri daily build? They can be found at https://cdimage.ubuntu.com/ubuntu-server/daily-preinstalled/pending/

18

We’d love to see what you guys accomplish with your Unmatched boards here at Canonical! Reach out to Ubuntu Community Team 4 if you have a project or anything else you’d like to share about your Unmatched experience, and we’ll get something started!

19

Did anyone manage to flash a bootloader to EEPROM and boot entirely without SD? I am kind of disappointed with my unmatched board as is, because it is really slow (booting, launching a browser, et cetera)! For the total price of a working board (which is quite noisy by the way), one could buy a rather powerful laptop…

20

I haven’t had the opportunity to work on this yet, but if we do get this working it will still need a hard drive to boot to. If you use an NVMe it will be significantly faster than the SD card and doesn’t require the EEPROM flashing to get it working (my guide covers how).

The board doesn’t have the price/performance ratio of a laptop, but that’s not really what the goal of this board was. The goal of this board is to have a functional RISC-V PC, and it’s really the first board that can claim to be that. As RISC-V matures I expect we will see much better price/performance ratio, but for now this technology is still very new and the price will reflect that.

21

Thank you for replying, and you’re right. I am aware of the fact, that the Unmatched wasn’t made to compete with laptops. And part of the reason I bought it is to support the technology by showing interest.

By the way I do have an NVMe SSD installed, and as you say, it does help a lot! Still: Why have an SPI-NOR flash chip, if it is not used (at least not yet - to my knowledge).

Thank you for sharing this guide on installing to NVMe. It helped me a lot. I will be sure to follow this thread for more tips and tricks, in case anyone shares.