[PATCH v2] 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_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>
---
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,
-- 
Quentin Schulz <quentin.schulz at cherry.de>