StarFive VisionFive 2

Resources

This article has been flagged for not conforming to the wiki guidelines. Please help Gentoo out by starting fixing things.

This page describes several methods for installing Gentoo on the StarFive VisionFive 2.

Introduction

This page aims to provide a comprehensive introduction to the various methods of installing Gentoo onto Embedded hardware using the VisionFive 2 as an example device.

The majority of the instructions here are not specific to the VisionFive 2 and may be applied to other devices with similar hardware. Please apply some common sense when adapting these instructions for other devices and do not blindly copy and paste commands without understanding what they do.

It should also be noted that the processes described hereafter are not always the most efficient in terms of commands used, and multiple commands may be used with, for example, environment variables that would typically be exported, or repeated additional options where a wrapper would be useful. This is intentional as it is intended to be a learning experience for the reader.

This article is intended to supplement the Embedded Handbook.

System build methods

There are several different ways to approach building the system image (root filesystem). This article will try to incorporate two of them:

Utilizing a Crossdev environment
Using a chroot to build packages with QEMU Userspace emulation.

Hardware

For a detailed overview of the StarFive hardware, please visit StarFive_VisionFive_2/Hardware

A JH7110 SoC block diagram is available at: SoC block diagram

Boot sequence

Boot ROM

The VisionFive 2 uses the JH7100 SOC, which has a write-only BootROM (BROM) built in. At power on, the configuration of the two-switch RGPIO header determines which storage device will used to load the Secondary Program Loader (SPL):


Option	RGPIO_0	RGPIO_1
Onboard QSPI Flash (factory setting)	Low	Low
SDIO3.0 (microSD card)	High	Low
eMMC	Low	High
UART	High	High

Low/High states vs switch position
RGPIO_0 = number 2 on the left
RGPIO_1 = number 1 on the left (just underneath the GPIO header)

Seondary Program Loader

If the BootROM is able to load the SPL (Secondary Program Loader) on the selected storage, it will perform basic operations such as RAM initialization, then launch load the Bootloader.

The SPL is loaded from the first partition with the GUID type code of 2E54B353-1271-4842-806F-E436D6AF6985 (HiFive BBL), by default U-Boot will attempt to load the Bootloader (FIT image) from partition 2. While not required, the recommended GUID type code for the bootloader partition is BC13C2FF-59E6-4262-A352-B275FD6F7172.

Note
The SPL itself is typically based on U-Boot, which is used to load the main U-Boot bootloader/payload.

Bootloader

The bootlader, typically, U-Boot with OpenSBI and bundled DTBs (Device Tree Blobs) packed into a FIT (Flat Image Tree).

Finally, U-Boot is used to load and execute the kernel and/or initramfs to start the OS.

Tip
The partition used by the SPL is defined by CONFIG_SYS_MMCSD_RAW_MODE_U_BOOT_PARTITION=0x2 when building U-Boot

Note
The FIT image (u-boot.itb) generally contains multiple DTBs for compatibility and can be inspected from the U-Boot build directory with with:

user $./tools/dumpimage -l u-boot.itb

First start

Out of the box, the board's SPI flash is preloaded with boot code. Before doing anything, it's worth checking that this works. This is accomplished using the UART (serial) interface, as the HDMI interface is not initialized without an OS.

Serial connection

UART is accessible via the pins 6 (GND), 8 (TX) and 10 (RX), similar to most Raspberry PIs.

StarFive VisionFive 2 (1.3B) GPIO pin	Serial adapter pin
6 (Ground)	Ground
8 (TX)	RX
10 (RX)	TX

Illustration for a 1.3B board revision with a connected USB serial adapter (from left to right its pins are GND - black wire, RXD - blue wire, TXD - violet wire, 3.3V + VCC - yellow jumper, 5V - not connected):

Connecting the StarFive VisionFive 2 (rev. 1.3B) to an USB serial adapter

Note
Unless the serial adapter is labeled backwards, the RX pin on one end should be connected to the TX pin on the other.

Tip
For extended debug sessions, using a JST-XH connection is preferred to dupont cables.

Warning
GPIO pins on the VisionFive 2 can only tolerate 3.3v. If the serial adapter uses 5v for uart data lines, it could damage the board. Some, but not all serial adapters support voltage level adjustments by shorting VCC to 3.3v

Once physically connected, a serial communication program which can handle a serial port connection and transfer files over X-Modem or Y-Modem protocols like net-dialup/minicom must be installed:

root #emerge --ask net-dialup/minicom

The serial port connection parameters should be set as being:

Speed: 115200 bps
Data: 8 bits
Parity: None
Stop bits: 1 bit
No control flow (hardware and software)

Using minicom, this configuration cab be specified for device /dev/ttyUSB0 using:

user $minicom -D /dev/ttyUSB0 -b 115200

Using picocom:

user $picocom /dev/ttyUSB0 -b 115200

Powering up

As the board's QSPI flash already contains a firmware (preloaded at factory), it is possible to use the board when unboxing it. QSPI flash is too small to contain a full-fledged OS nevertheless it is more than enough to contain an OpenSBI/U-Boot environment (comparable to OpenBOOT for SPARC machines users).

With the serial connection setup in Minicom and the serial cable connected to the StarFive VisionFive 2 UART pins, powering the board up should lead to the following display in Minicom:

U-Boot SPL 2021.10 (Sep 28 2024 - 01:14:56 +0800)

LPDDR4: 8G version: g8ad50857.
Trying to boot from SPI

OpenSBI v1.2
   ____                    _____ ____ _____
  / __ \                  / ____|  _ \_   _|
 | |  | |_ __   ___ _ __ | (___ | |_) || |
 | |  | | '_ \ / _ \ '_ \ \___ \|  _ < | |
 | |__| | |_) |  __/ | | |____) | |_) || |_
  \____/| .__/ \___|_| |_|_____/|___/_____|
        | |
        |_|

Platform Name             : StarFive VisionFive V2
Platform Features         : medeleg
Platform HART Count       : 5
Platform IPI Device       : aclint-mswi
Platform Timer Device     : aclint-mtimer @ 4000000Hz
Platform Console Device   : uart8250
Platform HSM Device       : ---
Platform PMU Device       : ---
Platform Reboot Device    : pm-reset
Platform Shutdown Device  : pm-reset
Platform Suspend Device   : ---
Firmware Base             : 0x40000000
Firmware Size             : 392 KB
Firmware RW Offset        : 0x40000
Runtime SBI Version       : 1.0

Domain0 Name              : root
Domain0 Boot HART         : 1
Domain0 HARTs             : 0*,1*,2*,3*,4*
Domain0 Region00          : 0x0000000002000000-0x000000000200ffff M: (I,R,W) S/U: ()
Domain0 Region01          : 0x0000000040000000-0x000000004003ffff M: (R,X) S/U: ()
Domain0 Region02          : 0x0000000040040000-0x000000004007ffff M: (R,W) S/U: ()
Domain0 Region03          : 0x0000000000000000-0xffffffffffffffff M: (R,W,X) S/U: (R,W,X)
Domain0 Next Address      : 0x0000000040200000
Domain0 Next Arg1         : 0x0000000042200000
Domain0 Next Mode         : S-mode
Domain0 SysReset          : yes
Domain0 SysSuspend        : yes

Boot HART ID              : 1
Boot HART Domain          : root
Boot HART Priv Version    : v1.11
Boot HART Base ISA        : rv64imafdcbx
Boot HART ISA Extensions  : none
Boot HART PMP Count       : 8
Boot HART PMP Granularity : 4096
Boot HART PMP Address Bits: 34
Boot HART MHPM Count      : 2
Boot HART MIDELEG         : 0x0000000000000222
Boot HART MEDELEG         : 0x000000000000b109

U-Boot 2021.10 (Sep 28 2024 - 01:14:56 +0800), Build: jenkins-github_visionfive2_6.6-5

CPU:   rv64imacu_zba_zbb
Model: StarFive VisionFive V2
DRAM:  8 GiB
MMC:   sdio0@16010000: 0, sdio1@16020000: 1
Loading Environment from SPIFlash... SF: Detected gd25lq128 with page size 256 Bytes, erase size 4 KiB, total 16 MiB
OK
StarFive EEPROM format v2

--------EEPROM INFO--------
Vendor : StarFive Technology Co., Ltd.
Product full SN: VF7110B1-2318-D008E000-00000000
data version: 0x2
PCB revision: 0xb2
BOM revision: A
Ethernet MAC0 address: 6c:cf:39:00:b0:16
Ethernet MAC1 address: 6c:cf:39:00:b0:17
--------EEPROM INFO--------

In:    serial
Out:   serial
Err:   serial
Model: StarFive VisionFive V2
Net:   eth0: ethernet@16030000, eth1: ethernet@16040000
Hit any key to stop autoboot:  0 
Card did not respond to voltage select! : -110
Card did not respond to voltage select! : -110
starfive_pcie pcie@2B000000: Port link up.
starfive_pcie pcie@2B000000: Starfive PCIe bus probed.
PCI: Failed autoconfig bar 10
starfive_pcie pcie@2C000000: Port link down.
starfive_pcie pcie@2C000000: Starfive PCIe bus probed.
PCI: Failed autoconfig bar 10

Device 0: unknown device

Device 0: unknown device
Tring booting distro ...
Card did not respond to voltage select! : -110
Card did not respond to voltage select! : -110

Device 0: unknown device

Device 0: unknown device
StarFive #

So far so good, an U-Boot command prompt beginning with StarFive # should show up at the end of the booting process. No worries for error messages like Card did not respond to voltage select! : -110 and Device 0: unknown device, they are normal at this point. Enter something like help to get a list of what valid commands are under the U-Boot shell as a test:

StarFive #help

?         - alias for 'help'
base      - print or set address offset
bdinfo    - print Board Info structure
blkcache  - block cache diagnostics and control
boot      - boot default, i.e., run 'bootcmd'
bootd     - boot default, i.e., run 'bootcmd'
bootefi   - Boots an EFI payload from memory
bootelf   - Boot from an ELF image in memory
booti     - boot Linux kernel 'Image' format from memory
bootm     - boot application image from memory
bootp     - boot image via network using BOOTP/TFTP protocol
bootvx    - Boot vxWorks from an ELF image
cmp       - memory compare
config    - print .config
coninfo   - print console devices and information
cp        - memory copy
cpu       - display information about CPUs
crc32     - checksum calculation
dhcp      - boot image via network using DHCP/TFTP protocol
dm        - Driver model low level access
echo      - echo args to console
editenv   - edit environment variable
eeprom    - EEPROM sub-system
efidebug  - Configure UEFI environment
env       - environment handling commands
erase     - erase FLASH memory
eraseenv  - erase environment variables from persistent storage
exit      - exit script
ext2load  - load binary file from a Ext2 filesystem
(...)
showvar   - print local hushshell variables
size      - determine a file's size
sleep     - delay execution for some time
source    - run script from memory
sysboot   - command to get and boot from syslinux files
test      - minimal test like /bin/sh
tftpboot  - boot image via network using TFTP protocol
tftpput   - TFTP put command, for uploading files to a server
true      - do nothing, successfully
unlz4     - lz4 uncompress a memory region
unzip     - unzip a memory region
usb       - USB sub-system
usbboot   - boot from USB device
version   - print monitor, compiler and linker version

Everything is in good working order at this point. The StarFive VisionFive 2 can be powered down by removing its USB-C power cable (safe operation, will not corrupt anything).

See also
If the system does not boot from SPI flash out of the box, see SPI issues

Prerequisites

This guide assumes the user will be cross compiling or using QEMU, preferring cross compilation. Setup is described below.

Tip
While not described on this page, Catalyst can be used to generate system images.

Preparing the crossdev environment

If building the system image from non-RISC-V hardware, a cross development environment must be created.

Important
If new to Crossdev, do not use this quick-start info as a substitute to primary docs.

An abridged setup process is as follows:

First, if a crossdev overlay has not been created, it can be initalzied with:

root #eselect repository create crossdev

Then, the riscv64 toolchain can be created with:

root #crossdev --target riscv64-unknown-linux-gnu

A r64 lp64d profile can be selected for that crossdev environment wtih:

root #PORTAGE_CONFIGROOT=/usr/riscv64-unknown-linux-gnu eselect profile set default/linux/riscv/23.0/rv64/lp64d

Tip
The U74 cores of a JH7110 SoC supports hardware double precision floating point operations, therefore any of the RV64GC/LP64D profiles are suitable starting point. RV64GC/LP64 stage 3 images require no hardware double precision floating point support thus can be used on all RV64GC processors.

Once the profile is selected, the environment can be setup with:

root #USE=build riscv64-unknown-linux-gnu-emerge -v1 baselayout

The cross build environment make.conf can be updated for optimized builds with:

FILE /usr/riscv64-unknwon-linux-gnu/etc/portage/make.conf

# Added to the end of make.conf
# Common flags for cross-compiling and colour; params pulled from -march=native
COMMON_FLAGS="-mabi=lp64d -march=rv64imafdc_zicsr_zba_zbb -mcpu=sifive-u74 -mtune=sifive-7-series -O2 -pipe --param l1-cache-size=32 --param l2-cache-size=2048"
CFLAGS="${COMMON_FLAGS}"
CXXFLAGS="${COMMON_FLAGS}"
FCFLAGS="${COMMON_FLAGS}"
FFLAGS="${COMMON_FLAGS}"

Glibc can be re-emerged with:

root #riscv64-unknown-linux-gnu-emerge -v1 sys-libs/glibc

Finally, the system set can be rebuilt with:

root #riscv64-unknown-linux-gnu-emerge -v1 @system

Optional: Configure QEMU-user and binfmt

Important
If unfamiliar with QEMU user chroots, this section is not a substitute for the reference material!

An abridged QEMU user chroot setup for RISC-V is as follows:

Configure riscv64 QEMU targets

FILE /etc/portage/package.use/qemu

app-emulation/qemu static-user qemu_softmmu_targets_riscv64 qemu_user_targets_riscv64

Emerge QEMU

root #emerge --ask --update --newuse --deep app-emulation/qemu

Start the qemu-binfmt service

Openrc

root #rc-service qemu-binfmt start

Manual

The binfmt handlers can also be manually configured:

root #

mount binfmt_misc -t binfmt_misc /proc/sys/fs/binfmt_misc

root #

echo ':riscv64:M::\x7fELF\x02\x01\x01\x00\x00\x00\x00\x00\x00\x00\x00\x00\x02\x00\xf3\x00:\xff\xff\xff\xff\xff\xff\xff\x00\xff\xff\xff\xff\xff\xff\xff\xff\xfe\xff\xff\xff:/usr/bin/qemu-riscv64:' > /etc/binfmt.d/qemu-riscv64-static.conf

Then restart binfmt support:

OpenRC:
root #rc-service binfmt restart
Systemd:
root #systemctl restart systemd-binfmt

Confirming binfmt registration

When properly configured, the /proc/sys/fs/binfmt_misc/qemu-riscv64 should exist:

user $

cat /proc/sys/fs/binfmt_misc/qemu-riscv64

enabled
interpreter /usr/bin/qemu-riscv64
flags: 
offset 0
magic 7f454c460201010000000000000000000200f300
mask ffffffffffffff00fffffffffffffffffeffffff

Copying the interpreter binary

The interpreter can be copied into the rootfs with:

root #cp /usr/bin/qemu-riscv64 /usr/riscv64-unknown-linux-gnu/usr/bin

Activating the user chroot

The chroot can be activated with:

root #arch-chroot /usr/riscv64-unknown-linux-gnu

Before the environment can be used for the first time, locales and ldconfig must be generated, then the profile must be sourced again:

root #locale-gen

root #ldconfig

root #. /etc/profile

Important
If using QEMU user chroots with a crossdev environment, the ROOT and CHOST definitions in the /etc/portage/make.conf must be disabled while using QEMU and re-enabled for crossdev use!

Warning
The crossdev environment make.conf must be restored to working configuration before being used, if used for a QEMU chroot!

Environment variables and initial setup

Tip
Put the export statements within a shell-script that can be on-demand sourced or within a .bash_file file.

To keep things clear along the various procedures detailed in the next sections, start by defining some shell variables as they will be used all along this explanation (the dash for RISCV_XCOMPILE is not an error):

root #

export RISCV_WORKDIR_PATH=/path/to/a/work/directory

root #

export RISCV_ROOTFS_PATH=${RISCV_WORKDIR_PATH}/rootfs

root #

export RISCV_XARCH=riscv64-unknown-linux-gnu

root #

export RISCV_XCOMPILE=${RISCV_XARCH}-

root #

export RISCV_XDEV_ROOT=/usr/${RISCV_XARCH}

root #

export QEMU_LD_PREFIX=${RISCV_ROOTFS_PATH}

And create the directories structure where the job will done:

root #

mkdir -p ${RISCV_ROOTFS_PATH}

Updating the bootloader

If building the boot code from source is preferred over using StarFive provided binaries, they can be rebuilt using the created crossdev toolchain.

Important
When building from sources, a stable release branch should be checked out, unless built purely for testing.

Building OpenSBI

OpenSBI (SBI standing for RISC-V Supervisor Binary Interface) is an open software layer that provides runtime services for the M-Mode and thus is required by U-Boot. A short presentation in PDF to get an overview of what OpenSBI consists of can be found at https://riscv.org/wp-content/uploads/2024/12/13.30-RISCV_OpenSBI_Deep_Dive_v5.pdf

It can be cloned wherever preferred by the user. In this guide, ~/projects/ will be used:

~/projects $git clone https://github.com/riscv/opensbi.git

With the sources, the OpenSBI image can be built with:

~/projects/opensbi $make ARCH=riscv CROSS_COMPILE=riscv64-unknown-linux-gnu- PLATFORM=generic FW_OPTIONS=0

oaded configuration '/home/larry/projects/opensbi/platform/generic/configs/defconfig'
Configuration saved to '/home/larry/projects/opensbi/build/platform/generic/kconfig/.config'
 CC-DEP    platform/generic/platform.dep
 CC-DEP    lib/sbi/riscv_asm.dep
 CC-DEP    lib/sbi/riscv_atomic.dep
...
 AS        platform/generic/firmware/fw_payload.o
 CPP       platform/generic/firmware/fw_payload.elf.ld
 ELF       platform/generic/firmware/fw_payload.elf
 OBJCOPY   platform/generic/firmware/fw_payload.bin

Important
build/platform/generic/firmware/fw_dynamic.bin will be used when building U-Boot.

Tip
FW_OPTIONS=0 makes OpenSBI display a banner at system startup.

Building U-Boot

Similarly to OpenSBI, U-Boot can be built by cloning the sources, and cross building:

~/projects $git clone https://github.com/u-boot/u-boot

Once cloned, a stable tag, such as v2025.04 can be checked out:

~/projects/u-boot $git checkout v2025.04

The VisionFive 2 default config can be generated with:

~/projects/u-boot $make ARCH=riscv CROSS_COMPILE=riscv64-unknown-linux-gnu- starfive_visionfive2_defconfig

Tip
It is possible to customize U-Boot via a configuration menu by issuing: make CROSS_COMPILE=riscv64-unknown-linux-gnu- menuconfig

Finally, it can be compiled using the previously generated OpenSBI firmware:

user $

make ARCH=riscv CROSS_COMPILE=riscv64-unknown-linux-gnu- OPENSBI=${HOME}/projects/opensbi/build/platform/generic/firmware/fw_dynamic.bin

Updating U-Boot

Warning
Updating U-Boot can reset the contents of U-Boot environment variables. Customized settings should be backed up before updating.

Older U-Boot versions may have bugs or compatibility issues with certain kernels. In the event of boot issues, a new U-Boot version can be installed to the SPI flash while U-Boot is running.

Official Firmware file	Source-built Firmware File	Base address in SPI flash memory
u-boot-spl.bin.normal.out	spi/u-boot-spl.bin.normal.out	0x0
visionfive2_fw_payload.img	u-boot.itb	0x100000

U-Boot supports several methods for firmware updates, including:

Firmware loaded from attached storage
TFTP
UART/Y-Modem

Additionally, the firmware may be updated from the running system using sys-fs/mtd-utils.

Important
While the VisionFive 2 can use boot code from SD or eMMC, the SPI flash should be preferred for general use.

See also
U-Boot StarFive 2 Update Docs

Updating from SD

U-Boot can read firmware files from external storage, such as a SD card, and write it to the SPI flash.

Files from the table above can be copied an EXT4 or FAT32 partition on a SD card. Partition 3 on a SD card is used in this example.

Initialize SPI flash

With U-Boot running, the SPI flash can be initialized with:

StarFive #sf probe

SF: Detected gd25lq128 with page size 256 Bytes, erase size 4 KiB, total 16 MiB

Read SD

MMC devices can be scanned with:

StarFive #mmc list

mmc@16010000: 0
mmc@16020000: 1 (SD)

The SD card can be selected with:

StarFive #mmc dev 1

switch to partitions #0, OK
mmc1 is current device

Partitions can be listed with:

StarFive #mmc part

Partition Map for mmc device 1  --   Partition Type: EFI

Part	Start LBA	End LBA		Name
	Attributes
	Type GUID
	Partition GUID
  1	0x00001000	0x00001fff	""
	attrs:	0x0000000000000000
	type:	2e54b353-1271-4842-806f-e436d6af6985
		(2e54b353-1271-4842-806f-e436d6af6985)
	guid:	0c4cd076-a05d-4b41-a482-3306a31a034d
  2	0x00002000	0x00003fff	""
	attrs:	0x0000000000000000
	type:	bc13c2ff-59e6-4262-a352-b275fd6f7172
		(bc13c2ff-59e6-4262-a352-b275fd6f7172)
	guid:	048b83df-86ce-4a1f-a48f-103350b1667a
  3	0x00004000	0x00095fff	""
	attrs:	0x0000000000000000
	type:	0fc63daf-8483-4772-8e79-3d69d8477de4
		(linux)
	guid:	84f09457-f4a4-42c9-8d7b-e5e04d9766e1
  4	0x00096000	0x0748b7ff	""
	attrs:	0x0000000000000000
	type:	0fc63daf-8483-4772-8e79-3d69d8477de4
		(linux)
	guid:	6df36844-5180-4485-8817-ad8053dde054

Files on the third partition can be listed with:

StarFive #ls mmc 1:3

   150071   u-boot-spl.bin.normal.out
  1277629   u-boot.itb

2 file(s), 0 dir(s)

Flashing the firmware

With the files located, they can be loaded into memory, then written to the SPI:

First the SPL can be loaded with:

StarFive #load mmc 1:3 $kernel_addr_r u-boot-spl.bin.normal.out

150071 bytes read in 9 ms (15.9 MiB/s)

Then it can be written to the SPI with:

StarFive #sf update $kernel_addr_r 0 $filesize

device 0 offset 0x0, size 0x24a37
150071 bytes written, 0 bytes skipped in 0.793s, speed 193056 B/s

This process can be repeated for U-Boot, with an offset:

StarFive #load mmc 1:3 $kernel_addr_r u-boot.itb

1277629 bytes read in 56 ms (21.8 MiB/s)

StarFive #sf update $kernel_addr_r 0x100000 $filesize

device 0 offset 0x100000, size 0x137ebd
1183421 bytes written, 94208 bytes skipped in 9.103s, speed 143673 B/s

UART method

First, gather the following firmware files from the latest VisionFive2 software release

Second, calculate their CRC-32 with /usr/bin/crc32 (provided by dev-perl/Archive-Zip) on the host, results might defer from what is show here:

user $crc32 u-boot-spl.bin.normal.out visionfive2_fw_payload.img

4f92e463        u-boot-spl.bin.normal.out
6949ec27        visionfive2_fw_payload.img

Third, ensure the StarFive VisionFive 2 is set up to boot off the onboard SPI Flash memory: both RGPIO_0 and RGPIO_1 switches must be set to High. Once done power the board on and the U-Boot command prompt should be reached after a few seconds. From that prompt there, run the following command to initialize a file transfer via the Y-Modem protocol (calculates a CRC for each chunk of transferred data to ensure no corruption has occurred):

StarFive #loady

## Ready for binary (ymodem) download to 0x60000000 at 115200 bps...
CCCCC

At this point, use Ctrl+A then S in Minicom to enter the file transfer menu, then select Ymodem, then a single firmware file of your choice (beginning with u-boot-spl.bin.normal.out or visionfive2_fw_payload.img is not important as long as both are processed) and wait for the transfer to complete.

StarFive #loady

## Ready for binary (ymodem) download to 0x60000000 at 115200 bps...                                                                                                                                                               
CC0(STX)/0(CAN) packets, 6 retries
## Total Size      = 0x00025a30 = 154160 Bytes

At this point the firmware payload lies in board's RAM but remains to be written on the SPI flash memory. Before committing it to the SPI flash memory, check the firmware payload's CRC-32 as it is seen on the StarFive VisionFive 2 board (the result should match what has been computed on the host):

StarFive #crc32 $loadaddr $filesize

crc32 for 60000000 ... 60025a2f ==> 4f92e463

Tip
$filesize is a shell variable automatically initialized when the transfer completes. A couple of shell variables like $loadaddr are preset at system startup. To see all defined variables use the shell command: printenv.

If the CRC-32 value calculated on the board matches the one calculated on the host, the firmware file contents can be comitted to the onboard SPI flash memory. Depending on which firmware file has been transferred, the command to use is:

For u-boot-spl.bin.normal.out:

StarFive #sf update $loadaddr 0x0 $filesize

For visionfive2_fw_payload.img:

StarFive #sf update $loadaddr 0x100000 $filesize

Repeat the operations above for the second firmware file. Once both firmware files have been transferred and committed to the onboard SPI flash memory, powercycle the board and the U-Boot command prompt should show up again after a couple of seconds. In the case some badluck would have happened making the board unable to boot on the onboard SPI flash memory, it is possible to recover from the situation using recovery boot image, see section First aid kit.

Build a system image

Warning
The BSP (VisionFive 2 SDK) is outdated and not very actively maintained so it will not be used here. However there is valuable valuable information inside.

There are two philosophies when it comes to installing an operating system onto a SBC / embedded device such as the VisionFive 2.

The first involves writing a static system image, typically a squashfs, onto some form of media (typically eMMC, though NVMe is on the rise). The initramfs is able to load this image into RAM and use it as a rootfs; when an update is required the whole image is replaced as a single operation. There are advantages to this approach, particularly for embedded devices where users are not expected to update individual packages and recovery 'in-the-field' may be impractical, or to provide an A/B partition layout for updates. Systems configured in this way are also resilient when it comes to unexpected shutdowns as the only time that the rootfs storage volume is performing writes is when this image is being updated. This approach will be described as an embedded installation going forward and called out where possible.

The second approach involves writing a rootfs onto some accessible storage media the device and using a package manager to install and update packages as required. For a Gentoo system this approach is more flexible and allows for a more traditional Linux experience, but requires more effort to set up and maintain. This approach will be described as a traditional installation going forward and called out where possible and will be the taken path for the next sections.

The process of generating a system image for a Gentoo installation on the VisionFive 2 may be broadly described as follows:

Check out the required files (pre-built Gentoo stage 3, OpenSBI, U-Boot, etc) ;
Build a cross-compiler and a QEMU emulator
Generate a Gentoo rootfs
Generate a Linux kernel and ramdisk (U-Boot format conversion required)
Flash the rootfs on some SD Card
Try to boot the machine

Download an existing RISC-V stage 3

Tip
To see all the available images: https://gentoo.osuosl.org/releases/riscv/autobuilds

Rather than building a full cross-dev environment and the subsequent stages archives with Catalyst, Gentoo offers some pre-built tarballs for RISC-V machines that avoids some tedious steps.

To begin with, grab a Gentoo stage 3 tarball from https://www.gentoo.org/downloads/#riscv.

For the rest of the explanations, the systemd flavor of rv64gc/lp64d will be used.

To download one of the available images, a tool like net-misc/aria2 or net-misc/wget can be used. E.g.:

root #

aria2c -x16 -s16 https://gentoo.osuosl.org/releases/riscv/autobuilds/20241213T160325Z/stage3-rv64_lp64d-systemd-20241213T160325Z.tar.xz

Create the root filesystem

It is possible to build the root filesystem via two options:

Directly use a prebuilt Gentoo stage 3 archive (the path taken here) ;
Build all stages from scratch via [Catalyst] and a crossdev environment

Extract and prepare the pre-built stage 3 archive

Important
Quoting the download page: Multilib stages include toolchain support for all 64-bit and 32-bit ABI and are based on lp64d. They are mostly useful for development and testing purposes.

Simply extract the stage 3 archive downloaded a few paragraphs ago:

root #

cd ${RISCV_WORKDIR_PATH}

root #

tar -Jxpvf stage3-*.tar.xz -C ${RISCV_ROOTFS_PATH}

From there, bind-mount the Gentoo repository. To avoid unfortunate incident it is advised to bind-mount as read-only:

root #

mkdir -p ${RISCV_ROOTFS_PATH}/var/db/repos/gentoo

root #

mount -o bind,ro /var/db/repos/gentoo ${RISCV_ROOTFS_PATH}/var/db/repos/gentoo

Same story for the Linux kernel but as read-write this time. To use the same kernel version in use on the host:

root #

mkdir -p ${RISCV_ROOTFS_PATH}/usr/src/linux

root #

mount -o bind /usr/src/linux ${RISCV_ROOTFS_PATH}/usr/src/linux

Refresh the root filesystem

Warning
Stick with the method exposed here and do not mess up with ${SYSROOT}, ${ROOT} or ${PORTAGE_CONFIGROOT} unless having the luxury of having a host system being broken beyond all repair as some critical system binaries like /lib/ld-linux.so.2 can be overwritten. If this would happen, restoring from a recent backup (e.g. virtual machine snapshot, filesystem snapshot or copy) would be the only way out!

From there two strategies are offered:

All @system packages are cross-built as binaries packages (and stored within the cross-compilation environment in ${RISCV_XDEV_ROOT}/var/db/pkg) then re-emerged in the target environment (${RISCV_XDEV_ROOT}). This approach is interesting if rebuilding the very same target environment multiple time is expected as it can save a lot of time by avoiding re-compiling the same packages over and over again.
All @system packages are cross-built, deployed in the target (${RISCV_ROOTFS_PATH}) environment and stored as binary packages within the target environment in ${RISCV_ROOTFS_PATH}/var/db/pkg (unless buildpkg is removed from the variable FEATURES).

To build everything within the cross-compilation environment then deploying the produced binary packages:

root #${RISCV_XARCH}-emerge --keep-going --jobs=$(nproc) -e @system

root #ROOT=${RISCV_ROOTFS_PATH} ${RISCV_XARCH}-emerge --usepkgonly --jobs=$(nproc) -e @system

If working directly within the target environment is preferred:

root #ROOT=${RISCV_ROOTFS_PATH} ${RISCV_XARCH}-emerge --keep-going --jobs=$(nproc) -e @system

As a suitable bare minimum the following should be refreshed:

Any dependency hell or failure can be resolved by playing around with ${RISCV_XDEV_ROOT}/etc/portage/package.* directories content as usually done on the host system. Good luck! Once this stage is done go ahead to the next section.

Set the system profile for the target environment

Important
Choose the same profile than the one chosen for the cross-build environment!

The very next step is to define the system profile for the target environment. The task is easy as both profiles must match: if the profile used for the cross-build environment is default/linux/riscv/23.0/rv64/lp64d (stable) then the profile to set for the target environment must also be default/linux/riscv/23.0/rv64/lp64d (stable) (or 35).

root #

PORTAGE_CONFIGROOT=${RISCV_ROOTFS_PATH} eselect profile list | grep 23.0

  [28]  default/linux/riscv/23.0/rv64/lp64d (stable)
  [29]  default/linux/riscv/23.0/rv64/lp64d/desktop (dev)
  [30]  default/linux/riscv/23.0/rv64/lp64d/desktop/gnome (dev)
  [31]  default/linux/riscv/23.0/rv64/lp64d/desktop/gnome/systemd (dev)
  [32]  default/linux/riscv/23.0/rv64/lp64d/desktop/plasma (dev)
  [33]  default/linux/riscv/23.0/rv64/lp64d/desktop/plasma/systemd (dev)
  [34]  default/linux/riscv/23.0/rv64/lp64d/desktop/systemd (dev)
  [35]  default/linux/riscv/23.0/rv64/lp64d/systemd (stable)
  [36]  default/linux/riscv/23.0/rv64/lp64 (stable)
  [37]  default/linux/riscv/23.0/rv64/lp64/desktop (dev)
  [38]  default/linux/riscv/23.0/rv64/lp64/desktop/gnome (dev)
  [39]  default/linux/riscv/23.0/rv64/lp64/desktop/gnome/systemd (dev)
  [40]  default/linux/riscv/23.0/rv64/lp64/desktop/plasma (dev)
  [41]  default/linux/riscv/23.0/rv64/lp64/desktop/plasma/systemd (dev)
  [42]  default/linux/riscv/23.0/rv64/lp64/desktop/systemd (dev)
  [43]  default/linux/riscv/23.0/rv64/lp64/systemd (stable)
  [44]  default/linux/riscv/23.0/rv64/multilib (exp)
  [45]  default/linux/riscv/23.0/rv64/multilib/systemd (exp)
  [46]  default/linux/riscv/23.0/rv32/ilp32d (exp)
  [47]  default/linux/riscv/23.0/rv32/ilp32d/systemd (exp)
  [48]  default/linux/riscv/23.0/rv32/ilp32 (exp)
  [49]  default/linux/riscv/23.0/rv32/ilp32/systemd (exp)
  [50]  default/linux/riscv/23.0/rv64/split-usr/lp64d (stable)
  [51]  default/linux/riscv/23.0/rv64/split-usr/lp64d/desktop (dev)
  [52]  default/linux/riscv/23.0/rv64/split-usr/lp64d/desktop/gnome (dev)
  [53]  default/linux/riscv/23.0/rv64/split-usr/lp64d/desktop/plasma (dev)
  [54]  default/linux/riscv/23.0/rv64/split-usr/lp64 (stable)
  [55]  default/linux/riscv/23.0/rv64/split-usr/lp64/desktop (dev)
  [56]  default/linux/riscv/23.0/rv64/split-usr/lp64/desktop/gnome (dev)
  [57]  default/linux/riscv/23.0/rv64/split-usr/lp64/desktop/plasma (dev)
  [58]  default/linux/riscv/23.0/rv64/split-usr/multilib (exp)
  [59]  default/linux/riscv/23.0/rv32/split-usr/ilp32d (exp)
  [60]  default/linux/riscv/23.0/rv32/split-usr/ilp32 (exp)
  [63]  default/linux/riscv/23.0/rv64/lp64d/musl (dev)
  [64]  default/linux/riscv/23.0/rv64/lp64/musl (dev)
  [65]  default/linux/riscv/23.0/rv64/split-usr/lp64d/musl (dev)
  [66]  default/linux/riscv/23.0/rv64/split-usr/lp64/musl (dev)
  [67]  default/linux/riscv/23.0/rv32/ilp32d/musl (exp)
  [68]  default/linux/riscv/23.0/rv32/ilp32/musl (exp)
  [69]  default/linux/riscv/23.0/rv32/split-usr/ilp32d/musl (exp)
  [70]  default/linux/riscv/23.0/rv32/split-usr/ilp32/musl (exp)

For example the following will select default/linux/riscv/23.0/rv64/lp64d (stable) in the target environment (pay attention to the environment variable name):

root #PORTAGE_CONFIGROOT=${RISCV_ROOTFS_PATH} eselect profile set 35

Prepare the RISC-V root filesystem for chrooting

Start by emerging app-emulation/qemu into the target from the pre-built binary package created in the prerequisites section:

root #

ROOT=${RISCV_ROOTFS_PATH} emerge --usepkgonly --oneshot --nodeps qemu

For convenience, while being outside the target, copy the file /etc/resolv.conf in the target:

root #

cp /etc/resolv.conf ${RISCV_ROOTFS_PATH}/etc

Then bind-mount all required (pseudo-)filesystems in the target:

root #

cd ${RISCV_ROOTFS_PATH}

root #

mount --bind /proc proc

root #

mount --bind /dev dev

root #

mount --bind /dev/pts dev/pts

The last step is to chroot in the target and change the root password:

root #

chroot . /bin/bash --login

root #

passwd root

All of the puzzle pieces are in place and incidentally the RISC-V binaries are runnable inside the chrooted environment from a X86/64 machine.

Customize and configure the RISC-V stage3

Tip
For a first time keep a lean environment: the less packages are emerged, the lower chances are to see breakages.

Some additional packages are required: sys-apps/dtc, dev-embedded/u-boot-tools and sys-kernel/dracut. Emerge them directly on the host:

root #emerge --ask sys-apps/dtc dev-embedded/u-boot-tools sys-kernel/dracut

Then proceed with a typical Stage 3 customization and emerge whatever package is needed (outside of Kernel and Bootloader) as seen before:

root #

${RISCV_XARCH}-emerge pkg1 pkg2 pkg3 ...

root #

ROOT=${RISCV_ROOTFS_PATH} ${RISCV_XARCH}-emerge --usepkgonly pkg1 pkg2 pkg3 ...

or:

root #

ROOT=${RISCV_ROOTFS_PATH} ${RISCV_XARCH}-emerge pkg1 pkg2 pkg3 ...

Build the kernel

Note
There are some out-of-tree kernel modules (jpu/venc/vdec) that should be installed in addition to this kernel. These modules are available from the VisionFive 2 soft_3rdpart repo, or by emerging media-video/vf2vpudev from the bingch overlay

While QEMU can be used to build the kernel, it's extremely slow compared to using a cross-compiling toolchain.

The kernel could be cross-built directly in the kernel source dir on the host, but it's best to copy the sources into the crossdev environment, so the host kernel config is untouched:

root #cp -a /usr/src/linux /usr/riscv64-unknown-linux-gnu/usr/src/linux

In this guide, config specifically for this board will be used. Advanced users can start from the defconfig.

To perform a clean build: