U-Boot Fastboot MMC Aliases: Resolve the Host Name Before Trusting a Partition Match

A factory host requests a familiar Fastboot partition name, and that
exact name exists in the device’s partition table. It is tempting to
conclude that the named partition must be the destination. In U-Boot
v2025.01’s normal MMC lookup path, an environment alias can replace the
requested name before partition lookup begins.

The practical question is therefore one of name resolution: which
target does this deployed bootloader derive from the host’s string? This
article examines the upstream MMC backend, including its boundaries
around special targets. It is relevant to a Buildroot product that
enables U-Boot Fastboot, without assuming Fastboot is enabled in every
product.

Treat the host string as an
input

The official
Fastboot documentation describes environment aliases with the
fastboot_partition_alias_ prefix. They allow a host-facing
name to differ from the actual storage name. This is useful for stable
factory interfaces, but it introduces another release-controlled
input.

Record the host selector and its expected resolved identity
separately. The host selector is what the script sends. The resolved
identity includes the MMC device, hardware partition where applicable,
partition-table entry or raw region, and the resulting block interval. A
string comparison against the partition table checks only part of this
contract.

Also distinguish a completed host-to-device download from the later
storage operation. Receiving bytes into a transfer buffer does not prove
which destination the subsequent flash request will select.
Qualification must associate the downloaded artifact with the exact
requested target and its resolved mapping.

Alias
substitution comes before normal lookup

The tagged
MMC backend implements
part_get_info_by_name_or_alias(). It constructs the
alias-variable name, reads its value and, if present, replaces the input
name before calling do_get_part_info().

This is not a fallback that is consulted only when a real partition
with the original name is missing. An existing alias can redirect a name
that would otherwise match a real partition. The function also performs
one substitution; it does not recursively walk a chain of alias
variables.

A release review should consequently flag three cases: an alias that
shadows an existing partition name, an alias pointing to an absent
target, and a value whose apparent target is itself another alias. The
last case must not be interpreted using shell-like or filesystem-like
recursive resolution that this function does not implement.

Follow the lookup stages in
order

do_get_part_info() first checks named partitions on
CONFIG_FASTBOOT_FLASH_MMC_DEV. If that lookup fails, it
tries a raw descriptor on that default device. Only after those attempts
does it use the device-and-partition parser for a device-qualified
specification.

This order matters when names collide with raw descriptors. A
matching real partition wins over the raw descriptor at this stage. The
same environment can therefore resolve differently if a later storage
image introduces a partition with the descriptor’s name. Review the
partition table and environment as a pair rather than validating each
independently.

Raw descriptors are another namespace, not ordinary byte offsets. The
backend parses a starting logical block and block count, uses the
device’s block size and can select an MMC hardware partition through the
optional descriptor field. Keep that distinction visible in the mapping
worksheet. This article does not provide a flashing recipe or assume one
block size for all devices.

Special
targets are outside the ordinary alias chain

Before normal partition lookup,
fastboot_mmc_flash_write() handles configured special
names, including supported MMC boot-area and partition-table operations.
The exact branches depend on build options. Other special handling is
also present in the backend.

Do not infer that an alias can safely redefine one of these names.
Audit the actual comparison order for every selector permitted by the
factory script. A normal data-partition example cannot establish the
behavior of a GPT update, a whole-device target or a board-specific
extension.

The same caution applies to erasure. Although aliases are used by
relevant normal paths, the erase implementation has its own special
handling and hardware constraints. Approval of a flash mapping is not
automatically approval of an erase operation using a similar string.

Review mapping
changes without writing storage

Begin with source and configuration inspection. Build a resolution
table containing the permitted host names, special-name matches, alias
values, default MMC device, current partition names and any raw
descriptors. Resolve each row through the tagged algorithm and mark
ambiguities that depend on the current media layout.

Add upgrade states to that table. A retained alias from an older
release can change the meaning of a newer host script. A changed
partition table can alter which lookup stage succeeds even when the
environment has not changed. Decide which component owns migration of
those values.

Only after this static review should a recovery-capable factory
fixture exercise real storage writes under an approved procedure. Use
disposable regions and distinguishable artifacts. Verify the resulting
destination and untouched neighboring regions with an independent
readback method appropriate to the hardware. No such writes or readbacks
were performed for this article.

Keep the
acceptance statement tied to the mapping

A strong qualification record names the bootloader build, host
request, effective alias state and resolved storage interval. It also
identifies special targets that were excluded from that normal-partition
test.

This prevents a successful protocol exchange from masking a stale
naming contract. The value of aliases is their ability to decouple host
scripts from physical layout; the engineering responsibility is to make
that decoupling explicit, versioned and testable whenever either side
changes.