開機映像檔標頭

Android 9 在啟動映像檔標頭中導入版本欄位，可更新標頭，同時維持回溯相容性。開機載入程式必須檢查標頭版本欄位，並據此剖析標頭。推出時搭載：

  • Android 13 可以使用啟動標頭版本 3 或 4。對於支援通用核心映像檔 (GKI) 架構的裝置，版本 4 是主要開機映像檔，且開機標頭中的 os_version 欄位必須為零。裝置啟動載入程式應改為從 Android 驗證開機 (AVB) 屬性取得版本資訊。
  • Android 12 可以使用啟動標頭版本 3 或 4。對於支援通用核心映像檔 (GKI) 架構的裝置，版本 4 是主要開機映像檔。
  • Android 11 可以使用啟動標頭版本 3。對於支援通用核心映像檔 (GKI) 架構的裝置，主要開機映像檔必須使用這個版本。
  • Android 10 必須使用啟動標頭版本 2。
  • Android 9 必須使用啟動標頭版本 1。
  • Android 8 以下版本會視為使用啟動映像檔標頭版本 0。

對於所有搭載 Android 9 以上版本的裝置，供應商測試套件 (VTS) 會檢查 boot/recovery 映像檔的格式，確保開機映像檔標頭使用正確版本。如要查看所有支援的開機和供應商開機映像檔標頭的 Android 開放原始碼計畫詳細資料，請參閱 system/tools/mkbootimg/include/bootimg/bootimg.h。

實作開機映像檔標頭版本管理

mkbootimg 工具接受下列引數。

引數 說明
header_version 設定開機映像檔標頭版本。具有標頭版本的開機映像檔：
  • 1 或 2 支援復原 DTBO 映像檔或復原 ACPIO 映像檔。
  • 3 不支援還原映像檔。
recovery_dtbo 適用於使用 DTB 的架構。指定復原 DTBO 映像檔的路徑。A/B 裝置可選用此選項，因為這類裝置不需要復原映像檔。 使用 header_version 的非 A/B 裝置：
  • 1 或 2 可以指定這個路徑，或使用 recovery_acpio 區段指定復原 ACPIO 映像檔的路徑。
  • 3 無法指定復原 DTBO 映像檔。
recovery_acpio 適用於使用 ACPI 而非 DTB 的架構。指定復原 ACPIO 映像檔的路徑。對於不需要復原映像檔的 A/B 裝置，這是選用步驟。使用 header_version 的非 A/B 裝置：
  • 1 或 2 可以指定這個路徑，或使用 recovery_dtbo 區段指定復原 DTBO 映像檔的路徑。
  • 3 無法指定復原 ACPIO 映像檔。
dtb 開機/復原映像檔中包含的 DTB 映像檔路徑。
dtb_offset 新增至 base 引數時，會提供最終裝置樹狀結構的實體載入位址。舉例來說，如果 base 引數為 0x10000000，且 dtb_offset 引數為 0x01000000，則開機映像檔標頭中的 dtb_addr_field 會填入 0x11000000。

裝置 BoardConfig.mk 會使用設定 BOARD_MKBOOTIMG_ARGS，將 header version 新增至 mkbootimg 的其他主機板專屬引數。例如：

BOARD_MKBOOTIMG_ARGS := --ramdisk_offset $(BOARD_RAMDISK_OFFSET) --tags_offset $(BOARD_KERNEL_TAGS_OFFSET) --header_version $(BOARD_BOOTIMG_HEADER_VERSION)

Android 建構系統會在建立復原映像檔時，使用 BoardConfig 變數 BOARD_PREBUILT_DTBOIMAGE 設定 mkbootimg 工具的引數 recovery_dtbo。如要瞭解 Android 開放原始碼計畫 (AOSP) 的變更，請參閱開機映像檔標頭版本控管的相關變更清單。

開機映像檔標頭，版本 4

Android 12 在啟動映像檔標頭版本 4 中提供 boot_signature，可用於檢查核心和 ramdisk 的完整性。這項檢查會在 VtsSecurityAvbTest 中完成，且使用 GKI 架構的裝置必須通過這項檢查。不過，boot_signature 不會參與裝置專屬的驗證開機程序，只會用於 VTS。詳情請參閱「GKI boot.img 板載設定」和「GKI 驗證開機設定」。

供應商開機映像檔標頭第 4 版支援多個供應商 ramdisk 片段。

啟動映像檔標頭版本 4 採用下列格式。

struct boot_img_hdr
{
#define BOOT_MAGIC_SIZE 8
    uint8_t magic[BOOT_MAGIC_SIZE];

    uint32_t kernel_size;    /* size in bytes */
    uint32_t ramdisk_size;   /* size in bytes */

    uint32_t os_version;

    uint32_t header_size;    /* size of boot image header in bytes */
    uint32_t reserved[4];
    uint32_t header_version; /* offset remains constant for version check */

#define BOOT_ARGS_SIZE 512
#define BOOT_EXTRA_ARGS_SIZE 1024
    uint8_t cmdline[BOOT_ARGS_SIZE + BOOT_EXTRA_ARGS_SIZE];

    uint32_t signature_size; /* size in bytes */
};

開機映像檔標頭，第 3 版

Android 11 會將啟動映像檔標頭更新至第 3 版，並移除下列資料：

  • 第二階段的系統啟動載入程式：啟動映像檔標頭中不再顯示 second_size 和 second_addr 欄位。具有第二階段系統啟動載入程式的裝置 必須將該系統啟動載入程式儲存在自己的分割區中。

  • 復原映像檔。指定復原映像檔的需求已遭淘汰，且 recovery_dtbo_size、recovery_dtbo_offset、recovery_acpio_size 和 recovery_acpio_offset 欄位不再顯示於開機映像檔標頭中。

    • A/B 裝置採用更新和復原機制，因此不需要指定 DTBO 或 ACPIO 映像檔進行復原。

    • 如要指定復原映像檔 (DTBO 或 ACPIO)，非 A/B 裝置應使用啟動映像檔標頭版本 1 或 2。

  • 裝置樹狀結構 Blob (DTB)。DTB 儲存在供應商開機分割區中，因此 dtb_size 和 dtb_addr 欄位不會再顯示在開機映像檔標頭中 (但會顯示在供應商開機映像檔標頭中)。

裝置可使用啟動映像檔標頭版本 3，以符合通用核心映像檔 (GKI) 架構，該架構會統一核心，並將啟動所需的供應商模組移至 vendor_boot 分割區 (也就是說，啟動映像檔只包含 GKI 元件)。裝置：

  • 使用 GKI (需要 android-4.19 或 android-5.4 核心)，但不要使用 A/B 更新可以透過開機映像檔版本 3 指定開機映像檔，並透過開機映像檔版本 2 指定復原映像檔。

  • 不使用 GKI 且不使用 A/B 更新的裝置，可以透過開機和復原映像檔的開機映像檔版本 1 或 2，指定復原映像檔。

啟動映像檔標頭版本 3 採用下列格式。

struct boot_img_hdr
{
#define BOOT_MAGIC_SIZE 8
    uint8_t magic[BOOT_MAGIC_SIZE];

    uint32_t kernel_size;    /* size in bytes */
    uint32_t ramdisk_size;   /* size in bytes */

    uint32_t os_version;

    uint32_t header_size;    /* size of boot image header in bytes */
    uint32_t reserved[4];
    uint32_t header_version; /* offset remains constant for version check */

#define BOOT_ARGS_SIZE 512
#define BOOT_EXTRA_ARGS_SIZE 1024
    uint8_t cmdline[BOOT_ARGS_SIZE + BOOT_EXTRA_ARGS_SIZE];
};

開機映像檔標頭，版本 2

Android 10 會將啟動映像檔標頭更新至版本 2， 並新增備援 DTB 映像檔資訊 (映像檔大小和實體載入位址) 的區段。

啟動映像檔標頭版本 2 採用下列格式。

struct boot_img_hdr
{
    uint8_t magic[BOOT_MAGIC_SIZE];
    uint32_t kernel_size;               /* size in bytes */
    uint32_t kernel_addr;               /* physical load addr */

    uint32_t ramdisk_size;              /* size in bytes */
    uint32_t ramdisk_addr;              /* physical load addr */

    uint32_t second_size;               /* size in bytes */
    uint32_t second_addr;               /* physical load addr */

    uint32_t tags_addr;                 /* physical addr for kernel tags */
    uint32_t page_size;                 /* flash page size we assume */
    uint32_t header_version;
    uint32_t os_version;
    uint8_t name[BOOT_NAME_SIZE];       /* asciiz product name */
    uint8_t cmdline[BOOT_ARGS_SIZE];
    uint32_t id[8];                     /* timestamp / checksum / sha1 / etc */
    uint8_t extra_cmdline[BOOT_EXTRA_ARGS_SIZE];
    uint32_t recovery_[dtbo|acpio]_size;    /* size of recovery image */
    uint64_t recovery_[dtbo|acpio]_offset;  /* offset in boot image */
    uint32_t header_size;               /* size of boot image header in bytes */
    uint32_t dtb_size;                  /* size of dtb image */
    uint64_t dtb_addr;                  /* physical load address */
};

開機映像檔標頭，版本 1

Android 9 會將啟動映像檔標頭的 unused 欄位轉換為標頭版本欄位。搭載 Android 9 的裝置必須使用啟動映像檔標頭，且標頭版本必須設為 1 以上 (VTS 會驗證這項設定)。

啟動映像檔標頭版本 1 採用下列格式。

struct boot_img_hdr
{
    uint8_t magic[BOOT_MAGIC_SIZE];
    uint32_t kernel_size;               /* size in bytes */
    uint32_t kernel_addr;               /* physical load addr */
    uint32_t ramdisk_size;              /* size in bytes */
    uint32_t ramdisk_addr;              /* physical load addr */

    uint32_t second_size;               /* size in bytes */
    uint32_t second_addr;               /* physical load addr */

    uint32_t tags_addr;                 /* physical addr for kernel tags */
    uint32_t page_size;                 /* flash page size we assume */
    uint32_t header_version;
    uint32_t os_version;
    uint8_t name[BOOT_NAME_SIZE];       /* asciiz product name */
    uint8_t cmdline[BOOT_ARGS_SIZE];
    uint32_t id[8];                     /* timestamp / checksum / sha1 / etc */
    uint8_t extra_cmdline[BOOT_EXTRA_ARGS_SIZE];
    uint32_t recovery_[dtbo|acpio]_size;    /* size of recovery image */
    uint64_t recovery_[dtbo|acpio]_offset;  /* offset in boot image */
    uint32_t header_size;               /* size of boot image header in bytes */
};

非 A/B 裝置可以指定用於復原的 DTB/ACPI 疊加映像檔，以協助減少無線更新 (OTA) 失敗的情況。(A/B 裝置不會有這個問題，也不需要指定重疊圖片)。您可以指定 DTBO 映像檔或 ACPIO 映像檔，但不能同時指定兩者 (因為兩者適用於不同架構)。如要正確設定啟動映像檔標頭，請使用：

  • 用於復原的 DTBO 映像檔，包括 recovery_dtbo_size 和 recovery_dtbo_offset 欄位 (不包括 recovery_acpio_size 和 recovery_acpio_offset 欄位)。

  • 用於復原的 ACPIO 映像檔，請加入 recovery_acpio_size 和 recovery_acpio_offset 欄位 (請勿加入 recovery_dtbo_size 和 recovery_dtbo_offset 欄位)。

header_size 欄位包含開機映像檔標頭的大小。如果開機映像檔標頭版本設為 1，除了 kernel、ramdisk 和 second sections 之外，id 欄位還會包含開機映像檔 recovery_[dtbo|acpio] 區段的 SHA-1 摘要。如要瞭解 recovery_[dtbo|acpio]_size 和 recovery_[dtbo|acpio]_offset 欄位的詳細資料，請參閱「復原映像檔」。

舊版開機映像檔標頭，版本 0

在 Android 9 推出前發布的裝置使用舊版開機映像檔標頭，因此視為使用開機映像檔標頭版本 0。

struct boot_img_hdr
{
    uint8_t magic[BOOT_MAGIC_SIZE];
    uint32_t kernel_size;                /* size in bytes */
    uint32_t kernel_addr;                /* physical load addr */

    uint32_t ramdisk_size;               /* size in bytes */
    uint32_t ramdisk_addr;               /* physical load addr */

    uint32_t second_size;                /* size in bytes */
    uint32_t second_addr;                /* physical load addr */

    uint32_t tags_addr;                  /* physical addr for kernel tags */
    uint32_t page_size;                  /* flash page size we assume */
    uint32_t unused;
    uint32_t os_version;
    uint8_t name[BOOT_NAME_SIZE];        /* asciiz product name */
    uint8_t cmdline[BOOT_ARGS_SIZE];
    uint32_t id[8];                      /* timestamp / checksum / sha1 / etc */
    uint8_t extra_cmdline[BOOT_EXTRA_ARGS_SIZE];
};