Add RK356x bare-metal support and board-scoped BL31/U-Boot chainloading

[hqnicolas]

Summary

One thing that really bothers me is the SPI-NOR firmware provided by board manufacturers.
I don't like the idea of ​​running something that has been pre-compiled.
I saw an opportunity in your project to include SPI-NOR NVMe boot capabilities,
allowing NVMe drives to be booted using open-source U-Boot.

https://wiki.radxa.com/Rock3/install/spi

It adds three explicit RK356x board targets:

• Firefly ROC-RK3566-PC (roc3566)
• Youyeetoo YY3568 (yy3568)
• Radxa ROCK 3A (rock3a)

YY3568 and ROCK 3A additionally receive optional, isolated BL31/U-Boot chainloader variants intended for booting Linux or an AArch64 EFI application from NVMe, removable SD, USB mass storage, or eMMC.

The chainloader is opt-in and board-scoped. Existing normal/demo images continue using the current FUEFI payload interface.

Bare-metal RK356x support

The shared src/rk356x/ platform implements:

• RK356x CRU, SGRF, GPIO and DRAM discovery
• UART2 M0 at 1.5 Mbaud
• Target-specific MMU and memory layout
• VOP2 and HDMI initialization
• EDID parsing and mode selection through 4K30
• XRGB8888 framebuffer reporting
• USB2 OHCI initialization
• HID boot-keyboard discovery and input
• FUEFI memory, display, input, DTB and reset services
• Reset-to-MaskROM recovery

Board-specific wiring remains in small descriptors and DTBs, preventing GPIO, USB topology and identity data from leaking between boards.

New normal/demo outputs include:

• roc3566.bin and demo_roc3566.bin
• yy3568.bin and demo_yy3568.bin
• rock3a.bin and demo_rock3a.bin
• Corresponding RKNS v2 SD images

Optional BL31/U-Boot chainloader

The shared src/chainload/ layer provides:

• FIT parsing and validation
• Required SHA-256 verification
• Split BL31 segment loading
• Address and overlap validation
• TF-A parameter construction
• Cache/MMU teardown
• BL31-to-U-Boot EL2 handoff
• UART error reporting and MaskROM recovery

Every supported chainloader board has an independent validated manifest containing its U-Boot source, overlay, load addresses, media policy and artifact names.

Current backends are:

• YY3568: pinned Radxa vendor U-Boot
• ROCK 3A: pinned mainline U-Boot v2026.04
• Both use the pinned RK3568 BL31 v1.46 binary

The automatic U-Boot policy is board-scoped and searches:

NVMe -> removable SD -> USB mass storage -> eMMC

The dedicated first stage does not initialize HDMI, framebuffer, USB host, filesystems or storage controllers. Those responsibilities remain with U-Boot.

SPI-NOR and eMMC installation

The chainloader can be packaged for:

• MaskROM USB loading
• RKNS v2 SD images
• eMMC user-area ID blocks at LBA 0x40
• Rockchip SPI-NOR layout at offset zero

A guarded Linux installer uses pinned xrock and rkdeveloptool revisions. Before writing, it:

• Requires exactly one RK356x device
• Requires an exact board/media confirmation
• Loads the DDR and USB-plug helpers into RAM
• Selects the manifest-declared storage device
• Checks detected capacity
• Backs up the affected storage
• Rejects MBR/GPT overlap for eMMC
• Prevents cross-board backup restoration
• Writes only the required range
• Reads the result back and verifies it byte-for-byte
• Avoids whole-device erase commands

CI/CD and releases

This also adds:

• Clean multi-board CI
• Separate manifest-driven chainloader builds
• Offline host unit tests
• FIT, address-policy and media-format validation
• Deterministic release packaging
• Strict SemVer tag releases
• Internal and top-level SHA-256 files
• Five board-specific release archives

Release archives are generated for:

• Pinebook Pro
• Cool-Pi Genbook
• ROC-RK3566-PC
• YY3568
• ROCK 3A

Host executables, Orange Pi 5 artifacts, object files and unrelated vendor blobs are excluded.

Documentation

The documentation now distinguishes:

• Normal bare-metal firmware
• Standalone demo firmware
• Appended EL2 payloads
• Optional BL31/U-Boot chainloading
• BootROM media selection
• U-Boot operating-system discovery
• Linux, EDK2 and OP-TEE responsibilities
• Safe SPI/eMMC installation and restoration
• Linux host setup with xrock, rkdeveloptool and restricted udev permissions
• The process for adding another collision-safe RK356x board

Compatibility

• Existing RK3399 and RK3588 targets and commands remain available.
• Normal RK356x firmware does not automatically become a U-Boot chainloader.
• ROC-RK3566-PC does not inherit YY3568 or ROCK 3A chainloading policy.
• No FUEFI opcode or structure layout was changed.
• U-Boot sources and objects are isolated under build/chainload/<board>/.
• Board-specific addresses, DTS overlays, GPIOs and media policy cannot be selected by another board manifest.

Automated validation

The following have been exercised in CI:

• make SHELL=/bin/bash check -j"$(nproc)"
• make chainload-check BOARD=yy3568
• make chainload-check BOARD=rock3a
• Normal/demo builds for existing and new targets
• FIT hashes, architecture, entries and memory bounds
• RKNS v2 and RK-SPI media generation
• Descriptor, EDID, HID and OHCI host tests
• Mocked backup, flashing, readback and restore tests
• Deterministic release archives and checksum verification
• Ubuntu-hosted and self-hosted Debian CI compatibility

Hardware validation still required

Before marking the new boards fully hardware-validated:

• Boot ROC-RK3566-PC normal/demo firmware through MaskROM and SD
• Boot YY3568 chainloader through USB, SD, eMMC and SPI NOR
• Boot ROCK 3A chainloader through USB, SD, eMMC and SPI NOR
• Verify UART, HDMI/EDID, framebuffer and USB keyboard
• Verify PCIe/NVMe discovery
• Boot Linux through extlinux
• Boot EFI/BOOT/BOOTAA64.EFI
• Confirm SPI priority and eMMC fallback
• Verify backup restoration and invalid-FIT recovery
• Save complete UART transcripts for both chainloader boards

Out of scope

This change does not add:

• Bare-metal PCIe or NVMe drivers
• Secure Boot or signed FIT keys
• OP-TEE/BL32 loading
• EDK2 firmware integration
• Network boot
• USB hubs or high-speed USB host controllers
• Linux storage or filesystem drivers in the first stage
• PMIC-controlled shutdown

[hqnicolas]

those interested in the project:
https://forum.armbian.com/topic/49775-board-bring-up-youyeetoo-yy3568-rockchip-rk3568/page/2/

[petabyt]

This is really cool! TBH though I think this pulls in enough external code (and seems like some LLM code?) that it would be better off as a separate repo.

You could include rk as a submodule if you need to depend on anything or you could just pull in firmware.h since that might be the only thing you to make it compatible. You can let me know if you think firmware.h/fuboot needs anything amended.

[petabyt]

Also I want to ask, what documentation/references did you use to create this? Did you use any uboot/linux/edk2 source code as reference?

[hqnicolas]

I brought everything from Armbian, this boards are enabled there, this week I bought two NVMe drives, and I'm going to use the two Rock-3A and YY3568 cards; it's actually code that I'll use myself.
I had no other way to boot NVME without recreating u-boot, so I'm pulling external dependencies.

[hqnicolas]

the repository will remain a fork of this project until someone needs to add other SPI-NOR chips.
the core idea of FUBS aims to eliminate reliance on legacy software stacks (like Linux, GNU, or LLVM)
I also believe that chainload should really be in an external repository

[petabyt]

Not exactly sure what you mean there but this repo has no FUBS dependency or any support for anything FUBS specific.

I would be okay with merging minimal support for rk356x and keeping Linux support stuff as part of an el2 payload binary.

[hqnicolas]

minimal support for rk356x applyed into: #3
this Chainloader for nvme was forked into another repo https://github.com/hqnicolas/RK-SPI-NOR-Chainloader