[Concept,02/24] doc: Provide documentation for the blkmap command

diff --git a/doc/usage/blkmap.rst b/doc/usage/blkmap.rst
index 75f736c259f..e9b3cfeaaa1 100644
--- a/doc/usage/blkmap.rst
+++ b/doc/usage/blkmap.rst
@@ -109,3 +109,8 @@  Now we can access the filesystem:
 
    blkmap get sq dev devnum
    load blkmap ${devnum} ${loadaddr} /etc/version
+
+See also
+--------
+
+* :doc:`/usage/cmd/blkmap`
diff --git a/doc/usage/cmd/blkmap.rst b/doc/usage/cmd/blkmap.rst
new file mode 100644
index 00000000000..aaa4cd403c0
--- /dev/null
+++ b/doc/usage/cmd/blkmap.rst
@@ -0,0 +1,323 @@ 
+.. SPDX-License-Identifier: GPL-2.0+
+
+.. index::
+   single: blkmap (command)
+
+blkmap command
+==============
+
+Synopsis
+--------
+
+::
+
+    blkmap info
+    blkmap part
+    blkmap dev [<dev>]
+    blkmap read <addr> <blk#> <cnt>
+    blkmap write <addr> <blk#> <cnt>
+    blkmap get <label> dev [<var>]
+    blkmap create <label>
+    blkmap destroy <label>
+    blkmap map <label> <blk#> <cnt> linear <interface> <dev> <blk#>
+    blkmap map <label> <blk#> <cnt> mem <addr>
+
+Description
+-----------
+
+The *blkmap* command is used to create and manage virtual block devices that
+are composed of one or more "slices" mapped from other block devices or memory
+regions.
+
+See :doc:`../blkmap` for an overview of the blkmap subsystem and usage examples.
+
+label
+    Unique label assigned to a blkmap device during creation. Used to identify
+    the device for subsequent operations (map, get, destroy).
+
+blk#
+    Block number. Blocks are 512 bytes in size. When used as a starting position,
+    this specifies where in the device to begin the operation. When used as a
+    mapping parameter, it indicates which block in the source or destination to
+    use.
+
+cnt
+    Number of blocks (count). Each block is 512 bytes, so cnt=1 represents 512
+    bytes, cnt=2048 represents 1MB, etc.
+
+addr
+    Memory address in hexadecimal format (e.g., ${loadaddr}, 0x82000000). Used
+    for specifying where to read/write data or where a memory region is located.
+
+blkmap info
+~~~~~~~~~~~
+
+List all configured blkmap devices and their properties::
+
+    blkmap info
+
+This displays information about all active blkmap devices, including device
+number, vendor, product, revision, type, and capacity.
+
+blkmap part
+~~~~~~~~~~~
+
+List available partitions on the current blkmap device::
+
+    blkmap part
+
+This command displays the partition table of the currently selected blkmap
+device. If the device has no partition table (whole-disk filesystem), it will
+report "no blkmap partition table available".
+
+blkmap dev
+~~~~~~~~~~
+
+Show or set the current blkmap device::
+
+    blkmap dev [<dev>]
+
+dev
+    Optional device number to set as current. If omitted, displays the current
+    device information.
+
+blkmap read
+~~~~~~~~~~~
+
+Read data from the current blkmap device::
+
+    blkmap read <addr> <blk#> <cnt>
+
+blkmap write
+~~~~~~~~~~~~
+
+Write data to the current blkmap device::
+
+    blkmap write <addr> <blk#> <cnt>
+
+**Note**: Write support is limited and may not be available for all blkmap
+types.
+
+blkmap get
+~~~~~~~~~~
+
+Get the device number for a labeled blkmap device::
+
+    blkmap get <label> dev [<var>]
+
+var
+    Optional environment variable name to store the device number. If omitted,
+    the device number is printed to stdout.
+
+This is useful for scripting, allowing you to find a blkmap device by its label
+and store or use its device number.
+
+blkmap create
+~~~~~~~~~~~~~
+
+Create a new blkmap device with the specified label::
+
+    blkmap create <label>
+
+After creation, the device has no mappings and is empty. Use ``blkmap map``
+to add slices to the device.
+
+blkmap destroy
+~~~~~~~~~~~~~~
+
+Destroy a blkmap device and free its resources::
+
+    blkmap destroy <label>
+
+This removes the blkmap device and all its mappings. Any data stored only in
+the blkmap device will be lost.
+
+blkmap map - linear
+~~~~~~~~~~~~~~~~~~~
+
+Map a region from another block device into the blkmap device::
+
+    blkmap map <label> <blk#> <cnt> linear <interface> <dev> <blk#>
+
+label
+    Label of the blkmap device to map into
+
+blk#
+    Starting block number in the blkmap device where this mapping begins
+
+cnt
+    Number of blocks to map
+
+interface
+    Source device interface (e.g., mmc, usb, scsi)
+
+dev
+    Source device number
+
+blk# (last parameter)
+    Starting block number on the source device
+
+This creates a linear mapping that redirects reads from a region of the blkmap
+device to the corresponding region on another block device. Multiple mappings
+can be added to compose a single virtual device from multiple sources.
+
+blkmap map - mem
+~~~~~~~~~~~~~~~~
+
+Map a memory region as a block device::
+
+    blkmap map <label> <blk#> <cnt> mem <addr>
+
+label
+    Label of the blkmap device to map into
+
+blk#
+    Starting block number in the blkmap device where this mapping begins
+
+cnt
+    Number of blocks to map
+
+addr
+    Memory address of the data to map
+
+This creates a mapping that exposes a memory region as block device sectors.
+The memory region must be at least ``cnt * 512`` bytes in size.
+
+Usage Examples
+--------------
+
+See :doc:`../blkmap` for complete examples including:
+
+* Netbooting an Ext4 image
+* Accessing filesystems inside FIT images
+* Creating composite devices from multiple sources
+* Using memory-backed block devices
+
+Implementation Details
+----------------------
+
+Blkmap devices are implemented as standard U-Boot block devices (UCLASS_BLK)
+with a custom driver. Each device maintains an ordered list of "slices" -
+mappings from a range of blocks to a source (another device or memory region).
+
+See :doc:`../blkmap` for more details on the implementation.
+
+Configuration
+-------------
+
+The blkmap command is available when CONFIG_CMD_BLKMAP is enabled::
+
+    CONFIG_BLKMAP=y
+    CONFIG_CMD_BLKMAP=y
+
+Return Value
+------------
+
+The return value $? is set to 0 on success, 1 on failure.
+
+Examples
+--------
+
+List all blkmap devices
+~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+    => blkmap info
+    Device 0: Vendor: U-Boot Rev: 1.0 Prod: blkmap
+                Type: Hard Disk
+                Capacity: 60.0 MB = 0.0 GB (122880 x 512)
+
+Check or set current device
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+    => blkmap dev
+    Device 0: Vendor: U-Boot Rev: 1.0 Prod: blkmap
+                Type: Hard Disk
+                Capacity: 60.0 MB = 0.0 GB (122880 x 512)
+    ... is now current device
+
+    => blkmap dev 0
+    Device 0: Vendor: U-Boot Rev: 1.0 Prod: blkmap
+                Type: Hard Disk
+                Capacity: 60.0 MB = 0.0 GB (122880 x 512)
+    ... is now current device
+
+Create a new device
+~~~~~~~~~~~~~~~~~~~
+
+::
+
+    => blkmap create mydisk
+    => blkmap info
+    Device 0: Vendor: U-Boot Rev: 1.0 Prod: blkmap
+                Type: Hard Disk
+                Capacity: 0.0 MB = 0.0 GB (1 x 512)
+
+Map a linear region from MMC
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Map MMC blocks 1000-1999 to blkmap blocks 0-999::
+
+    => blkmap create composed
+    => blkmap map composed 0 1000 linear mmc 0 1000
+
+Map memory as a block device
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Map 1MB of memory as blocks::
+
+    => blkmap create ramdisk
+    => blkmap map ramdisk 0 2048 mem ${loadaddr}
+
+Read from a blkmap device
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+    => blkmap dev 0
+    => blkmap read ${loadaddr} 0 10
+    blkmap read: device 0 block # 0, count 10 ... 10 blocks read: OK
+
+Get device number by label
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+    => blkmap get testdev dev mydev
+    => printenv mydev
+    mydev=0
+
+Complete workflow example
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Create, map, and use a device::
+
+    => blkmap create testdev
+    => blkmap map testdev 0 2048 linear mmc 0 2048
+    => blkmap dev 0
+    => blkmap read ${loadaddr} 0 1
+
+Destroy a device
+~~~~~~~~~~~~~~~~
+
+::
+
+    => blkmap destroy mydisk
+
+Accessing whole-disk filesystems
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Blkmap devices often contain whole-disk filesystems (no partition table).
+Access them using partition 0 or omitting the partition specification::
+
+    => ls blkmap 0 /
+    => ext4load blkmap 0 ${loadaddr} /boot/vmlinuz
+    => cat blkmap 0 /etc/config.txt
+
+See Also
+--------
+
+* :doc:`../blkmap` - Blkmap device documentation and examples
diff --git a/doc/usage/index.rst b/doc/usage/index.rst
index 701f03ca373..2fff101868c 100644
--- a/doc/usage/index.rst
+++ b/doc/usage/index.rst
@@ -34,6 +34,7 @@  Shell commands
    cmd/bdinfo
    cmd/bind
    cmd/blkcache
+   cmd/blkmap
    cmd/bootd
    cmd/bootdev
    cmd/bootefi