Wake-Capable Hardware with Wake Disabled: Separate Capability, Policy and Wiring

Diagnose a non-waking device by recording three distinct Linux facts: the driver declares wake capability, policy currently permits system wake, and the IRQ or bus wake mechanism was actually armed for the selected sleep state. A working runtime interrupt or a successful sysfs write proves less than this complete chain.

Applicability: this guide pins device wake policy, sysfs behavior, and IRQ arming to Linux v6.12 with system-sleep support. The hypothetical GPIO-connected peripheral is not a board design. Exact pad retention, interrupt routing, supply requirements, and supported sleep modes must come from the target platform documentation.

1. Distinguish capability from current permission

The v6.12 device-PM interface distinguishes device_can_wakeup, representing declared capability, from device_may_wakeup, used to decide whether system-wakeup mechanisms should be enabled under current policy. These are different questions even when the same physical interrupt implements both normal operation and wake.

Create an audit row with device identity, driver, capability initialization site, current policy observation, suspend callback, and wake-arm operation. Do not begin with a list of every interrupt on the system. Start from the specific event and follow its implemented device object and routing.

A capability declaration is a software assertion about the hardware/driver integration. It is not a probe that electrically verifies every board variant. If a device-tree change reuses the same driver on a pad without the required wake path, the flag can remain misleadingly optimistic.

2. Read back the policy instead of trusting the write alone

In the exact v6.12 wakeup_show implementation, a capable device reports enabled or disabled according to device_may_wakeup. Its incapable branch emits an empty value. A missing attribute is a separate observation involving the device/configuration and must not be silently interpreted as disabled.

The store handler rejects an incapable device or an invalid string. However, for an accepted enabled string it calls device_set_wakeup_enable without propagating that helper’s result. The underlying wakeup-source setup can fail, including allocation failure. Thus a successful write alone is insufficient evidence that this v6.12 path established enabled policy.

For an approved controlled test, preserve the original policy, apply the intended setting through the platform’s normal management path, and read it back. Record both results. If readback disagrees, investigate the exact implementation and concurrent policy manager before proceeding to electrical tests.

Do not broaden capability in a driver merely to make the sysfs setting writable. First establish that the hardware and interrupt controller support the intended route. A policy interface cannot manufacture missing retention or wiring.

3. Inspect the actual wake-arm operation

Find where the driver or subsystem evaluates wake permission during system suspend. Follow the branch to the bus-specific wake configuration or IRQ wake helper, and record its result. Merely reaching the suspend callback does not establish that the arming branch ran.

The suspend-and-interrupts documentation explains enable_irq_wake as configuring platform handling for a system-wakeup IRQ. Normal IRQ enablement is a different operation. Check the platform’s implementation and return value rather than assuming every valid Linux IRQ supports wake.

Keep a balanced record of successful wake-arm and disarm operations. The v6.12 IRQ management implementation tracks wake depth and invokes the interrupt-chip wake operation at the relevant boundary. Do not add extra calls opportunistically in unrelated recovery paths.

Some drivers use managed wake-IRQ infrastructure instead of calling the helper directly. Audit the effective path in that subsystem; do not introduce a second arming owner alongside it.

4. Do not substitute IRQF_NO_SUSPEND

IRQF_NO_SUSPEND leaves an IRQ available during suspend phases for special-purpose handling. It does not guarantee system wake. The interrupt guide also explains that a system-wakeup IRQ normally causes pending-event handling without running its ordinary handler during the suspended-IRQ interval.

Consequently, the absence of a driver’s normal handler print before full resume does not prove its wake IRQ failed. Conversely, seeing that print from an IRQF_NO_SUSPEND handler does not prove that the system completed a wake transition from the intended low-power state.

The flags affect an IRQ line, including other users when shared. Do not “fix” one peripheral by adding NO_SUSPEND to a shared line without reviewing every handler’s suspended-device access. Use the documented special cases only when their complete requirements are met.

5. Run a policy-by-arm diagnostic matrix

Use a harmless controlled stimulus and independent recovery access. Record actual sleep entry, stimulus timing, wake-arm result, resume evidence, and first post-resume device operation. A suspend abort before entry is a different outcome from wake after entry.

For the disabled-policy control, keep unrelated sources identifiable. If another source wakes the machine, that does not establish that the target ignored its disabled policy. Correlate the event path rather than assigning cause from temporal proximity alone.

6. Stop at the first unsupported link

If capability is absent, review driver/platform support. If policy readback is disabled, investigate policy establishment. If arming fails, inspect the interrupt-controller or bus support. Only after those checks should a missing physical wake focus the investigation on pad state, retained supplies, routing, or the selected sleep mode.

No wake policy was changed and no target was suspended for this article. The deliverable is an exact API-to-IRQ audit with positive and negative policy cases. It explains which software assertion is missing without treating an enabled flag, ordinary interrupt, or callback log as electrical proof.