driver: add RKUSBMaskromDriver bootstrap driver#1721
driver: add RKUSBMaskromDriver bootstrap driver#1721Kwiboo wants to merge 4 commits intolabgrid-project:masterfrom
Conversation
Codecov Report❌ Patch coverage is
Additional details and impacted files@@ Coverage Diff @@
## master #1721 +/- ##
========================================
+ Coverage 45.2% 45.5% +0.3%
========================================
Files 174 175 +1
Lines 13752 13952 +200
========================================
+ Hits 6224 6358 +134
- Misses 7528 7594 +66
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Sentry. |
Kwiboo
force-pushed
the
rkusbmaskrom
branch
6 times, most recently
from
d011ad1 to
c096575
Compare
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
question: use
snagbootinstead?
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 ;-)
There was a problem hiding this comment.
@Kwiboo Are you aware of a specific issue why snagboot couldn't work as well as this driver? They also use pyusb and no vendor-specific tool.
There was a problem hiding this comment.
Are you aware of a specific issue why snagboot couldn't work as well as this driver? They also use pyusb and no vendor-specific tool.
@jluebbe snagboot does not support Rockchip, I did send review comments on the snagboot Rockchip PR, but there has not been any progress.
This is adding optimized and full featured support to ramboot all Rockchip boards in my labgrid boardfarm using a simple template:
targets:
main:
resources:
RemotePlace:
name: !template $LG_PLACE
drivers:
SerialDriver: {}
LinkPiSmartHUBPowerDriver: {}
RKUSBMaskromDriver:
initial: rkmaskrom471
image: rkmaskrom472
BootstrapStrategy: {}
images:
rkmaskrom471: /srv/u-boot/$LG_PLACE/u-boot-rockchip-usb471.bin
rkmaskrom472: /srv/u-boot/$LG_PLACE/u-boot-rockchip-usb472.bin
options:
coordinator_address: 'labgrid'
This works fine for my limited need and allows me to not have to deal with trying to bend yet another third party tools or system like snagboot and pdudaemon to work for my need.
There was a problem hiding this comment.
@jluebbe The original contributor for Rockchip support in snagboot doesn't seem to be active anymore since June 2nd last year, so I'm of the opinion we shouldn't wait for this hypothetical support in snagboot and go ahead with this here. If support comes along to snagboot in the future, then we can always deprecate this implementation here and switch to snagboot if we wanted to. What do you think?
| RKUSBMaskromDriver: | ||
| initial: 'rkmaskrom471' | ||
| image: 'rkmaskrom472' |
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
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 ;-)
There was a problem hiding this comment.
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 add 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.
There was a problem hiding this comment.
I have now pushed one more commit with support for decoding the legacy IDBlock image format, the boot image format used for Rockchip SoCs prior to the RK35xx line.
With this I can now use something like the following labgrid-client command on my Rockchip boards:
labgrid-client -v -c remote.yaml -p rk3399-rock-4 bootstrap u-boot-rockchip.bin
And as expected, without a proper FIT available or SPL DFU working, U-Boot SPL will fail trying to bootstrap a plain U-Boot u-boot-rockchip.bin image:
U-Boot TPL 2025.10-rc5 (Sep 29 2025 - 19:04:10)
lpddr4_set_rate: change freq to 400MHz 0, 1
Channel 0: LPDDR4, 400MHz
BW=32 Col=10 Bk=8 CS0 Row=15 CS=1 Die BW=16 Size=1024MB
Channel 1: LPDDR4, 400MHz
BW=32 Col=10 Bk=8 CS0 Row=15 CS=1 Die BW=16 Size=1024MB
256B stride
lpddr4_set_rate: change freq to 800MHz 1, 0
Trying to boot from BOOTROM
Returning to boot ROM...
spl:init dram
U-Boot SPL 2025.10-rc5 (Sep 29 2025 - 19:04:10 +0000)
board_spl_was_booted_from: failed to resolve brom_bootdevice_id a
Trying to boot from MMC1
mmc_load_image_raw_sector: mmc block read error
Error: -38
Trying to boot from MMC2
Card did not respond to voltage select! : -110
spl: mmc init failed with error: -95
Error: -95
SPL: failed to boot from all boot devices
### ERROR ### Please RESET the board ###
There was a problem hiding this comment.
And as expected, without a proper FIT available or SPL DFU working, U-Boot SPL will fail trying to bootstrap a plain U-Boot
In u-boot-rockchip.bin, there's a FIT already. But I'm assuming since its information is not stored in the idblock header, we cannot know where to look for it in the file? Do you think it'd be possible to find where in the file the FIT binary is (without elaborate and error-prone guessing)? We do have binman symbols available in SPL so maybe there's something to do with that.
I'm wondering if another option isn't to generate a u-boot-rockchip-usb.bin in that format (or maybe rather the one from boot_merger?) in U-Boot. I'm assuming this is why you wanted to have the ability to upload to 0x472 directly with the first patch in this PR, so you can directly use u-boot-rockchip-usb472.bin generated by U-Boot without having to go through boot_merger or mkimage?
Kwiboo
force-pushed
the
rkusbmaskrom
branch
7 times, most recently
from
2d0a61a to
5af8184
Compare
Kwiboo
force-pushed
the
rkusbmaskrom
branch
4 times, most recently
from
ea24587 to
77dff7d
Compare
Kwiboo
force-pushed
the
rkusbmaskrom
branch
2 times, most recently
from
cb06a96 to
9fbba8f
Compare
Kwiboo
force-pushed
the
rkusbmaskrom
branch
2 times, most recently
from
1838792 to
d4626c9
Compare
Kwiboo
force-pushed
the
rkusbmaskrom
branch
2 times, most recently
from
b5d5459 to
361549d
Compare
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 <jonas@kwiboo.se>
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 <jonas@kwiboo.se>
Add support for using vendor idblock v2 image files, typically created using the U-Boot mkimage or Barebox rkimage tools. Signed-off-by: Jonas Karlman <jonas@kwiboo.se>
Add support for using vendor idblock v1 image files, typically created using the U-Boot mkimage tool. Signed-off-by: Jonas Karlman <jonas@kwiboo.se>
|
General comments. As far as I understood this supports many things:
I am not sure we absolutely need 1. We could ask the user to generate binaries with If I understood patch 1 in the PR, 1. requires two binaries, If I understood correctly, 3. and 4. are only actually usable with U-Boot if using SPL_DFU or entering rockusb (how?) from SPL, or if a FIT is already on a storage medium somewhere the SPL can find it. So not really an option for recovering a device as part of a strategy for example. I think it's nice for Barebox though! My understanding is that we would gain the ability to boot a Barebox for rk3188 and rk3288 (the only old SoCs supported by Barebox right now I believe). Once this PR is merged, I think we need to revamp RKUSBDriver entirely to split the logic of uploading a binary over USB to BootROM ( I'll give this a try tomorrow once I'm in office and have access to my neglected labgrid desktop :) Jonas, thanks again for all the work you do on Rockchip. |
| - image (str): optional, key in :ref:`images <labgrid-device-config-images>` containing the path | ||
| of a bootloader image to load to start of DRAM, or to SRAM when an initial image is unused |
There was a problem hiding this comment.
suggestion (non-blocking): specify this can be overridden at runtime
The user can actually override (or provide if none is provided in the conf) the image via the load(filename: str) method of the BootstrapProtocol class.
But we cannot change initial.
| An :any:`RKUSBMaskromDriver` is used to upload an image into a device in the | ||
| *Rockchip USB Maskrom state*. |
There was a problem hiding this comment.
issue: confusing documentation
This states that we're expecting the device to be in the USB Maskrom state while we bind to an RKUSBLoader which
describes a USB device in the Rockchip loader state.
and we even check here: c091cde#diff-4717e427bdffde63a29a83ebf945dd18f8e5caf30896ef89f71f303891a66cecR89 that we are NOT in the LOADER state. So which is which?
| RKUSBMaskromDriver: | ||
| initial: 'rkmaskrom471' | ||
| image: 'rkmaskrom472' |
There was a problem hiding this comment.
And as expected, without a proper FIT available or SPL DFU working, U-Boot SPL will fail trying to bootstrap a plain U-Boot
In u-boot-rockchip.bin, there's a FIT already. But I'm assuming since its information is not stored in the idblock header, we cannot know where to look for it in the file? Do you think it'd be possible to find where in the file the FIT binary is (without elaborate and error-prone guessing)? We do have binman symbols available in SPL so maybe there's something to do with that.
I'm wondering if another option isn't to generate a u-boot-rockchip-usb.bin in that format (or maybe rather the one from boot_merger?) in U-Boot. I'm assuming this is why you wanted to have the ability to upload to 0x472 directly with the first patch in this PR, so you can directly use u-boot-rockchip-usb472.bin generated by U-Boot without having to go through boot_merger or mkimage?
This Mostly added support for format I am only using the And run To be more precise I am using something closer to https://github.com/Kwiboo/scripts/blob/main/labgrid.sh so that I can simplify my U-Boot (and Linux) dev workflow with something like following: while having another terminal constant connected to the serial console of the board for interaction: |
Correct, this PR does not try to make any assumptions or enforcement on how the user wants to use it, it can be used with
My primary need (based on my limited knowledge of labgrid) is to use the I even sometime (ab)use the
Correct, this only make it possible to transfer binary blobs encoded in common RK image formats to the BootROM and does not impose any restriction or make assumptions on what the blobs/images are used for. I use |
Oh well, I had forgotten but seems like my opinion hasn't changed since :D
Considering you're parsing the file generated by
FYI, the [...]
I'm a bit confused by labgrid choices sometimes. My understanding is that you need the environment (the one with
Yeah but we cannot decide to not support
Yeah, I was also very confused upon reading bootstrap command from labgrid-client actually requires a file... Why? It's already in the env (use that one, and if it isn't in the env, then tell the user?). I think we're missing some use-cases that warranted this kind of split. [...]
OK. I'm assuming this could be useful to Barebox where they have SPL+proper (or whatever their terms are :) ) concatenated into one big binary if I remember correctly. Limited use for upstream U-Boot so far.
You should be able to simply control the console via the For what it's worth, I tested on PX30, RK3399 and RK3588 option 1. (slow on RK3399, likely due to BootROM having a slow CRC16 implementation according to you; it uploads decently fast but then takes some time to boot into SPL (the first part of our upstream U-Boot 472 payload), and option 3. for RK3588, and option 4. for PX30. All do what they must. |
3 participants
Description
Add a
RKUSBMaskromDriverbootstrap driver with an accompanyingrkusbmaskromagent to support bootstrapping targets with Rockchip SoCs.The
rkusbmaskromagent expects the target to be in MASKROM mode and send images to BootROM using vendor specific0x471and0x472control transfers, in 4 KiB chunks.The first image is loaded to SRAM using
0x471and is expected to initialize DRAM and then return back to BootROM.A second image can then be loaded to start of DRAM using
0x472.The
rkusbmaskromagent also support extracting the needed0x471and0x472images from a vendor loader image, typically created with the vendorboot_mergertool from the rkbin repo, or idblock boot images, typically created with the U-Bootmkimageor the Bareboxrkimagetools.Related
Checklist
Example usage