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

[Jonas Karlman]

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.

> + *
> + * "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:

"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.

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.

Regards,
Jonas

>   *
>   * @magic:		Magic (must be RK_MAGIC)
>   * @disable_rc4:	0 to use rc4 for boot image,  1 to use plain binary
> - * @init_offset:	Offset in blocks of the SPL code from this header
> - *			block. E.g. 4 means 2KB after the start of this header.
> + * @init_offset:	Offset in 512-byte blocks of the "init" code from the
> + *			start of this header. For instance, 4 means 2KiB.
> + * @init_size:		Size (in blocks) of the "init" code.
> + * @init_boot_size:	Size (in blocks) of the "init_boot" code.
> + *
>   * Other fields are not used by U-Boot
>   */
>  struct header0_info {
> 
> ---
> base-commit: fdf36c2e9ad4f770ee951398a86bd55404d9b7ec
> change-id: 20251107-rkcommon-hdr-99fef99b4b64
> 
> Best regards,