===== 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]].
- Download a copy of the memstick or mini-memstick installer from [[https://www.freebsd.org/where/|FreeBSD's Download Page]].
- 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%%''
- Insert the SD card and USB drive into the Unmatched.
- Power-on the board. It should boot straight to the installer.
- Follow the installation steps, targeting your NVMe drive for the root filesystem (most likely it will show up as ''%%nda0%%'').
- 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|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 ====
* [[https://sifive.cdn.prismic.io/sifive/65937c64-c6ca-4bc7-80d1-e830a895636a_hifive-unmatched-getting-started-guide-v1p4.pdf|HiFive Unmatched Getting Started Guide]]
* [[https://sifive.cdn.prismic.io/sifive/05d149d5-967c-4ce3-a7b9-292e747e6582_hifive-unmatched-sw-reference-manual-v1p0.pdf|HiFive Unmatched Software Reference Manual]]
* [[https://forums.sifive.com/c/hifive-unmatched/16|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:
| 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 (20220516), a u-boot flavor built for the Unmatched is available in ports ([[https://www.freshports.org/sysutils/u-boot-sifive-fu740/|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 ====
^ Patch for -CURRENT ^ MFC'ed to stable/13? ^
| [[https://reviews.freebsd.org/D31021|D31021]] | yes |
| [[https://reviews.freebsd.org/D31022|D31022]] | yes |
| [[https://reviews.freebsd.org/D31023|D31023]] | yes |
| [[https://reviews.freebsd.org/D31024|D31024]] | yes |
| [[https://reviews.freebsd.org/D31025|D31025]] | yes |
| [[https://reviews.freebsd.org/D31026|D31026]] | yes |
| [[https://reviews.freebsd.org/D31027|D31027]] | yes |
| [[https://reviews.freebsd.org/D31028|D31028]] | yes |
| [[https://reviews.freebsd.org/D31029|D31029]] | yes |
| [[https://reviews.freebsd.org/D31030|D31030]] | yes |
| [[https://reviews.freebsd.org/D31031|D31031]] | yes |
| [[https://reviews.freebsd.org/D31032|D31032]] | yes |
| [[https://reviews.freebsd.org/D31033|D31033]] | yes |
| [[https://reviews.freebsd.org/D31034|D31034]] | yes |
| [[https://reviews.freebsd.org/D31035|D31035]] | yes |
| [[https://reviews.freebsd.org/D31036|D31036]] | yes |