doc: android: Add documentation for Android Boot Image

Describe Android Boot Image format, how its support is implemented in
U-Boot and associated commands usage.

Signed-off-by: Sam Protsenko <joe.skb7@gmail.com>
Signed-off-by: Lokesh Vutla <lokeshvutla@ti.com>

1 files changed, 154 insertions, 0 deletions

diff --git a/doc/android/boot-image.rst b/doc/android/boot-image.rst
new file mode 100644
index 0000000000..195da688f4
--- /dev/null
+++ b/doc/android/boot-image.rst
@@ -0,0 +1,154 @@
+.. SPDX-License-Identifier: GPL-2.0+
+.. sectionauthor:: Sam Protsenko <joe.skb7@gmail.com>
+
+Android Boot Image
+==================
+
+Overview
+--------
+
+Android Boot Image is used to boot Android OS. It usually contains kernel image
+(like ``zImage`` file) and ramdisk. Sometimes it can contain additional
+binaries. This image is built as a part of AOSP (called ``boot.img``), and being
+flashed into ``boot`` partition on eMMC. Bootloader then reads that image from
+``boot`` partition to RAM and boots the kernel from it. Kernel than starts
+``init`` process from the ramdisk. It should be mentioned that recovery image
+(``recovery.img``) also has Android Boot Image format.
+
+Android Boot Image format is described at [1]_. At the moment it can have one of
+next image headers:
+
+* v0: it's called *legacy* boot image header; used in devices launched before
+  Android 9; contains kernel image, ramdisk and second stage bootloader
+  (usually unused)
+* v1: used in devices launched with Android 9; adds ``recovery_dtbo`` field,
+  which should be used for non-A/B devices in ``recovery.img`` (see [2]_ for
+  details)
+* v2: used in devices launched with Android 10; adds ``dtb`` field, which
+  references payload containing DTB blobs (either concatenated one after the
+  other, or in Android DTBO image format)
+
+v2, v1 and v0 formats are backward compatible.
+
+Android Boot Image format is represented by :c:type:`struct andr_img_hdr` in
+U-Boot, and can be seen in ``include/android_image.h``. U-Boot supports booting
+Android Boot Image and also has associated command
+
+Booting
+-------
+
+U-Boot is able to boot the Android OS from Android Boot Image using ``bootm``
+command. In order to use Android Boot Image format support, next option should
+be enabled::
+
+    CONFIG_ANDROID_BOOT_IMAGE=y
+
+Then one can use next ``bootm`` command call to run Android:
+
+.. code-block:: bash
+
+    => bootm $loadaddr $loadaddr $fdtaddr
+
+where ``$loadaddr`` - address in RAM where boot image was loaded; ``$fdtaddr`` -
+address in RAM where DTB blob was loaded.
+
+And parameters are, correspondingly:
+
+  1. Where kernel image is located in RAM
+  2. Where ramdisk is located in RAM (can be ``"-"`` if not applicable)
+  3. Where DTB blob is located in RAM
+
+``bootm`` command will figure out that image located in ``$loadaddr`` has
+Android Boot Image format, will parse that and boot the kernel from it,
+providing DTB blob to kernel (from 3rd parameter), passing info about ramdisk to
+kernel via DTB.
+
+DTB and DTBO blobs
+------------------
+
+``bootm`` command can't just use DTB blob from Android Boot Image (``dtb``
+field), because:
+
+* there is no DTB area in Android Boot Image before v2
+* there may be several DTB blobs in DTB area (e.g. for different SoCs)
+* some DTBO blobs may have to be merged in DTB blobs before booting
+  (e.g. for different boards)
+
+So user has to prepare DTB blob manually and provide it in a 3rd parameter
+of ``bootm`` command. Next commands can be used to do so:
+
+1. ``abootimg``: manipulates Anroid Boot Image, allows one to extract
+   meta-information and payloads from it
+2. ``adtimg``: manipulates Android DTB/DTBO image [3]_, allows one to extract
+   DTB/DTBO blobs from it
+
+In order to use those, please enable next config options::
+
+    CONFIG_CMD_ABOOTIMG=y
+    CONFIG_CMD_ADTIMG=y
+
+For example, let's assume we have next Android partitions on eMMC:
+
+* ``boot``: contains Android Boot Image v2 (including DTB blobs)
+* ``dtbo``: contains DTBO blobs
+
+Then next command sequence can be used to boot Android:
+
+.. code-block:: bash
+
+    => mmc dev 1
+
+       # Read boot image to RAM (into $loadaddr)
+    => part start mmc 1 boot boot_start
+    => part size mmc 1 boot boot_size
+    => mmc read $loadaddr $boot_start $boot_size
+
+       # Read DTBO image to RAM (into $dtboaddr)
+    => part start mmc 1 dtbo dtbo_start
+    => part size mmc 1 dtbo dtbo_size
+    => mmc read $dtboaddr $dtbo_start $dtbo_size
+
+       # Copy required DTB blob (into $fdtaddr)
+    => abootimg get dtb --index=0 dtb0_start dtb0_size
+    => cp.b $dtb0_start $fdtaddr $dtb0_size
+
+       # Merge required DTBO blobs into DTB blob
+    => fdt addr $fdtaddr 0x100000
+    => adtimg addr $dtboaddr
+    => adtimg get dt --index=0 $dtbo0_addr
+    => fdt apply $dtbo0_addr
+
+       # Boot Android
+    => bootm $loadaddr $loadaddr $fdtaddr
+
+This sequence should be used for Android 10 boot. Of course, the whole Android
+boot procedure includes much more actions, like:
+
+* obtaining reboot reason from BCB (see [4]_)
+* implementing recovery boot
+* implementing fastboot boot
+* implementing A/B slotting (see [5]_)
+* implementing AVB2.0 (see [6]_)
+
+But Android Boot Image booting is the most crucial part in Android boot scheme.
+
+All Android bootloader requirements documentation is available at [7]_. Some
+overview on the whole Android 10 boot process can be found at [8]_.
+
+C API for working with Android Boot Image format
+------------------------------------------------
+
+.. kernel-doc:: common/image-android.c
+   :internal:
+
+References
+----------
+
+.. [1] https://source.android.com/devices/bootloader/boot-image-header
+.. [2] https://source.android.com/devices/bootloader/recovery-image
+.. [3] https://source.android.com/devices/architecture/dto/partitions
+.. [4] :doc:`bcb`
+.. [5] :doc:`ab`
+.. [6] :doc:`avb2`
+.. [7] https://source.android.com/devices/bootloader
+.. [8] https://connect.linaro.org/resources/san19/san19-217/