Add initial documentation for the Android bootmeth.

Signed-off-by: Mattijs Korpershoek mkorpershoek@baylibre.com --- MAINTAINERS | 1 + doc/develop/bootstd/android.rst | 39 +++++++++++++++++++++++++++++++++++++++ doc/develop/bootstd/index.rst | 1 + doc/develop/bootstd/overview.rst | 2 +- 4 files changed, 42 insertions(+), 1 deletion(-)

diff --git a/MAINTAINERS b/MAINTAINERS index a6e47e8a2179..c2832345ab18 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -945,6 +945,7 @@ S: Maintained T: git https://source.denx.de/u-boot/custodians/u-boot-dfu.git F: boot/bootmeth_android.c F: boot/bootmeth_android.h +F: doc/develop/bootstd/android.rst

BTRFS M: Marek Behún kabel@kernel.org diff --git a/doc/develop/bootstd/android.rst b/doc/develop/bootstd/android.rst new file mode 100644 index 000000000000..41701d5bdff3 --- /dev/null +++ b/doc/develop/bootstd/android.rst @@ -0,0 +1,39 @@ +.. SPDX-License-Identifier: GPL-2.0+: + +Android Bootmeth +================ + +Android provides a mechanism for booting its Operating System from eMMC storage, +described on `source.android.com https://source.android.com/docs/core/architecture/bootloader`_. + +Android has strong requirements about partitioning layout which are described +`here https://source.android.com/docs/core/architecture/partitions`_. +Because multiple partitions are required, this bootmeth only operates on whole mmc +devices which have a valid partition table. + +When invoked on a bootdev, this bootmeth searches for the ``misc`` partition in order +to read the *boot mode*, which can be one of following: + +Normal + Boot the regular Android Operating System. + +Recovery + Boot a slimmed down Recovery Operating System. Can be used + to factory reset the device or to apply system updates. + +Bootloader + Stay in U-Boot and wait for fastboot commands from the host. + +After the *boot mode* has been determined, this bootmeth will read the *slot suffix* +from the ``misc`` partition. For details about slots, see +`the AOSP documentation https://source.android.com/docs/core/ota/ab#slots`_. + +When both the *boot mode* and the *slot suffix* are known, the bootflow is created. + +When the bootflow is booted, the bootmeth reads the kernel, the boot arguments and +the vendor ramdisk. +It then boots the kernel using bootm. The relevant devicetree blob is extracted +from the ``boot`` partition based on the ``adtb_idx`` environment variable. + +The compatible string "u-boot,android" is used for the driver. It is present +if `CONFIG_BOOTMETH_ANDROID` is enabled. diff --git a/doc/develop/bootstd/index.rst b/doc/develop/bootstd/index.rst index 9d35b567d55d..4c4e26ccdb70 100644 --- a/doc/develop/bootstd/index.rst +++ b/doc/develop/bootstd/index.rst @@ -10,6 +10,7 @@ Standard Boot extlinux pxelinux qfw + android cros script sandbox diff --git a/doc/develop/bootstd/overview.rst b/doc/develop/bootstd/overview.rst index ff3cc48eb64f..c6f003851b2a 100644 --- a/doc/develop/bootstd/overview.rst +++ b/doc/develop/bootstd/overview.rst @@ -429,7 +429,7 @@ Available bootmeth drivers

Bootmeth drivers are provided for booting from various media:

- - Android bootflow (boot image v4) + - :doc:`Android <android>` bootflow (boot image v4) - :doc:`ChromiumOS <cros>` ChromiumOS boot from a disk - EFI boot using bootefi from disk - EFI boot using boot manager

--- base-commit: f659ba43837e5ae5a35fdff3736c8e13f9062abd change-id: 20240724-doc-bootstd-android-ddf081b3622a

Best regards,