6 files changed, 186 insertions, 1 deletions
diff --git a/doc/android/boot-image.rst b/doc/android/boot-image.rst
index 71db02521b..c719b4d711 100644
--- a/doc/android/boot-image.rst
+++ b/doc/android/boot-image.rst
@@ -27,11 +27,21 @@ next image headers:
 * 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)
+* v3: used in devices launched with Android 11; adds ``vendor_boot`` partition
+  and removes the second-stage bootloader and recovery image support. The new
+  ``vendor_boot`` partition holds the device tree blob (DTB) and a vendor ramdisk.
+  The generic ramdisk in ``boot`` partition is loaded immediately following
+  the vendor ramdisk.
+* v4: used in devices launched with Android 12; provides a boot signature in boot
+  image header, supports multiple vendor ramdisk fragments in ``vendor_boot``
+  partition. This version also adds a bootconfig section at the end of the vendor
+  boot image, this section contains boot configuration parameters known at build time
+  (see [9]_ for details).
 
 v2, v1 and v0 formats are backward compatible.
 
 The Android Boot Image format is represented by
-:c:type:`struct andr_img_hdr <andr_img_hdr>` in U-Boot, and can be seen in
+:c:type:`struct andr_image_data <andr_image_data>` in U-Boot, and can be seen in
 ``include/android_image.h``. U-Boot supports booting Android Boot Image and also
 has associated command
 
@@ -153,3 +163,4 @@ References
 .. [6] :doc:`avb2`
 .. [7] https://source.android.com/devices/bootloader
 .. [8] https://connect.linaro.org/resources/san19/san19-217/
+.. [9] https://source.android.com/docs/core/architecture/bootloader/implementing-bootconfig
diff --git a/doc/board/beacon/beacon-imx8mp.rst b/doc/board/beacon/beacon-imx8mp.rst
new file mode 100644
index 0000000000..375931c07d
--- /dev/null
+++ b/doc/board/beacon/beacon-imx8mp.rst
@@ -0,0 +1,52 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+U-Boot for the Beacon EmbeddedWorks i.MX8M Plus Devkit
+======================================================
+
+Quick Start
+-----------
+
+- Build the ARM Trusted firmware binary
+- Get DDR firmware
+- Build U-Boot
+- Burn U-Noot to microSD Card
+- Boot
+
+Get and Build the ARM Trusted firmware
+--------------------------------------
+
+.. code-block:: bash
+
+    $ git clone https://github.com/nxp-imx/imx-atf.git -b v2.6
+    $ make PLAT=imx8mp bl31 CROSS_COMPILE=aarch64-linux-gnu-
+    $ cp build/imx8mn/release/bl31.bin ../
+
+Get the DDR firmware
+--------------------
+
+.. code-block:: bash
+
+    $ wget https://www.nxp.com/lgfiles/NMG/MAD/YOCTO/firmware-imx-8.15.bin
+    $ chmod +x firmware-imx-8.15.bin
+    $ ./firmware-imx-8.15
+    $ cp firmware-imx-8.15/firmware/ddr/synopsys/lpddr4*.bin .
+
+Build U-Boot
+------------
+
+.. code-block:: bash
+
+    $ make imx8mp_beacon_defconfig
+    $ make CROSS_COMPILE=aarch64-linux-gnu-
+
+Burn U-Boot to microSD Card
+---------------------------
+
+.. code-block:: bash
+
+    $ sudo dd if=flash.bin of=/dev/sd[x] bs=1024 seek=32
+
+Boot
+----
+Set baseboard DIP switch:
+S17: 1100XXXX
diff --git a/doc/board/beacon/index.rst b/doc/board/beacon/index.rst
new file mode 100644
index 0000000000..1fe1046a4c
--- /dev/null
+++ b/doc/board/beacon/index.rst
@@ -0,0 +1,9 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+Beacon
+======
+
+.. toctree::
+   :maxdepth: 2
+
+   beacon-imx8mp
diff --git a/doc/board/index.rst b/doc/board/index.rst
index 618d22e616..69e2cd5fb8 100644
--- a/doc/board/index.rst
+++ b/doc/board/index.rst
@@ -14,6 +14,7 @@ Board-specific doc
    apple/index
    armltd/index
    atmel/index
+   beacon/index
    broadcom/index
    bsh/index
    cloos/index
diff --git a/doc/usage/blkmap.rst b/doc/usage/blkmap.rst
new file mode 100644
index 0000000000..dbfa8e5aad
--- /dev/null
+++ b/doc/usage/blkmap.rst
@@ -0,0 +1,111 @@
+.. SPDX-License-Identifier: GPL-2.0+
+..
+.. Copyright (c) 2023 Addiva Elektronik
+.. Author: Tobias Waldekranz <tobias@waldekranz.com>
+
+Block Maps (blkmap)
+===================
+
+Block maps are a way of looking at various sources of data through the
+lens of a regular block device. It lets you treat devices that are not
+block devices, like RAM, as if they were. It also lets you export a
+slice of an existing block device, which does not have to correspond
+to a partition boundary, as a new block device.
+
+This is primarily useful because U-Boot's filesystem drivers only
+operate on block devices, so a block map lets you access filesystems
+wherever they might be located.
+
+The implementation is loosely modeled on Linux's "Device Mapper"
+subsystem, see `kernel documentation`_ for more information.
+
+.. _kernel documentation: https://docs.kernel.org/admin-guide/device-mapper/index.html
+
+
+Example: Netbooting an Ext4 Image
+---------------------------------
+
+Say that our system is using an Ext4 filesystem as its rootfs, where
+the kernel is stored in ``/boot``. This image is then typically stored
+in an eMMC partition. In this configuration, we can use something like
+``load mmc 0 ${kernel_addr_r} /boot/Image`` to load the kernel image
+into the expected location, and then boot the system. No problems.
+
+Now imagine that during development, or as a recovery mechanism, we
+want to boot the same type of image by downloading it over the
+network. Getting the image to the target is easy enough:
+
+::
+
+   dhcp ${ramdisk_addr_r} rootfs.ext4
+
+But now we are faced with a predicament: how to we extract the kernel
+image? Block maps to the rescue!
+
+We start by creating a new device:
+
+::
+
+   blkmap create netboot
+
+Before setting up the mapping, we figure out the size of the
+downloaded file, in blocks:
+
+::
+
+   setexpr fileblks ${filesize} + 0x1ff
+   setexpr fileblks ${filesize} / 0x200
+
+Then we can add a mapping to the start of our device, backed by the
+memory at `${loadaddr}`:
+
+::
+
+   blkmap map netboot 0 ${fileblks} mem ${fileaddr}
+
+Now we can access the filesystem via the virtual device:
+
+::
+
+   blkmap get netboot dev devnum
+   load blkmap ${devnum} ${kernel_addr_r} /boot/Image
+
+
+Example: Accessing a filesystem inside an FIT image
+---------------------------------------------------
+
+In this example, an FIT image is stored in an eMMC partition. We would
+like to read the file ``/etc/version``, stored inside a Squashfs image
+in the FIT. Since the Squashfs image is not stored on a partition
+boundary, there is no way of accessing it via ``load mmc ...``.
+
+What we can to instead is to first figure out the offset and size of
+the filesystem:
+
+::
+
+   mmc dev 0
+   mmc read ${loadaddr} 0 0x100
+
+   fdt addr ${loadaddr}
+   fdt get value squashaddr /images/ramdisk data-position
+   fdt get value squashsize /images/ramdisk data-size
+
+   setexpr squashblk  ${squashaddr} / 0x200
+   setexpr squashsize ${squashsize} + 0x1ff
+   setexpr squashsize ${squashsize} / 0x200
+
+Then we can create a block map that maps to that slice of the full
+partition:
+
+::
+
+   blkmap create sq
+   blkmap map sq 0 ${squashsize} linear mmc 0 ${squashblk}
+
+Now we can access the filesystem:
+
+::
+
+   blkmap get sq dev devnum
+   load blkmap ${devnum} ${loadaddr} /etc/version
diff --git a/doc/usage/index.rst b/doc/usage/index.rst
index bc85e1d49a..729541bcff 100644
--- a/doc/usage/index.rst
+++ b/doc/usage/index.rst
@@ -4,6 +4,7 @@ Use U-Boot
 .. toctree::
    :maxdepth: 1
 
+   blkmap
    dfu
    environment
    fdt_overlays