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 [OPTIONS] COMMAND [ARGS]

bmaptool create [OPTIONS]
bmaptool copy [OPTIONS]
bmaptool verify [OPTIONS]
bmaptool show [OPTIONS]

create
    Generates a block map (.bmap) file for the specified image file. The output is typically redirected to a file.

copy
    Copies the image file to the target block device, utilizing an optionally provided block map file to optimize the transfer by skipping empty blocks.

verify
    Compares the contents of the image file with the specified block device, using a block map file to verify data integrity only for blocks marked as used.

show
    Parses and displays the content of a block map file in a human-readable format, or generates one from an image and displays it.

-h, --help
    Displays help message and exits.

-V, --version
    Prints version information and exits.

--debug
    Enables verbose debug output.

-o , --output= (for create)
    Specifies the output .bmap file for the create command. If omitted, output goes to standard output.

--no-empty-blocks (for create)
    Excludes zero-filled blocks from the generated block map. (Default behavior is to include them, but mark them as empty.)

--size-in-blocks (for create)
    Calculates and includes the image size in 4KiB blocks in the .bmap file's metadata.

--xml-indent (for create)
    Adds indentation to the generated XML output for better readability.

--min-alloc-len= (for create)
    Sets the minimum allocation length for blocks in the map, in bytes. Defaults to 4KiB.

-p, --show-progress (for copy, verify)
    Displays progress information during the operation.

-b , --bmap= (for copy, verify, show)
    Specifies the block map file to use. If not specified for copy/verify, bmaptool will look for a .bmap file with the same base name as the image.

--no-verify (for copy)
    Disables the automatic post-copy verification check. Using this can be risky as it skips data integrity checks.

--no-fsync (for copy)
    Disables flushing cached data to disk immediately after writing. Can speed up copy but increases risk of data loss on power failure.

bmaptool is a powerful command-line utility designed to streamline and accelerate the process of flashing disk images onto block devices. It is part of the bmap-tools project, primarily developed to address the inefficiency of traditional flashing methods (like dd) which copy the entire image, including empty sections.

Instead, bmaptool generates a 'block map' file (.bmap file) from an image. This XML-based file precisely describes which blocks within the image contain actual data and which are empty. When flashing, bmaptool (or other bmap-aware tools) uses this map to copy *only* the used blocks, skipping the large, often sparse, empty regions. This significantly reduces flashing time, especially for large images that contain much unused space, and minimizes wear on the target storage device.

The tool supports various operations including creating block maps, copying images to devices using block maps, verifying flashed images, and displaying block map contents. It's widely used in embedded systems development, manufacturing, and general Linux environments where efficient image deployment is crucial.

A .bmap file is an XML document that contains metadata about the image file, such as its size and checksums, but most importantly, a list of 'data' sections (ranges of blocks) that are actually occupied. Empty or zero-filled blocks are either explicitly marked as such or simply omitted from these data sections, allowing tools to skip them during operations. This format makes it highly extensible and human-readable.

A common workflow with bmaptool involves two main steps:
1. Creation: First, generate a .bmap file from your image:

bmaptool create my_image.img > my_image.bmap

sudo bmaptool copy --bmap my_image.bmap my_image.img /dev/sdX

bmaptool is a core utility within the bmap-tools project, which was primarily developed by Intel. Its creation was driven by the need for more efficient image flashing solutions in embedded Linux development and manufacturing pipelines, especially within the Yocto Project ecosystem. Traditional methods like dd, while robust, are inefficient for sparse images common in embedded systems. bmap-tools was designed to optimize this by introducing the block map concept, allowing for significantly faster deployment times and reduced wear on storage media. It has since become a standard tool for many developers working with large, sparse disk images.

dd(1), losetup(8), parted(8), fdisk(8), mkfs(8)