U-Boot PXE: An Explicit DHCP Configuration Path Can Disable the Usual Search Fallback

If U-Boot fails to fetch a DHCP-specified PXE configuration, do not
assume it will next try the UUID, MAC-address and default filenames. In
v2025.01’s enabled DHCP-option path, that explicit configuration attempt
is a separate branch: failure exits pxe_get() instead of
continuing into the ordinary search sequence.

This distinction explains a useful diagnostic pattern. A server can
contain a valid default configuration while a client still fails
immediately after requesting one stale explicit filename. Repair the
path-selection contract rather than repeatedly editing an unrequested
default file.

Establish which
branch selected the filename

The PXE
command implementation checks the applicable build option and the
presence of pxelinux_configfile before its general search.
The IPv4 branch is associated with DHCP option 209; the corresponding
IPv6 branch is associated with option 60.

When the relevant branch applies, pxe_dhcp_option_path()
attempts the supplied configuration name. Success finishes retrieval.
Failure jumps to cleanup and returns an error. It does not merely record
one unsuccessful candidate before proceeding through the UUID and MAC
paths.

Keep the protocol condition explicit. Receiving an option does not
prove the running build enabled its handling, and the IPv4 and IPv6
branches have separate configuration gates. Record the actual firmware
configuration together with the supplied option and requested
filename.

Contrast the ordinary search
path

When no applicable explicit-option branch is selected, the command
tries the UUID path, then the MAC path, then IP-derived names. It stops
at the first successful retrieval. If those fail, it tries the compiled
default-name list.

The IP-derived loop formats the current IPv4 address as eight
uppercase hexadecimal digits and successively shortens the name by one
trailing digit. The default list can contain architecture, SoC and
board-qualified forms, depending on which build definitions exist,
followed by the general default name.

This ordering is a retrieval policy, not a comparison of
configuration quality. An earlier file that downloads successfully
prevents later candidates from being requested, even if an administrator
considers a later file newer or more appropriate. Parsing and booting
that downloaded file are subsequent stages.

Check the complete requested
path

The PXE
file helpers add pxelinux.cfg/ for the ordinary
filename-search helpers. The explicit DHCP configuration helper calls
the general PXE-file retrieval function directly instead. Do not
mechanically insert the ordinary search directory into both paths.

The retrieval context also supplies a boot directory derived from the
bootfile context. The tagged
PXE guide describes the bootfile and server environment used for
network retrieval. Compare the complete requested pathname shown by the
client or server, not just the last filename component.

A hypothetical server might offer an explicit old configuration path
while its new configuration exists only under the default search
directory. A successful DHCP exchange and an accessible default file do
not bridge that mismatch: the selected branch never asks for that
default after the explicit fetch fails.

Use a branch-discriminating
fixture

On an authorized test network, compare two proposed cases: an
applicable explicit configuration option naming a missing file, and the
same client without that applicable explicit option. Preserve requested
filenames and retrieval outcomes. Expect the first case to exit its
explicit branch, while the second follows the ordinary candidate
sequence.

Add a positive explicit-file case to establish that the offered path
is resolved as intended. Then validate the downloaded configuration and
its chosen payload separately. No DHCP exchange, TFTP transfer or target
boot was executed here.

The practical acceptance evidence is a trace connecting the
configuration option, compiled branch, complete requested path and
returned retrieval result. The existence of a default configuration on
the server is insufficient when the client has selected a different
retrieval policy.