[PATCH v2 11/11] doc: imagemap: document on-demand loading framework

Describe the imagemap framework architecture: the translation table
that tracks mapped regions and its phase-determined caching, reading
from a block-device partition (including MTD via mtdblock and UBI via
ubiblock), the integration with bootm for on-demand FIT sub-image
loading, and the SPL build.

Signed-off-by: Daniel Golle <[email protected]>
---
 MAINTAINERS              |   1 +
 doc/develop/imagemap.rst | 100 +++++++++++++++++++++++++++++++++++++++
 doc/develop/index.rst    |   1 +
 3 files changed, 102 insertions(+)
 create mode 100644 doc/develop/imagemap.rst

diff --git a/MAINTAINERS b/MAINTAINERS
index e8f0e94597f..f874443d87c 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -1191,6 +1191,7 @@ M:	Daniel Golle <[email protected]>
 L:	[email protected]
 S:	Maintained
 F:	boot/imagemap.c
+F:	doc/develop/imagemap.rst
 F:	include/imagemap.h
 F:	test/boot/imagemap.c
 
diff --git a/doc/develop/imagemap.rst b/doc/develop/imagemap.rst
new file mode 100644
index 00000000000..f1fea1bba78
--- /dev/null
+++ b/doc/develop/imagemap.rst
@@ -0,0 +1,100 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+On-Demand Image Loading from Storage (imagemap)
+================================================
+
+This document describes the ``imagemap`` framework that enables
+loading FIT images directly from storage devices without first
+copying the entire image into RAM.
+
+Architecture Overview
+---------------------
+
+The framework is built around the ``UCLASS_IMAGEMAP`` device class
+(``include/imagemap.h``), which provides:
+
+``imagemap_create(dev, name, part)``
+   Create an imagemap device over a partition of block device *dev*,
+   selected by *name* or by index *part*.
+
+``imagemap_map(dev, offset, size)``
+   Return a pointer to a buffer holding the requested region.
+   Consecutive calls that fall within the same region reuse the
+   existing mapping, so sub-image header look-ups are essentially
+   free.
+
+``imagemap_map_to(dev, offset, size, dst_addr)``
+   Like ``imagemap_map()`` but place the data at a specific physical
+   address (``dst_addr``).  This is used by ``fit_image_load()`` to
+   stream sub-images directly into their final load addresses.
+
+Translation Table
+~~~~~~~~~~~~~~~~~
+
+Every ``imagemap`` device maintains an internal translation
+table that records which byte ranges of the storage image have been
+read into memory and where they reside.  When ``imagemap_map()`` is
+called:
+
+1. The table is checked for an existing mapping that covers the
+   requested range.
+2. If found, the existing buffer pointer (adjusted for the offset
+   within the region) is returned immediately.
+3. If not found, a buffer is allocated via the LMB allocator, the
+   data is read from storage, and a new entry is added to the table.
+
+Reuse of already-loaded regions (steps 1 and 2) is what lets a header
+probe, signature verification and the final load of the same range share
+a single read; the FIT flow relies on it to hand already-read data back
+through ``fit_image_get_data()``.  The table also serves as the registry
+of LMB allocations that ``imagemap_cleanup()`` frees.
+
+``imagemap_cleanup()`` frees all allocated buffers and resets
+the table.
+
+Storage Access
+--------------
+
+``imagemap_create()`` reads from a partition on a block device (MMC,
+SCSI, NVMe, ...), selected by name or by index.  Reads go through the
+same ``struct spl_load_info`` load-to-mem abstraction that SPL uses, so
+a byte range is fetched with native sector alignment via
+``spl_load_region()``.
+
+MTD partitions and UBI volumes are read the same way, by way of the
+existing block layers that expose them:
+
+- with ``CONFIG_MTD_BLOCK`` a non-NAND MTD (parallel NOR, SPI-NOR, ...)
+  is automatically given a ``mtd_blk`` block device, and each of its
+  partitions appears as a partition on it;
+- with ``CONFIG_UBI_BLOCK`` a UBI volume appears as a partition on the
+  ``ubi_blk`` block device (the block descriptor's ``hwpart`` selects
+  the volume).
+
+NAND bad-block handling and wear-levelling therefore stay with UBI, as
+they do for the rest of U-Boot; on NOR a partition is read linearly and
+end-to-end integrity is provided by the FIT hash or signature, so no
+MTD-specific read path is needed in imagemap.
+
+Boot Integration
+----------------
+
+The ``imagemap`` framework integrates with the boot pipeline through
+``bootm_run_states()`` in ``boot/bootm.c``:
+
+1. The imagemap device pointer is stored in ``struct bootm_info``
+   and propagated to the global ``images`` structure.
+
+2. ``boot_get_kernel()`` uses ``imagemap_map()`` to read the image
+   header and FIT metadata without loading the full image into RAM.
+
+3. ``fit_image_load()`` uses the on-demand storage path via
+   ``images->imagemap`` to stream individual sub-images directly to
+   their final load addresses.
+
+4. Before jumping to the OS, ``imagemap_cleanup()`` releases all
+   allocated resources.
+
+The ``bootmeth_openwrt`` boot method is the primary consumer of this
+framework, using it to boot OpenWrt-style FIT firmware images stored
+directly on raw storage.
diff --git a/doc/develop/index.rst b/doc/develop/index.rst
index 0b757e8601e..3b4cc2e28a7 100644
--- a/doc/develop/index.rst
+++ b/doc/develop/index.rst
@@ -31,6 +31,7 @@ Implementation
 
    directories
    bloblist
+   imagemap
    bootstd/index
    ci_testing
    commands
-- 
2.55.0