AIHD is the first-stage boot image format used by the SpacemiT K1 and K3 BootROMs. Document its layout and the K3 non-secure CRC32 path currently supported by mkimage.
Signed-off-by: Junhui Liu <[email protected]> --- doc/board/spacemit/aihd.rst | 145 +++++++++++++++++++++++++++++++++++++++++++ doc/board/spacemit/index.rst | 2 +- 2 files changed, 146 insertions(+), 1 deletion(-) diff --git a/doc/board/spacemit/aihd.rst b/doc/board/spacemit/aihd.rst new file mode 100644 index 000000000000..9a14fefc4d75 --- /dev/null +++ b/doc/board/spacemit/aihd.rst @@ -0,0 +1,145 @@ +.. SPDX-License-Identifier: GPL-2.0-or-later + +SpacemiT AIHD image format +========================== + +The SpacemiT K1 and K3 BootROMs load an AIHD image as the first-stage +bootloader (FSBL), either from persistent storage or over USB in MaskROM mode. +Vendor firmware calls this image ``FSBL.bin``. The format is named after its +AIHD header magic. + +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 aihdimage -n k3 -d u-boot-spl.bin FSBL.bin + +K1 images and RSA-authenticated K3 images are not yet supported. diff --git a/doc/board/spacemit/index.rst b/doc/board/spacemit/index.rst index a5e35ee12ab6..45ef54f1543b 100644 --- a/doc/board/spacemit/index.rst +++ b/doc/board/spacemit/index.rst @@ -5,6 +5,6 @@ SpacemiT .. toctree:: :maxdepth: 1 + aihd bananapi-f3 k1-spl - -- 2.55.0
