[PATCH] rockchip: mkimage: enhance comments for v1 header

[Quentin Schulz]

Hi Jonas,

On 11/7/25 6:24 PM, Jonas Karlman wrote:
> Hi Quentin,
> 
> On 11/7/2025 5:49 PM, Quentin Schulz wrote:
>> From: Quentin Schulz <quentin.schulz at cherry.de>
>>
>> Improve the image header documentation for v1 header:
>>
>> - specify this applies to all MMC, not only SD cards,
>> - specify the offset for SPI flashes,
>> - specify the key used for RC4 encoding,
>> - specify what "init" refers to, especially since some configs enable
>>    TPL,
>> - specify what "init_boot" refers to, especially since some configs
>>    enable TPL,
>> - specify the size of a block,
>> - add documentation for init_size and init_boot_size,
>>
>> Note that the offset on the storage medium isn't necessarily 32KiB (64
>> blocks) for MMC or 0 for SPI flashes, it's just the first offset the
>> BootROM checks. Barebox[1] lists a few options, though those are
>> applicable to RK35xx which use the v2 header, so not guaranteed they can
>> be shared. On RK3399, the binary can at least be stored at offset 0 and
>> 32KiB on SPI flashes.
>>
>> [1] https://git.pengutronix.de/cgit/barebox/tree/arch/arm/mach-rockchip/bbu.c#n19
>>
>> Signed-off-by: Quentin Schulz <quentin.schulz at cherry.de>
>> ---
>>   tools/rkcommon.c | 19 +++++++++++++++----
>>   1 file changed, 15 insertions(+), 4 deletions(-)
>>
>> diff --git a/tools/rkcommon.c b/tools/rkcommon.c
>> index d191ea72c63..6d1f88bcac1 100644
>> --- a/tools/rkcommon.c
>> +++ b/tools/rkcommon.c
>> @@ -76,13 +76,24 @@ struct header0_info_v2 {
>>   /**
>>    * struct header0_info - header block for boot ROM
>>    *
>> - * This is stored at SD card block 64 (where each block is 512 bytes, or at
>> - * the start of SPI flash. It is encoded with RC4.
>> + * This is stored at MMC block 64 (where each block is 512 bytes), or at
>> + * the start of SPI flash. It is encoded with RC4 with the below rc4_key.
>> + *
>> + * In Rockchip terminology:
>> + *
>> + * "init" means TPL if there is one, SPL otherwise.
> 
> Maybe mention something about SRAM here?
> 
> "init" is what BootROM load into SRAM, typically TPL if there is one,
> SPL otherwise.
> 

True, that I can do.

>> + *
>> + * "init_boot" means the entire software the boot ROM has to load for booting
>> + * U-Boot, typically the TPL if any, and the SPL.
>> + * Basically, it is the content of "init" plus the SPL if relevant.
> 
> The "init_boot" naming is very strange, I would probably try to describe
> it as the "boot" or next stage, maybe something like:
> 

Fair, I was trying to describe init_boot_size which is the combined size 
of TPL+SPL if TPL or SPL otherwise (as far as I remember) and got 
confused by the member name in the struct.

> "boot" is the next stage that BootROM load into start of DRAM, if "init"
> decide to return back to BROM using 0 as return code and init_boot_size
> exceeds init_size. Typically SPL if there is one, U-Boot proper
> otherwise.
> 

We don't really currently put U-Boot proper in idbloader.img, so I'm not 
entirely sure it makes that much sense to give the example of U-Boot 
proper. I vaguely recall you did or attempted to have U-Boot proper FIT 
image in there for USB booting without needing SPL_DFU or something like 
that, so maybe we should still document it.

> For newer SoCs using the v2 header this basically just continues for up
> to 4 images, BootROM loads next stage/image when prior stage return back
> to BROM using 0 as return code.
> 

I guess stages 1+ are all loaded at offset 0 in DRAM then?

Cheers,
Quentin