U-Boot EFI Capsules: Trace FMP Identity Through to the DFU Alternate

A capsule matches a firmware image GUID, yet that is only part of the
evidence needed to approve its destination. U-Boot v2025.01 first
selects a Firmware Management Protocol implementation using descriptor
identity, then the raw-image updater maps the image index to a DFU
alternate. The two mappings must remain consistent across a board
release.

This article covers the raw capsule backend without
FWU_MULTI_BANK_UPDATE. It is directly applicable to a
product’s selected U-Boot build, including one packaged by Buildroot.
FIT capsules, multi-bank target selection and signing-key enrollment are
outside scope. No capsule is submitted or flashed here.

Match the descriptor’s
actual fields

The capsule handler passes the image type GUID, image index and
hardware instance to efi_fmp_find(). That function
enumerates FMP image descriptors and requires the type GUID and image
index to match. Its instance condition accepts a zero requested
instance, a zero descriptor instance or an exact instance match. Tagged
capsule matching implementation.

This is not matching by the capsule filename, display name or an
informal board label. Those labels may help a person, but they do not
replace the compared fields. A zero hardware-instance value also should
not be described as selecting a unique physical unit through this
comparison.

U-Boot’s image-descriptor builder obtains indices, type GUIDs and
display names from update_info.images. In the tagged
implementation it sets the descriptor hardware instance to one. Record
the actual descriptor values used by the build rather than copying an
old capsule-generation command whose identifiers may no longer agree. Descriptor
construction.

Continue from identity to
destination

For the non-multi-bank raw backend,
efi_firmware_raw_set_image() computes the DFU alternate as
image_index - 1. It then calls
dfu_write_by_alt(). Thus image index three refers to
alternate two in this path; the arithmetic is not a search by the
firmware’s display name. Raw
image backend.

The DFU helper initializes entities, retrieves the entity for that
alternate and writes through it. An absent alternate is an error, but a
present alternate is not proof that its region has the intended product
meaning. Reordering the DFU configuration while leaving firmware indices
unchanged can therefore change the index-to-target relationship. Alternate
lookup helper.

The official guide explicitly relates non-multi-bank image indices to
alternate numbers and describes firmware-provided DFU configuration.
Treat the descriptor array and that target mapping as one reviewed
release artifact. For each image, record the type GUID, index, accepted
instance semantics, resulting alternate and physical region. Capsule
configuration guide.

Keep selection
separate from authorization

Before the raw backend writes,
efi_firmware_verify_image() invokes authentication
handling, extracts firmware-version information and compares it with the
configured lowest supported version. Authentication behavior depends on
the build’s capsule-authentication configuration. Successful destination
matching alone is neither signature validation nor a complete rollback
policy. Verification
call chain.

Likewise, preserving signature checks cannot correct a mistaken
descriptor-to-region mapping. A release review must establish both that
the payload is permitted and that the permitted payload reaches the
intended component. Do not disable verification to experiment with
target selection.

For controlled qualification, inspect descriptors and the resolved
DFU list without submitting an update. Use a model or disposable fixture
to exercise a wrong type GUID, wrong image index, incompatible nonzero
instance and missing alternate. Separately review an alternate-order
change while holding descriptor indices fixed; it should trigger a
mapping review even if every entry still exists.

No target rejection or update success is claimed from executed tests.
The desired release evidence is an unbroken identity chain from capsule
fields to firmware descriptor to storage destination. Multi-bank builds
require their own runtime bank-resolution analysis rather than reusing
the simple index-minus-one rule.