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

[Kever Yang]

On 2025/11/12 22:58, 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_size" 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>
Reviewed-by: Kever Yang <kever.yang at rock-chips.com>

Thanks,
- Kever
> ---
> Changes in v2:
> - specify init stage is loaded into SRAM by BootROM,
> - specify boot stages are loaded into DRAM by BootROM,
> - reworded explanation of the "boot" stages to mention multiple stages
>    and possibly U-Boot proper, as well as the conditions for BootROM to
>    load those, suggestions from Jonas (thanks!),
> - Link to v1: https://patch.msgid.link/20251107-rkcommon-hdr-v1-1-6b456bb3dd93@cherry.de
> ---
>   tools/rkcommon.c | 24 ++++++++++++++++++++----
>   1 file changed, 20 insertions(+), 4 deletions(-)
>
> diff --git a/tools/rkcommon.c b/tools/rkcommon.c
> index d191ea72c63..e7e78ef7e5b 100644
> --- a/tools/rkcommon.c
> +++ b/tools/rkcommon.c
> @@ -76,13 +76,29 @@ 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 the stage that is loaded into SRAM. TPL if there is one, SPL
> + * otherwise.
> + *
> + * "boot" means the next stages after "init" stage that are loaded by the
> + * BootROM into DRAM. Only applicable if "init" stage returns to BootROM (via
> + * the appropriate ROCKCHIP_BACK_TO_BROM symbol, BOOT_DEVICE_BOOTROM is used as
> + * boot device for the next stage and the "init" stage successfully booted) and
> + * if "init_boot_size" > "init_size".
> + * Basically, it is the content of "init" plus the SPL or even U-Boot proper if
> + * relevant.
>    *
>    * @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" and "boot" code combined.
> + *
>    * Other fields are not used by U-Boot
>    */
>   struct header0_info {
>
> ---
> base-commit: fdf36c2e9ad4f770ee951398a86bd55404d9b7ec
> change-id: 20251107-rkcommon-hdr-99fef99b4b64
>
> Best regards,