Zephyr OS Pinctrl States: Distinguish a Missing Sleep State from a Failed Pin Transition
A pinctrl call returning -ENOENT can mean that the requested state is absent from the device's generated configuration. That is different from finding the state and failing while applying its hardware settings. Treating both as a generic pinmux error sends debugging toward the wrong layer.
For a Zephyr OS driver with default and sleep states, inspect generation and lookup before probing registers. The API discussion uses v4.4.0; board-level electrical behavior still requires the selected SoC, schematic and peripheral documentation.
Follow lookup before hardware application
The tagged pinctrl header defines default and sleep state identifiers. pinctrl_apply_state() first looks up the requested identifier and returns an error if lookup fails. Only after a successful lookup does it call the direct application helper, which reaches the SoC-specific pin configuration function.
For a hypothetical peripheral that fails to suspend, first record the requested state identifier and the actual device configuration object. Verify that the call refers to the intended peripheral instance rather than another instance with a different state list.
A missing-state result is evidence about that configuration lookup. It does not prove the physical pin rejected the requested setting, because the hardware application step was not reached through this path. Conversely, once lookup succeeds, investigate the returned hardware-specific error without continuing to blame an absent state.
Check whether build configuration removed the state
The tagged header's generation macros can skip states. In particular, it defines the sleep-state skip when CONFIG_PINCTRL_KEEP_SLEEP_STATE is not enabled. A sleep definition visible in source devicetree therefore does not by itself prove that a corresponding state exists in the compiled configuration.
Inspect the resolved build configuration and generated state list together. A hypothetical low-power build and a diagnostic build can legitimately differ here. Comparing only their source overlay files misses a build-option difference that changes which states are emitted.
The official pin-control guide explains the state model and configuration ownership. Use its general model to understand the driver, while keeping the tagged declarations as the version boundary for exact names and behavior.
Decide whether absence is optional for this driver
An application should not universally turn -ENOENT into success. Some drivers may intentionally tolerate a missing optional sleep state; others rely on that state to establish a required low-power pin configuration. Determine the contract of the specific driver and board before choosing recovery.
For a hypothetical external sensor, leaving the operational state unchanged could preserve a communication pin or bias path that affects power or behavior. Whether that is acceptable depends on the hardware. No generic pinctrl success policy can establish the electrical consequence without those facts.
Likewise, adding an empty sleep state merely to silence lookup failure can hide the original requirement. State existence, correct pin settings and verified peripheral behavior are three separate acceptance questions.
Keep pin ownership inside the driver contract
The header warns against using the low-level configuration function directly on pins owned by an instantiated device driver. A diagnostic workaround that changes those pins behind the driver can make its software state disagree with hardware.
Use the driver's supported transition path, or build a controlled test configuration in which ownership is explicit. If dynamic state replacement is involved, preserve the required state set and respect the API's availability and validation rules. Do not assume replacing a configuration array is a universal live reconfiguration method.
For proposed tests, compare a build with the expected sleep state, a deliberately omitted test state and a supported state whose hardware configuration is rejected in a controlled setup. Record whether failure occurred at lookup or application. Then verify actual pin and peripheral behavior only under safe electrical conditions.
This layered result makes the defect actionable: wrong configuration object, omitted generated state, unsupported hardware setting or incorrect transition ownership. “Sleep pinctrl failed” alone cannot distinguish them.
