[PATCH 05/17] android: boot: add documentation for boot image header v3/v4 structure

[Sean Anderson]

On 11/26/22 11:59, Safae Ouajih wrote:
> [You don't often get email from souajih at baylibre.com. Learn why this is important at https://aka.ms/LearnAboutSenderIdentification ]
> 
> This was imported from [1], commit [2], file: include/bootimg/bootimg.h
> [1] https://android.googlesource.com/platform/system/tools/mkbootimg
> [2] cce5b1923e3cd2fcb765b512610bdc5c42bc501d

In general, downstream commits are not terribly useful. However, this is just
the current tip of that repo, not even the commit which this is imported from.

Please write your commit messages to describe what you are doing and why.

> Signed-off-by: Safae Ouajih <souajih at baylibre.com>
> ---
>  include/android_image.h | 136 +++++++++++++++++++++++++++++++++++++++-
>  1 file changed, 135 insertions(+), 1 deletion(-)
> 
> diff --git a/include/android_image.h b/include/android_image.h
> index ec36e6512ad6..62121e2a109b 100644
> --- a/include/android_image.h
> +++ b/include/android_image.h
> @@ -3,7 +3,7 @@
>   * This is from the Android Project,
>   * Repository: https://android.googlesource.com/platform/system/tools/mkbootimg
>   * File: include/bootimg/bootimg.h
> - * Commit: e55998a0f2b61b685d5eb4a486ca3a0c680b1a2f
> + * Commit: cce5b1923e3cd2fcb765b512610bdc5c42bc501d
>   *
>   * Copyright (C) 2007 The Android Open Source Project
>   */
> @@ -183,4 +183,138 @@ struct andr_boot_img_hdr_v0_v1_v2 {
>   *    else: jump to kernel_addr
>   */
> 
> +/* When the boot image header has a version of 3, the structure of the boot
> + * image is as follows:
> + *
> + * +---------------------+
> + * | boot header         | 4096 bytes
> + * +---------------------+
> + * | kernel              | m pages
> + * +---------------------+
> + * | ramdisk             | n pages
> + * +---------------------+
> + *
> + * m = (kernel_size + 4096 - 1) / 4096
> + * n = (ramdisk_size + 4096 - 1) / 4096
> + *
> + * Note that in version 3 of the boot image header, page size is fixed at 4096 bytes.
> + *
> + * The structure of the vendor boot image (introduced with version 3 and
> + * required to be present when a v3 boot image is used) is as follows:
> + *
> + * +---------------------+
> + * | vendor boot header  | o pages
> + * +---------------------+
> + * | vendor ramdisk      | p pages
> + * +---------------------+
> + * | dtb                 | q pages
> + * +---------------------+
> + * o = (2112 + page_size - 1) / page_size
> + * p = (vendor_ramdisk_size + page_size - 1) / page_size
> + * q = (dtb_size + page_size - 1) / page_size
> + *
> + * 0. all entities in the boot image are 4096-byte aligned in flash, all
> + *    entities in the vendor boot image are page_size (determined by the vendor
> + *    and specified in the vendor boot image header) aligned in flash
> + * 1. kernel, ramdisk, vendor ramdisk, and DTB are required (size != 0)
> + * 2. load the kernel and DTB at the specified physical address (kernel_addr,
> + *    dtb_addr)
> + * 3. load the vendor ramdisk at ramdisk_addr
> + * 4. load the generic ramdisk immediately following the vendor ramdisk in
> + *    memory
> + * 5. set up registers for kernel entry as required by your architecture
> + * 6. if the platform has a second stage bootloader jump to it (must be
> + *    contained outside boot and vendor boot partitions), otherwise
> + *    jump to kernel_addr
> + */
> +
> +/* When the boot image header has a version of 4, the structure of the boot
> + * image is as follows:
> + *
> + * +---------------------+
> + * | boot header         | 4096 bytes
> + * +---------------------+
> + * | kernel              | m pages
> + * +---------------------+
> + * | ramdisk             | n pages
> + * +---------------------+
> + * | boot signature      | g pages
> + * +---------------------+
> + *
> + * m = (kernel_size + 4096 - 1) / 4096
> + * n = (ramdisk_size + 4096 - 1) / 4096
> + * g = (signature_size + 4096 - 1) / 4096
> + *
> + * Note that in version 4 of the boot image header, page size is fixed at 4096
> + * bytes.
> + *
> + * The structure of the vendor boot image version 4, which is required to be
> + * present when a version 4 boot image is used, is as follows:
> + *
> + * +------------------------+
> + * | vendor boot header     | o pages
> + * +------------------------+
> + * | vendor ramdisk section | p pages
> + * +------------------------+
> + * | dtb                    | q pages
> + * +------------------------+
> + * | vendor ramdisk table   | r pages
> + * +------------------------+
> + * | bootconfig             | s pages
> + * +------------------------+
> + *
> + * o = (2128 + page_size - 1) / page_size
> + * p = (vendor_ramdisk_size + page_size - 1) / page_size
> + * q = (dtb_size + page_size - 1) / page_size
> + * r = (vendor_ramdisk_table_size + page_size - 1) / page_size
> + * s = (vendor_bootconfig_size + page_size - 1) / page_size
> + *
> + * Note that in version 4 of the vendor boot image, multiple vendor ramdisks can
> + * be included in the vendor boot image. The bootloader can select a subset of
> + * ramdisks to load at runtime. To help the bootloader select the ramdisks, each
> + * ramdisk is tagged with a type tag and a set of hardware identifiers
> + * describing the board, soc or platform that this ramdisk is intended for.
> + *
> + * The vendor ramdisk section is consist of multiple ramdisk images concatenated
> + * one after another, and vendor_ramdisk_size is the size of the section, which
> + * is the total size of all the ramdisks included in the vendor boot image.
> + *
> + * The vendor ramdisk table holds the size, offset, type, name and hardware
> + * identifiers of each ramdisk. The type field denotes the type of its content.
> + * The vendor ramdisk names are unique. The hardware identifiers are specified
> + * in the board_id field in each table entry. The board_id field is consist of a
> + * vector of unsigned integer words, and the encoding scheme is defined by the
> + * hardware vendor.
> + *
> + * For the different type of ramdisks, there are:
> + *    - VENDOR_RAMDISK_TYPE_NONE indicates the value is unspecified.
> + *    - VENDOR_RAMDISK_TYPE_PLATFORM ramdisks contain platform specific bits, so
> + *      the bootloader should always load these into memory.
> + *    - VENDOR_RAMDISK_TYPE_RECOVERY ramdisks contain recovery resources, so
> + *      the bootloader should load these when booting into recovery.
> + *    - VENDOR_RAMDISK_TYPE_DLKM ramdisks contain dynamic loadable kernel
> + *      modules.
> + *
> + * Version 4 of the vendor boot image also adds a bootconfig section to the end
> + * of the image. This section contains Boot Configuration parameters known at
> + * build time. The bootloader is responsible for placing this section directly
> + * after the generic ramdisk, followed by the bootconfig trailer, before
> + * entering the kernel.
> + *
> + * 0. all entities in the boot image are 4096-byte aligned in flash, all
> + *    entities in the vendor boot image are page_size (determined by the vendor
> + *    and specified in the vendor boot image header) aligned in flash
> + * 1. kernel, ramdisk, and DTB are required (size != 0)
> + * 2. load the kernel and DTB at the specified physical address (kernel_addr,
> + *    dtb_addr)
> + * 3. load the vendor ramdisks at ramdisk_addr
> + * 4. load the generic ramdisk immediately following the vendor ramdisk in
> + *    memory
> + * 5. load the bootconfig immediately following the generic ramdisk. Add
> + *    additional bootconfig parameters followed by the bootconfig trailer.
> + * 6. set up registers for kernel entry as required by your architecture
> + * 7. if the platform has a second stage bootloader jump to it (must be
> + *    contained outside boot and vendor boot partitions), otherwise
> + *    jump to kernel_addr
> + */
>  #endif
> --
> 2.25.1
> 

Please combine this with the previous commit.

--Sean