doc/android/boot-image.rst

   1 .. SPDX-License-Identifier: GPL-2.0+
   2 .. sectionauthor:: Sam Protsenko <joe.skb7@gmail.com>
   3
   4 Android Boot Image
   5 ==================
   6
   7 Overview
   8 --------
   9
  10 Android Boot Image is used to boot Android OS. It usually contains kernel image
  11 (like ``zImage`` file) and ramdisk. Sometimes it can contain additional
  12 binaries. This image is built as a part of AOSP (called ``boot.img``), and being
  13 flashed 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
  18 Android Boot Image format is described at [1]_. At the moment it can have one of
  19 next 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
  31 v2, v1 and v0 formats are backward compatible.
  32
  33 The 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
  36 has associated command
  37
  38 Booting
  39 -------
  40
  41 U-Boot is able to boot the Android OS from Android Boot Image using ``bootm``
  42 command. In order to use Android Boot Image format support, next option should
  43 be enabled::
  44
  45     CONFIG_ANDROID_BOOT_IMAGE=y
  46
  47 Then one can use next ``bootm`` command call to run Android:
  48
  49 .. code-block:: bash
  50
  51     => bootm $loadaddr $loadaddr $fdtaddr
  52
  53 where ``$loadaddr`` - address in RAM where boot image was loaded; ``$fdtaddr`` -
  54 address in RAM where DTB blob was loaded.
  55
  56 And 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
  63 Android Boot Image format, will parse that and boot the kernel from it,
  64 providing DTB blob to kernel (from 3rd parameter), passing info about ramdisk to
  65 kernel via DTB.
  66
  67 DTB and DTBO blobs
  68 ------------------
  69
  70 ``bootm`` command can't just use DTB blob from Android Boot Image (``dtb``
  71 field), 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
  78 So user has to prepare DTB blob manually and provide it in a 3rd parameter
  79 of ``bootm`` command. Next commands can be used to do so:
  80
  81 1. ``abootimg``: manipulates Anroid Boot Image, allows one to extract
  82    meta-information and payloads from it
  83 2. ``adtimg``: manipulates Android DTB/DTBO image [3]_, allows one to extract
  84    DTB/DTBO blobs from it
  85
  86 In order to use those, please enable next config options::
  87
  88     CONFIG_CMD_ABOOTIMG=y
  89     CONFIG_CMD_ADTIMG=y
  90
  91 For 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
  96 Then 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
 125 This sequence should be used for Android 10 boot. Of course, the whole Android
 126 boot 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
 134 But Android Boot Image booting is the most crucial part in Android boot scheme.
 135
 136 All Android bootloader requirements documentation is available at [7]_. Some
 137 overview on the whole Android 10 boot process can be found at [8]_.
 138
 139 C API for working with Android Boot Image format
 140 ------------------------------------------------
 141
 142 .. kernel-doc:: boot/image-android.c
 143    :internal:
 144
 145 References
 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/