This page explains how to get Fedora running on the StarFive VisionFive 2 board.
Machine-specific instructions
For the most part you can just follow the generic instructions.
Requirements
Firmware
You need to replace the vendor firmware with the one built in Fedora. This version contains additional features and is based on a more recent U-Boot release.
Note that the firmware you will be installing can boot most modern UEFI-based distros (e.g. Ubuntu) just fine, but it cannot (at least out of the box) boot the vendor provided Debian-based image. It's always possible to revert back to the vendor firmware later if desired.
Firmware builds can be obtained from:
As of this writing, the most recent firmware build is:
The file you've just downloaded will be referred to as UBOOT.rpm below.
To extract the contents of the package, run:
$ rpm2cpio UBOOT.rpm | cpio -id
You can now update the board's SPI-NOR flash:
$ sudo flashcp -v usr/share/uboot/starfive_visionfive2/spl/u-boot-spl.bin.normal.out /dev/mtd0 Erasing blocks: 3/3 (100%) Writing data: 137k/137k (100%) Verifying data: 137k/137k (100%) $ sudo flashcp -v usr/share/uboot/starfive_visionfive2/u-boot.itb /dev/mtd2 Erasing blocks: 16/16 (100%) Writing data: 989k/989k (100%) Verifying data: 989k/989k (100%)
One last step is necessary to complete the upgrade. Reset the machine, but interrupt the boot process before any entry is chosen to get access to the U-Boot prompt. If you're having trouble with this part, disconnecting all storage devices could help.
At the U-Boot prompt, type the following commands:
StarFive # env default -f -a; env save ## Resetting to default environment Saving Environment to SPIFlash... Erasing SPI flash...Writing to SPI flash...done OK
You've now completed the firmware update process and can proceed with installing Fedora.
This is the simplest way to update the firmware, which works if you already have Linux running. For an alternative method, see below.
Post-installation tasks
Access U-Boot environment from Linux
Add the following the the /etc/fw_env.config file:
/dev/mtd1 0x0 0x10000
You will now be able to use fw_printenv and fw_setenv to manipulate the U-Boot environment from within Linux.
Additional information
Installing SPI-NOR firmware via UART boot mode
This method allows to boot upstream U-Boot SPL (XMODEM) and U-Boot proper (YMODEM) using your serial console. This is especially helpful is SPI-NOR content is damaged and the board no longer boots. Once booted you can flash SPI-NOR with a new firmware images.
SPI-NOR partitions:
$ cat /proc/mtd dev: size erasesize name mtd0: 00080000 00010000 "spl" mtd1: 00010000 00010000 "uboot-env" mtd2: 00400000 00010000 "uboot" mtd3: 00a00000 00010000 "reserved-data"
Make sure your board is powered down.
Connect UART-Serial to USB dongle to VF2 using GPIO headers (3V3):
- PIN 6: GND
- PIN 8: UART-TX
- PIN 10: UART-RX
More details here: https://doc-en.rvspace.org/VisionFive2/Quick_Start_Guide/VisionFive2_SDK_QSG/recovering_bootloader%20-%20vf2.html
Switch the board to UART boot mode:
1 (High) 0 (Low) ┌───────┐ ┌───────┐ │XXXXXXX│ │ │ RGPIO_1: 1 (H) └───────┘ └───────┘ ┌───────┐ ┌───────┐ │XXXXXXX│ │ │ RGPIO_0: 1 (H) └───────┘ └───────┘
More details here: https://doc-en.rvspace.org/VisionFive2/Boot_UG/VisionFive2_SDK_QSG/boot_mode_settings.html?hl=uart
Let's use microSD card with FAT or ext4 partition to store new firmware files:
u-boot-spl.bin.normal.out(U-Boot SPL)u-boot.itb(U-Boot, OpenSBI, DTB)
These are the files mentioned above.
Remove M.2 NVMe if installed. We don't want to have bootable media in any form otherwise Linux will boot before you can get to U-Boot prompt.
Insert the card to the board, and power it on.
You should see similar output:
(C)StarFive CCCCCCCCCCCCCCCCCCCCC
It will constantly write C.
Press CTRL-A S. You will see upload menu:
+-[Upload]--+ | zmodem | | ymodem | | xmodem | | kermit | | ascii | +-----------+
Select xmodem, then [Goto] button at the bottom. Select u-boot-spl.bin.normal.out using SPACE and then press the [Okay] button. It will start uploading the first binary:
+----------------[xmodem upload - Press CTRL-C to quit]----------------+ |Sending u-boot-spl.bin.normal.out, 1142 blocks: Give your local XMODEM| | receive command now. | |Xmodem sectors/kbytes sent: 414/51k | | | | | | | | | +----------------------------------------------------------------------+
Press any key once it's uploaded. Now you should see U-Boot SPL booted and C will continue to be printed out:
U-Boot SPL 2024.10 (Nov 07 2024 - 00:00:00 +0000) DDR version: dc2e84f0. Trying to boot from UART CCCCCCCCC
Now press CTRL-A S and select ymodem. This time we want to send u-boot.itb file. This file is large and thus will take a bit longer to upload.
+----------------[ymodem upload - Press CTRL-C to quit]----------------+ |Sending: u-boot.itb | |Bytes Sent:1151104 BPS:8710 | |Sending: | |Ymodem sectors/kbytes sent: 0/ 0k | |Transfer complete | | | | READY: press any key to continue... | +----------------------------------------------------------------------+
U-Boot will not find any bootable media and will drop you into the prompt.
Loading Boot0000 'mmc 1' failed Loading from BootNext failed, falling back to BootOrder Loading Boot0000 'mmc 1' failed EFI boot manager: Cannot load any image StarFive #
Check the content of microSD card:
StarFive # ls mmc 1:1
<DIR> 4096 .
<DIR> 4096 ..
<DIR> 16384 lost+found
1151019 u-boot.itb
146178 u-boot-spl.bin.normal.out
Update U-Boot SPL and U-Boot data:
sf probe
load mmc 1:1 ${loadaddr} u-boot-spl.bin.normal.out
setenv ldsize ${filesize}
sf update ${loadaddr} 0x0 ${ldsize}
load mmc 1:1 ${loadaddr} u-boot.itb
setenv ldsize ${filesize}
sf update ${loadaddr} 0x100000 ${ldsize}
We booted using UART mode with the same files thus we can update default U-Boot environment too:
# env default -a -f; env save ## Resetting to default environment Saving Environment to SPIFlash... Erasing SPI flash...Writing to SPI flash...done OK
Remove power cable and microSD card.
Switch back to SPI-NOR boot mode:
1 (High) 0 (Low) ┌───────┐ ┌───────┐ │ │ │XXXXXXX│ RGPIO_1: 1 (H) └───────┘ └───────┘ ┌───────┐ ┌───────┐ │ │ │XXXXXXX│ RGPIO_0: 1 (H) └───────┘ └───────┘
