proposals/01-riscv-visionfive2-disk-partition-layout.md

Disk image partition layout for the VisionFive 2 SBC

The VisionFive 2 SBC has two dip switches on board which dictate how the board boots. Two switches mean 4 combinations and by extension, 4 modes in which this SBC can boot. These modes are as follows:

Boot mode	RGPIO_0	RGPIO_1
QSPI flash (on-board)	0	0
SD Card	1	0
EMMC (add-on)	0	1
UART (firmware recovery)	1	1

NOTE: I don't have an EMMC module so I haven't tested the 3rd option of EMMC boot. But I changed the dip switches to boot from EMMC and it refused to boot because the EMMC flash module was not detected. Based on that, I can conclude that SD Card boot and EMMC boot behave the same way, the only difference being where the board firmware + OS are being read from.

Instead of thinking of this as "Boot from SD or EMMC", think of these boot modes more like "Where the ZSBL (Zero^th^ Stage Bootloader) looks for the firmware: SPL (u-boot) fw_payload (OpenSBI)".

So, even when you have selected QSPI flash as the boot mode, it will read SPL and the fw_payload from there. But once the hardware initialization is complete, it will need a media to load the OS from. That can be either the SD Card, the EMMC flash or even an NVMe drive (support is not upstreamed yet!).

If the dip switches are set to boot either from the SD Card or from the EMMC flash, the partition table for the image that goes on the media in this case needs to have the following layout:

Partition	Start	End	Sectors	Size	Type
1	4096	8191	4096	2M	HiFive BBL
2	8192	16383	8192	4M	HiFive FSBL
3	16384	1064959	1048576	512M	EFI System
4	1064960	NA	NA	NA	Linux filesystem

Since partitions 1 and 2 contain board specific files (SPL and fw_payload respectively), creating a generic image with this obviously not possible.

With a generic image, we can go with the conventional PC-style disk layout where we have a 512M partition for /boot and rest of the disk space for / (root). The board specific files are already on the board.

So now, two routes exist for us and I will lay out advantages and disadvantages for the generic route. You can assume the inverse to be true for the board-specific-image route.

Types of boards

On a high level, there are two types of boards. This is categorized based on how much support for them is present in upstream. These categories are as follows:

1. Zero or "barely working" support in upstream: Any board that requires vendor kernel and/or vendor firmware to even boot will obviously need a board-specific image. (Supporting such boards will be a decision based on several aspects like 'community requests for supporting', 'any possible upstream effort', 'board provided to us (Rocky Linux) for supporting it', etc.)
2. Full or "everything except GPU and other specialized hardware works" support in upstream: Some boards, like the HiFive Unleashed, HiFive Unmatched and the StarFive VisionFive 2 can boot with unpatched upstream sources.

Since building a generic image for the first category of boards is by definition not possible, those are not considered for this proposal. This proposal is for generating images for the second category of boards, which enjoy full or nice upstream support.

Advantages

1. Less storage + CDN cost.
2. Only one image to maintain, test and fix.
3. Less support headache.
4. Our image boots off SD, MMC and NVMe. Maybe over PXE too! (MMC and NVMe support will obviously depend on board I/O and firmware support.)

Disadvantages

1. The firmware on the QSPI flash is not "prod ready". This obviously means that the user needs to be informed that their board firmware needs to be flashed. IF DONE INCORRECTLY THE BOARD MAY BECOME A BRICK! ("Prod ready" means any distro can depend on it to base their image off of.)
2. We need the user to have access to the Serial console to issue some uboot related commands that enable a boot order of 'sd emmc nvme pxe dhcp'. Not everyone has a USB-to-TTL cable though.
3. Adding features like GPU support (in the kernel), PCIe support (in u-boot), etc will be slower because, well, we are relying on upstream, not the vendor.
4. New firmware versions should be delivered somehow. If going the generic image route, it needs to be done, preferably, using the fwupd mechanism. If the SBC-specific route is taken, we need to dd partitions 1 and 2.