On 10/4/26 14:22, E Shattow wrote: > Hi Junhui, > > On 9/9/26 08:51, 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 <[email protected]> >> Signed-off-by: Junhui Liu <[email protected]> >> --- >> 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..edcc3091e8e7 >> --- /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. > > Introduce the topic of SpacemiT boot image format without the unrelated > boot flow. If the BootROM of both K1 and K3 are identical then use "K1 > and K3", else if they are distinct and being described sharing the same > data structure format as input then use "K1 or K3". > > Try instead, "BootROM on SpacemiT K1 or K3 System-on-Chip expects the > First Stage BootLoader to be wrapped in a specially constructed image > layout." > >> + >> +Image layout >> +------------ >> + >> +K1 and K3 share the same layout. A fixed 4 KiB prefix contains two 32-byte > > Drop the 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 > > The reasoning of alignment should be written if it is known, by changing > "The aligned SPL payload" to e.g. "The word-aligned SPL payload" or "The > half-word aligned SPL payload" or "The nibble-aligned SPL payload" etc. > whatever that is actually, or disregard my suggestion here if it is not > known the reason for this. > >> +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) | > > Keep as-is when discussing byte-layout to describe alignment as "n-byte" > and not word or half-word or nibble etc. when considering my previous > suggestion, FYI. > >> + +-------------------------------+ >> + | 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 > > list-table format on this axis orientation is confusing to review > without first rendering the formatted output, and is a problem for > 'diff' tool output in future changes. Please flip the axis i.e.: > > Category 1 > SoC 1 > SoC 2 > SoC 3 > > Category 2 > SoC 1 > SoC 2 > SoC 3 > > Write instead this as: > > SoC 1 > Category 1 > Category 2 > > SoC 2 > Category 1 > Category 2 > > SoC 3 > Category 1 > Category 2 > >> + >> + * - 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 > > Why the mixed-use of square brackets and parenthesis? > >> + - 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 > > 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. I think it is more unnecessary work for > later to update and remove it. > > -E
P.S. I somehow miss there is v3 of this series posted due to mail configuration problem, ignore this response to v2 and I will re-send as review of v3. Sorry for the noise. -E
