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

[Quentin Schulz]

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.
+ *
+ * "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.
  *
  * @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,
-- 
Quentin Schulz <quentin.schulz at cherry.de>