rk2aw loader

rk2aw loader program can be used on various modern Rockchip SoCs to change apparent boot ROM bootloader load order from original and inflexible "SPI NOR flash -> eMMC -> SD card" to "SD card -> eMMC -> SPI NOR flash" and to implement robust, seamless A/B bootloader updates in SPI NOR flash with user selectable fallback (via a pre-boot menu).

Benefits of rk2aw

Major benefits:

Supported boards / SoCs

Basic support for any RK3399, RK3566, or RK3588 based device, and enhanced support for many existing Rockchip SoC based devices:

How rk2aw works

rk2aw extends BROM (boot ROM) with a simple user interface, that you can use to affect the boot process in various ways. Access to the user interface is board specific, but usually the menu is controlled via the same button you power on the device with, and feedback is provided by blinking an onboard LED.

If supported, rk2aw will first consult PMIC (power management IC) to check the power on reason. If power on was due to USB power plug in, rk2aw will hold boot in an initial fairly low power state, and it will just blink the indicator LED in a 1s period with 50% duty cycle, until one of these two things happen:

Absent any user interaction, rk2aw will try loading a bootloader from SD card, then from eMMC and last from SPI NOR flash. (this is a normal rk2aw boot mode)

The menu can be entered by holding the power button during powerup. First you'll see and indication that rk2aw is present and is detecting an intent to enter the boot menu (indicator LED will flash very fast for 1.5s). You can release the button at any time during this period to proceed with normal boot and to not enter the menu.

After 1.5s, rk2aw will indicate that you can release the button, by stopping the LED flashing. If you'll hold the button too long, you'll typically just force power off the board via a PMIC power key long press poweroff feature (typically after 6s). If you release the button before forced power off, indicator LED will flash N times quickly each second to indicate currently selected menu item.

Menu items have a fixed meaning:

  1. Perform a normal rk2aw boot.
  2. Boot from a primary bootloader on a boot device rk2aw was installed to (SPI NOR flash or eMMC). SD card boot will be skipped, even if there's a working bootloader there.
  3. Boot from a backup bootloader on a boot device rk2aw was installed to.
  4. Enter Rockchip mask ROM USB mode.

You can confirm the menu item by long pressing the power button. The same mechanism applies as for menu entry: fast flashing indicates that you should keep pressing the button, and you can release it any time after the flashing stops. Very long power key press will again cause a forced power off of the device. rk2aw waits until you release the power button. This is meant to make it compatible with bootloaders that have their own use for power button, like Levinboot. Without this feature, it would be hard for you to time the power button presses to make both rk2aw and Levinboot happy.

At this point, rk2aw is completely gone from the system, overwritten by whatever bootloader was now loaded by BROM to replace it, and perform the actual boot of the OS. rk2aw is not a memory resident software during the runtime of the OS.

Overall, this gives you great bootloader flexibility, safe bootloader updates and very simple recovery options. If bootloader update fails, you can just press a power button a bit longer and boot using a known working backup bootloader from SPI NOR flash. You can also easily test bootloader builds or recover the board by placing flashing bootloader to SD card and using it directly, without having to erase or disable your primary bootloader. It also frees you from all device specific, error prone hacks (shorting data pins, or clock signals to ground, for not too short, but not too long either, etc.) that are used by board makers to froce boot from SD card for recovery or bootloader installation purposes.

Basically, this makes Rockchip SoCs behave like Allwinner SoC's as far as boot order goes. Thus the name of the project. :)

Technical details

There are many boot block locations that Rockchip BROM tries to boot from. All these locations are tried by boot ROM in the given order:

(sector size is 512 bytes)

rk2aw is primarily meant to be flashed to the first boot location on SPI NOR flash, or if SPI NOR flash is absent, to the first boot location on eMMC.

That way it will always be executed by BROM immediately after powerup, before any other boot locations are tried. It will then make BROM try to boot from locations 1-5 of uSD card, 1-5 of eMMC, and 2-13 of SPI NOR flash (only when booted from SPI NOR flash) in that order.

Boot process is identical to a normal Rockchip SoC boot process. You flash TPL+SPL (idbloader.img) to a boot block and U-Boot (u-boot.itb) to a regular location. There are no special requirements or limits placed on the bootloader by rk2aw. rk2aw is completely transparent to the bootloader during the boot process.

Beware that U-Boot SPL has location of main U-Boot hardcoded in SPL code and optionally also in SPL device tree. If you want to have multiple U-Boot builds on a single storage device, you'll need to flash idbloader.img images to two different boot blocks, and point each SPL build to a unique location where you flashed each u-boot.itb image.

Typeical U-Boot builds configure SPL to look for u-boot.itb at sector 16384 of the same storage device SPL itself was loaded from (in case of SD card or eMMC).

For example, you can have this layout on SPI NOR flash:

rk2aw doesn't care, but U-Boot SPL must be able to locate the correct u-boot.itb.

rk2aw flashing tool automatically adjusts SPL device tree during flashing, to make U-Boot SPL find u-boot.itb at the location it was actually flashed to. You don't need to configure U-Boot build in any special way to use U-Boot with rk2aw "dual bootloader in SPI" setup.

On eMMC, or SD card you can use boot location 1 (sector 64) for your bootloader, so you don't need any special U-Boot configuration either. Default U-Boot build for your board will work fine.

Levinboot doesn't have these issues, because it's very lean. You can just flash it to any boot location directly, and that's it. It's a single image bootloader.


rk2aw builds can be downloaded from https://xff.cz/kernels/rk2aw/

Third-party resources

Author / Distribution

rk2aw was written by Ondrej Jirman <megi@xff.cz> 2023

See LICENSE file for licensing information.

See https://xnux.eu/log/ for various mostly Pinephone related low level development news.

PGP key: https://xff.cz/key.txt

You can donate money, if you appreciate the project: https://xnux.eu/contribute.html