[PATCH v3 0/2] tools: mkimage: add SpacemiT K3 boot image support

[PATCH v3 0/2] tools: mkimage: add SpacemiT K3 boot image support

[Junhui Liu]

The SpacemiT BootROM loads a first-stage bootloader from storage or over
USB in MaskROM mode. Vendor firmware packages this bootloader as FSBL.bin.

This series documents the SpacemiT boot image format and adds the
"smtimage" mkimage type for the CRC32-protected K3 variant used in
non-secure boot mode. It provides the FSBL packaging needed for future
K3 SPL support. Select K3 with "-n k3" when creating an image.

K1 and K3 secure boot use RSA authentication and are not supported yet.

How to test
-----------

Rebuild mkimage, wrap a small UART test payload, and load it through K3
MaskROM fastboot. The payload is linked at 0xc0801000 because the BootROM
places the complete image at 0xc0800000 and enters the payload after the
4 KiB prefix. UART0 should print "Hello SpacemiT K3!" and then loop
indefinitely.

  $ make tools-only_defconfig
  $ make tools-only

  $ cat > k3-uart.S << 'EOF'
  	.equ	UART0_THR, 0xd4017000
	.equ	UART0_LSR, 0xd4017014

	.section	.text
	.global	_start
_start:
	la	s0, str
1:
	lbu	a0, (s0)
	beqz	a0, exit
	call	uart_send
	addi	s0, s0, 1
	j	1b

exit:
	j	exit

uart_send:
	li	t0, UART0_LSR
	lw	t1, (t0)
	andi	t1, t1, 0x20
	beqz	t1, uart_send
	li	t0, UART0_THR
	sw	a0, (t0)
	ret

	.section	.rodata
str:
	.asciz	"Hello SpacemiT K3!\n"
EOF

  $ riscv64-linux-gnu-gcc -nostdlib -fno-builtin -fno-pie -no-pie -static \
    -march=rv64gc -mabi=lp64 -g -Wall -Wl,--build-id=none \
    -Ttext=0xc0801000 -o k3-uart.elf k3-uart.S
  $ riscv64-linux-gnu-objcopy -O binary k3-uart.elf k3-uart.bin
  $ ./tools/mkimage -T smtimage -n k3 -d k3-uart.bin k3-uart-smt.bin

Hold the FDL button, power on the board to enter MaskROM, then run
fastboot on host:

  $ fastboot stage k3-uart-smt.bin
  $ fastboot continue

---
Changes in v3:
- Align the uimage_type table entry with surrounding columns
- Explicitly include the needed headers
- Drop SMT_PAYLOAD_ALIGN macro
- Simplify the NULL check in smtimage_get_variant()
- Fix the title underline length in smtimage.rst
- Link to v2: https://patch.msgid.link/20260909-spacemit-aihd-v2-0-780e98cf2fec@pigmoral.tech

Changes in v2:
- Use "smtimage" for the image type
- Update the documentation and command examples to match
- Link to v1: https://patch.msgid.link/20260822-spacemit-aihd-v1-0-bf4c41993891@pigmoral.tech

---
Junhui Liu (2):
      tools: mkimage: add SpacemiT K3 boot image support
      doc: board: spacemit: document the SpacemiT boot image format

 boot/image.c                    |   1 +
 doc/board/spacemit/index.rst    |   2 +-
 doc/board/spacemit/smtimage.rst | 143 +++++++++++++++++++++++++++
 include/image.h                 |   1 +
 tools/Makefile                  |   1 +
 tools/smtimage.c                | 208 ++++++++++++++++++++++++++++++++++++++++
 6 files changed, 355 insertions(+), 1 deletion(-)
---
base-commit: 211de43d0f954a00a490220c1aac9db298287c40
change-id: 20260820-spacemit-aihd-05c46aae886e

Best regards,
--  
Junhui Liu <junhui.liu@pigmoral.tech>

[PATCH v3 1/2] tools: mkimage: add SpacemiT K3 boot image support

[Junhui Liu]

The SpacemiT BootROM loads the FSBL from a boot image consisting of a
fixed 4 KiB header with two metadata headers and authentication
information, followed by a 32-byte-aligned SPL payload and a trailing
authentication area. K1 and K3 share the same layout, but use different
integrity and authentication schemes. K1 requires RSA-signed images,
while K3 uses CRC32 to verify images in non-secure boot mode.

Add mkimage type "smtimage" for the K3 CRC32 path. Populate both
metadata headers, fill their CRC32 values and the payload CRC32, and
reserve the authentication areas required by the layout.

The K1 and K3 image headers cannot be easily differentiated, and
dumpimage has no way to select the variant, so dumpimage support is
not implemented.

mkimage selects the SoC variant with "-n <soc>". For now only
"-n k3" with non-secure boot (CRC32) is supported. A variant table
is added to hold the SoC-specific parameters, making it easier to
add K1 support and RSA authentication later.

Tested-by: E Shattow <e@freeshell.de>
Signed-off-by: Junhui Liu <junhui.liu@pigmoral.tech>
---
 boot/image.c     |   1 +
 include/image.h  |   1 +
 tools/Makefile   |   1 +
 tools/smtimage.c | 208 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 4 files changed, 211 insertions(+)

diff --git a/boot/image.c b/boot/image.c
index 185d52ba492f..289e80f23a7f 100644
--- a/boot/image.c
+++ b/boot/image.c
@@ -179,6 +179,7 @@ static const table_entry_t uimage_type[] = {
 	{	IH_TYPE_TFA_BL31, "tfa-bl31",  "TFA BL31 Image", },
 	{	IH_TYPE_STM32IMAGE_V2, "stm32imagev2", "STMicroelectronics STM32 Image V2.0" },
 	{	IH_TYPE_AMLIMAGE,   "amlimage",   "Amlogic Boot Image" },
+	{	IH_TYPE_SMTIMAGE,   "smtimage",   "SpacemiT Boot Image" },
 	{	-1,		    "",		  "",			},
 };
 
diff --git a/include/image.h b/include/image.h
index 1de0a84007af..edbbcf45ba62 100644
--- a/include/image.h
+++ b/include/image.h
@@ -235,6 +235,7 @@ enum image_type_t {
 	IH_TYPE_TFA_BL31,		/* TFA BL31 image */
 	IH_TYPE_STM32IMAGE_V2,		/* STMicroelectronics STM32 Image V2.0 */
 	IH_TYPE_AMLIMAGE,		/* Amlogic Boot Image */
+	IH_TYPE_SMTIMAGE,		/* SpacemiT Boot Image */
 
 	IH_TYPE_COUNT,			/* Number of image types */
 };
diff --git a/tools/Makefile b/tools/Makefile
index 535a5d51c89e..fc0aa52455aa 100644
--- a/tools/Makefile
+++ b/tools/Makefile
@@ -138,6 +138,7 @@ dumpimage-mkimage-objs := aisimage.o \
 			pbl_crc32.o \
 			renesas_spkgimage.o \
 			sfspl.o \
+			smtimage.o \
 			vybridimage.o \
 			stm32image.o \
 			$(ROCKCHIP_OBS) \
diff --git a/tools/smtimage.c b/tools/smtimage.c
new file mode 100644
index 000000000000..462279e80a3f
--- /dev/null
+++ b/tools/smtimage.c
@@ -0,0 +1,208 @@
+// SPDX-License-Identifier: GPL-2.0-or-later
+/*
+ * Copyright (C) 2026 Junhui Liu <junhui.liu@pigmoral.tech>
+ *
+ * The SpacemiT boot image consists of a fixed image header followed by an
+ * aligned SPL payload and a trailing authentication area. The image header
+ * contains two metadata headers and areas reserved for authentication data.
+ *
+ * The image layout is:
+ *
+ *   0x000             root key
+ *   0x100             header0
+ *   0x120             key metadata
+ *   0x300             OEM keys
+ *   0xb00             signature0
+ *   0xfe0             header1
+ *   0x1000            SPL payload, with its end aligned to 32 bytes
+ *   payload end       signature1 (0x100 bytes)
+ */
+
+#include <image.h>
+#include "imagetool.h"
+#include <stddef.h>
+#include <stdint.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <sys/stat.h>
+#include <u-boot/crc.h>
+
+#define SMT_MAGIC		"AIHD"
+#define SMT_AUTH_SIZE		0x100
+
+#define SMT_FLAG_CRC32		(1U << 0)
+
+/**
+ * struct smtimage_header - metadata header within a SpacemiT boot image header
+ *
+ * @magic:	Magic (must be SMT_MAGIC)
+ * @version:	Image version used when anti-rollback is enabled by eFuse
+ * @secure:	Version slot used when anti-rollback is enabled by eFuse
+ * @reserved:	Reserved
+ * @image_size:	Header0 stores the image header size
+ *		Header1 stores the aligned payload size
+ * @load_addr:	Unused
+ * @header_crc:	Header0 and Header1 store the CRC32 of the preceding 24 bytes on K3
+ * @image_crc:	Header1 stores the CRC32 of the aligned payload on K3
+ */
+struct smtimage_header {
+	uint8_t magic[4];
+	uint8_t version;
+	uint8_t secure;
+	uint16_t reserved;
+	uint64_t image_size;
+	uint64_t load_addr;
+	uint32_t header_crc;
+	uint32_t image_crc;
+} __packed;
+
+/**
+ * struct smtimage_image_header - fixed header area of a SpacemiT boot image
+ *
+ * @root_key:	Root public key
+ * @header0:	Image layout and load information
+ * @key_data:	Key metadata
+ * @oem_keys:	OEM public-key area
+ * @signature0:	Signature of the image configuration
+ * @reserved:	Reserved
+ * @header1:	SPL payload information
+ */
+struct smtimage_image_header {
+	uint8_t root_key[0x100];
+	struct smtimage_header header0;
+	uint8_t key_data[0x1e0];
+	uint8_t oem_keys[0x800];
+	uint8_t signature0[SMT_AUTH_SIZE];
+	uint8_t reserved[0x3e0];
+	struct smtimage_header header1;
+} __packed;
+
+/**
+ * struct smtimage_variant - SoC-specific image properties
+ *
+ * @name:	SoC name passed to mkimage with -n
+ * @flags:	SoC-specific image flags
+ */
+struct smtimage_variant {
+	const char *name;
+	unsigned int flags;
+};
+
+static const struct smtimage_variant smtimage_variants[] = {
+	{
+		.name = "k3",
+		.flags = SMT_FLAG_CRC32,
+	},
+};
+
+static const struct smtimage_variant *smtimage_get_variant(const char *name)
+{
+	int i;
+
+	if (!name)
+		return NULL;
+
+	for (i = 0; i < ARRAY_SIZE(smtimage_variants); i++)
+		if (!strcmp(name, smtimage_variants[i].name))
+			return &smtimage_variants[i];
+
+	return NULL;
+}
+
+static void smtimage_init_header(struct smtimage_header *header, uint64_t image_size,
+				 const struct smtimage_variant *variant)
+{
+	uint32_t crc;
+
+	memcpy(header->magic, SMT_MAGIC, sizeof(header->magic));
+
+	header->image_size = cpu_to_le64(image_size);
+
+	if (variant->flags & SMT_FLAG_CRC32) {
+		crc = crc32(0, (uint8_t *)header,
+			    offsetof(struct smtimage_header, header_crc));
+		header->header_crc = cpu_to_le32(crc);
+	}
+}
+
+static int smtimage_check_params(struct image_tool_params *params)
+{
+	if (!smtimage_get_variant(params->imagename)) {
+		fprintf(stderr, "%s: SpacemiT SoC must be specified with -n\n",
+			params->cmdname);
+		return EXIT_FAILURE;
+	}
+
+	if (!params->dflag)
+		return EXIT_FAILURE;
+
+	return EXIT_SUCCESS;
+}
+
+static void smtimage_print_header(const void *buf, struct image_tool_params *params)
+{
+	const struct smtimage_image_header *image_header = buf;
+	const struct smtimage_header *header1 = &image_header->header1;
+	uint64_t payload_size = le64_to_cpu(header1->image_size);
+
+	printf("Image Type:   SpacemiT Boot Image\n");
+	printf("SoC Variant:  %s\n", params->imagename);
+	printf("Total Size:   %llu bytes\n",
+	       (unsigned long long)(sizeof(*image_header) + payload_size + SMT_AUTH_SIZE));
+	printf("Payload Size: %llu bytes\n", (unsigned long long)payload_size);
+}
+
+static void smtimage_set_header(void *buf, struct stat *sbuf, int infd,
+				struct image_tool_params *params)
+{
+	const struct smtimage_variant *variant = smtimage_get_variant(params->imagename);
+	struct smtimage_image_header *image_header = buf;
+	struct smtimage_header *header0 = &image_header->header0;
+	struct smtimage_header *header1 = &image_header->header1;
+	size_t payload_size;
+	uint32_t crc;
+
+	payload_size = sbuf->st_size - sizeof(*image_header) - SMT_AUTH_SIZE;
+
+	smtimage_init_header(header0, sizeof(*image_header), variant);
+	smtimage_init_header(header1, payload_size, variant);
+
+	if (variant->flags & SMT_FLAG_CRC32) {
+		crc = crc32(0, (uint8_t *)(image_header + 1), payload_size);
+		header1->image_crc = cpu_to_le32(crc);
+	}
+}
+
+static int smtimage_check_image_type(uint8_t type)
+{
+	if (type == IH_TYPE_SMTIMAGE)
+		return EXIT_SUCCESS;
+
+	return EXIT_FAILURE;
+}
+
+static int smtimage_vrec_header(struct image_tool_params *params,
+				struct image_type_params *tparams)
+{
+	size_t payload_size = params->file_size - tparams->header_size;
+
+	tparams->hdr = calloc(tparams->header_size, 1);
+
+	return ALIGN(payload_size, 32) - payload_size + SMT_AUTH_SIZE;
+}
+
+U_BOOT_IMAGE_TYPE(
+	smtimage,
+	"SpacemiT Boot Image support",
+	sizeof(struct smtimage_image_header),
+	NULL,
+	smtimage_check_params,
+	NULL,
+	smtimage_print_header,
+	smtimage_set_header,
+	NULL,
+	smtimage_check_image_type,
+	NULL,
+	smtimage_vrec_header
+);

-- 
2.55.0

[PATCH v3 2/2] doc: board: spacemit: document the SpacemiT boot image format

[Junhui Liu]

Document the boot image layout shared by the SpacemiT K1 and K3
BootROMs, including the metadata headers and authentication areas.

Describe the K3 non-secure CRC32 path supported by mkimage and provide
an example using the "smtimage" image type with "-n k3".

Tested-by: E Shattow <e@freeshell.de>
Signed-off-by: Junhui Liu <junhui.liu@pigmoral.tech>
---
 doc/board/spacemit/index.rst    |   2 +-
 doc/board/spacemit/smtimage.rst | 143 ++++++++++++++++++++++++++++++++++++++++
 2 files changed, 144 insertions(+), 1 deletion(-)

diff --git a/doc/board/spacemit/index.rst b/doc/board/spacemit/index.rst
index a5e35ee12ab6..5797ada37d15 100644
--- a/doc/board/spacemit/index.rst
+++ b/doc/board/spacemit/index.rst
@@ -7,4 +7,4 @@ SpacemiT
 
    bananapi-f3
    k1-spl
-
+   smtimage
diff --git a/doc/board/spacemit/smtimage.rst b/doc/board/spacemit/smtimage.rst
new file mode 100644
index 000000000000..19a5c9972f75
--- /dev/null
+++ b/doc/board/spacemit/smtimage.rst
@@ -0,0 +1,143 @@
+.. SPDX-License-Identifier: GPL-2.0-or-later
+
+SpacemiT boot image format
+==========================
+
+The SpacemiT K1 and K3 BootROMs load a SpacemiT boot image as the first-stage
+bootloader (FSBL), either from persistent storage or over USB in MaskROM mode.
+
+Image layout
+------------
+
+K1 and K3 share the same layout. A fixed 4 KiB prefix contains two 32-byte
+metadata headers, key slots, and signature slots. The aligned SPL payload and
+a trailing authentication area follow::
+
+    offset                                    size
+    0x000  +-------------------------------+
+           | root RSA-2048 modulus         |  0x100
+    0x100  +-------------------------------+
+           | header0                       |  0x020
+    0x120  +-------------------------------+
+           | key-selection metadata        |  0x1e0
+    0x300  +-------------------------------+
+           | OEM public-key slots          |  0x800
+    0xb00  +-------------------------------+
+           | signature0                    |  0x100
+    0xc00  +-------------------------------+
+           | reserved                      |  0x3e0
+    0xfe0  +-------------------------------+
+           | header1                       |  0x020
+    0x1000 +-------------------------------+
+           | SPL payload (32-byte aligned) |
+           +-------------------------------+
+           | signature1                    |  0x100
+           +-------------------------------+
+
+For payload size ``P`` and ``A = ALIGN(P, 32)``, the image size is
+``0x1000 + A + 0x100``.
+
+Metadata header
+---------------
+
+Both header0 and header1 use the following format:
+
+.. list-table::
+   :header-rows: 1
+
+   * - Offset
+     - Size
+     - Field
+     - Description
+   * - 0x00
+     - 4
+     - ``magic``
+     - ``AIHD``
+   * - 0x04
+     - 1
+     - ``version``
+     - Anti-rollback image version
+   * - 0x05
+     - 1
+     - ``secure``
+     - Zero selects anti-rollback bank 0
+
+       Non-zero selects anti-rollback bank 1
+   * - 0x06
+     - 2
+     - ``reserved``
+     - Reserved
+   * - 0x08
+     - 8
+     - ``image_size``
+     - header0: prefix information
+
+       header1: aligned payload size
+   * - 0x10
+     - 8
+     - ``load_addr``
+     - Unused by the common authentication code
+   * - 0x18
+     - 4
+     - ``header_crc``
+     - K3: CRC32 over header bytes ``[0x00, 0x18)``
+   * - 0x1c
+     - 4
+     - ``image_crc``
+     - K3: CRC32 over the payload in header1 only
+
+``header1.image_size`` records the aligned payload size and therefore
+determines the location of signature1.
+
+Authentication
+--------------
+
+K1 and K3 apply different authentication policies:
+
+.. list-table::
+   :header-rows: 1
+
+   * - Area
+     - K1
+     - K3 non-secure boot mode
+     - K3 secure boot mode
+   * - Root and OEM keys
+     - RSA-2048 moduli with an eFuse root-hash check when secure boot is
+       enabled
+     - Unused
+     - RSA-2048 moduli with an eFuse root-hash check
+   * - Header CRC
+     - Not checked separately
+     - header1 verified
+
+       header0 ignored
+     - Both verified and covered by RSA
+   * - Image CRC
+     - Not checked separately
+     - Payload CRC32 in header1
+     - Covered by RSA but not checked separately
+   * - signature0
+     - Verified with the root key over ``[0x100, 0xb00)``
+     - Unused
+     - Verified with the root key over ``[0x100, 0xb00)``
+   * - signature1
+     - Verified with the SPL key over header1 and the aligned payload
+     - Unused
+     - Verified with the SPL key over header1 and the aligned payload
+
+K1 verifies both signatures even without a programmed root-key hash. In this
+case, the root key comes from the image and is not authenticated by hardware,
+so the image, keys, and signatures can be replaced together.
+
+K3 uses CRC32 in non-secure boot mode and hardware-rooted RSA in secure boot
+mode.
+
+Creating an image
+-----------------
+
+U-Boot currently creates only K3 images for non-secure boot mode. Package an
+SPL payload with::
+
+    $ tools/mkimage -T smtimage -n k3 -d u-boot-spl.bin FSBL.bin
+
+K1 images and RSA-authenticated K3 images are not yet supported.

-- 
2.55.0

Re: [PATCH v3 0/2] tools: mkimage: add SpacemiT K3 boot image support

[Yao Zi]

On Mon, Sep 21, 2026 at 10:54:37PM +0800, Junhui Liu wrote:
> The SpacemiT BootROM loads a first-stage bootloader from storage or over
> USB in MaskROM mode. Vendor firmware packages this bootloader as FSBL.bin.
> 
> This series documents the SpacemiT boot image format and adds the
> "smtimage" mkimage type for the CRC32-protected K3 variant used in
> non-secure boot mode. It provides the FSBL packaging needed for future
> K3 SPL support. Select K3 with "-n k3" when creating an image.
> 
> K1 and K3 secure boot use RSA authentication and are not supported yet.
> 
> How to test
> -----------
> 
> Rebuild mkimage, wrap a small UART test payload, and load it through K3
> MaskROM fastboot. The payload is linked at 0xc0801000 because the BootROM
> places the complete image at 0xc0800000 and enters the payload after the
> 4 KiB prefix. UART0 should print "Hello SpacemiT K3!" and then loop
> indefinitely.
> 
>   $ make tools-only_defconfig
>   $ make tools-only
> 
>   $ cat > k3-uart.S << 'EOF'
>   	.equ	UART0_THR, 0xd4017000
> 	.equ	UART0_LSR, 0xd4017014
> 
> 	.section	.text
> 	.global	_start
> _start:
> 	la	s0, str
> 1:
> 	lbu	a0, (s0)
> 	beqz	a0, exit
> 	call	uart_send
> 	addi	s0, s0, 1
> 	j	1b
> 
> exit:
> 	j	exit
> 
> uart_send:
> 	li	t0, UART0_LSR
> 	lw	t1, (t0)
> 	andi	t1, t1, 0x20
> 	beqz	t1, uart_send
> 	li	t0, UART0_THR
> 	sw	a0, (t0)
> 	ret
> 
> 	.section	.rodata
> str:
> 	.asciz	"Hello SpacemiT K3!\n"
> EOF
> 
>   $ riscv64-linux-gnu-gcc -nostdlib -fno-builtin -fno-pie -no-pie -static \
>     -march=rv64gc -mabi=lp64 -g -Wall -Wl,--build-id=none \
>     -Ttext=0xc0801000 -o k3-uart.elf k3-uart.S
>   $ riscv64-linux-gnu-objcopy -O binary k3-uart.elf k3-uart.bin
>   $ ./tools/mkimage -T smtimage -n k3 -d k3-uart.bin k3-uart-smt.bin
> 
> Hold the FDL button, power on the board to enter MaskROM, then run
> fastboot on host:
> 
>   $ fastboot stage k3-uart-smt.bin
>   $ fastboot continue

For the series,

Reviewed-by: Yao Zi <me@ziyao.cc>

Thanks,
Yao Zi

Re: [PATCH v3 0/2] tools: mkimage: add SpacemiT K3 boot image support

[Yixun Lan]

Hi Junhui,

On 22:54 Mon 21 Sep     , Junhui Liu wrote:
> The SpacemiT BootROM loads a first-stage bootloader from storage or over
> USB in MaskROM mode. Vendor firmware packages this bootloader as FSBL.bin.
> 
> This series documents the SpacemiT boot image format and adds the
> "smtimage" mkimage type for the CRC32-protected K3 variant used in
> non-secure boot mode. It provides the FSBL packaging needed for future
> K3 SPL support. Select K3 with "-n k3" when creating an image.
> 
> K1 and K3 secure boot use RSA authentication and are not supported yet.
> 
> How to test
> -----------
> 
> Rebuild mkimage, wrap a small UART test payload, and load it through K3
> MaskROM fastboot. The payload is linked at 0xc0801000 because the BootROM
> places the complete image at 0xc0800000 and enters the payload after the
> 4 KiB prefix. UART0 should print "Hello SpacemiT K3!" and then loop
> indefinitely.
> 
>   $ make tools-only_defconfig
>   $ make tools-only
> 
>   $ cat > k3-uart.S << 'EOF'
>   	.equ	UART0_THR, 0xd4017000
> 	.equ	UART0_LSR, 0xd4017014
> 
> 	.section	.text
> 	.global	_start
> _start:
> 	la	s0, str
> 1:
> 	lbu	a0, (s0)
> 	beqz	a0, exit
> 	call	uart_send
> 	addi	s0, s0, 1
> 	j	1b
> 
> exit:
> 	j	exit
> 
> uart_send:
> 	li	t0, UART0_LSR
> 	lw	t1, (t0)
> 	andi	t1, t1, 0x20
> 	beqz	t1, uart_send
> 	li	t0, UART0_THR
> 	sw	a0, (t0)
> 	ret
> 
> 	.section	.rodata
> str:
> 	.asciz	"Hello SpacemiT K3!\n"
> EOF
> 
>   $ riscv64-linux-gnu-gcc -nostdlib -fno-builtin -fno-pie -no-pie -static \
>     -march=rv64gc -mabi=lp64 -g -Wall -Wl,--build-id=none \
>     -Ttext=0xc0801000 -o k3-uart.elf k3-uart.S
>   $ riscv64-linux-gnu-objcopy -O binary k3-uart.elf k3-uart.bin
>   $ ./tools/mkimage -T smtimage -n k3 -d k3-uart.bin k3-uart-smt.bin
> 
> Hold the FDL button, power on the board to enter MaskROM, then run
> fastboot on host:
> 
>   $ fastboot stage k3-uart-smt.bin
>   $ fastboot continue
> 
> ---
> Changes in v3:
> - Align the uimage_type table entry with surrounding columns
> - Explicitly include the needed headers
> - Drop SMT_PAYLOAD_ALIGN macro
> - Simplify the NULL check in smtimage_get_variant()
> - Fix the title underline length in smtimage.rst
> - Link to v2: https://patch.msgid.link/20260909-spacemit-aihd-v2-0-780e98cf2fec@pigmoral.tech
> 
> Changes in v2:
> - Use "smtimage" for the image type
> - Update the documentation and command examples to match
> - Link to v1: https://patch.msgid.link/20260822-spacemit-aihd-v1-0-bf4c41993891@pigmoral.tech
> 
> ---
> Junhui Liu (2):
>       tools: mkimage: add SpacemiT K3 boot image support
>       doc: board: spacemit: document the SpacemiT boot image format
> 
>  boot/image.c                    |   1 +
>  doc/board/spacemit/index.rst    |   2 +-
>  doc/board/spacemit/smtimage.rst | 143 +++++++++++++++++++++++++++
>  include/image.h                 |   1 +
>  tools/Makefile                  |   1 +
>  tools/smtimage.c                | 208 ++++++++++++++++++++++++++++++++++++++++
>  6 files changed, 355 insertions(+), 1 deletion(-)
> ---
Looks good, so with

Reviewed-by: Yixun Lan <dlan@kernel.org>

-- 
Yixun Lan (dlan)

Re: [PATCH v3 2/2] doc: board: spacemit: document the SpacemiT boot image format

[E Shattow]

Hi Junhui,

On 9/21/26 07:54, Junhui Liu wrote:
> Document the boot image layout shared by the SpacemiT K1 and K3
> BootROMs, including the metadata headers and authentication areas.
> 
> Describe the K3 non-secure CRC32 path supported by mkimage and provide
> an example using the "smtimage" image type with "-n k3".
> 
> Tested-by: E Shattow <e@freeshell.de>
> Signed-off-by: Junhui Liu <junhui.liu@pigmoral.tech>
> ---
>  doc/board/spacemit/index.rst    |   2 +-
>  doc/board/spacemit/smtimage.rst | 143 ++++++++++++++++++++++++++++++++++++++++
>  2 files changed, 144 insertions(+), 1 deletion(-)
> 
> diff --git a/doc/board/spacemit/index.rst b/doc/board/spacemit/index.rst
> index a5e35ee12ab6..5797ada37d15 100644
> --- a/doc/board/spacemit/index.rst
> +++ b/doc/board/spacemit/index.rst
> @@ -7,4 +7,4 @@ SpacemiT
>  
>     bananapi-f3
>     k1-spl
> -
> +   smtimage
> diff --git a/doc/board/spacemit/smtimage.rst b/doc/board/spacemit/smtimage.rst
> new file mode 100644
> index 000000000000..19a5c9972f75
> --- /dev/null
> +++ b/doc/board/spacemit/smtimage.rst
> @@ -0,0 +1,143 @@
> +.. SPDX-License-Identifier: GPL-2.0-or-later
> +
> +SpacemiT boot image format
> +==========================
> +
> +The SpacemiT K1 and K3 BootROMs load a SpacemiT boot image as the first-stage
> +bootloader (FSBL), either from persistent storage or over USB in MaskROM mode.

"BootROM on SpacemiT K1 or K3 System-on-Chip expects the First Stage
BootLoader to be wrapped in a specially constructed image layout." and
delete the unrelated fact about boot flow.

> +
> +Image layout
> +------------
> +
> +K1 and K3 share the same layout. A fixed 4 KiB prefix contains two 32-byte

Delete redundant sentence "K1 and K3 share the same layout", as it is
implied above and cannot be anything else by the later description.


> +metadata headers, key slots, and signature slots. The aligned SPL payload and
> +a trailing authentication area follow::

The architectural reasoning of payload alignment should be part of this
sentence if it is known. From my experience looking at disassembled
BootROM of another SoC there is a trend of structs and string data
sections to be extended to 8-byte alignment (word-aligned for 64-bit
RISC-V); Why would the payload be extended to quad-word alignment, is
this related to the NOR flash page size and/or a cryptography
requirement? Disregard my inquiry here if it is not known the reason for
this.

> +
> +    offset                                    size
> +    0x000  +-------------------------------+
> +           | root RSA-2048 modulus         |  0x100
> +    0x100  +-------------------------------+
> +           | header0                       |  0x020
> +    0x120  +-------------------------------+
> +           | key-selection metadata        |  0x1e0
> +    0x300  +-------------------------------+
> +           | OEM public-key slots          |  0x800
> +    0xb00  +-------------------------------+
> +           | signature0                    |  0x100
> +    0xc00  +-------------------------------+
> +           | reserved                      |  0x3e0
> +    0xfe0  +-------------------------------+
> +           | header1                       |  0x020
> +    0x1000 +-------------------------------+
> +           | SPL payload (32-byte aligned) |

Keep "n-byte" as-is when discussing byte-layout to describe alignment
and not i.e. word or half-word or nibble etc. considering my previous
suggestion.

> +           +-------------------------------+
> +           | signature1                    |  0x100
> +           +-------------------------------+
> +
> +For payload size ``P`` and ``A = ALIGN(P, 32)``, the image size is
> +``0x1000 + A + 0x100``.
> +
> +Metadata header
> +---------------
> +
> +Both header0 and header1 use the following format:
> +
> +.. list-table::
> +   :header-rows: 1
> +
> +   * - Offset
> +     - Size
> +     - Field
> +     - Description
> +   * - 0x00
> +     - 4
> +     - ``magic``
> +     - ``AIHD``
> +   * - 0x04
> +     - 1
> +     - ``version``
> +     - Anti-rollback image version
> +   * - 0x05
> +     - 1
> +     - ``secure``
> +     - Zero selects anti-rollback bank 0
> +
> +       Non-zero selects anti-rollback bank 1
> +   * - 0x06
> +     - 2
> +     - ``reserved``
> +     - Reserved
> +   * - 0x08
> +     - 8
> +     - ``image_size``
> +     - header0: prefix information
> +
> +       header1: aligned payload size
> +   * - 0x10
> +     - 8
> +     - ``load_addr``
> +     - Unused by the common authentication code
> +   * - 0x18
> +     - 4
> +     - ``header_crc``
> +     - K3: CRC32 over header bytes ``[0x00, 0x18)``
> +   * - 0x1c
> +     - 4
> +     - ``image_crc``
> +     - K3: CRC32 over the payload in header1 only
> +
> +``header1.image_size`` records the aligned payload size and therefore
> +determines the location of signature1.
> +
> +Authentication
> +--------------
> +
> +K1 and K3 apply different authentication policies:
> +
> +.. list-table::
> +   :header-rows: 1

The previous list-table of offsets is okay for review and diff output,
however the following list-table is not acceptable.

> +
> +   * - Area
> +     - K1
> +     - K3 non-secure boot mode
> +     - K3 secure boot mode
> +   * - Root and OEM keys
> +     - RSA-2048 moduli with an eFuse root-hash check when secure boot is
> +       enabled
> +     - Unused
> +     - RSA-2048 moduli with an eFuse root-hash check
> +   * - Header CRC
> +     - Not checked separately
> +     - header1 verified
> +
> +       header0 ignored
> +     - Both verified and covered by RSA
> +   * - Image CRC
> +     - Not checked separately
> +     - Payload CRC32 in header1
> +     - Covered by RSA but not checked separately
> +   * - signature0
> +     - Verified with the root key over ``[0x100, 0xb00)``
> +     - Unused
> +     - Verified with the root key over ``[0x100, 0xb00)``

Why the mixed-use of square brackets and parenthesis?

> +   * - signature1
> +     - Verified with the SPL key over header1 and the aligned payload
> +     - Unused
> +     - Verified with the SPL key over header1 and the aligned payload
> +

I don't know what is preferred here by documentation reviewers but this
above list-table is not reviewable as-is. Maybe try to flip the axis, or
split into a series of tables as one-per-name of K1, K3 non-secure boot
mode, and K3 secure boot mode?  The purpose of restructuring this should
be readability before being rendered, and minimal 'diff' impact for
future changes.

> +K1 verifies both signatures even without a programmed root-key hash. In this
> +case, the root key comes from the image and is not authenticated by hardware,
> +so the image, keys, and signatures can be replaced together.
> +
> +K3 uses CRC32 in non-secure boot mode and hardware-rooted RSA in secure boot
> +mode.
> +
> +Creating an image
> +-----------------
> +
> +U-Boot currently creates only K3 images for non-secure boot mode. Package an
> +SPL payload with::
> +
> +    $ tools/mkimage -T smtimage -n k3 -d u-boot-spl.bin FSBL.bin

Use lowercase letters for the output filename if it is not any CONFIG_
symbol or preprocessor define symbol, and re-use an existing filename
stem as for example any of:

u-boot-spl.smtimage
u-boot-spl-mkimage.bin
u-boot-spl.bin.smtimage
spl.bin

A distro package of u-boot or later user of the build system may copy
this output to "FSBL.bin" but that is nothing to do with us here. In
fact for documentation purpose here it is useful to retain "FSBL.bin" as
a distinct description of the vendor firmware SPL and not get this
confused for mainline u-boot.

> +
> +K1 images and RSA-authenticated K3 images are not yet supported.
> 

This statement may be simply deleted. It is obvious that support does
not exist when it is not described here. If you would like to keep this
line it is not any problem. Similarly for the sentence "U-Boot currently
creates only K3 images for non-secure boot mode." which is not really
accurate to say, as there is no makefile target or binman setup for any
of this yet. Technically U-Boot does nothing at all regarding this
documentation. It would just have to be more diff lines to review later
and can be omitted now.

-E

Re: [PATCH v3 0/2] tools: mkimage: add SpacemiT K3 boot image support

[E Shattow]

Hi Junhui,

On 9/21/26 07:54, Junhui Liu wrote:
> The SpacemiT BootROM loads a first-stage bootloader from storage or over
> USB in MaskROM mode. Vendor firmware packages this bootloader as FSBL.bin.
> 
> This series documents the SpacemiT boot image format and adds the
> "smtimage" mkimage type for the CRC32-protected K3 variant used in
> non-secure boot mode. It provides the FSBL packaging needed for future
> K3 SPL support. Select K3 with "-n k3" when creating an image.
> 
> K1 and K3 secure boot use RSA authentication and are not supported yet.
> 
> How to test
> -----------
> 
> Rebuild mkimage, wrap a small UART test payload, and load it through K3
> MaskROM fastboot. The payload is linked at 0xc0801000 because the BootROM
> places the complete image at 0xc0800000 and enters the payload after the
> 4 KiB prefix. UART0 should print "Hello SpacemiT K3!" and then loop
> indefinitely.
> 
>   $ make tools-only_defconfig
>   $ make tools-only
> 
>   $ cat > k3-uart.S << 'EOF'
>   	.equ	UART0_THR, 0xd4017000
> 	.equ	UART0_LSR, 0xd4017014
> 
> 	.section	.text
> 	.global	_start
> _start:
> 	la	s0, str
> 1:
> 	lbu	a0, (s0)
> 	beqz	a0, exit
> 	call	uart_send
> 	addi	s0, s0, 1
> 	j	1b
> 
> exit:
> 	j	exit
> 
> uart_send:
> 	li	t0, UART0_LSR
> 	lw	t1, (t0)
> 	andi	t1, t1, 0x20
> 	beqz	t1, uart_send
> 	li	t0, UART0_THR
> 	sw	a0, (t0)
> 	ret
> 
> 	.section	.rodata
> str:
> 	.asciz	"Hello SpacemiT K3!\n"
> EOF
> 
>   $ riscv64-linux-gnu-gcc -nostdlib -fno-builtin -fno-pie -no-pie -static \
>     -march=rv64gc -mabi=lp64 -g -Wall -Wl,--build-id=none \
>     -Ttext=0xc0801000 -o k3-uart.elf k3-uart.S
>   $ riscv64-linux-gnu-objcopy -O binary k3-uart.elf k3-uart.bin
>   $ ./tools/mkimage -T smtimage -n k3 -d k3-uart.bin k3-uart-smt.bin
> 
> Hold the FDL button, power on the board to enter MaskROM, then run
> fastboot on host:
> 
>   $ fastboot stage k3-uart-smt.bin
>   $ fastboot continue
> 
> ---
> Changes in v3:
> - Align the uimage_type table entry with surrounding columns
> - Explicitly include the needed headers
> - Drop SMT_PAYLOAD_ALIGN macro
> - Simplify the NULL check in smtimage_get_variant()
> - Fix the title underline length in smtimage.rst
> - Link to v2: https://patch.msgid.link/20260909-spacemit-aihd-v2-0-780e98cf2fec@pigmoral.tech
> 
> Changes in v2:
> - Use "smtimage" for the image type
> - Update the documentation and command examples to match
> - Link to v1: https://patch.msgid.link/20260822-spacemit-aihd-v1-0-bf4c41993891@pigmoral.tech
> 
> ---
> Junhui Liu (2):
>       tools: mkimage: add SpacemiT K3 boot image support
>       doc: board: spacemit: document the SpacemiT boot image format
> 
>  boot/image.c                    |   1 +
>  doc/board/spacemit/index.rst    |   2 +-
>  doc/board/spacemit/smtimage.rst | 143 +++++++++++++++++++++++++++
>  include/image.h                 |   1 +
>  tools/Makefile                  |   1 +
>  tools/smtimage.c                | 208 ++++++++++++++++++++++++++++++++++++++++
>  6 files changed, 355 insertions(+), 1 deletion(-)
> ---
> base-commit: 211de43d0f954a00a490220c1aac9db298287c40
> change-id: 20260820-spacemit-aihd-05c46aae886e
> 
> Best regards,
> --  
> Junhui Liu <junhui.liu@pigmoral.tech>
> 

Thanks for your work on this, the actionable concerns I have with this
series are about keeping documentation short for being reviewable in
diff output, and revising the suggested SPL image output name to be more
sensible for mainline u-boot. Let's see another version and get this
merged, please.

-E

Re: [PATCH v3 2/2] doc: board: spacemit: document the SpacemiT boot image format

[Junhui Liu]

Hi E,

On Mon Oct 5, 2026 at 8:40 AM CST, E Shattow wrote:
> Hi Junhui,
>
> On 9/21/26 07:54, Junhui Liu wrote:
>> Document the boot image layout shared by the SpacemiT K1 and K3
>> BootROMs, including the metadata headers and authentication areas.
>> 
>> Describe the K3 non-secure CRC32 path supported by mkimage and provide
>> an example using the "smtimage" image type with "-n k3".
>> 
>> Tested-by: E Shattow <e@freeshell.de>
>> Signed-off-by: Junhui Liu <junhui.liu@pigmoral.tech>
>> ---
>>  doc/board/spacemit/index.rst    |   2 +-
>>  doc/board/spacemit/smtimage.rst | 143 ++++++++++++++++++++++++++++++++++++++++
>>  2 files changed, 144 insertions(+), 1 deletion(-)
>> 
>> diff --git a/doc/board/spacemit/index.rst b/doc/board/spacemit/index.rst
>> index a5e35ee12ab6..5797ada37d15 100644
>> --- a/doc/board/spacemit/index.rst
>> +++ b/doc/board/spacemit/index.rst
>> @@ -7,4 +7,4 @@ SpacemiT
>>  
>>     bananapi-f3
>>     k1-spl
>> -
>> +   smtimage
>> diff --git a/doc/board/spacemit/smtimage.rst b/doc/board/spacemit/smtimage.rst
>> new file mode 100644
>> index 000000000000..19a5c9972f75
>> --- /dev/null
>> +++ b/doc/board/spacemit/smtimage.rst
>> @@ -0,0 +1,143 @@
>> +.. SPDX-License-Identifier: GPL-2.0-or-later
>> +
>> +SpacemiT boot image format
>> +==========================
>> +
>> +The SpacemiT K1 and K3 BootROMs load a SpacemiT boot image as the first-stage
>> +bootloader (FSBL), either from persistent storage or over USB in MaskROM mode.
>
> "BootROM on SpacemiT K1 or K3 System-on-Chip expects the First Stage
> BootLoader to be wrapped in a specially constructed image layout." and
> delete the unrelated fact about boot flow.

I will update it.

>
>> +
>> +Image layout
>> +------------
>> +
>> +K1 and K3 share the same layout. A fixed 4 KiB prefix contains two 32-byte
>
> Delete redundant sentence "K1 and K3 share the same layout", as it is
> implied above and cannot be anything else by the later description.
>

I will update it.

>
>> +metadata headers, key slots, and signature slots. The aligned SPL payload and
>> +a trailing authentication area follow::
>
> The architectural reasoning of payload alignment should be part of this
> sentence if it is known. From my experience looking at disassembled
> BootROM of another SoC there is a trend of structs and string data
> sections to be extended to 8-byte alignment (word-aligned for 64-bit
> RISC-V); Why would the payload be extended to quad-word alignment, is
> this related to the NOR flash page size and/or a cryptography
> requirement? Disregard my inquiry here if it is not known the reason for
> this.

Both the K1 and K3 RSA authentication paths require 32-byte payload
alignment when determining the signed length and the location of
signature1. Although the K3 non-secure CRC32 path does not have this
requirement, we use the same alignment for a consistent image layout and
to follow the behavior of the vendor packaging tool.

I will add a short note about this.

>
>> +
>> +    offset                                    size
>> +    0x000  +-------------------------------+
>> +           | root RSA-2048 modulus         |  0x100
>> +    0x100  +-------------------------------+
>> +           | header0                       |  0x020
>> +    0x120  +-------------------------------+
>> +           | key-selection metadata        |  0x1e0
>> +    0x300  +-------------------------------+
>> +           | OEM public-key slots          |  0x800
>> +    0xb00  +-------------------------------+
>> +           | signature0                    |  0x100
>> +    0xc00  +-------------------------------+
>> +           | reserved                      |  0x3e0
>> +    0xfe0  +-------------------------------+
>> +           | header1                       |  0x020
>> +    0x1000 +-------------------------------+
>> +           | SPL payload (32-byte aligned) |
>
> Keep "n-byte" as-is when discussing byte-layout to describe alignment
> and not i.e. word or half-word or nibble etc. considering my previous
> suggestion.
>
>> +           +-------------------------------+
>> +           | signature1                    |  0x100
>> +           +-------------------------------+
>> +
>> +For payload size ``P`` and ``A = ALIGN(P, 32)``, the image size is
>> +``0x1000 + A + 0x100``.
>> +
>> +Metadata header
>> +---------------
>> +
>> +Both header0 and header1 use the following format:
>> +
>> +.. list-table::
>> +   :header-rows: 1
>> +
>> +   * - Offset
>> +     - Size
>> +     - Field
>> +     - Description
>> +   * - 0x00
>> +     - 4
>> +     - ``magic``
>> +     - ``AIHD``
>> +   * - 0x04
>> +     - 1
>> +     - ``version``
>> +     - Anti-rollback image version
>> +   * - 0x05
>> +     - 1
>> +     - ``secure``
>> +     - Zero selects anti-rollback bank 0
>> +
>> +       Non-zero selects anti-rollback bank 1
>> +   * - 0x06
>> +     - 2
>> +     - ``reserved``
>> +     - Reserved
>> +   * - 0x08
>> +     - 8
>> +     - ``image_size``
>> +     - header0: prefix information
>> +
>> +       header1: aligned payload size
>> +   * - 0x10
>> +     - 8
>> +     - ``load_addr``
>> +     - Unused by the common authentication code
>> +   * - 0x18
>> +     - 4
>> +     - ``header_crc``
>> +     - K3: CRC32 over header bytes ``[0x00, 0x18)``
>> +   * - 0x1c
>> +     - 4
>> +     - ``image_crc``
>> +     - K3: CRC32 over the payload in header1 only
>> +
>> +``header1.image_size`` records the aligned payload size and therefore
>> +determines the location of signature1.
>> +
>> +Authentication
>> +--------------
>> +
>> +K1 and K3 apply different authentication policies:
>> +
>> +.. list-table::
>> +   :header-rows: 1
>
> The previous list-table of offsets is okay for review and diff output,
> however the following list-table is not acceptable.
>
>> +
>> +   * - Area
>> +     - K1
>> +     - K3 non-secure boot mode
>> +     - K3 secure boot mode
>> +   * - Root and OEM keys
>> +     - RSA-2048 moduli with an eFuse root-hash check when secure boot is
>> +       enabled
>> +     - Unused
>> +     - RSA-2048 moduli with an eFuse root-hash check
>> +   * - Header CRC
>> +     - Not checked separately
>> +     - header1 verified
>> +
>> +       header0 ignored
>> +     - Both verified and covered by RSA
>> +   * - Image CRC
>> +     - Not checked separately
>> +     - Payload CRC32 in header1
>> +     - Covered by RSA but not checked separately
>> +   * - signature0
>> +     - Verified with the root key over ``[0x100, 0xb00)``
>> +     - Unused
>> +     - Verified with the root key over ``[0x100, 0xb00)``
>
> Why the mixed-use of square brackets and parenthesis?

I think this is a fairly common mathematical notation for a half-open
interval. If you find it less readable in this context, I can change it
to [0x100, 0xaff] instead.

>
>> +   * - signature1
>> +     - Verified with the SPL key over header1 and the aligned payload
>> +     - Unused
>> +     - Verified with the SPL key over header1 and the aligned payload
>> +
>
> I don't know what is preferred here by documentation reviewers but this
> above list-table is not reviewable as-is. Maybe try to flip the axis, or
> split into a series of tables as one-per-name of K1, K3 non-secure boot
> mode, and K3 secure boot mode?  The purpose of restructuring this should
> be readability before being rendered, and minimal 'diff' impact for
> future changes.

I combined the three cases in one table intentionally, so readers can
compare the treatment of each field across the K1, K3 non-secure, and K3
secure paths side by side. Splitting it into three tables would make
that comparison less direct and require readers to move back and forth
between them. It would also duplicate the field names across the three
tables.

Given that trade-off, I would prefer to keep the current table layout.

>
>> +K1 verifies both signatures even without a programmed root-key hash. In this
>> +case, the root key comes from the image and is not authenticated by hardware,
>> +so the image, keys, and signatures can be replaced together.
>> +
>> +K3 uses CRC32 in non-secure boot mode and hardware-rooted RSA in secure boot
>> +mode.
>> +
>> +Creating an image
>> +-----------------
>> +
>> +U-Boot currently creates only K3 images for non-secure boot mode. Package an
>> +SPL payload with::
>> +
>> +    $ tools/mkimage -T smtimage -n k3 -d u-boot-spl.bin FSBL.bin
>
> Use lowercase letters for the output filename if it is not any CONFIG_
> symbol or preprocessor define symbol, and re-use an existing filename
> stem as for example any of:
>
> u-boot-spl.smtimage
> u-boot-spl-mkimage.bin
> u-boot-spl.bin.smtimage
> spl.bin

Okay. I prefer .bin as the filename suffix. I think I will use
u-boot-spl-smtimage.bin.

>
> A distro package of u-boot or later user of the build system may copy
> this output to "FSBL.bin" but that is nothing to do with us here. In
> fact for documentation purpose here it is useful to retain "FSBL.bin" as
> a distinct description of the vendor firmware SPL and not get this
> confused for mainline u-boot.
>
>> +
>> +K1 images and RSA-authenticated K3 images are not yet supported.
>> 
>
> This statement may be simply deleted. It is obvious that support does
> not exist when it is not described here. If you would like to keep this
> line it is not any problem. Similarly for the sentence "U-Boot currently
> creates only K3 images for non-secure boot mode." which is not really
> accurate to say, as there is no makefile target or binman setup for any
> of this yet. Technically U-Boot does nothing at all regarding this
> documentation. It would just have to be more diff lines to review later
> and can be omitted now.

I will remove it.

>
> -E

-- 
Best regards,
Junhui Liu

Re: [PATCH v3 2/2] doc: board: spacemit: document the SpacemiT boot image format

[E Shattow]

Hi Junhui, I have some follow-up to add to the discussion,

On 10/4/26 21:25, Junhui Liu wrote:
> Hi E,
> 
> On Mon Oct 5, 2026 at 8:40 AM CST, E Shattow wrote:
>> Hi Junhui,
...
>>
>> The previous list-table of offsets is okay for review and diff output,
>> however the following list-table is not acceptable.
>>
>>> +
>>> +   * - Area
>>> +     - K1
>>> +     - K3 non-secure boot mode
>>> +     - K3 secure boot mode
>>> +   * - Root and OEM keys
>>> +     - RSA-2048 moduli with an eFuse root-hash check when secure boot is
>>> +       enabled
>>> +     - Unused
>>> +     - RSA-2048 moduli with an eFuse root-hash check
>>> +   * - Header CRC
>>> +     - Not checked separately
>>> +     - header1 verified
>>> +
>>> +       header0 ignored
>>> +     - Both verified and covered by RSA
>>> +   * - Image CRC
>>> +     - Not checked separately
>>> +     - Payload CRC32 in header1
>>> +     - Covered by RSA but not checked separately
>>> +   * - signature0
>>> +     - Verified with the root key over ``[0x100, 0xb00)``
>>> +     - Unused
>>> +     - Verified with the root key over ``[0x100, 0xb00)``
>>
>> Why the mixed-use of square brackets and parenthesis?
> 
> I think this is a fairly common mathematical notation for a half-open
> interval. If you find it less readable in this context, I can change it
> to [0x100, 0xaff] instead.

Let's qualify the interval notation with verbose "interval", for example:

-     - Verified with the root key over ``[0x100, 0xb00)``
+     - Verified with the root key over ``[0x100, 0xb00)`` interval

With this verbose qualifier I have some hope to search Wikipedia for
"interval" and learn about the symbolic representation. I assume here a
half-open interval representation is one of many forms of a
classification of "interval", so simply adding "interval" is enough context.

> 
>>
>>> +   * - signature1
>>> +     - Verified with the SPL key over header1 and the aligned payload
>>> +     - Unused
>>> +     - Verified with the SPL key over header1 and the aligned payload
>>> +
>>
>> I don't know what is preferred here by documentation reviewers but this
>> above list-table is not reviewable as-is. Maybe try to flip the axis, or
>> split into a series of tables as one-per-name of K1, K3 non-secure boot
>> mode, and K3 secure boot mode?  The purpose of restructuring this should
>> be readability before being rendered, and minimal 'diff' impact for
>> future changes.
> 
> I combined the three cases in one table intentionally, so readers can
> compare the treatment of each field across the K1, K3 non-secure, and K3
> secure paths side by side. Splitting it into three tables would make
> that comparison less direct and require readers to move back and forth
> between them. It would also duplicate the field names across the three
> tables.
> 
> Given that trade-off, I would prefer to keep the current table layout.
> 

No complaint about the rendered output it is very useful.

What I am meaning by "flip the axis" is for example:

.. list-table:: Authentication policy
   :header-rows: 1

   * - Image Variant
     - Root and OEM keys
     - Header CRC
     - Image CRC
     - signature0
     - signature1
   * - K1
     - RSA-2048 moduli with an eFuse root-hash check when secure boot is
       enabled
     - Not checked separately
     - Not checked separately
     - Verified with the root key over ``[0x100, 0xb00)`` interval
     - Verified with the SPL key over header1 and the aligned payload
   * - K3 non-secure
     - Unused
     - | header1 verified
       | header0 ignored
     - Payload CRC32 in header1
     - Unused
     - Unused
   * - K3 secure
     - RSA-2048 moduli with an eFuse root-hash check
     - Both verified and covered by RSA
     - Covered by RSA but not checked separately
     - Verified with the root key over ``[0x100, 0xb00)``
     - Verified with the SPL key over header1 and the aligned payload

Reviewability is improved yet it remains confusing and is less readable
on the rendered output.

Next, to then delete the column headers, move column descriptions to
natural-language descriptions, and keep a single-table format:

.. list-table:: Authentication policy

   * - K1
     - RSA-2048 moduli root and OEM keys with an eFuse root-hash check
       when secure boot is enabled
     - No additional header verification
     - No additional image checksum
     - Verified signature0 with the root key over ``[0x100, 0xb00)``
       interval
     - Verified signature1 with the SPL key over header1 and the aligned
       payload
   * - K3 non-secure
     - Unused root and OEM keys
     - header0 ignored, header1 verified
     - Image payload CRC32 in header1
     - Unused signature0
     - Unused signature1
   * - K3 secure
     - RSA-2048 moduli root and OEM keys with an eFuse root-hash check
     - header0 and header1 both verified and covered by RSA
     - No additional image checksum
     - Verified signature0 with the root key over ``[0x100, 0xb00)``
       interval
     - Verified signature1 with the SPL key over header1 and the aligned
       payload

I can now read this comfortably both in source and in rendered output.
What do you think?

>>
>>> +K1 verifies both signatures even without a programmed root-key hash. In this
>>> +case, the root key comes from the image and is not authenticated by hardware,
>>> +so the image, keys, and signatures can be replaced together.
>>> +
>>> +K3 uses CRC32 in non-secure boot mode and hardware-rooted RSA in secure boot
>>> +mode.
>>> +
>>> +Creating an image
>>> +-----------------
>>> +
>>> +U-Boot currently creates only K3 images for non-secure boot mode. Package an
>>> +SPL payload with::
>>> +
>>> +    $ tools/mkimage -T smtimage -n k3 -d u-boot-spl.bin FSBL.bin
>>
>> Use lowercase letters for the output filename if it is not any CONFIG_
>> symbol or preprocessor define symbol, and re-use an existing filename
>> stem as for example any of:
>>
>> u-boot-spl.smtimage
>> u-boot-spl-mkimage.bin
>> u-boot-spl.bin.smtimage
>> spl.bin
> 
> Okay. I prefer .bin as the filename suffix. I think I will use
> u-boot-spl-smtimage.bin.

Let's re-use "u-boot-spl-mkimage.bin" and
"u-boot-spl-mkimage.signed.bin" since you prefer ".bin" suffix and not
"smtimage" suffix?

`uniq` counts:

4  "spl/boot.bin"
4  "u-boot-spl-mkimage.bin"
4  "u-boot-spl-mkimage.signed.bin"
8  "spl.bin"
17  "u-boot-spl-ddr.bin"

SpacemiT K1 boards do use "u-boot-spl-ddr.bin" filename for the
processed SPL image but that is a binman artifact of some DDR training
blob from before support for smtimage is added to mkimage.

It may be a benefit for distro packagers and CI/CD workflow to have
distinct filenames for unsigned and signed output, so
"u-boot-spl-mkimage.bin" and "u-boot-spl-mkimage.signed.bin", otherwise
I would say "spl.bin" is short and popular for re-use.

> 
>>
>> A distro package of u-boot or later user of the build system may copy
>> this output to "FSBL.bin" but that is nothing to do with us here. In
>> fact for documentation purpose here it is useful to retain "FSBL.bin" as
>> a distinct description of the vendor firmware SPL and not get this
>> confused for mainline u-boot.
>>
>>> +
>>> +K1 images and RSA-authenticated K3 images are not yet supported.
>>>
>>
>> This statement may be simply deleted. It is obvious that support does
>> not exist when it is not described here. If you would like to keep this
>> line it is not any problem. Similarly for the sentence "U-Boot currently
>> creates only K3 images for non-secure boot mode." which is not really
>> accurate to say, as there is no makefile target or binman setup for any
>> of this yet. Technically U-Boot does nothing at all regarding this
>> documentation. It would just have to be more diff lines to review later
>> and can be omitted now.
> 
> I will remove it.
> 
>>
>> -E
> 

With all that, and I'll confirm my R-by tag again in the next round so
not to delay the series,

Reviewed-by: E Shattow <e@freeshell.de>