U-Boot EFI Boot Entries: Separate BootOrder Selection from Default-File Resolution

A device boots an EFI executable even though the expected boot entry
is missing, or stops despite a valid fallback file on storage. It is
tempting to describe both cases as “UEFI fallback.” That label hides two
separate questions: which boot option is tried, and how that option
resolves to a file.

This article follows the U-Boot v2025.01 boot manager implementation.
For a Buildroot product, inspect its selected EFI configuration and
actual entry path. Board scripts, automatic option maintenance and
standard-boot methods can add behavior around the functions discussed
here. No EFI variables were changed and no executable was launched for
this article.

Capture the
selection state before changing it

The bootefi
reference describes bootefi bootmgr and Boot#### options containing
a label, device path and load options. BootNext identifies a next
option, while BootOrder supplies the sequence to try when the
next-option path does not produce a loadable binary. The manager
subcommand requires its build support.

Record BootNext, BootOrder and the referenced option data before
attempting repair. Include the bootloader artifact and the command or
boot method that invoked EFI. A filename on a mounted partition does not
explain whether the manager considered that partition or whether an
option pointed to another device.

Keep the variables’ storage and persistence behavior as a separate
product check. Seeing a value during one session does not prove it will
survive reset, and seeing a value after startup does not prove it was
present before initialization or option-maintenance logic ran. Capture
state at the boundaries relevant to the failure.

Trace
BootNext and BootOrder in the tagged loader

The tagged
EFI boot manager source attempts to delete BootNext before loading
its selected option. If that path does not return success, it proceeds
to BootOrder. Its option loader also rejects an option that is not
active.

These details make a repeated test stateful. A successful first
attempt and a second attempt may not start with the same BootNext state.
Record before and after snapshots instead of treating the second run as
a repetition of the first. Use an isolated qualification setup when
testing variable changes, because those changes alter future boot
selection.

At the efi_bootmgr_load function boundary, a missing BootOrder
produces EFI_NOT_FOUND. That function does not, at that point, turn the
absence of BootOrder into an unconditional scan for every fallback file.
Surrounding initialization or board policy may maintain options, so this
is a precise statement about the tagged function, not a universal
prediction for every complete board boot.

Separate a
media option from an explicit file option

The same source contains a media-loading path that can resolve a
device path without a filename to an architecture-specific default boot
file. An option already naming a file follows a different resolution
case. This is the distinction that a broad “fallback works” report
usually loses.

Inspect the decoded device path, not just its human-readable label.
Does it identify a particular file, a media device or a partition? Which
architecture-specific file is expected on that path? Does the available
device expose the protocols the selected resolution path needs? Answer
those questions before modifying the contents of the storage device.

A file with the right basename on the wrong partition will not
satisfy a path that points elsewhere. Likewise, a correct file on
removable storage does not establish that the current option-selection
path will reach it. Selection and resolution need separate evidence even
when a familiar EFI directory exists.

Account for
automatically maintained options

The tagged source also includes media-device option maintenance that
can create entries for detected devices and remove obsolete
automatically generated entries. Determine whether the product’s
surrounding flow invokes that maintenance and when it runs. Do not
assume it runs solely because the function exists in the source.

This check explains an otherwise puzzling diagnostic pattern: an
engineer deletes an option, restarts the relevant flow and finds an
option again. The next step is to trace its producer, not to conclude
immediately that variable persistence is broken. Preserve enough state
to distinguish a retained variable from a newly generated one.

Review manual and generated options as separate owners. If
manufacturing sets a deliberate boot order while a later interface
maintains media entries, document how those policies coexist. Avoid
repairing a single unit with an unexplained reorder that the next normal
initialization will reverse.

Qualify selection
and execution separately

A proposed test matrix includes a valid BootNext option, an unusable
next option followed by a valid BootOrder entry, an inactive option and
a media option with and without the expected default file. Add a
missing-BootOrder case at the actual product entry point and record any
option-generation behavior that occurs before loading.

Use harmless EFI qualification applications and recoverable test
media. Distinct application markers help identify which executable was
selected without relying only on a file’s presence. Record the resolved
device path and artifact identity with the marker. A test that changes
secure-boot policy as well as selection cannot isolate the ordering
question.

Loading an image is also not the same as the application or operating
system completing its job. The manager’s file-selection evidence stops
before those later outcomes. Keep required image verification, execution
and product readiness as separate acceptance checks, without weakening
the normal trust policy to make a test pass.

A useful failure report therefore has a chain: initial option state,
any maintenance step, selected option, resolved file and subsequent
execution result. That chain turns an ambiguous fallback claim into a
reproducible explanation of why this U-Boot build did, or did not, reach
the intended EFI executable.