Architectures/RISC-V/VisionFive2

This page provides instructions how to install Fedora 40 (or newer) on StarFive VisionFive 2 (JH7110) SBC. The instructions assume that main partitions will be on M.2 NVMe. microSD card is not required, but can be used to flash SPI-NOR firmware with a new U-Boot and OpenSBI.

This guide assumes that your host system is running Fedora 40 (or newer).

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"

[..]
partitions {
        compatible = "fixed-partitions";
        #address-cells = <1>;
        #size-cells = <1>;

        spl@0 {
                reg = <0x0 0x80000>;
        };
        uboot-env@f0000 {
                reg = <0xf0000 0x10000>;
        };
        uboot@100000 {
                reg = <0x100000 0x400000>;
        };
        reserved-data@600000 {
                reg = <0x600000 0xa00000>;
        };
};
[..]

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

Check dmesg or usb-devices output for a new device (could be written as "UART", "Serial", etc.).

Your USB serial port adapter will be /dev/ttyUSB<NUMBER> and /dev/serial/by-id/<NAME>. The latter name is generated base d on vendor, product name, serial code of your USB serial port adapter.

These devices are in dialout group. If you don't want to use sudo and your user to this group:

usermod -aG dialout <USERNAME>

We will use minicom for serial console. Let's launch it with minicom -s for setup:

 +-----[configuration]------+
 | Filenames and paths      |
 | File transfer protocols  |
 | Serial port setup        |
 | Modem and dialing        |
 | Screen and keyboard      |
 | Save setup as dfl        |
 | Save setup as..          |
 | Exit                     |
 | Exit from Minicom        |
 +--------------------------+

Select Serial port setup. Press A and modify the path for your USB serial port adapter. Hit ENTER until you return to the original menu. Then choose Exit to start.

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) [REQUIRED]
• u-boot.itb (U-Boot, OpenSBI, DTB) [REQUIRED]
• uboot-env.bin (default U-Boot environment in binary format) [OPTIONAL]

All required files can be found in uboot-images-riscv64 (noarch) package. It's also installed in the disk image.

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. Enter directory were you have downloaded your U-Boot firmware files. Select u-boot-spl.bin.normal.out using SPACE and then active [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-rc2 (Aug 22 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
           65536 uboot-env.bin

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

Alternative would be to load uboot-env.bin from microSD card and write it out:

load mmc 1:1 ${loadaddr} uboot-env.bin
setenv ldsize ${filesize}
sf update ${loadaddr} 0xf0000 ${ldsize}

Let's shutdown the system for now with poweroff command. Remove power cable. Remove the microSD card. Switch to SPI-NOR boot mode:

 1 (High)  0 (Low)                
┌───────┐ ┌───────┐               
│       │ │XXXXXXX│ RGPIO_1: 1 (H)
└───────┘ └───────┘               
┌───────┐ ┌───────┐               
│       │ │XXXXXXX│ RGPIO_0: 1 (H)
└───────┘ └───────┘