[PATCH] doc: Add a description for bootmeth_android

[Mattijs Korpershoek]

Add initial documentation for the Android bootmeth.

Signed-off-by: Mattijs Korpershoek <mkorpershoek at 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 at 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,
-- 
Mattijs Korpershoek <mkorpershoek at baylibre.com>