En-tête de l'image de démarrage

Android 9 a introduit un champ de version dans l'en-tête de l'image de démarrage, ce qui permet de mettre à jour l'en-tête tout en conservant la rétrocompatibilité. Le bootloader doit vérifier le champ de version de l'en-tête et l'analyser en conséquence. Appareils lancés avec :

  • Android 13 peut utiliser la version 3 ou 4 de l'en-tête de démarrage. Pour les appareils compatibles avec l'architecture Generic Kernel Image (GKI), la version 4 est l'image de démarrage principale et le champ os_version de l'en-tête de démarrage doit être défini sur zéro. Le bootloader de l'appareil est censé obtenir les informations sur la version à partir des propriétés Android Verified Boot (AVB).
  • Android 12 peut utiliser la version 3 ou 4 de l'en-tête de démarrage. Pour les appareils compatibles avec l'architecture Generic Kernel Image (GKI), la version 4 est l'image de démarrage principale.
  • Android 11 peut utiliser la version 3 de l'en-tête de démarrage. Pour les appareils compatibles avec l'architecture Generic Kernel Image (GKI), cette version doit être utilisée pour l'image de démarrage principale.
  • Android 10 doit utiliser la version 2 de l'en-tête de démarrage.
  • Android 9 doit utiliser la version 1 de l'en-tête de démarrage.
  • Android 8 et les versions antérieures sont considérés comme utilisant une version 0 de l'en-tête de l'image de démarrage.

Pour tous les appareils équipés d'Android 9 ou version ultérieure, la Vendor Test Suite (VTS) vérifie le format de l'image boot/recovery pour s'assurer que l'en-tête de l'image de démarrage utilise la bonne version. Pour afficher les détails AOSP sur tous les en-têtes d'image de démarrage et de démarrage du fournisseur compatibles, consultez system/tools/mkbootimg/include/bootimg/bootimg.h.

Implémenter la gestion des versions de l'en-tête de l'image de démarrage

L'outil mkbootimg accepte les arguments suivants.

Argument Description
header_version Définit la version de l'en-tête de l'image de démarrage. Image de démarrage avec une version d'en-tête :
  • 1 ou 2 prend en charge une image DTBO de récupération ou une image ACPIO de récupération.
  • 3 n'est pas compatible avec les images de récupération.
recovery_dtbo Utilisé pour les architectures qui utilisent DTB. Spécifie le chemin d'accès à l'image DTBO de récupération. Facultatif pour les appareils A/B, qui n'ont pas besoin d'image de récupération. Appareils non A/B utilisant header_version :
  • 1 ou 2 peuvent spécifier ce chemin d'accès ou utiliser la section recovery_acpio pour spécifier un chemin d'accès à une image ACPIO de récupération.
  • 3 ne peut pas spécifier d'image DTBO de récupération.
recovery_acpio Utilisé pour les architectures qui utilisent ACPI au lieu de DTB. Indique le chemin d'accès à l'image ACPIO de récupération. Facultatif pour les appareils A/B, qui n'ont pas besoin d'image de récupération. Appareils non A/B utilisant header_version :
  • 1 ou 2 peuvent spécifier ce chemin d'accès ou utiliser la section recovery_dtbo pour spécifier un chemin d'accès à une image DTBO de récupération.
  • 3 : Impossible de spécifier une image ACPIO de récupération.
dtb Chemin d'accès à l'image DTB incluse dans les images de démarrage/récupération.
dtb_offset Lorsqu'il est ajouté à l'argument base, il fournit l'adresse de chargement physique pour l'arborescence des périphériques finale. Par exemple, si l'argument base est 0x10000000 et que l'argument dtb_offset est 0x01000000, le dtb_addr_field dans l'en-tête de l'image de démarrage est renseigné en tant que 0x11000000.

L'appareil BoardConfig.mk utilise la configuration BOARD_MKBOOTIMG_ARGS pour ajouter header version aux autres arguments spécifiques à la carte de mkbootimg. Exemple :

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

Le système de compilation Android utilise la variable BoardConfig BOARD_PREBUILT_DTBOIMAGE pour définir l'argument recovery_dtbo de l'outil mkbootimg lors de la création de l'image de récupération. Pour en savoir plus sur les modifications apportées au projet Android Open Source (AOSP), consultez les listes de modifications associées à la gestion des versions de l'en-tête de l'image de démarrage.

En-tête de l'image de démarrage, version 4

Android 12 fournit un boot_signature dans l'en-tête de l'image de démarrage version 4, qui peut être utilisé pour vérifier l'intégrité du noyau et du disque RAM. La vérification est effectuée dans VtsSecurityAvbTest et est obligatoire pour les appareils utilisant l'architecture GKI. Toutefois, boot_signature n'est pas impliqué dans le processus de démarrage sécurisé spécifique à l'appareil et n'est utilisé que dans VTS. Pour en savoir plus, consultez Configuration de la carte boot.img GKI et Paramètres de démarrage sécurisé GKI.

La version 4 de l'en-tête de l'image de démarrage du fournisseur est compatible avec plusieurs fragments de disque RAM du fournisseur.

La version 4 de l'en-tête de l'image de démarrage utilise le format suivant.

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

En-tête de l'image de démarrage, version 3

Android 11 met à jour l'en-tête de l'image de démarrage vers la version 3, ce qui supprime les données suivantes :

  • Bootloader de deuxième niveau. Les champs second_size et second_addr n'apparaissent plus dans l'en-tête de l'image de démarrage. Les appareils dotés d'un bootloader de deuxième niveau doivent stocker ce bootloader dans sa propre partition.

  • Image de récupération. L'obligation de spécifier une image de récupération a été abandonnée, et les champs recovery_dtbo_size, recovery_dtbo_offset, recovery_acpio_size et recovery_acpio_offset n'apparaissent plus dans l'en-tête de l'image de démarrage.

    • Les appareils A/B utilisent un système de mise à jour et de récupération qui rend inutile la spécification d'une image DTBO ou ACPIO pour la récupération.

    • Les appareils non A/B qui souhaitent spécifier une image de récupération (DTBO ou ACPIO) doivent utiliser la version 1 ou 2 de l'en-tête de l'image de démarrage.

  • Blob d'arborescence de périphériques (DTB) Le DTB est stocké dans la partition de démarrage du fournisseur. Les champs dtb_size et dtb_addr n'apparaissent donc plus dans l'en-tête de l'image de démarrage (mais sont présents dans l'en-tête de l'image de démarrage du fournisseur).

Les appareils peuvent utiliser la version 3 de l'en-tête de l'image de démarrage pour se conformer à l'architecture Generic Kernel Image (GKI), qui unifie le noyau principal et déplace les modules du fournisseur requis pour le démarrage vers la partition vendor_boot (ce qui signifie que l'image de démarrage ne contient que des composants GKI). Appareils :

  • Utiliser GKI (nécessite le noyau android-4.19 ou android-5.4) mais ne pas utiliser les mises à jour A/B peut spécifier une image de récupération en utilisant la version 3 de l'image de démarrage pour l'image de démarrage et la version 2 de l'image de démarrage pour l'image de récupération.

  • Les appareils qui n'utilisent pas GKI et qui n'utilisent pas les mises à jour A/B peuvent spécifier une image de récupération en utilisant la version 1 ou 2 de l'image de démarrage pour les images de démarrage et de récupération.

La version 3 de l'en-tête de l'image de démarrage utilise le format suivant.

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

En-tête de l'image de démarrage, version 2

Android 10 met à jour l'en-tête de l'image de démarrage vers la version 2, qui ajoute une section pour les informations de l'image DTB de récupération (taille de l'image et adresse de chargement physique).

La version 2 de l'en-tête de l'image de démarrage utilise le format suivant.

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

En-tête de l'image de démarrage, version 1

Android 9 convertit le champ unused de l'en-tête de l'image de démarrage en champ de version de l'en-tête. Les appareils lancés avec Android 9 doivent utiliser l'en-tête de l'image de démarrage avec la version de l'en-tête définie sur 1 ou une valeur supérieure (cette valeur est vérifiée par VTS).

La version 1 de l'en-tête de l'image de démarrage utilise le format suivant.

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

Les appareils non A/B peuvent spécifier une image de superposition DTB/ACPI pour la récupération afin d'atténuer les échecs de mise à jour OTA (Over The Air). (Les appareils A/B ne présentent pas ce problème et n'ont pas besoin de spécifier une image de superposition.) Vous pouvez spécifier une image DTBO ou une image ACPIO, mais pas les deux (car elles sont utilisées par des architectures différentes). Pour configurer correctement l'en-tête de l'image de démarrage, lorsque vous utilisez :

  • Pour une image DTBO pour la récupération, incluez les champs recovery_dtbo_size et recovery_dtbo_offset (et n'incluez pas les champs recovery_acpio_size et recovery_acpio_offset).

  • Pour une image ACPIO de récupération, incluez les champs recovery_acpio_size et recovery_acpio_offset (et n'incluez pas les champs recovery_dtbo_size et recovery_dtbo_offset).

Le champ header_size contient la taille de l'en-tête de l'image de démarrage. Si la version de l'en-tête de l'image de démarrage est définie sur 1, le champ id contient le résumé SHA-1 pour la section recovery_[dtbo|acpio] de l'image de démarrage, en plus de kernel, ramdisk et second sections. Pour en savoir plus sur les champs recovery_[dtbo|acpio]_size et recovery_[dtbo|acpio]_offset, consultez Images de récupération.

Ancien en-tête d'image de démarrage, version 0

Les appareils lancés avant Android 9 et utilisant l'ancien en-tête d'image de démarrage sont considérés comme utilisant un en-tête d'image de démarrage de version 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];
};