• riscv
• HiFiveUnmatched

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.

UART1 Quirk

Whilst seemingly not very detrimental to performance, the board suffers from a missing pull-up resistor on its UART1_RX line, which is wired to both the M.2 E-key (WiFi/Bluetooth) slot and the J28 header. This results in a floating signal value that can be sampled as a start bit and trigger interrupts for incoming data, with the interrupt rate having been seen to be as high as 180k per second. Unless you are using this secondary UART, it is recommended that it be disabled by adding the following to /boot/loader.conf and restarting:

hint.uart.1.disabled="1"

You can verify that this has taken effect by checking the output of devinfo(8); if successful, only uart0 should appear in the output (or, when using the -v option, uart1 should show as disabled). Note that devctl(8) can be used to enable and disable the UART once booted.

External Links

• HiFive Unmatched Getting Started Guide

• HiFive Unmatched Software Reference Manual

• HiFive Unmatched Forum

• https://github.com/sifive/freedom-u-sdk

• https://github.com/sifive/meta-sifive/tree/2021.04/recipes-bsp/u-boot/files/unmatched

• https://sifive.cdn.prismic.io/sifive/167a1a56-03f4-4615-a79e-b2a86153148f_FU740_errata_20210205.pdf

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:

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 (20220516), a u-boot flavor built for the Unmatched is available in ports (sysutils/u-boot-sifive-fu740) on the latest branch.

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

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

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

Patch Series