Kopfzeile des Boot-Images

Mit Android 9 wurde ein Versionsfeld im Boot-Image-Header eingeführt, das Updates des Headers ermöglicht und gleichzeitig die Abwärtskompatibilität beibehält. Der Bootloader muss das Feld für die Headerversion prüfen und den Header entsprechend parsen. Geräte, die mit Folgendem auf den Markt kommen:

• Android 13 können die Boot-Headerversion 3 oder 4 verwenden. Bei Geräten, die die GKI-Architektur (Generic Kernel Image) unterstützen, ist Version 4 das primäre Boot-Image und das os_version Feld im Boot-Header muss null sein. Der Geräte-Bootloader ruft die Versionsinformationen stattdessen aus den AVB-Properties (Android Bootmodus mit Verifikation) ab.
• Android 12 können die Boot-Headerversion 3 oder 4 verwenden. Bei Geräten, die die GKI-Architektur (Generic Kernel Image) unterstützen, ist Version 4 das primäre Boot-Image.
• Android 11 können die Boot-Headerversion 3 verwenden. Bei Geräten, die die GKI-Architektur (Generic Kernel Image) unterstützen, muss diese Version für das primäre Boot-Image verwendet werden.
• Android 10 müssen die Boot-Headerversion 2 verwenden.
• Android 9 müssen die Boot-Headerversion 1 verwenden.
• Bei Android 8 und niedriger wird davon ausgegangen, dass die Boot-Image-Headerversion 0 verwendet wird.

Auf allen Geräten mit Android 9 oder höher prüft die Vendor Test Suite (VTS) das Format des boot/recovery Images, um sicherzustellen, dass der Boot-Image-Header die richtige Version verwendet. Details zu allen unterstützten Boot- und Vendor-Boot Image-Headern in AOSP finden Sie unter system/tools/mkbootimg/include/bootimg/bootimg.h.

Boot-Image-Header-Versionsverwaltung implementieren

Das Tool mkbootimg akzeptiert die folgenden Argumente.

Die Gerätekonfiguration BoardConfig.mk verwendet die Konfiguration BOARD_MKBOOTIMG_ARGS, um header version zu den anderen boardspezifischen Argumenten von mkbootimg hinzuzufügen. Beispiel:

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

Das Android-Buildsystem verwendet die BoardConfig-Variable BOARD_PREBUILT_DTBOIMAGE, um das Argument recovery_dtbo des Tools mkbootimg bei der Erstellung des Wiederherstellungsimages festzulegen. Details zu den Änderungen im Open-Source-Projekt für Android (AOSP) finden Sie in den zugehörigen Changelists für die Boot-Image-Header Versionsverwaltung.

Boot-Image-Header, Version 4

Android 12 bietet eine boot_signature in der Boot-Image-Headerversion 4, mit der die Integrität des Kernels und der Ramdisk überprüft werden kann. Die Prüfung erfolgt in VtsSecurityAvbTest und ist für Geräte erforderlich, die die GKI-Architektur verwenden. Die boot_signature ist jedoch nicht am gerätespezifischen Prozess für den verifizierten Start beteiligt und wird nur in VTS verwendet. Weitere Informationen finden Sie unter GKI-Boot-Image-Board konfiguration und GKI-Einstellungen für den verifizierten Start .

Die Vendor-Boot-Image Header version 4 unterstützt mehrere Vendor-Ramdisk-Fragmente.

Version 4 der Boot-Image-Headerversion verwendet das folgende Format.

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 */
};

Boot-Image-Header, Version 3

Mit Android 11 wird der Boot-Image-Header auf Version 3 aktualisiert, wodurch die folgenden Daten entfernt werden:

• Bootloader der zweiten Phase Die Felder second_size und second_addr werden nicht mehr im Boot-Image-Header angezeigt. Geräte mit einem Bootloader der zweiten Phase müssen diesen Bootloader in einer eigenen Partition speichern.

• Wiederherstellungsimage Die Anforderung, ein Wiederherstellungsimage anzugeben, wurde eingestellt und die Felder recovery_dtbo_size, recovery_dtbo_offset, recovery_acpio_size und recovery_acpio_offset werden nicht mehr im Boot-Image-Header angezeigt.

  • A/B‑Geräte verwenden ein Update- und Wiederherstellungsschema, bei dem es nicht erforderlich ist, ein DTBO- oder ACPIO-Image für die Wiederherstellung anzugeben.

  • Geräte, die keine A/B‑Geräte sind und ein Wiederherstellungsimage (entweder DTBO oder ACPIO) angeben möchten, sollten die Boot-Image-Headerversion 1 oder 2 verwenden.

• Gerätebaum-Blob (Device Tree Blob, DTB) Der DTB wird in der Vendor-Boot Partition gespeichert. Daher werden die Felder dtb_size und dtb_addr nicht mehr im Boot-Image Header angezeigt (sind aber im Vendor-Boot-Image-Header vorhanden).

Geräte können die Boot-Image-Headerversion 3 verwenden, um die Generic Kernel Image (GKI)-Architektur zu erfüllen, die den Kern vereinheitlicht und Vendor-Module, die für den Start erforderlich sind, in die vendor_boot-Partition verschiebt (was bedeutet, dass das Boot-Image nur GKI -Komponenten enthält). Geräte, die:

• GKI verwenden (erfordert den Kernel android-4.19 oder android-5.4), aber keine A/B‑Updates verwenden, können ein Wiederherstellungsimage angeben, indem sie die Boot-Image-Version 3 für das Boot-Image und die Boot-Image-Version 2 für das Wiederherstellungsimage verwenden.

• GKI nicht verwenden und keine A/B‑Updates verwenden, können ein Wiederherstellungsimage angeben, indem sie die Boot-Image-Version 1 oder 2 für das Boot-Image und das Wiederherstellungsimage verwenden.

Version 3 der Boot-Image-Headerversion verwendet das folgende Format.

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];
};

Boot-Image-Header, Version 2

Mit Android 10 wird der Boot-Image-Header auf Version 2 aktualisiert. Dadurch wird ein Abschnitt für Informationen zum DTB-Image für die Wiederherstellung (Imagegröße und physische Ladeadresse) hinzugefügt.

Version 2 der Boot-Image-Headerversion verwendet das folgende Format.

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 */
};

Boot-Image-Header, Version 1

Mit Android 9 wird das Feld unused des Boot-Image-Headers in ein Feld für die Headerversion umgewandelt. Geräte, die mit Android 9 auf den Markt kommen, müssen den Boot-Image-Header verwenden, bei dem die Headerversion auf 1 oder höher festgelegt ist (dies wird von VTS überprüft).

Version 1 der Boot-Image-Headerversion verwendet das folgende Format.

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 */
};

Geräte, die keine A/B‑Geräte sind, können ein DTB-/ACPI-Overlay-Image für die Wiederherstellung angeben, um Fehler bei Over-the-Air-Updates (OTA) zu vermeiden. (A/B‑Geräte haben dieses Problem nicht und müssen kein Overlay-Image angeben.) Sie können entweder ein DTBO-Image oder ein ACPIO-Image angeben, aber nicht beides, da sie von verschiedenen Architekturen verwendet werden. So konfigurieren Sie den Boot-Image-Header richtig, wenn Sie Folgendes verwenden:

• Ein DTBO-Image für die Wiederherstellung: Fügen Sie die Felder recovery_dtbo_size und recovery_dtbo_offset ein (und nicht die Felder recovery_acpio_size und recovery_acpio_offset).

• Ein ACPIO-Image für die Wiederherstellung: Fügen Sie die Felder recovery_acpio_size und recovery_acpio_offset ein (und nicht die Felder recovery_dtbo_size und recovery_dtbo_offset).

Das Feld header_size enthält die Größe des Boot-Image-Headers. Wenn die Boot Image-Headerversion auf 1 festgelegt ist, enthält das Feld id zusätzlich zu den kernel, ramdisk und second sections den SHA‑1-Digest für den Abschnitt recovery_[dtbo|acpio] des Boot-Images. Weitere Informationen zu den recovery_[dtbo|acpio]_size und recovery_[dtbo|acpio]_offset Feldern finden Sie unter Wiederherstellungsimages.

Legacy-Boot-Image-Header, Version 0

Bei Geräten, die vor Android 9 auf den Markt kamen und den Legacy-Boot-Image-Header verwenden, wird davon ausgegangen, dass die Boot-Image-Headerversion 0 verwendet wird.

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];
};