From acc2b7a432d9599fc847ed34b7d4efe11ac6d518 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Aur=C3=A9lio?= Date: Sun, 12 Jul 2026 12:44:36 +0000 Subject: [PATCH] docs: add Bootlin article on Rockchip recovery boot Reference for MaskROM mode, rockUSB protocol, and rkdeveloptool usage. Relevant for future Rockchip platform support and recovery mechanisms. --- .../bootlin-recovery-boot-rockchip.md | 229 ++++++++++++++++++ 1 file changed, 229 insertions(+) create mode 100644 docs/references/bootlin-recovery-boot-rockchip.md diff --git a/docs/references/bootlin-recovery-boot-rockchip.md b/docs/references/bootlin-recovery-boot-rockchip.md new file mode 100644 index 000000000..ff9afd679 --- /dev/null +++ b/docs/references/bootlin-recovery-boot-rockchip.md @@ -0,0 +1,229 @@ +Skip to content + +[![Bootlin](https://bootlin.com/wp-content/uploads/2018/01/bootlin-logo-240.png)](https://bootlin.com/) + +[Bootlin](https://bootlin.com/) + +Embedded Linux and kernel engineering + +Menu + + * [Home](https://bootlin.com) + * [Engineering](https://bootlin.com/engineering/) + * [Training](https://bootlin.com/training/) + * [Docs](https://bootlin.com/docs/) + * [Community](https://bootlin.com/community/) + * [Company](https://bootlin.com/company/) + * [Youtube![Youtube](https://bootlin.com/wp-content/uploads/2025/06/youtube-24x24.png)](https://www.youtube.com/Bootlin) + * [LinkedIn![LinkedIn](https://bootlin.com/wp-content/uploads/2021/03/linkedin-icon-rounded-24x24.png)](https://www.linkedin.com/company/bootlin) + + + +# Recovery boot on Rockchip SoCs + +Rockchip is a well-known silicon vendor whose System-on-Chips (SoCs) are integrated in a wide range of embedded Linux systems. For example, [Pine64](https://pine64.org), a company manufacturing embedded devices targeted for the Open Source community uses the [RK3399](https://www.rock-chips.com/a/en/products/RK33_Series/2016/0419/758.html) for its [PinePhone Pro](https://pine64.org/devices/pinephone_pro/), and the [RK3566](https://www.rock-chips.com/a/en/products/RK35_Series/2021/0113/1274.html) for its [PineTab 2](https://pine64.org/devices/pinetab2/). Rockchip SoCs implement a rather powerful recovery bootflow. + +Unfortunately, that capability is poorly documented, and the tooling available is fragmented and only partially open source. + +The aim of this article is to present this capability and give a step-by-step guide to using it. + +# The Rockchip BootROM + +Like all SoCs, the ones Rockchip produces have a well-defined boot sequence whose goal is to load the bootloader and firmwares from storage into main memory. This is implemented by Rockchip in the SoCs' bootROM, and described in [this Rockchip wiki page](https://opensource.rock-chips.com/wiki_Boot_option). + +A clearer description is provided for the RK3399 on the [Pine64 wiki](https://wiki.pine64.org/wiki/RK3399_boot_sequence). Importantly, this wiki mentions "USB gadget boot", which is more commonly referred to as "MaskROM mode", and is common to a large selection of Rockchip SoCs. + +## MaskROM mode + +As mentioned in the Pine64 wiki, the Rockchip bootROM defaults to MaskROM mode once it has failed loading the second stage from any of its hardcoded boot locations. In this mode, it will expose a USB device over its USB OTG interface, identifiable through Rockchip's Vendor ID, which, as can be seen in [this list](https://www.usb.org/sites/default/files/vendor_ids01312025.pdf) from the [USB Implementers Forum](https://www.usb.org/developers), is `8711/0x2207`: + + + lsusb -d '2207:' + Bus 003 Device 063: ID 2207:330c Fuzhou Rockchip Electronics Company RK3399 in Mask ROM mode + +That interface exposes 2 **Vendor control requests** : + + * `0x471`, which will load code into the SRAM and execute it before returning to the bootROM + * `0x472`, which will load code into the DRAM and jump to it + + + +The first is usually used to load a DRAM initialization binary, while the second one is used to start the rest of the boot process. This is no different from a normal boot, the binaries are simply being loaded into RAM over the USB interface using the capability exposed by the bootROM. For each supported SoC, [Rockchip provides](https://github.com/rockchip-linux/rkbin/tree/master) binaries that can be used for each step: + + * * `_ddr__.bin` for `0x471` e. g. [rk3399_ddr_800MHz_v1.30.bin](https://github.com/rockchip-linux/rkbin/blob/master/bin/rk33/rk3399_ddr_800MHz_v1.30.bin) + * `_usbplug_.bin` for `0x472` e.g. [rk3399_usbplug_v1.30.bin](https://github.com/rockchip-linux/rkbin/blob/master/bin/rk33/rk3399_usbplug_v1.30.bin) + + + +As explained above, the `_ddr__.bin` binaries are responsible for DRAM initialization. +`_usbplug_.bin` is the more interesting of the two, and the binary that implements the next stage of the recovery boot. + +# Usbplug & the rockUSB protocol + +The next stage in the Rockchip recovery boot flow continues to happens over USB, but uses opCodes to issue commands in accordance with the vendor-specific [rockUSB](https://opensource.rock-chips.com/wiki_Rockusb) protocol, which is summarily described on the Rockchip wiki. This protocol is not implemented in the ROM code, but in the custom [usbplug](https://github.com/rockchip-linux/rkbin/blob/master/bin/rk33/rk3399_usbplug_v1.30.bin) program, distributed by Rockchip in binary form. This is documented in a [readme](https://github.com/rockchip-linux/rkdeveloptool/blob/master/Readme.txt#L15) in the Rockchip client for rockUSB, [rkdeveloptool: ](https://github.com/rockchip-linux/rkdeveloptool) + +` sudo ./rkdeveloptool db RKXXLoader.bin //download usbplug to device` + +The "download usbplug to device" is terse and slightly misleading, but let's look at the [implementation](https://github.com/rockchip-linux/rkdeveloptool/blob/master/RKDevice.cpp#L510). In short, the software will parse the binary for an `ENTRY471` object, then use USB vendor request `0x471` to load it, wait, then do the same for an `ENTRY472` object and load it with the `0x472` USB vendor request. + +### The rockUSB clients + +Rockchip has open-sourced rkdeveloptool, which serves as a client both for the USB Vendor requests, and the rockUSB protocol. An alternative client called [xrock](https://github.com/xboot/xrock) is more actively maintained and slightly better documented. + +Neither of these clients implement the full list of opcodes they embed in their own source code. Because rkdeveloptool is the client officially supported by Rockchip and probably the one most used, this post will focus on using it rather than xrock. + +### Using rkdeveloptool + +rkdeveloptool refers to "RKXXLoader.bin" as its first argument, but this binary is absent from the Rockchip [rkbin repo](https://github.com/rockchip-linux/rkbin). From what we've read before, we can infer that it is generated from the DRAM initialization binary, and usbplug. Looking a bit though the repo shows that the [RKBOOT](https://github.com/rockchip-linux/rkbin/tree/master/RKBOOT) directory contains `.ini` files that look like recipes to generate the loader: + + + [CHIP_NAME] + NAME=RK330C + [VERSION] + MAJOR=1 + MINOR=30 + [CODE471_OPTION] + NUM=1 + Path1=bin/rk33/rk3399_ddr_800MHz_v1.30.bin + Sleep=1 + [CODE472_OPTION] + NUM=1 + Path1=bin/rk33/rk3399_usbplug_v1.30.bin + [LOADER_OPTION] + NUM=2 + LOADER1=FlashData + LOADER2=FlashBoot + FlashData=bin/rk33/rk3399_ddr_800MHz_v1.30.bin + FlashBoot=bin/rk33/rk3399_miniloader_v1.30.bin + [OUTPUT] + PATH=rk3399_loader_v1.30.130.bin + + +This is a configuration file for [rkbin/tools/boot_merger](https://github.com/rockchip-linux/rkbin/blob/master/tools/boot_merger), the sources of which can be found in Rockchip's [U-Boot](https://github.com/rockchip-linux/u-boot) tree, under [tools/rockchip/boot_merger.c](https://github.com/rockchip-linux/u-boot/blob/next-dev/tools/rockchip/boot_merger.c). + +### Putting it all together + +In summary, here's how to get an RK3399-based device ready to receive rockUSB commands from scratch: + + 1. Get the device into MaskROM mode by having it fail to load the second stage bootloader (e.g. by electrically disabling the SPI flash) + + $ lsusb -d '2207:' + Bus 003 Device 063: ID 2207:330c Fuzhou Rockchip Electronics Company RK3399 in Mask ROM mode + + 2. Build the loader by combining DDR init and `usbplug`: + + $ git clone https://github.com/rockchip-linux/rkbin.git + $ cd rkbin + $ ./tools/boot_merger RKBOOT/RK3399MINIALL.ini + $ cd .. + +Here, we use the pre-built `boot_merger` for simplicity, but we recommend using one built from the U-Boot source, especially if you build U-Boot tools as part of your build process. + 3. Build `rkdeveloptool`: + + $ cgit clone https://github.com/rockchip-linux/rkdeveloptool.git + $ cd rkdeveloptool + $ ./autogen.sh + $ ./configure + $ make + + 4. Enable rockUSB by downloading the previously built loader: + + $ sudo ./rkdeveloptool rci + Read Chip Info failed! + + $ sudo ./rkdeveloptool db ../rkbin/rk3399_loader_v1.30.130.bin + Downloading bootloader succeeded. + + 5. Run some rockUSB commands. Below, an example using `rci` (read chip info): + + $ sudo ./rkdeveloptool rci + Chip Info: 43 30 33 33 E9 F9 FF 7F F1 D1 BF EF FC F5 3E DB + +This prints out some information about the chip embedded by the manufacturer. Many more commands are available, including ones to write files to the boot medium. + + + +## Recovery boot flow + +The interesting aspect of `MaskROM` mode is the ability to boot over USB, even when all boot locations are corrupted. That is a perfect candidate to have a recovery mechanism when a device is bricked or during manufacturing or provisioning of new devices. Indeed, this has been proposed in [snagboot](https://github.com/bootlin/snagboot) to support recovery on [Rockchip-based devices](https://github.com/bootlin/snagboot/pull/56), by: + + * Loading the U-Boot Tertiary Program Loader (TPL), built from the Rockchip closed-source DDR init blob, as entry `0x471` + * Loading the U-Boot Secondary Program Loader (SPL) + U-Boot's FIT image as entry `0x472`. + + + +or: + + * Loading the U-Boot Tertiary Program Loader (TPL), built from the Rockchip closed-source DDR init blob, as entry `0x471` + * Loading a Direct Firmware Update (DFU)-enabled SPL as entry `0x472` + * Using DFU to load U-Boot proper into RAM + + + +# Conclusion + +Rockchip's SoCs embed a great recovery boot capability over USB, directly in their bootROM, as well as an interesting toolkit in the form of the rockUSB protocol and its implementation, `usbplug`. The former could be useful e.g. for automatic bootstrapping of Rockchip SoC-based devices from scratch over USB. + +![Olivier Benjamin](https://bootlin.com/wp-content/uploads/2024/10/cropped-olivier-benjamin-small-49x49.jpg)Author [Olivier Benjamin](https://bootlin.com/blog/author/olivier-benjamin/)Posted on [July 9, 2026July 9, 2026](https://bootlin.com/blog/recovery-boot-on-rockchip-socs/)Categories [Hardware](https://bootlin.com/blog/category/hardware/), [Technical](https://bootlin.com/blog/category/technical/)Tags [bootloader](https://bootlin.com/blog/tag/bootloader/), [rockchip](https://bootlin.com/blog/tag/rockchip/), [snagboot](https://bootlin.com/blog/tag/snagboot/) + +## Leave a Reply [Cancel reply](/blog/recovery-boot-on-rockchip-socs/#respond) + +Comment * + +Nickname + +## Post navigation + +[Previous Previous post: Updated OpenWrt support for STM32 platforms, OpenWrt 24.10.6 with ST BSP v6.2](https://bootlin.com/blog/updated-openwrt-support-for-stm32-platforms-openwrt-24-10-2-with-st-bsp-v6-2/) + +[Next Next post: Welcome to Paul Louvel and Diogo Ivo](https://bootlin.com/blog/welcome-to-paul-louvel-and-diogo-ivo/) + +Search for: Search + +## Next training sessions dates + +![Student penguins](/graphics/2penguins-students.png) [Embedded Linux](/training/embedded-linux/) +[Linux kernel](/training/kernel/) +[Buildroot](/training/buildroot/) +[Yocto / OpenEmbedded](/training/yocto/) +[Embedded Linux audio](/training/audio/) +[Real-time Linux with PREEMPT_RT](/training/preempt-rt) +[Debugging, profiling, tracing in Linux](/training/debugging) +[Embedded Linux Security](/training/security) +[Embedded Linux Networking](/training/networking) +[Linux graphics](/training/graphics/) + +## Useful links + +![French flag](/graphics/flag-fr.gif) [Version française](/fr/) +![Youtube](/graphics/youtube.png) [Youtube](https://www.youtube.com/@Bootlin) +![LinkedIn](/graphics/linkedin-icon-rounded.png) [LinkedIn](https://www.linkedin.com/company/bootlin) +![RSS icon](/graphics/rss.png) [ Follow new articles](/feed/rss/) + +## Recent articles + + * [Welcome to Paul Louvel and Diogo Ivo](https://bootlin.com/blog/welcome-to-paul-louvel-and-diogo-ivo/) + * [Recovery boot on Rockchip SoCs](https://bootlin.com/blog/recovery-boot-on-rockchip-socs/) + * [Updated OpenWrt support for STM32 platforms, OpenWrt 24.10.6 with ST BSP v6.2](https://bootlin.com/blog/updated-openwrt-support-for-stm32-platforms-openwrt-24-10-2-with-st-bsp-v6-2/) + * [Poison, redzones and shadows: inside KASAN](https://bootlin.com/blog/poison-redzones-and-shadows-inside-kasan/) + * [Feedback from Embedded Recipes 2026](https://bootlin.com/blog/feedback-embedded-recipes-2026/) + * [Embedded Linux Security training: materials available, new sessions open](https://bootlin.com/blog/embedded-linux-security-training-materials-available-new-sessions-open/) + * [yocto-kiss: new name, cleaner architecture, and ZynqMP support](https://bootlin.com/blog/yocto-kiss-new-name-cleaner-architecture-and-zynqmp-support/) + * [eBPF at LSFMMBPF 2026](https://bootlin.com/blog/ebpf-at-lsfmmbpf-2026/) + * [Linux 7.1 released, Bootlin contributions inside](https://bootlin.com/blog/linux-7-1-released-bootlin-contributions-inside/) + * [Updated Buildroot support for STM32MPU platforms, ST BSP v6.2](https://bootlin.com/blog/updated-buildroot-support-for-stm32mpu-platforms-st-bsp-v6-2/) + + + + * [Home](https://bootlin.com) + * [Engineering](https://bootlin.com/engineering/) + * [Training](https://bootlin.com/training/) + * [Docs](https://bootlin.com/docs/) + * [Community](https://bootlin.com/community/) + * [Company](https://bootlin.com/company/) + * [Youtube![Youtube](https://bootlin.com/wp-content/uploads/2025/06/youtube-24x24.png)](https://www.youtube.com/Bootlin) + * [LinkedIn![LinkedIn](https://bootlin.com/wp-content/uploads/2021/03/linkedin-icon-rounded-24x24.png)](https://www.linkedin.com/company/bootlin) + + + +[Bootlin](https://bootlin.com/) [Privacy Policy](https://bootlin.com/company/privacy-policy/) [ Proudly powered by WordPress ](https://wordpress.org/)