boot-image.rst 5.3 KB

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