doc: Provide documentation for the blkmap command
This command lacks documentation in the normal place. Add it. Co-developed-by: Claude <noreply@anthropic.com> Signed-off-by: Simon Glass <sjg@chromium.org>
This commit is contained in:
Simon Glass
@@ -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`
|
||||
|
||||
323
doc/usage/cmd/blkmap.rst
Normal file
323
doc/usage/cmd/blkmap.rst
Normal file
@@ -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
|
||||
@@ -34,6 +34,7 @@ Shell commands
|
||||
cmd/bdinfo
|
||||
cmd/bind
|
||||
cmd/blkcache
|
||||
cmd/blkmap
|
||||
cmd/bootd
|
||||
cmd/bootdev
|
||||
cmd/bootefi
|
||||
|
||||
Reference in New Issue
Block a user