Header image booting

Android 9 memperkenalkan kolom versi di header image boot, sehingga memungkinkan update pada header sambil mempertahankan kompatibilitas mundur. Bootloader harus memeriksa kolom versi header dan mengurai header dengan tepat. Perangkat yang diluncurkan dengan:

• Android 13 dapat menggunakan header booting versi 3 atau 4. Untuk perangkat yang mendukung arsitektur Generic Kernel Image (GKI), versi 4 adalah image booting utama dan kolom os_version di header booting harus nol. Bootloader perangkat diharapkan mendapatkan informasi versi dari properti Android Verified Boot (AVB).
• Android 12 dapat menggunakan header boot versi 3 atau 4. Untuk perangkat yang mendukung arsitektur Generic Kernel Image (GKI), versi 4 adalah image booting utama.
• Android 11 dapat menggunakan header booting versi 3. Untuk perangkat yang mendukung arsitektur Generic Kernel Image (GKI), versi ini harus digunakan untuk image booting utama.
• Android 10 harus menggunakan header boot versi 2.
• Android 9 harus menggunakan header boot versi 1.
• Android 8 dan yang lebih lama dianggap menggunakan header image booting versi 0.

Untuk semua perangkat yang berjalan dengan Android 9 atau yang lebih tinggi, Vendor Test Suite (VTS) memeriksa format image boot/recovery untuk memastikan header image booting menggunakan versi yang benar. Untuk melihat detail AOSP di semua header image boot dan vendor boot yang didukung, lihat system/tools/mkbootimg/include/bootimg/bootimg.h.

Menerapkan pembuatan versi header image booting

Alat mkbootimg menerima argumen berikut.

Perangkat BoardConfig.mk menggunakan config BOARD_MKBOOTIMG_ARGS untuk menambahkan header version ke argumen khusus papan lainnya dari mkbootimg. Contoh:

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

Sistem build Android menggunakan variabel BoardConfig BOARD_PREBUILT_DTBOIMAGE untuk menetapkan argumen recovery_dtbo dari alat mkbootimg selama pembuatan image pemulihan. Untuk mengetahui detail tentang perubahan Project Open Source Android (AOSP), tinjau daftar perubahan terkait untuk pembuatan versi header image boot.

Header gambar boot, versi 4

Android 12 menyediakan boot_signature di header image boot versi 4, yang dapat digunakan untuk memeriksa integritas kernel dan ramdisk. Pemeriksaan dilakukan di VtsSecurityAvbTest dan diperlukan untuk perangkat yang menggunakan arsitektur GKI. Namun, boot_signature tidak terlibat dalam proses boot terverifikasi khusus perangkat dan hanya digunakan di VTS. Lihat konfigurasi board boot.img GKI dan setelan booting terverifikasi GKI untuk mengetahui detailnya.

Versi 4 header image boot vendor mendukung beberapa fragmen ramdisk vendor.

Versi 4 dari versi header image booting menggunakan format berikut.

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

Header gambar boot, versi 3

Android 11 mengupdate header image booting ke versi 3, yang menghapus data berikut:

• Bootloader tahap kedua. Kolom second_size dan second_addr tidak lagi muncul di header image booting. Perangkat dengan bootloader tahap kedua harus menyimpan bootloader tersebut di partisi sendiri.

• Gambar pemulihan. Persyaratan untuk menentukan gambar pemulihan telah dihentikan, dan kolom recovery_dtbo_size, recovery_dtbo_offset, recovery_acpio_size, dan recovery_acpio_offset tidak lagi muncul di header gambar booting.

  • Perangkat A/B menggunakan skema update dan pemulihan yang tidak memerlukan penentuan gambar DTBO atau ACPIO untuk pemulihan.

  • Perangkat non-A/B yang ingin menentukan image pemulihan (DTBO atau ACPIO) harus menggunakan header image booting versi 1 atau 2.

• Blob device tree (DTB). DTB disimpan di partisi boot vendor, sehingga kolom dtb_size dan dtb_addr tidak lagi muncul di header image boot (tetapi ada di header image boot vendor).

Perangkat dapat menggunakan header image booting versi 3 untuk mematuhi arsitektur Generic Kernel Image (GKI), yang menyatukan kernel inti dan memindahkan modul vendor yang diperlukan untuk booting ke partisi vendor_boot (artinya, image booting hanya berisi komponen GKI). Perangkat yang:

• Menggunakan GKI (memerlukan kernel android-4.19 atau android-5.4), tetapi tidak menggunakan update A/B dapat menentukan image pemulihan dengan menggunakan versi image boot 3 untuk image boot dan versi image boot 2 untuk image pemulihan.

• Jangan gunakan GKI dan jangan gunakan update A/B dapat menentukan image pemulihan dengan menggunakan boot image versi 1 atau 2 untuk boot image dan image pemulihan.

Versi 3 dari versi header image booting menggunakan format berikut.

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

Header gambar boot, versi 2

Android 10 memperbarui header image booting ke versi 2, yang menambahkan bagian untuk informasi image DTB pemulihan (ukuran image dan alamat pemuatan fisik).

Versi 2 dari versi header image booting menggunakan format berikut.

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

Header image boot, versi 1

Android 9 mengonversi kolom unused header image boot menjadi kolom versi header. Perangkat yang diluncurkan dengan Android 9 harus menggunakan header image booting dengan versi header yang ditetapkan ke 1 atau yang lebih tinggi (hal ini diverifikasi oleh VTS).

Versi 1 header versi image booting menggunakan format berikut.

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

Perangkat non-A/B dapat menentukan image overlay DTB/ACPI untuk pemulihan guna membantu mengurangi kegagalan update over-the-air (OTA). (Perangkat A/B tidak mengalami masalah ini dan tidak perlu menentukan gambar overlay.) Anda dapat menentukan image DTBO atau image ACPIO, tetapi tidak keduanya (karena digunakan oleh arsitektur yang berbeda). Untuk mengonfigurasi header image booting dengan benar, saat menggunakan:

• Gambar DTBO untuk pemulihan, sertakan kolom recovery_dtbo_size dan recovery_dtbo_offset (dan jangan sertakan kolom recovery_acpio_size dan recovery_acpio_offset).

• Gambar ACPIO untuk pemulihan, sertakan kolom recovery_acpio_size dan recovery_acpio_offset (dan jangan sertakan kolom recovery_dtbo_size dan recovery_dtbo_offset).

Kolom header_size berisi ukuran header image booting. Jika versi header image boot disetel ke 1, kolom id berisi ringkasan SHA-1 untuk bagian recovery_[dtbo|acpio] image boot selain kernel, ramdisk, dan second sections. Untuk mengetahui detail tentang kolom recovery_[dtbo|acpio]_size dan recovery_[dtbo|acpio]_offset, lihat Gambar Pemulihan.

Header image boot lama, versi 0

Perangkat yang diluncurkan sebelum Android 9 menggunakan header image booting lama dianggap menggunakan header image booting versi 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];
};