HiFive Unmatched

As of 20210807, -CURRENT and 13-STABLE have support for the HiFive Unmatched, including USB, Ethernet and NVMe.

Note that no SD card support is present, as that requires a driver for mmc-spi-slot, which itself requires an overhaul of FreeBSD's spibus to expose more low-level functionality required to control the SDC/MMC directly via SPI without an intervening controller.

Quick Start

The following steps describe how to install FreeBSD to an NVMe drive on the Unmatched. Make sure you have the SD card that shipped with the board, otherwise see #Booting.

  1. Download a copy of the memstick or mini-memstick installer from FreeBSD's Download Page.

  2. Copy the installer to a USB drive, e.g. dd if=FreeBSD-14.0-CURRENT-riscv-riscv64-mini-memstick.img of=/dev/da1 bs=1m status=progress

  3. Insert the SD card and USB drive into the Unmatched.
  4. Power-on the board. It should boot straight to the installer.
  5. Follow the installation steps, targeting your NVMe drive for the root filesystem (most likely it will show up as nda0).

  6. Reboot, and optionally remove the USB drive. The board should boot into the newly installed system either way.

If you don't have an NVMe drive and would like to boot from a USB instead, then choose the GENERICSD image from the download page. Despite the name, this contains a live install that can be copied directly to a USB.

Booting

The HiFive Unmatched can load the first stage boot from either onboard flash or SD card. The board ships with an SD card with U-Boot and Linux preinstalled. For now we will use the provided SD card to boot.

Per the reference manual there are four partitions on the provided card:

Partition

Format

Description

1

Raw

U-Boot SPL

2

Raw

U-Boot Proper

3

fat16

Linux kernel, .dtb, ...

4

ext4

Root FS

For our purposes we care only abut the first two partitions. U-Boot will search NVMe, USB, then the SD card.

u-boot

At the time of writing (20211013), there is no u-boot build for the Unmatched available in ports, although one is planned. MitchellHorne has built one by hand based on the v2021.10 u-boot release, which includes the proposed eMMC patches.

Available here: https://people.freebsd.org/~mhorne/unmatched/

SD Card

To boot from the SD card, ensure the MSEL[3:0] DIP switches on the board are configured as 1011:

  +----------> CHIPIDSEL
  | +--------> MSEL3
  | | +------> MSEL2
  | | | +----> MSEL1
  | | | | +--> MSEL0
  | | | | |
 +-+-+-+-+-+
 | |X| |X|X| ON(1)
 | | | | | |
 |X| |X| | | OFF(0)
 +-+-+-+-+-+
BOOT MODE SEL

To install a fresh copy of u-boot to an SD card, install sysutils/gdisk, and execute the following (assuming da0 as the target device):

# sgdisk -g --clear -a 1 \
    --new=1:34:2081 --change-name=1:spl --typecode=1:5B193300-FC78-40CD-8002-E86C45580B47 \
    --new=2:2082:10273 --change-name=2:uboot --typecode=2:2E54B353-1271-4842-806F-E436D6AF6985 \
    /dev/da0

# dd if=u-boot-spl.bin of=/dev/da0p1 bs=512 conv=sync
# dd if=u-boot.itb of=/dev/da0p2 bs=512 conv=sync

{i} These partition offsets and types must be exact, as u-boot is hard-coded to look for them there. This is the reason sgdisk must be used, since gpart(8) creates a header that extends past LBA 34.

eMMC

To boot from the internal flash (QSPI0 in SiFive's documentation), set MSEL[3:0] to 0110:

  +----------> CHIPIDSEL
  | +--------> MSEL3
  | | +------> MSEL2
  | | | +----> MSEL1
  | | | | +--> MSEL0
  | | | | |
 +-+-+-+-+-+
 | | |X|X| | ON(1)
 | | | | | |
 |X|X| | |X| OFF(0)
 +-+-+-+-+-+
BOOT MODE SEL

/!\ Note: It is not yet possible to write to the eMMC properly from FreeBSD. To complete the following, boot into Linux (run bootcmd_mmc0 at the u-boot prompt).

To install a fresh copy of u-boot to eMMC, execute the following:

sgdisk -g --clear -a 1 \
  --new=1:40:2087         --change-name=1:spl --typecode=1:5B193300-FC78-40CD-8002-E86C45580B47 \
  --new=2:2088:10279      --change-name=2:uboot  --typecode=2:2E54B353-1271-4842-806F-E436D6AF6985 \
  --new=3:10280:10535     --change-name=3:env   --typecode=3:0FC63DAF-8483-4772-8E79-3D69D8477DE4 \
  /dev/mtdblock0

partprobe

dd if=u-boot-spl.bin of=/dev/mtdblock0 bs=4096 seek=5 conv=sync
dd if=u-boot.itb  of=/dev/mtdblock0 bs=4096 seek=261 conv=sync

{i} These partition offsets and types must be exact. Notice that they differ slightly from what is required for an SD card.

Patch Series

Patch for -CURRENT

MFC'ed to stable/13?

D31021

yes

D31022

yes

D31023

yes

D31024

yes

D31025

yes

D31026

yes

D31027

yes

D31028

yes

D31029

yes

D31030

yes

D31031

yes

D31032

yes

D31033

yes

D31034

yes

D31035

yes

D31036

yes

riscv/HiFiveUnmatched (last edited 2021-10-13T22:17:42+0000 by MitchellHorne)