U-Boot Extlinux FDT Selection: Separate Exact Files from Directory Fallback

A board boots with an unexpected device tree after a DTB file is
removed from its boot filesystem. Another extlinux entry, apparently
describing the same board, stops instead. The difference can come from
whether the entry names an exact FDT file or asks U-Boot to construct a
filename from a directory and environment values.

This analysis follows upstream U-Boot v2025.01. It focuses on
ordinary non-FIT kernel labels, a configured fdt_addr_r, and
CONFIG_SUPPORT_PASSING_ATAGS disabled. FIT-contained device trees,
legacy ATAGS behavior and downstream changes require their own review.
No boot experiment is reported here. For a Buildroot-based product,
trace these mechanisms in the U-Boot revision and board configuration
selected by that product; Buildroot integration does not replace that
check.

Begin with the label
that actually ran

Preserve the selected extlinux label, its configuration file and the
relevant environment values. Record whether the entry uses
fdt or fdtdir, whether fdtfile is set, and
which addresses are configured for loading or fallback. Do not infer the
selected tree merely from the DTB filenames present on storage.

The distro
configuration guide explains the extlinux device-tree options and
the environment used for loading them. Its broader boot configuration
discussion is useful context, but the exact failure path should be
checked in the implementation used by the product.

Give each candidate tree a reliable, harmless identity in the test
fixture. A filename alone is insufficient when two files have been
copied from the same build output or when a fallback blob was supplied
by firmware. Record an artifact digest and the expected board identity
alongside the label.

Follow the exact-file branch

In the tagged label_boot
implementation, an explicit FDT name takes priority over a
directory-derived name. If retrieval of that explicit file fails, the
label path exits through cleanup. That is a materially different result
from treating any missing device-tree file as permission to try another
source.

The engineering implication is straightforward: an exact-file entry
can express a stronger selection expectation, but only within the actual
loader configuration and code path. Do not advertise it as a complete
authenticated-device-tree policy. File selection and cryptographic trust
remain separate review questions.

When debugging this branch, capture the retrieval request and the
first error. A later attempt at another menu label can make the overall
console session appear to recover, even though the first label correctly
rejected its missing required file. Associate each event with its
label.

Follow the
directory-derived branch separately

The same implementation constructs a directory-based filename using
fdtfile when available, otherwise using the soc and board values. A
failed directory-derived retrieval can proceed to fallback sources. In
the scoped non-FIT path, those include fdt_addr and then fdtcontroladdr
when no earlier tree was selected.

This creates an important diagnostic possibility: a boot that reaches
Linux does not prove that the expected filesystem DTB was used. The
fallback may be correct, stale or inappropriate for a particular
hardware revision. The outcome must be established from the selected
blob and the resulting hardware description, not from the absence of a
fatal message.

Review the policy with the board owner. Is fallback intentional for
this product? Which source is authoritative for hardware revision?
Should a missing filesystem artifact be recoverable, or should it stop
that label? Answer those questions before changing fdtfile or adding
another address to make the system start.

Distinguish an
address from a valid artifact

An environment value containing a plausible RAM address does not show
that the intended DTB occupies that memory. Trace who populated it,
when, and whether another load can overwrite the region before boot.
Include the configured load map in the review rather than checking each
variable independently.

Likewise, do not casually modify the control device tree to
experiment with Linux’s hardware description. Keep firmware-owned data
and the selected operating-system input distinct in your test design.
Use recoverable fixtures and a documented restoration path when changing
boot inputs.

Where the product intentionally passes a firmware-provided blob,
capture its identity before handing control to the kernel. Where it
requires a filesystem artifact, make that requirement visible in the
release checklist. A successful transfer of some blob is weaker evidence
than selection of the approved artifact.

Test a
selection matrix rather than one happy path

Create separate fixtures with a known-good explicit file, a missing
explicit file, a valid directory-derived file and a missing
directory-derived file. For the directory cases, vary the presence of
fallback inputs deliberately. Keep the kernel and other boot
configuration constant so the observation concerns tree selection.

Before each run, write the expected selected source or expected label
rejection. Record the actual retrieval path, the selected label and the
blob identity passed onward. Then verify a small set of board-specific
properties that distinguish the approved tree from a plausible wrong
one. Those properties should be chosen by the hardware team, not
invented from a generic example.

Repeat after an ordinary firmware or filesystem update that changes
where the tree is supplied. This proposed regression is about selection
behavior, not a claim that the update is power-loss safe. An
interruption campaign would need its own storage and update
analysis.

Make the fallback policy
auditable

Close the issue with a short selection rule: exact file required,
directory-derived lookup with approved fallback, or another explicitly
reviewed policy. Include the scoped U-Boot revision and the fixture that
exercises its failure branch.

The useful lesson is not that one keyword is always superior. It is
that similar-looking extlinux entries can make different decisions when
retrieval fails. Once those branches are visible, the team can choose a
policy intentionally and stop treating “Linux started” as proof that the
right device tree reached it.