U-Boot USB Mass Storage: Audit the Exact Region Exported as a LUN

A manufacturing tool may request one partition yet receive a USB disk
representing a much larger region. Before diagnosing the host
filesystem, check how U-Boot constructed the logical unit. In v2025.01,
successful partition lookup does not always determine the region
exported by ums: a later compatibility rule examines the
original selector text.

This article covers the U-Boot USB gadget mass-storage command and
its backing block-device selection. It does not describe USB host
enumeration or establish an isolation guarantee against arbitrary host
requests.

Resolve the two
device numbers separately

The first command argument selects the USB gadget controller. The
backing interface and device selector identify storage. These numbers
belong to different namespaces; matching numeric values do not establish
that the intended eMMC, USB disk or hardware partition was selected.

The tagged
command guide documents a numeric partition suffix, with partition
zero exposing the complete selected block-device view. When no backing
interface is supplied, the command uses MMC. Its optional interface
position therefore matters when generating arguments
programmatically.

For each LUN, preserve the interface, backing device number and
hardware-partition number as a single identity. “Whole device” here
means the block-device view selected by the storage layer, not every
hardware partition that physically exists on an eMMC package.

A successful name
lookup can be overridden

The partition
resolver first attempts the device#partition-name form.
If it finds the named partition, it returns the partition number and
fills the partition information. Otherwise, it tries the numeric
partition-description path.

However, ums_init
then checks whether the original selector contains a colon. Without one,
it forcibly sets the partition number to zero for legacy compatibility.
The test does not ask whether a name lookup succeeded.

Consequently, a source-derived selector such as
0#factory, assuming that named partition exists and
resolves successfully, reaches the whole-view branch because it contains
no colon. The selected partition’s start and size are no longer used.
This is an implementation-specific consequence of the v2025.01 command,
not a general rule for every U-Boot command accepting partition
syntax.

For an automation interface intended to export a numeric partition,
use the documented colon-based form and independently validate the
resolved result. Do not assume that support in the shared resolver makes
every syntax equivalent in its caller. Vendor changes and later releases
require another check of this final selection step.

Follow the start and
count into the LUN

For partition zero, U-Boot sets the exported start sector to zero and
the sector count to the backing descriptor’s total LBA count. For a
selected nonzero partition, it uses the partition information’s start
and size. The command prints the LUN number, backing device, hardware
partition, start and count during setup.

The storage callbacks translate a host-relative starting sector by
adding the saved start sector before calling the block layer. That
explains why host LBA zero can refer to the beginning of a partition
rather than the physical disk’s first sector. It also explains why a
partition-only export and a whole-disk export can present different
partition-table expectations to host software.

These fields describe the intended mapping. They do not, by
themselves, prove complete bounds enforcement for every SCSI request.
Treat that as a separate gadget-protocol and block-layer review if the
host is outside the product’s trust boundary.

Qualify
the selector without exposing production storage

A disposable fixture can compare a numeric partition selector, an
explicit whole-view selector and a successfully resolved named selector.
Record the resulting LUN start/count and host-reported capacity, then
compare them with the approved storage map. The named-selector case
specifically tests the compatibility override rather than merely testing
whether name lookup works.

Avoid attaching production media to a writable host as a discovery
technique. This article did not run ums, enumerate a gadget
or transfer files. Its result is a code-derived selection rule: verify
the final exported extent after all caller-side overrides, not only the
shared resolver’s answer.