This repository produces several files that look bootable but have different roles. The distinction matters most when choosing an SD image.
| Model | Standalone? | Final program | Runtime storage drivers |
|---|---|---|---|
Firmware-only .bin or .img |
No | A separately appended FUEFI payload | No |
Demo .bin or .img |
Yes | The repository’s example EL2 payload | No |
| Board-enabled RK3568 chainloader | Yes | BL31 and U-Boot at EL2 | U-Boot provides them |
The normal bare-metal firmware is a hardware-initialization and service layer,
not an operating system or conventional storage bootloader. It initializes the
supported parts of the board, exposes FUEFI calls, and unconditionally looks
for a FuPayloadHeader immediately after the firmware image. A firmware-only
artifact has no such payload: when run by itself it reports Bad payload magic
and halts. It is distributed as a base for payload developers.
The demo artifact is the corresponding firmware with demo.bin appended. It
is the correct standalone image for initial hardware testing. The demo reports
the board, current exception level, video mode, DTB status, and memory map. It
also exercises input on boards where a USB keyboard driver is implemented.
The optional RK3568 chainloader is a separate build variant. It does not use the FUEFI payload path and deliberately excludes display, USB HID, and demo code. It validates a U-Boot FIT and enters BL31, which then starts U-Boot.
An SD image does not imply that the bare-metal firmware contains an SD/MMC driver. For the normal and demo flows, the immutable Rockchip BootROM reads the RKNS image from SD before this project’s code starts:
SD card
-> Rockchip BootROM reads the RKNS image
-> BootROM runs the image's DDR loader
-> BootROM loads the firmware or firmware+payload into RAM
-> this project's firmware initializes the supported hardware
-> jump to the appended payload, if present
Once control reaches this firmware, the SD card is only the delivery medium. The normal/demo firmware cannot mount its partitions or load another file from it. The same principle applies to direct MaskROM USB loading: USB transports the image into RAM, but it does not automatically provide a runtime USB host stack.
A FUEFI payload begins with the packed header described in src/firmware.h.
The supplied demo requests relocation to 0x00a00000 and runs at EL2. A custom
payload must use the selected board’s reviewed memory map and must not overlap
the firmware, stacks, shared/DMA arena, framebuffer, or MMIO.
The basic source-tree workflow is:
# Build the board firmware and your FUEFI-compatible payload first.
cat rock3a.bin my_payload.bin > my_rock3a.bin
# Package the combined binary, not the firmware-only binary.
./makeboot.out --v2 \
--ddr img/rk3568_ddr_1560MHz_v1.25.bin \
--os my_rock3a.bin -o my_rock3a.img
Use the DDR loader and RKNS version appropriate for the selected board. The
existing demo_<board>.bin and demo-image rules are the reference packaging
implementation.
A DTB is data passed to a payload. It can describe addresses, interrupts, GPIOs, regulators, clocks, and board identity, but it does not initialize a controller and it does not add a driver to the firmware. Rockchip BootROM does not read this project’s DTB.
There are therefore three separate questions for every device:
All three are required before a payload can rely on a DT-described peripheral. The minimal DTBs in this repository document the firmware contract; they are not replacements for the complete upstream Linux board DTBs.
The distinction is especially visible on RK3588. Its minimal SoC DTS lists
SDMMC and several USB controller placeholders, but several reg and status
properties are intentionally absent or commented out, and the current RK3588
firmware links no MMC, OHCI, xHCI, or USB-PHY driver. Those nodes do not provide
runtime SD or USB support. The Genbook demo is useful for UART, eDP/framebuffer,
DTB, memory-map, and EL2 validation; its keyboard prompt cannot currently
receive USB input.
RK356x normal firmware has a broader implemented service set: fixed-mode HDMI, framebuffer, polled OHCI boot-keyboard input, DTB, memory-map services, and reset-to-MaskROM. It still has no filesystem or runtime SD/eMMC/NVMe driver. See RK356x common bare-metal firmware for its exact memory, display, and input contract.
.img for a standalone first boot and hardware smoke test..bin as the base for a custom appended payload.