Linux Wakeup IRQ Evidence: Identify the First Recorded Interrupt Without Claiming It Explains Every Wake

Use /sys/power/pm_wakeup_irq as a bounded attribution clue, then correlate it with the same suspend attempt’s trace and device evidence. In Linux v6.12 it exposes the current first recorded wake IRQ, not the interrupt armed first, an exhaustive event list, or proof of the physical cause of every wake.

Applicability: this article pins Linux v6.12 wakeup.c, IRQ PM handling, and the power sysfs implementation. The attribute requires the relevant system-sleep debug configuration. Example IRQ numbers are hypothetical identifiers, not fixed assignments. No target was suspended and no IRQ stimulus was generated.

1. Preserve read success and read failure separately

The v6.12 pm_wakeup_irq_show() returns a decimal IRQ number when pm_wakeup_irq() is nonzero. When no number is recorded, it returns -ENODATA rather than printing zero. The attribute is included under CONFIG_PM_SLEEP_DEBUG in the relevant sleep-support path.

Record the read result, returned bytes when successful, kernel configuration, and timestamp. A missing attribute, an access failure, and ENODATA are different observations. Do not convert every unsuccessful read into a numeric zero and then label it “no interrupt wake.”

Archive the pre-attempt observation too, but do not subtract IRQ identifiers as if they were counters. The useful comparison is whether a fresh attempt produced a recorded identifier and which surrounding events support it.

2. Understand which IRQ path records the identifier

In irq_pm_check_wakeup(), an armed wake IRQ is marked pending and suspended, disabled through the IRQ path, and passed to pm_system_irq_wakeup(). This is an event-recording path, distinct from ordinary interrupt counting after the system is running.

The suspend-and-interrupts guide explains that a wake IRQ can abort an in-progress transition or wake an already-suspended system. Its normal device handler is not necessarily executed during the suspended-IRQ interval. A delayed handler log therefore need not be the instant the wake event was recognized.

Identify whether the platform’s relevant wake mechanism actually reaches this recording path. Firmware-mediated events and other wake notifications need their own source evidence. Do not assume every supported platform wake is represented by one Linux IRQ number in this attribute.

3. Keep the two-slot implementation limit visible

The exact v6.12 wakeup implementation stores two IRQ slots. pm_system_irq_wakeup fills the first empty slot; pm_wakeup_irq returns slot zero. Once both slots are occupied, another call does not become an additional stored entry.

For a hypothetical sequence recording IRQ 37 and then IRQ 52, the exposed number is 37. That does not establish that 52 never occurred. Nor does ordering under the recorder’s lock establish the chronological order of physical edges at different controllers.

pm_wakeup_clear also matters. Clearing a matching first IRQ promotes the second slot; a zero clear resets the slots and the abort counter. Other clear arguments follow their exact implementation branch. Thus a later read can differ from an earlier read within a platform’s processing sequence.

Do not call this private machinery from an ad hoc diagnostic module just to make a test cleaner. Inspect the platform’s legitimate callers and preserve their effects in the trace. The article’s two-slot illustration is a source-level model, not a recommendation to manipulate wake bookkeeping.

4. Bind evidence to one attempted transition

The v6.12 freeze_processes path calls pm_wakeup_clear(0) before its task-freezing work. A failure that occurs before reaching that point can leave earlier observations relevant to an older attempt. Record how far the current request progressed.

For each attempt, assign a test identifier and preserve requested sleep mode, entry trace, stimulus time, wake or abort result, first post-return attribute read, and subsequent device handling. Capture promptly before another automatic sleep cycle replaces the context.

Distinguish “request returned without reaching the intended state” from “state entered and later exited.” Both can involve wake events, but they answer different questions. A number in pm_wakeup_irq alone does not prove deep-state residency or its duration.

If the system automatically retries sleep, arrange a controlled development test through the normal power manager so the attempt boundaries are visible. Do not disable unrelated production wake sources merely to simplify attribution.

5. Resolve the number to the current routing

Map the recorded Linux IRQ to the running kernel’s interrupt-controller and device information. Save the mapping from the same boot. IRQ assignments can change across configurations; do not hard-code the hypothetical 37 as a permanent identity.

A shared IRQ can name several handlers or devices. A parent interrupt can represent a downstream controller with multiple pending sources. In either case, inspect non-destructive device or controller evidence through its owning driver to determine which source was actually asserted.

Ordinary interrupt-count deltas are supporting evidence only. Many interrupts can occur after resume, including work triggered by recovery itself. The largest increase does not identify the event that caused entry to abort or initiated wake.

6. Exercise attribution limits deliberately

Propose a benign single-source trial with a supported stimulus and independent recovery route. Check the recorded identifier against the actual route and device status. Repeat the same case to establish whether the mapping and evidence are stable under the chosen mode.

Then test two allowed sources separately before combining them. In a combined trial, preserve both physical or device observations even if only one identifier is exposed. Avoid declaring the second source ineffective just because it loses the first-slot observation.

Include a transition aborted before full entry and, where the platform supports it, a wake notification that lacks this IRQ evidence. The expected result is an accurately limited record, not a forced number. A model test of slot behavior can complement these trials but cannot validate board routing.

7. Report a bounded cause statement

A useful result says that a specified IRQ was recorded for a specified attempt, identifies its current route, and states whether source evidence and actual entry/resume were observed. List shared-line ambiguity or missing platform coverage explicitly.

Escalate to targeted tracing or a documented hardware wake-cause register when the bounded evidence is insufficient. Do not turn an available identifier into an unrestricted causal claim, and do not turn ENODATA into proof that no wake event happened.