bmaptool

Output a blockmap file from image file

$ bmaptool create [[-o|--output]] [blockmap.bmap] [source.img]

$ bmaptool copy --bmap [blockmap.bmap] [source.img] [/dev/sdb]

$ bmaptool copy --bmap [blockmap.bmap] [source.img.gz] [/dev/sdb]

$ bmaptool copy --nobmap [source.img] [/dev/sdb]

bmaptool copy [--nobmap] [--bmap bmap-file] image-file device
bmaptool create [--blocksize block-size] image-file bmap-file
bmaptool verify [--nobmap] [--bmap bmap-file] image-file device
bmaptool info image-file

copy
    Copies the image-file to the device. The tool reads or calculates bmap and only copy blocks specified in bmap.

create
    Creates a bmap file for the specified image-file.

verify
    Verifies the image-file on the device using the bmap. The tool reads or calculates bmap and verifies blocks specified in bmap.

info
    Prints information about the bmap in the image-file.

--nobmap
    Treat the image-file as if it has no bmap. copy and verify will copy all data from the image file.

--bmap bmap-file
    Specifies the path to the external bmap file. If not specified, bmaptool attempts to find the bmap within the image-file.

--blocksize block-size
    Specifies the block size to use when creating a bmap file. Defaults to 4096.

image-file
    Path to the source image file.

device
    Path to the target block device (e.g., /dev/sdb).

bmap-file
    Path to the bmap file.

bmaptool is a generic tool for copying any kind of files to block devices using the block map (bmap) information embedded in the file. It is primarily used for flashing images to flash memory devices like SD cards, eMMC, NVMe or USB drives. Instead of blindly copying the entire image, bmaptool analyzes the bmap and copies only the data regions, significantly speeding up the process and reducing wear on the flash memory. It supports various image formats and uses different methods to identify bmap. bmaptool reads bmap from an external file if specified or finds it within image file. It skips free space and unallocated areas as indicated in the bmap. This approach drastically reduces both write time and wear leveling, essential for flash-based storage.

Be extremely careful when specifying the device. Writing to the wrong device can cause data loss. Ensure that you have the correct device path before running bmaptool.

The bmap format is an XML-based description of which blocks of a file contain meaningful data and which blocks are empty. bmaptool uses this information to skip unnecessary writes, leading to faster flashing and reduced wear on flash memory. The XML describes partitions, data regions and ranges of filled and empty blocks.

Most modern image formats already contain bmap as metadata. bmaptool is able to recognize it. It checks if image is qcow2, raw or extlinux.

bmaptool was developed to efficiently manage flash memory devices. It addresses the limitations of traditional tools like dd by utilizing block maps to reduce write operations and improve performance. It has become increasingly popular with the growth of embedded systems and IoT devices, where flash memory is widely used.

dd(1), fdisk(8)