driver: add RKUSBMaskromDriver bootstrap driver #1721

Kwiboo · 2025-08-27T23:23:37Z

Description

Add a RKUSBMaskromDriver bootstrap driver with an accompanying rkusbmaskrom agent to support bootstrapping targets with Rockchip SoCs.

The rkusbmaskrom agent expects the target to be in MASKROM mode and send images to BootROM using vendor specific 0x471 and 0x472 control transfers, in 4 KiB chunks.

The first image is loaded to SRAM using 0x471 and is expected to initialize DRAM and then return back to BootROM.
A second image can then be loaded to start of DRAM using 0x472.

Related

Checklist

Documentation for the feature
The arguments and description in doc/configuration.rst have been updated
PR has been tested

Example usage

$ labgrid-client -v -c remote.yaml -p rk3528-radxa-e20c bootstrap u-boot-rockchip-usb472.bin
INFO               root: Selected role rk3528-radxa-e20c from configuration file
INFO         StepLogger:  → RKUSBMaskromDriver.load(filename='<path>/u-boot-rockchip-usb472.bin')
INFO    SSHConnection(h:   Created new SSH connection to noble
INFO    ManagedFile(loc:   Synchronizing <path>/u-boot-rockchip-usb471.bin to noble
INFO         StepLogger:   → ProcessWrapper.check_output(command=['rsync', ...])
INFO         StepLogger:   ← ProcessWrapper.check_output() result=b'' [0.073s]
INFO    ManagedFile(loc:   Synchronizing <path>/u-boot-rockchip-usb472.bin to noble
INFO         StepLogger:   → ProcessWrapper.check_output(command=['rsync', ...])
INFO         StepLogger:   ← ProcessWrapper.check_output() result=b'' [0.072s]
INFO         StepLogger:  ← RKUSBMaskromDriver.load() [3.001s]
INFO    SSHConnection(h:  Closing SSH connection to noble

$ labgrid-client -v -c remote.yaml -p rk3528-radxa-e20c console
INFO               root: Selected role rk3528-radxa-e20c from configuration file
INFO               root: microcom not available, using telnet instead
INFO               root: connecting to NetworkSerialPort(target=Target(name='rk3528-radxa-e20c', env=Environment(config_file='remote.yaml')), name='USBSerialPort', state=<BindingState.bound: 1>, avail=True, host='noble', port=57985, speed=1500000, protocol='rfc2217') calling telnet noble 57985
Connected to noble.
Escape character is '^]'.
DDR 56f70fd2ad huan.he 25/02/26-09:55:30,fwver: v1.11
LP4/4x derate e, other dram:1x trefi
ddrconfig:0
MID:0x6
LPDDR4, 324MHz
BW=32 Co=10 Bk=8 CS0 Row=16 CS=1 Die BW=16 Size=2048MB
...
out

U-Boot SPL 2025.10-rc2 (Aug 25 2025 - 22:27:40 +0000)
Trying to boot from RAM
## Checking hash(es) for config config-1 ... OK
## Checking hash(es) for Image atf-1 ... sha256+ OK
## Checking hash(es) for Image u-boot ... sha256+ OK
## Checking hash(es) for Image fdt-1 ... sha256+ OK
## Checking hash(es) for Image atf-2 ... sha256+ OK
## Checking hash(es) for Image atf-3 ... sha256+ OK
NOTICE:  BL31: v2.3():v2.3-912-gfe961b77f:derrick.huang, fwver: v1.20
NOTICE:  BL31: Built : 16:59:19, Mar 31 2025
INFO:    rk_otp_init finish!
INFO:    code: 0x28
INFO:    ARM GICv2 driver initialized
INFO:    nonboot_cpus_off: clst_st=0xc0e, core_st=0xe1e0 boot_cpu=0
INFO:    idle_st=0x0, pd_st=0x0
INFO:    Using opteed sec cpu_context!
INFO:    boot cpu mask: 1
INFO:    RK3528 SoC (0x101)
INFO:    BL31: Initializing runtime services
WARNING: No OPTEE provided by BL2 boot loader, Booting device without OPTEE initialization. SMC`s destined for OPTEE will return SMC_UNK
ERROR:   Error initializing runtime service opteed_fast
INFO:    BL31: Preparing for EL3 exit to normal world
INFO:    Entry point address = 0x800000
INFO:    SPSR = 0x3c9


U-Boot 2025.10-rc2 (Aug 25 2025 - 22:27:40 +0000)

Model: Radxa E20C
SoC:   RK3528A
DRAM:  2 GiB
Core:  197 devices, 32 uclasses, devicetree: separate
MMC:   mmc@ffbf0000: 0, mmc@ffc30000: 1
Loading Environment from nowhere... OK
In:    serial@ff9f0000
Out:   serial@ff9f0000
Err:   serial@ff9f0000
Net:   eth0: ethernet@ffbe0000
Hit any key to stop autoboot: 0
=>
telnet> quit
Connection closed.

codecov · 2025-08-28T16:39:29Z

Codecov Report

❌ Patch coverage is 72.51462% with 47 lines in your changes missing coverage. Please review.
✅ Project coverage is 45.8%. Comparing base (e9e43aa) to head (5af8184).
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
labgrid/util/agents/rkusbmaskrom.py	65.8%	44 Missing ⚠️
labgrid/driver/usbloader.py	92.6%	3 Missing ⚠️

Additional details and impacted files

@@           Coverage Diff            @@
##           master   #1721     +/-   ##
========================================
+ Coverage    45.4%   45.8%   +0.3%     
========================================
  Files         172     173      +1     
  Lines       13500   13670    +170     
========================================
+ Hits         6130    6261    +131     
- Misses       7370    7409     +39

Flag	Coverage Δ
3.10	`45.8% <72.5%> (+0.3%)`	⬆️
3.11	`45.8% <72.5%> (+0.3%)`	⬆️
3.12	`45.8% <72.5%> (+0.3%)`	⬆️
3.13	`45.7% <72.5%> (+0.3%)`	⬆️
3.9	`45.8% <72.3%> (+0.3%)`	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

doc/configuration.rst

labgrid/driver/usbloader.py

QSchulz · 2025-09-08T10:07:38Z

labgrid/util/agents/rkusbmaskrom.py

question: use snagboot instead?

bootlin/snagboot#56 brings Rockchip support to snagboot.

The benefit is that other SoC vendors are supported by snagboot so we could have a snagboot driver to support multiple SoC vendors at once in labgrid.

This would also stop reimplementing the rockusb protocol in yet another project (hello rkdeveloptool, rockusb from rockchiprs, rkflashtool, snagboot, ...).

This was briefly discussed with @a3f @jluebbe at OSSEU/ELCE this year. Talking with snagboot's maintainer, there are plans to merge the Rockchip support for snagboot very soon and do a release soon after.

question: use snagboot instead?

I will be using this agent/driver and not snagboot in my personal lab ;-)

bootlin/snagboot#56 brings Rockchip support to snagboot.

I will take a closer look little bit later and add some review comments, I can already see some issues in that implementation.

This would also stop reimplementing the rockusb protocol in yet another project (hello rkdeveloptool, rockusb from rockchiprs, rkflashtool, snagboot, ...).

All of those seem to have their own special issues, are not fully featured or can get stuck etc.
This driver works and only requires pyusb installed on the exporter, for my personal lab I do not want to deal with lots of third party tools ;-)

QSchulz · 2025-09-08T10:24:28Z

doc/configuration.rst

+         RKUSBMaskromDriver:
+           initial: 'rkmaskrom471'
+           image: 'rkmaskrom472'


question: is this compatible with Barebox?

Barebox seems to be generating only one binary which contains both "files". I think it'd make sense to support Barebox file format as well, which likely differs from U-Boot's (currently two separate files IIRC) or the binary generated by Rockchip's boot_merger?

@a3f any opinion on that maybe?

EDIT: I see that the next patch adds the implementation for reading the file from boot_merger, so I guess if we have a unique way of identifying Barebox's implementation that would work too. Still, wondering if we shouldn't simply use snagboot and implement stuff there if necessary?

Barebox seems to be generating only one binary which contains both "files". I think it'd make sense to support Barebox file format as well, which likely differs from U-Boot's (currently two separate files IIRC)

Barebox uses the IDBlock v2 format, i.e. same format that mkimage produce for TPL and SPL in U-Boot for RK35xx.
Will add an implementation for extracting images from the IDBlock v1 and v2 formats, thanks!

or the binary generated by Rockchip's boot_merger?

This format is supported with the second commit, one special thing that boot_merger does differently for RK35xx is that it adds an IDBlock v2 header for the 471 and 472 files referenced in the rkboot .ini-files.
However, this extra header does not seem to be required on all RK35xx SoCs I have tested.

Also the BootROM seem to use a much slower crc16 implementation, so validating a huge blob for i.e. U-Boot RAM boot can take several seconds.
Will send an updated Rockchip U-Boot RAM-boot series that take advantage of FIT compression along with relocation the FIT to the 2 MiB offset to help speed up RAM-boot.

Still, wondering if we shouldn't simply use snagboot and implement stuff there if necessary?

Feel free to implement and use a snagboot driver, I will be using this for my personal lab ;-)

I have now added a new commit with support for decoding the IDBlock v2 image format (both unsigned and signed) in addition to the loader image format.

With that added we should be able to use the Barebox output image or u-boot-rockchip.bin to at least boot into SPL on newer Rockchip SoCs.

Will run some more tests and add one more commit to support for the legacy IDBlock image format to make this fully featured.

This will need to be tested some more on e.g. RK3576 where more than two idblock images is typically used to e.g. fixup booting from SD-card.

labgrid/util/agents/rkusbmaskrom.py

Add a RKUSBMaskromDriver bootstrap driver with an accompanying rkusbmaskrom agent to support bootstrapping targets with Rockchip SoCs. The rkusbmaskrom agent expects the target to be in MASKROM mode and send images to BootROM using vendor specific 0x471 and 0x472 control transfers, in 4 KiB chunks. The first image is loaded to SRAM using 0x471 and is expected to initialize DRAM and then return back to BootROM. A second image can then be loaded to start of DRAM using 0x472. Signed-off-by: Jonas Karlman <[email protected]>

Add support for using vendor loader image files, typically created using the vendor boot_merger tool in the rkbin repo. Signed-off-by: Jonas Karlman <[email protected]>

Add support for using vendor idblock v2 image files, typically created using the U-Boot mkimage tool. Signed-off-by: Jonas Karlman <[email protected]>

Kwiboo force-pushed the rkusbmaskrom branch from 8adcd1e to 0357fed Compare August 28, 2025 16:33

Kwiboo force-pushed the rkusbmaskrom branch 6 times, most recently from d011ad1 to c096575 Compare September 3, 2025 07:54

QSchulz reviewed Sep 8, 2025

View reviewed changes

Kwiboo mentioned this pull request Sep 8, 2025

Rockchip SoC support bootlin/snagboot#56

Open

Kwiboo force-pushed the rkusbmaskrom branch from c096575 to 9fd159a Compare September 8, 2025 15:36

Kwiboo force-pushed the rkusbmaskrom branch from 9fd159a to 87c520d Compare September 13, 2025 22:47

RKUSBMaskromDriver: add support for using vendor loader images

028ff1e

Add support for using vendor loader image files, typically created using the vendor boot_merger tool in the rkbin repo. Signed-off-by: Jonas Karlman <[email protected]>

Kwiboo force-pushed the rkusbmaskrom branch 4 times, most recently from 191a6cd to 2d0a61a Compare September 14, 2025 21:12

RKUSBMaskromDriver: add support for using vendor idblock v2 images

5af8184

Add support for using vendor idblock v2 image files, typically created using the U-Boot mkimage tool. Signed-off-by: Jonas Karlman <[email protected]>

Kwiboo force-pushed the rkusbmaskrom branch from 2d0a61a to 5af8184 Compare September 14, 2025 21:26

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

driver: add RKUSBMaskromDriver bootstrap driver #1721

driver: add RKUSBMaskromDriver bootstrap driver #1721

Uh oh!

Kwiboo commented Aug 27, 2025 •

edited

Loading

Uh oh!

codecov bot commented Aug 28, 2025 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

QSchulz Sep 8, 2025

Uh oh!

Kwiboo Sep 8, 2025 •

edited

Loading

Uh oh!

QSchulz Sep 8, 2025

Uh oh!

Kwiboo Sep 8, 2025

Uh oh!

Kwiboo Sep 14, 2025

Uh oh!

Uh oh!

Uh oh!

driver: add RKUSBMaskromDriver bootstrap driver #1721

Are you sure you want to change the base?

driver: add RKUSBMaskromDriver bootstrap driver #1721

Uh oh!

Conversation

Kwiboo commented Aug 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codecov bot commented Aug 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Uh oh!

Uh oh!

Uh oh!

QSchulz Sep 8, 2025

Choose a reason for hiding this comment

Uh oh!

Kwiboo Sep 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

QSchulz Sep 8, 2025

Choose a reason for hiding this comment

Uh oh!

Kwiboo Sep 8, 2025

Choose a reason for hiding this comment

Uh oh!

Kwiboo Sep 14, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Kwiboo commented Aug 27, 2025 •

edited

Loading

codecov bot commented Aug 28, 2025 •

edited

Loading

Kwiboo Sep 8, 2025 •

edited

Loading