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 --- cmd/Kconfig | 2 + doc/android/boot-image.rst | 154 +++++++++++++++++++++++++++++++++++++ 2 files changed, 156 insertions(+) create mode 100644 doc/android/boot-image.rst
diff --git a/cmd/Kconfig b/cmd/Kconfig index 4734da17fe..6a2f6fb070 100644 --- a/cmd/Kconfig +++ b/cmd/Kconfig @@ -394,6 +394,8 @@ config CMD_ABOOTIMG images contained in boot.img, like kernel, ramdisk, dtb, etc, and obtain corresponding meta-information from boot.img.
+ See doc/android/boot-image.rst for details. + config CMD_ELF bool "bootelf, bootvx" default y 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/