U-Boot Full Pinctrl: A Zero Return Can Hide Failed Entries in a State List

In U-Boot v2025.01’s full pinctrl implementation, selecting a state
can return zero after one or more referenced pin-configuration entries
failed. The loop warns and continues for those per-entry failures, then
returns success at the function boundary.

For board bring-up, a successful state-selection return therefore
does not prove that every phandle in the selected list was resolved and
applied. Retain the warning stream and verify the intended configuration
groups individually before treating the state as completely
installed.

Separate state
lookup from per-entry application

The pinctrl
API header defines state selection and the controller operations.
The concrete behavior here comes from the full
uclass implementation, rather than an assumption that a state name
represents one atomic hardware operation.

pinctrl_select_state_full() first searches
pinctrl-names for the requested name. If it cannot find
that name, it attempts to interpret the argument as a decimal state
number. It then looks up the corresponding pinctrl-N
property.

Failure to identify that property can return an error before the
iteration begins. Once the property exists, however, the function walks
its phandle list. Each entry requires locating a
UCLASS_PINCONFIG device and applying its configuration
through the owning pin controller.

These are different failure layers. A missing state property is not
reported through the same path as a missing device for one of the
state’s entries.

Follow the
warning-and-continue branches

If lookup of an entry’s pin-configuration device fails, the loop
emits a warning and continues with the next phandle. If
pinctrl_config_one() fails, it also warns and continues.
After processing the list, the function returns zero without
accumulating those individual failures into a final error.

For a hypothetical three-entry state, the first entry can apply, the
second can fail and the third can still be attempted. A zero final
return is compatible with that sequence. It does not establish that the
second entry was repaired, ignored intentionally or unnecessary for the
peripheral.

The wrapper also contains no rollback of previously applied entries
when a later entry fails. Controller-specific callbacks can have their
own behavior, but the shared loop does not make the whole state change
transactional. Inspect the hardware-facing callback before claiming what
a failed individual application left behind.

Do not
infer a simple-mode fallback from the comment

The public pinctrl_select_state() wrapper selects its
implementation from the build configuration. With
PINCTRL_FULL enabled, it directly returns the full
implementation’s result. Otherwise it calls the simple
implementation.

Although the nearby comment describes trying a simpler implementation
after failure, the inspected control flow does not perform that runtime
fallback. Use the executable branch as the evidence. A missing
full-state property is not automatically rescued by a simple callback in
this version.

There is another early boundary: a device without a valid devicetree
node returns zero without selecting a state through either
implementation. That supports logical devices, but it is another reason
a bare return code cannot prove physical pin changes occurred.

Diagnose the group that
failed

For the actual build, map each state-list phandle to its
configuration node, owning controller and callback. Check which nodes
survived phase filtering and binding. Preserve warnings from the same
boot phase in which the peripheral is probed; a later successful
configuration can conceal the earlier defect.

A proposed fixture should include a fully valid state and a
recoverable test state with one deliberately unresolved configuration
reference. Record the returned value, per-entry attempts and permitted
pin-state observations. Do not apply experimental configurations to pins
controlling live equipment.

No pinctrl operation or hardware test was executed. The useful
diagnostic result is an entry-by-entry explanation of what applied, what
failed and what remained unchanged, rather than a single success label
for a multi-entry state.