UART

The board features makes both JTAG and UART available over a micro USB connector. It appears as two separate devices in Linux (/dev/ttyUSB0, /dev/ttyUSB1). The second ttyUSB device represents the UART. The baudrate is 57600 for the Boot ROM but 115200 for U-Boot and Linux.

You can use the package picocom to access the serial console:

sudo apt-get install picocom
sudo picocom -b 115200 /dev/ttyUSB1

Boot device selection

Set jumpers to boot from the microSD by setting MSEL=1011 (MSEL2 to the outside of the board, the rest to the inside).

Using the server install image

Copying Ubuntu onto the SD-card

Download the Ubuntu live install server image and flash it on your sdcard using:

zcat ubuntu-22.04.2-live-server-riscv64.img.gz | sudo dd of=/dev/sdX bs=1M conv=fsync

You will have to replace /dev/sdX by the actual device name of your SD card. Please, be especially cautious not to overwrite the wrong drive as this cannot be undone.

Installation

Establish a serial console connection to the Unmatched board.

sudo picocom -b 115200 /dev/ttyUSB1

Insert the SD card and power up the system.

If no prior operating system installation exists, U-Boot will start up GRUB on the SD card.

Otherwise press the enter key when seeing the Hit any key to stop autoboot: message and execute:

pci enum
nvme scan
load mmc 0:1 $fdt_addr_r dtb/sifive/hifive-unmatched-a00.dtb
load mmc 0:1 $kernel_addr_r EFI/boot/bootriscv64.efi
bootefi $kernel_addr_r $fdt_addr_r

In the GRUB menu select Try or Install Ubuntu Server.

Reading from the SD card is very slow. Loading the installer takes several minutes. Once it is loaded follow the installation steps in https://ubuntu.com/tutorials/install-ubuntu-server.

When the installation is finished reboot the board without removing the SD card.

U-Boot does not allow the operating system to write UEFI variables. We have to do this manually. While rebooting press the enter key when seeing the Hit any key to stop autoboot: message. The following commands set up the installation on the NVMe drive as UEFI boot option 0001.

pci enum
nvme scan
efidebug boot add -b 0001 'Ubuntu Jammy' nvme 0:1 /EFI/ubuntu/grubriscv64.efi
efidebug boot order 0001

To boot into your fresh installation you can use:

bootefi bootmgr

On the next boot U-Boot will automatically start into GRUB.

Installing the Gnome desktop

If you have a graphics card install you may want to use a graphical desktop. The Gnome desktop can be installed with

sudo apt-get update
sudo apt-get install ubuntu-desktop
sudo systemctl start gdm3

Using the preinstalled server image

Copying Ubuntu onto the SD-card

Download the Ubuntu preinstalled server image and flash it on your sdcard using:

xzcat lunar-preinstalled-server-riscv64+unmatched.img.xz | sudo dd bs=1M conv=fsync of=/dev/sdX

You will have to replace /dev/sdX by the actual device name of your SD card. Please, be especially cautious not to overwrite the wrong drive as this cannot be undone.

First boot

Establish a serial console connection to the Unmatched board.

sudo picocom -b 115200 /dev/ttyUSB1

Insert the SD card and power on the board.

When booting the first time wait until you see an output line confirming that cloud-init has finished. Cloud init is responsible for generating the SSH keys and setting the default password. Cloud init itself will also need a few minutes. The line to wait for will look similar to

[  150.053340] cloud-init[1274]: Cloud-init v. 23.1.1-0ubuntu2 finished at Mon, 03 Apr 2023 11:14:35 +0000. Datasource DataSourceNoCloud [seed=/var/lib/cloud/seed/nocloud-net][dsmode=net].  Up 150.00 seconds

Now you can login with user ubuntu and the default password ubuntu and will be asked to choose a new password.

cloud-init integration

The image has a fallback cloud-init datasource that configures sudo user ubuntu with password ubuntu and DHCP networking. You will be asked to change the password on first login.

The image has CIDATA partition which can be used as a valid datasource to adjust cloud-config metadata. If you wish to customize user password, networking information, add ssh keys, etc. Please mount CIDATA partition rename meta-data and user-data files and adjust them to taste. You can use network-info to configure networking if something more sophisticated than just DHCP is desired.

For example ssh keys, disabling interactive login, and so on. See https://cloudinit.readthedocs.io/en/latest.