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 than 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 31v2, v1 and v0 formats are backward compatible. 32 33The Android Boot Image format is represented by 34:c:type:`struct andr_img_hdr <andr_img_hdr>` in U-Boot, and can be seen in 35``include/android_image.h``. U-Boot supports booting Android Boot Image and also 36has associated command 37 38Booting 39------- 40 41U-Boot is able to boot the Android OS from Android Boot Image using ``bootm`` 42command. In order to use Android Boot Image format support, next option should 43be enabled:: 44 45 CONFIG_ANDROID_BOOT_IMAGE=y 46 47Then one can use next ``bootm`` command call to run Android: 48 49.. code-block:: bash 50 51 => bootm $loadaddr $loadaddr $fdtaddr 52 53where ``$loadaddr`` - address in RAM where boot image was loaded; ``$fdtaddr`` - 54address in RAM where DTB blob was loaded. 55 56And parameters are, correspondingly: 57 58 1. Where kernel image is located in RAM 59 2. Where ramdisk is located in RAM (can be ``"-"`` if not applicable) 60 3. Where DTB blob is located in RAM 61 62``bootm`` command will figure out that image located in ``$loadaddr`` has 63Android Boot Image format, will parse that and boot the kernel from it, 64providing DTB blob to kernel (from 3rd parameter), passing info about ramdisk to 65kernel via DTB. 66 67DTB and DTBO blobs 68------------------ 69 70``bootm`` command can't just use DTB blob from Android Boot Image (``dtb`` 71field), because: 72 73* there is no DTB area in Android Boot Image before v2 74* there may be several DTB blobs in DTB area (e.g. for different SoCs) 75* some DTBO blobs may have to be merged in DTB blobs before booting 76 (e.g. for different boards) 77 78So user has to prepare DTB blob manually and provide it in a 3rd parameter 79of ``bootm`` command. Next commands can be used to do so: 80 811. ``abootimg``: manipulates Anroid Boot Image, allows one to extract 82 meta-information and payloads from it 832. ``adtimg``: manipulates Android DTB/DTBO image [3]_, allows one to extract 84 DTB/DTBO blobs from it 85 86In order to use those, please enable next config options:: 87 88 CONFIG_CMD_ABOOTIMG=y 89 CONFIG_CMD_ADTIMG=y 90 91For example, let's assume we have next Android partitions on eMMC: 92 93* ``boot``: contains Android Boot Image v2 (including DTB blobs) 94* ``dtbo``: contains DTBO blobs 95 96Then next command sequence can be used to boot Android: 97 98.. code-block:: bash 99 100 => mmc dev 1 101 102 # Read boot image to RAM (into $loadaddr) 103 => part start mmc 1 boot boot_start 104 => part size mmc 1 boot boot_size 105 => mmc read $loadaddr $boot_start $boot_size 106 107 # Read DTBO image to RAM (into $dtboaddr) 108 => part start mmc 1 dtbo dtbo_start 109 => part size mmc 1 dtbo dtbo_size 110 => mmc read $dtboaddr $dtbo_start $dtbo_size 111 112 # Copy required DTB blob (into $fdtaddr) 113 => abootimg get dtb --index=0 dtb0_start dtb0_size 114 => cp.b $dtb0_start $fdtaddr $dtb0_size 115 116 # Merge required DTBO blobs into DTB blob 117 => fdt addr $fdtaddr 0x100000 118 => adtimg addr $dtboaddr 119 => adtimg get dt --index=0 $dtbo0_addr 120 => fdt apply $dtbo0_addr 121 122 # Boot Android 123 => bootm $loadaddr $loadaddr $fdtaddr 124 125This sequence should be used for Android 10 boot. Of course, the whole Android 126boot procedure includes much more actions, like: 127 128* obtaining reboot reason from BCB (see [4]_) 129* implementing recovery boot 130* implementing fastboot boot 131* implementing A/B slotting (see [5]_) 132* implementing AVB2.0 (see [6]_) 133 134But Android Boot Image booting is the most crucial part in Android boot scheme. 135 136All Android bootloader requirements documentation is available at [7]_. Some 137overview on the whole Android 10 boot process can be found at [8]_. 138 139C API for working with Android Boot Image format 140------------------------------------------------ 141 142.. kernel-doc:: common/image-android.c 143 :internal: 144 145References 146---------- 147 148.. [1] https://source.android.com/devices/bootloader/boot-image-header 149.. [2] https://source.android.com/devices/bootloader/recovery-image 150.. [3] https://source.android.com/devices/architecture/dto/partitions 151.. [4] :doc:`bcb` 152.. [5] :doc:`ab` 153.. [6] :doc:`avb2` 154.. [7] https://source.android.com/devices/bootloader 155.. [8] https://connect.linaro.org/resources/san19/san19-217/ 156