driver: add RKUSBMaskromDriver bootstrap driver

[Kwiboo]

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

• [PATCH v3 0/4] rockchip: Add support for RAM boot from maskrom mode
• driver/usbloader: rename RKUSBDriver to reflect rkdeveloptool usage #1542
• RKUSBDriver: allow to specify the offset at which the image should be flashed #1703

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]

Codecov Report

❌ Patch coverage is 44.44444% with 60 lines in your changes missing coverage. Please review.
✅ Project coverage is 55.5%. Comparing base (22f4b81) to head (fdaeea3).
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
labgrid/util/agents/rkusbmaskrom.py	48.4%	34 Missing ⚠️
labgrid/driver/usbloader.py	36.5%	26 Missing ⚠️

Additional details and impacted files

@@           Coverage Diff            @@
##           master   #1721     +/-   ##
========================================
- Coverage    55.6%   55.5%   -0.1%     
========================================
  Files         172     173      +1     
  Lines       13495   13602    +107     
========================================
+ Hits         7514    7561     +47     
- Misses       5981    6041     +60     

Flag	Coverage Δ
3.10	55.5% <44.4%> (-0.1%)	⬇️
3.11	55.5% <44.4%> (-0.1%)	⬇️
3.12	55.5% <44.4%> (-0.1%)	⬇️
3.13	55.5% <44.4%> (-0.1%)	⬇️
3.9	55.6% <43.9%> (-0.1%)	⬇️

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.