Kopfzeile des Boot-Images

In 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 „Headerversion“ prüfen und den Header entsprechend parsen. Geräte, die bei Markteinführung folgende Versionen nutzen:

• Unter Android 13 kann die Boot-Header-Version 3 oder 4 verwendet werden. Bei Geräten, die die Generic Kernel Image (GKI)-Architektur unterstützen, ist Version 4 das primäre Boot-Image und das Feld os_version im Boot-Header muss null sein. Der Geräte-Bootloader sollte die Versionsinformationen stattdessen aus den AVB-Eigenschaften (Android Verified Boot) abrufen.
• Unter Android 12 kann die Boot-Header-Version 3 oder 4 verwendet werden. Bei Geräten, die die GKI-Architektur (Generic Kernel Image) unterstützen, ist Version 4 das primäre Boot-Image.
• Android 11 kann Version 3 des Boot-Headers verwenden. Für Geräte, die die Generic Kernel Image (GKI)-Architektur unterstützen, muss diese Version für das primäre Boot-Image verwendet werden.
• Unter Android 10 muss Version 2 des Boot-Headers verwendet werden.
• Unter Android 9 muss Version 1 des Boot-Headers verwendet werden.
• Bei Android 8 und niedriger wird davon ausgegangen, dass Version 0 des Boot-Image-Headers verwendet wird.

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

Versionierung des Boot-Image-Headers implementieren

Das mkbootimg-Tool akzeptiert die folgenden Argumente.

Das Gerät 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-Build-System verwendet die Variable BoardConfig BOARD_PREBUILT_DTBOIMAGE, um das Argument recovery_dtbo des Tools mkbootimg während der Erstellung des Wiederherstellungs-Images festzulegen. Details zu den Änderungen am Android Open Source Project (AOSP) finden Sie in den zugehörigen Änderungslisten für die Versionsverwaltung von Boot-Image-Headern.

Boot-Image-Header, Version 4

Android 12 bietet einen boot_signature in der Boot-Image-Header-Version 4, mit dem die Integrität des Kernels und der Ramdisk geprüft werden kann. Die Prüfung erfolgt in VtsSecurityAvbTest und ist für Geräte mit der GKI-Architektur erforderlich. Der boot_signature ist jedoch nicht am gerätespezifischen Prozess für den bestätigten Bootmodus beteiligt und wird nur in VTS verwendet. Weitere Informationen finden Sie unter GKI-Boot-Image-Boardkonfiguration und Einstellungen für Verified Boot für GKI.

Die Header-Version 4 des Anbieter-Boot-Images unterstützt mehrere Anbieter-Ramdisk-Fragmente.

Version 4 des Boot-Image-Headers hat 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

In Android 11 wird der Boot-Image-Header auf Version 3 aktualisiert. Dadurch werden die folgenden Daten entfernt:

• Bootloader der zweiten Phase: Die Felder second_size und second_addr werden nicht mehr im Header des Boot-Images 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. 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 Version 1 oder 2 des Boot-Image-Headers verwenden.

• Device Tree Blob (DTB): Der Gerätebaum wird in der Vendor-Boot-Partition gespeichert. Die Felder dtb_size und dtb_addr sind daher nicht mehr im Header des Boot-Images enthalten, sondern im Header des Vendor-Boot-Images.

Geräte können die Boot-Image-Header-Version 3 verwenden, um die GKI-Architektur (Generic Kernel Image) zu unterstützen. Dabei wird der Core-Kernel vereinheitlicht und die für den Start erforderlichen Anbietermodule werden in die vendor_boot-Partition verschoben. Das Boot-Image enthält also nur GKI-Komponenten. Geräte, die

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

• Wenn Sie kein GKI und keine A/B-Updates verwenden, können Sie ein Wiederherstellungs-Image angeben, indem Sie die Boot-Image-Version 1 oder 2 für Boot- und Wiederherstellungs-Images verwenden.

Version 3 des Boot-Image-Headers hat 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

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

Version 2 des Boot-Image-Headers hat 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

Unter Android 9 wird das Feld unused des Boot-Image-Headers in ein Header-Versionsfeld konvertiert. Geräte, die bei Markteinführung Android 9 nutzen, müssen den Boot-Image-Header mit der Header-Version 1 oder höher verwenden (dies wird von VTS überprüft).

Version 1 des Boot-Image-Headers hat 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 */
};

Für Geräte, die keine A/B-Geräte sind, kann ein DTB-/ACPI-Overlay-Image für die Wiederherstellung angegeben werden, um Fehler bei OTA-Updates (Over-the-Air) zu vermeiden. Bei A/B-Geräten tritt dieses Problem nicht auf und es muss kein Overlay-Bild angegeben werden. 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 muss die Felder recovery_dtbo_size und recovery_dtbo_offset enthalten, nicht aber die Felder recovery_acpio_size und recovery_acpio_offset.

• Ein ACPIO-Image für die Wiederherstellung muss die Felder recovery_acpio_size und recovery_acpio_offset enthalten (und darf die Felder recovery_dtbo_size und recovery_dtbo_offset nicht enthalten).

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

Alter Boot-Image-Header, Version 0

Bei Geräten, die vor Android 9 mit dem alten Boot-Image-Header eingeführt wurden, wird davon ausgegangen, dass sie die Boot-Image-Header-Version 0 verwenden.

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