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, devp)Create an imagemap device over a partition of block device dev, selected by name or by index part, and return it through devp.
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 byfit_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:
The table is checked for an existing mapping that covers the requested range.
If found, the existing buffer pointer (adjusted for the offset within the region) is returned immediately.
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_BLOCKa non-NAND MTD (parallel NOR, SPI-NOR, …) is automatically given amtd_blkblock device, and each of its partitions appears as a partition on it;with
CONFIG_UBI_BLOCKa UBI volume appears as a partition on theubi_blkblock device (the block descriptor’shwpartselects 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.
Build Phases
CONFIG_IMAGEMAP builds only in full U-Boot. Nothing in the xpl
phases sets images->imagemap, so SPL and TPL would carry the code
without ever reaching it, and their FIT loading is unaffected. The
struct spl_load_info reader and spl_load_region() that imagemap
builds on are shared with SPL rather than duplicated, which is why they
live in include/spl.h.
Boot Integration
The imagemap framework integrates with the boot pipeline through
bootm_run_states() in boot/bootm.c:
The imagemap device pointer is stored in
struct bootm_infoand propagated to the globalimagesstructure.While finding the OS,
imagemap_map()reads the image header and FIT metadata without loading the full image into RAM. This happens inboot_get_kernel(), an internal helper ofbootm_find_os().fit_image_load()uses the on-demand storage path viaimages->imagemapto stream individual sub-images directly to their final load addresses. Its internalfit_image_load_storage()callsimagemap_map_to()for an uncompressed sub-image that has a load address, andimagemap_map()otherwise.Before jumping to the OS,
imagemap_cleanup()releases all allocated resources.
The bootmeth_openwrt boot method will be the first in-tree consumer
of this framework, using it to boot OpenWrt-style FIT firmware images
stored directly on raw storage.