ⓘ 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
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!
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
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
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”.
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
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
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.
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
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
To apply these changes, run
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
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
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!