ブートイメージ ヘッダー

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 イメージの形式をチェックし、ブートイメージ ヘッダーに適切なバージョンが使用されていることを確認します。現在サポートされているすべてのブートイメージ ヘッダーとベンダー ブートイメージ ヘッダーに AOSP の詳細を表示するには、system/tools/mkbootimg/include/bootimg/bootimg.h を参照してください。

ブートイメージ ヘッダーのバージョニングの実装

mkbootimg ツールでは、以下の引数を指定できます。

引数 説明
header_version ブートイメージ ヘッダーのバージョンを設定します。ブートイメージとヘッダー バージョン:
  • 1 または 2 は、リカバリ DTBO イメージまたはリカバリ ACPIO イメージをサポートしています。
  • 3 はリカバリ イメージをサポートしていません。
recovery_dtbo DTB を使用するアーキテクチャに使用されます。リカバリ DTBO イメージへのパスを指定します。リカバリ イメージを必要としない A/B デバイスの場合、省略可能です。 非 A/B デバイスが次の header_version を使用する場合:
  • 1 または 2 の場合、このパスを指定することも、recovery_acpio セクションを使用してリカバリ ACPIO イメージへのパスを指定することもできます。
  • 3 の場合、リカバリ DTBO イメージを指定できません。
recovery_acpio DTB の代わりに ACPI を使用するアーキテクチャに使用されます。リカバリ ACPIO イメージへのパスを指定します。リカバリ イメージを必要としない A/B デバイスの場合、省略可能です。非 A/B デバイスが次の header_version を使用する場合:
  • 1 または 2 の場合、このパスを指定することも、recovery_dtbo セクションを使用してリカバリ DTBO イメージへのパスを指定することもできます。
  • 3 の場合、リカバリ ACPIO イメージを指定することはできません。
dtb ブート / リカバリ イメージに含まれている DTB イメージのパス。
dtb_offset base 引数に追加した場合、最終的なデバイスツリーの物理ロードアドレスを表します。たとえば、base 引数が 0x10000000dtb_offset 引数が 0x01000000 の場合、ブートイメージ ヘッダーの dtb_addr_field には 0x11000000 が代入されます。

デバイス BoardConfig.mk は構成 BOARD_MKBOOTIMG_ARGS を使用して、header versionmkbootimg のボード固有の他の引数に追加します。たとえば、以下の場合です。

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 が用意されています。これを使用して、カーネルと RAM ディスクの整合性をチェックできます。このチェックは VtsSecurityAvbTest で行われ、GKI アーキテクチャを使用するデバイスには必須となっています。ただし、boot_signature はデバイス固有の確認付きブートプロセスには関与せず、VTS でのみ使用されます。詳しくは、GKI boot.img ボードの構成GKI の確認付きブートの設定をご覧ください。

ベンダー ブートイメージ ヘッダーのバージョン 4 では、複数のベンダー RAM ディスク フラグメントがサポートされています。

ブートイメージ ヘッダーのバージョン 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 に更新します。これにより、次のデータが削除されます。

  • 第 2 段階のブートローダー。ブートイメージ ヘッダーに second_size フィールドと second_addr フィールドが表示されなくなります。第 2 段階のブートローダーを使用するデバイスは、そのブートローダーを独自のパーティションに格納する必要があります。

  • リカバリ イメージ。リカバリ イメージを指定するための要件が非推奨になり、recovery_dtbo_sizerecovery_dtbo_offsetrecovery_acpio_sizerecovery_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 に設定されている場合、id フィールドには、ブートイメージの kernelramdisksecond sections に加えて 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];
};