ブートイメージヘッダー

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` 引数が `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 が用意されています。これを使用して、カーネルと 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_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 に設定されている場合、id フィールドには、ブートイメージの kernel、ramdisk、second 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];
};

ブートイメージ ヘッダー

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

ブートイメージ ヘッダー、バージョン 4

ブートイメージ ヘッダー、バージョン 3

ブートイメージ ヘッダー、バージョン 2

ブートイメージ ヘッダー、バージョン 1

以前のブートイメージ ヘッダー、バージョン 0