開機映像檔標頭

Android 9 在啟動映像檔中導入了版本欄位 標頭,允許更新標頭,同時維持回溯相容性。 系統啟動載入程式必須檢查標頭版本欄位並剖析標頭 。啟動裝置:

對於搭載 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 設定新增 其他 mkbootimg 的主機專用引數 header version。例如:

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 來設定recovery_dtbo mkbootimg 工具。如要進一步瞭解 Android 開放原始碼計畫 (AOSP) 的異動,請參閱與啟動映像檔標頭版本控制相關的變更清單

開機映像檔標頭,第 4 版

Android 12 會在開機映像檔中提供 boot_signature 標頭版本 4,可用於檢查核心的完整性 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_sizesecond_addr 欄位否 則會顯示在開機映像檔標頭中搭載第二階段系統啟動載入程式的裝置必須將該系統啟動載入程式儲存在自己的分區中。

  • 復原映像檔。是指定還原映像檔的需求 淘汰,以及 recovery_dtbo_sizerecovery_dtbo_offset recovery_acpio_sizerecovery_acpio_offset欄位不再顯示 開機映像檔標頭

    • A/B 裝置會使用更新和復原配置,因此不必指定 DTBO 或 ACPIO 映像檔來復原。

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

  • 裝置樹狀結構 blob (DTB)。DTB 會儲存在供應商的開機分割區中,因此 dtb_sizedtb_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_sizerecovery_dtbo_offset 欄位 (且不包含 recovery_acpio_sizerecovery_acpio_offset 欄位)。

  • 用於復原的 ACPIO 映像檔,請納入 recovery_acpio_sizerecovery_acpio_offset 欄位 (且不包含 recovery_dtbo_sizerecovery_dtbo_offset 欄位)。

header_size 欄位包含開機映像檔標頭的大小。如果開機映像檔標頭版本設為 1,id 欄位除了 kernelramdisksecond sections 之外,還會包含開機映像檔 recovery_[dtbo|acpio] 部分的 SHA-1 摘要。如要進一步瞭解 recovery_[dtbo|acpio]_sizerecovery_[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];
};