1.. SPDX-License-Identifier: GPL-2.0+ 2.. sectionauthor:: Sam Protsenko <joe.skb7@gmail.com> 3 4Android Boot Image 5================== 6 7Overview 8-------- 9 10Android Boot Image is used to boot Android OS. It usually contains kernel image 11(like ``zImage`` file) and ramdisk. Sometimes it can contain additional 12binaries. This image is built as a part of AOSP (called ``boot.img``), and being 13flashed into ``boot`` partition on eMMC. Bootloader then reads that image from 14``boot`` partition to RAM and boots the kernel from it. Kernel then starts 15``init`` process from the ramdisk. It should be mentioned that recovery image 16(``recovery.img``) also has Android Boot Image format. 17 18Android Boot Image format is described at [1]_. At the moment it can have one of 19next image headers: 20 21* v0: it's called *legacy* boot image header; used in devices launched before 22 Android 9; contains kernel image, ramdisk and second stage bootloader 23 (usually unused) 24* v1: used in devices launched with Android 9; adds ``recovery_dtbo`` field, 25 which should be used for non-A/B devices in ``recovery.img`` (see [2]_ for 26 details) 27* v2: used in devices launched with Android 10; adds ``dtb`` field, which 28 references payload containing DTB blobs (either concatenated one after the 29 other, or in Android DTBO image format) 30* v3: used in devices launched with Android 11; adds ``vendor_boot`` partition 31 and removes the second-stage bootloader and recovery image support. The new 32 ``vendor_boot`` partition holds the device tree blob (DTB) and a vendor ramdisk. 33 The generic ramdisk in ``boot`` partition is loaded immediately following 34 the vendor ramdisk. 35* v4: used in devices launched with Android 12; provides a boot signature in boot 36 image header, supports multiple vendor ramdisk fragments in ``vendor_boot`` 37 partition. This version also adds a bootconfig section at the end of the vendor 38 boot image, this section contains boot configuration parameters known at build time 39 (see [9]_ for details). 40 41v2, v1 and v0 formats are backward compatible. 42 43The Android Boot Image format is represented by 44:c:type:`struct andr_image_data <andr_image_data>` in U-Boot, and can be seen in 45``include/android_image.h``. U-Boot supports booting Android Boot Image and also 46has associated command 47 48Booting 49------- 50 51U-Boot is able to boot the Android OS from Android Boot Image using ``bootm`` 52command. In order to use Android Boot Image format support, next option should 53be enabled:: 54 55 CONFIG_ANDROID_BOOT_IMAGE=y 56 57Then one can use next ``bootm`` command call to run Android: 58 59.. code-block:: bash 60 61 => bootm $loadaddr $loadaddr $fdtaddr 62 63where ``$loadaddr`` - address in RAM where boot image was loaded; ``$fdtaddr`` - 64address in RAM where DTB blob was loaded. 65 66And parameters are, correspondingly: 67 68 1. Where kernel image is located in RAM 69 2. Where ramdisk is located in RAM (can be ``"-"`` if not applicable) 70 3. Where DTB blob is located in RAM 71 72``bootm`` command will figure out that image located in ``$loadaddr`` has 73Android Boot Image format, will parse that and boot the kernel from it, 74providing DTB blob to kernel (from 3rd parameter), passing info about ramdisk to 75kernel via DTB. 76 77DTB and DTBO blobs 78------------------ 79 80``bootm`` command can't just use DTB blob from Android Boot Image (``dtb`` 81field), because: 82 83* there is no DTB area in Android Boot Image before v2 84* there may be several DTB blobs in DTB area (e.g. for different SoCs) 85* some DTBO blobs may have to be merged in DTB blobs before booting 86 (e.g. for different boards) 87 88So user has to prepare DTB blob manually and provide it in a 3rd parameter 89of ``bootm`` command. Next commands can be used to do so: 90 911. ``abootimg``: manipulates Anroid Boot Image, allows one to extract 92 meta-information and payloads from it 932. ``adtimg``: manipulates Android DTB/DTBO image [3]_, allows one to extract 94 DTB/DTBO blobs from it 95 96In order to use those, please enable next config options:: 97 98 CONFIG_CMD_ABOOTIMG=y 99 CONFIG_CMD_ADTIMG=y 100 101For example, let's assume we have next Android partitions on eMMC: 102 103* ``boot``: contains Android Boot Image v2 (including DTB blobs) 104* ``dtbo``: contains DTBO blobs 105 106Then next command sequence can be used to boot Android: 107 108.. code-block:: bash 109 110 => mmc dev 1 111 112 # Read boot image to RAM (into $loadaddr) 113 => part start mmc 1 boot boot_start 114 => part size mmc 1 boot boot_size 115 => mmc read $loadaddr $boot_start $boot_size 116 117 # Read DTBO image to RAM (into $dtboaddr) 118 => part start mmc 1 dtbo dtbo_start 119 => part size mmc 1 dtbo dtbo_size 120 => mmc read $dtboaddr $dtbo_start $dtbo_size 121 122 # Copy required DTB blob (into $fdtaddr) 123 => abootimg get dtb --index=0 dtb0_start dtb0_size 124 => cp.b $dtb0_start $fdtaddr $dtb0_size 125 126 # Merge required DTBO blobs into DTB blob 127 => fdt addr $fdtaddr 0x100000 128 => adtimg addr $dtboaddr 129 => adtimg get dt --index=0 $dtbo0_addr 130 => fdt apply $dtbo0_addr 131 132 # Boot Android 133 => bootm $loadaddr $loadaddr $fdtaddr 134 135This sequence should be used for Android 10 boot. Of course, the whole Android 136boot procedure includes much more actions, like: 137 138* obtaining reboot reason from BCB (see [4]_) 139* implementing recovery boot 140* implementing fastboot boot 141* implementing A/B slotting (see [5]_) 142* implementing AVB2.0 (see [6]_) 143 144But Android Boot Image booting is the most crucial part in Android boot scheme. 145 146All Android bootloader requirements documentation is available at [7]_. Some 147overview on the whole Android 10 boot process can be found at [8]_. 148 149C API for working with Android Boot Image format 150------------------------------------------------ 151 152.. kernel-doc:: boot/image-android.c 153 :internal: 154 155References 156---------- 157 158.. [1] https://source.android.com/devices/bootloader/boot-image-header 159.. [2] https://source.android.com/devices/bootloader/recovery-image 160.. [3] https://source.android.com/devices/architecture/dto/partitions 161.. [4] :doc:`bcb` 162.. [5] :doc:`ab` 163.. [6] :doc:`avb2` 164.. [7] https://source.android.com/devices/bootloader 165.. [8] https://connect.linaro.org/resources/san19/san19-217/ 166.. [9] https://source.android.com/docs/core/architecture/bootloader/implementing-bootconfig 167