1. 唤醒源框架到底在解决什么问题

第一次接触wakeup source的人，十有八九是在调一个“设备明明该睡了，电流却下不去”的问题。你查cat /sys/kernel/debug/wakeup_sources，看到一长串名字，有的active_count一直在涨，有的prevent_suspend_time大得离谱，但就是不知道从哪下手。这个框架存在的意义，说白了就一句话：让内核知道“是谁在阻止系统进入低功耗状态”，并且把这个信息以可读、可统计、可追踪的方式暴露出来。

在没有这套框架之前，功耗调试基本靠猜。驱动里到处是pm_stay_awake之类的私有实现，每个子系统各写各的，出了问题只能一个个模块去加打印。后来 PM Core 把唤醒源抽象成统一对象，所有会“唤醒系统”或者“阻止系统睡眠”的东西——中断、GPIO、网络收包、RTC 闹钟、USB 插入事件——都必须注册成一个struct wakeup_source。这样一来，谁在活跃、活跃了多久、阻止了多长时间的 suspend，全都有账可查。

它适合谁看？如果你在做嵌入式 Linux 功耗优化、在写带中断唤醒能力的驱动、在排查待机电流偏高的问题，那这套框架是你绕不过去的基础设施。哪怕你只是做应用层，理解它也能帮你判断“为什么我调了echo mem > /sys/power/state系统没睡下去”。我见过太多人卡在这一步，其实答案就藏在wakeup_sources这个 debugfs 节点里。

需要先明确一个概念区分：唤醒源（wakeup source）不等于中断（IRQ）。中断是硬件层面的信号，唤醒源是软件层面的抽象。一个中断可以关联一个唤醒源，但唤醒源还能被用户空间通过 sysfs 主动激活，也能被驱动在事件处理路径里手动__pm_stay_awake。这个区别是后面所有调试逻辑的起点，搞混了就会在错误的方向上浪费时间。

2. 核心数据结构与注册机制拆解

2.1 struct wakeup_source 里到底存了什么

这个结构体是整个框架的心脏，定义在include/linux/pm_wakeup.h。字段不少，但真正影响调试的就那么几个，我按重要性排一下：

• name：唤醒源名字，就是你在 debugfs 里看到的那个字符串。命名规范很重要，建议用“设备名+用途”的格式，比如gpio-keys、wlan0-rx，别用ws0、ws1这种，出问题时你会想哭。
• active：布尔值，表示当前是否处于激活状态。注意它和active_count不是一回事。
• active_count：累计激活次数。这个值只增不减（除非手动清零），用来判断某个源是不是频繁触发。
• event_count：事件计数，和active_count的区别在于，它统计的是“唤醒事件”而非“激活动作”。
• total_time：累计激活总时长，单位是毫秒（内核内部用 ktime，debugfs 显示时换算）。
• prevent_suspend_time：这个字段是功耗调试的核心。它记录的是该唤醒源阻止系统进入 suspend 的累计时间。如果这个值很大，说明它就是待机电流下不去的元凶。
• max_time：单次激活的最长持续时间，用来抓“某次异常长时间持有”的情况。
• last_time：最近一次激活的持续时间。

我个人的经验是，排查功耗问题先看prevent_suspend_time和active_count这两个，基本能锁定 80% 的问题源。max_time用来确认是否存在偶发的长持有，last_time则适合在复现问题时实时观察。

2.2 唤醒源的注册与注销流程

注册一个唤醒源有两种方式，取决于你的场景：

方式一：设备树 + 驱动自动注册。在设备树节点里加wakeup-source;属性，驱动调用device_init_wakeup(dev, true)后，PM Core 会自动为这个设备创建一个唤醒源，名字取自设备名。这是最推荐的方式，因为生命周期由设备模型管理，不会出现野指针。

方式二：手动注册。调用wakeup_source_register(dev, name)，传入设备指针和名字。注销时用wakeup_source_unregister(ws)。手动方式灵活，但你必须保证注册和注销成对出现，否则会留下悬空对象。

这里有个容易踩的坑：注册时机。如果你在probe早期就注册，但设备还没完全初始化，此时如果有中断触发激活，可能访问到未初始化的资源。稳妥的做法是在probe末尾、设备完全就绪后再注册。反过来，注销要在remove的最开始做，先断掉唤醒源，再释放其他资源。

/* 典型的注册与注销配对 */ static int foo_probe(struct platform_device *pdev) { struct foo_dev *foo; /* ... 资源初始化 ... */ foo->ws = wakeup_source_register(&pdev->dev, "foo-wakeup"); if (!foo->ws) return -ENOMEM; device_init_wakeup(&pdev->dev, true); return 0; } static int foo_remove(struct platform_device *pdev) { struct foo_dev *foo = platform_get_drvdata(pdev); wakeup_source_unregister(foo->ws); /* ... 其他清理 ... */ return 0; }

2.3 激活与去激活的引用计数逻辑

唤醒源内部维护了一个引用计数，__pm_stay_awake加一，__pm_relax减一。计数从 0 变 1 时，唤醒源进入 active 状态，同时记录激活时间戳；计数从 1 变 0 时，退出 active，累加total_time和prevent_suspend_time。

这个设计的好处是支持嵌套：一个驱动可能在多个路径里都需要保持唤醒，只要成对调用就不会提前释放。但坏处也很明显——只要有一处漏了__pm_relax，唤醒源就永远 active，系统永远睡不下去。这是实际项目里最高频的 bug 之一。

注意：__pm_stay_awake和__pm_relax是内核内部接口，带下划线前缀，调用时需要持有锁或确保在原子上下文。驱动里更常用的是pm_stay_awake(dev)和pm_relax(dev)，它们内部会做设备到唤醒源的转换。

3. 从 sysfs 到 debugfs 的实操观察方法

3.1 用户空间如何主动控制唤醒源

sysfs 提供了两个入口，路径在/sys/devices/.../power/下：

• wakeup：读写。写enabled表示允许该设备唤醒系统，写disabled表示禁止。读出来是当前状态。
• wakeup_count：只读（部分内核版本可写）。显示当前活跃的唤醒源数量。

用户空间主动激活唤醒源的接口是/sys/power/wake_lock和/sys/power/wake_unlock。往wake_lock写一个名字，就会创建一个同名唤醒源并激活；往wake_unlock写同样的名字，就释放它。这个机制在 Android 上被大量使用，用来让上层服务临时持有唤醒锁。

# 创建一个名为 my_lock 的唤醒锁并持有 echo my_lock > /sys/power/wake_lock # 查看当前所有唤醒源状态 cat /sys/kernel/debug/wakeup_sources # 释放 echo my_lock > /sys/power/wake_unlock

实测下来，wake_lock机制非常适合做“临时保活”的调试。比如你想验证某个外设是不是导致无法休眠，可以手动持有一个锁，观察prevent_suspend_time的变化，再释放，对比前后差异。

3.2 debugfs 输出字段逐列解读

/sys/kernel/debug/wakeup_sources的输出是表格形式，列的含义必须搞清楚，否则数据看了也白看。我按实际调试中最常关注的顺序说明：

我通常的排查顺序是：先按prevent_suspend_time降序排，看谁排第一；再看它的active_count，如果次数很多但每次时间短，说明是高频事件；如果次数少但max_time很大，说明是某次异常长持有。两种情况的处理思路完全不同。

3.3 用脚本自动化抓取与对比

手动看一次数据容易，难的是对比“修改前”和“修改后”。我一般会写个小脚本，定时抓取并做差：

#!/bin/bash # 抓取两次快照并计算差值 SNAP1=/tmp/ws1.txt SNAP2=/tmp/ws2.txt cat /sys/kernel/debug/wakeup_sources > $SNAP1 sleep 30 cat /sys/kernel/debug/wakeup_sources > $SNAP2 # 用 awk 对比 prevent_suspend_time 的增量 awk 'NR==FNR{a[$1]=$8; next} {if($1 in a) print $1, $8-a[$1]}' \ $SNAP1 $SNAP2 | sort -k2 -nr | head -20

这个脚本跑 30 秒，就能看出这段时间内谁在持续阻止 suspend。比盯着静态数据有效得多。注意列号可能因内核版本不同而变化，用之前先head -1确认一下表头。

4. 典型功耗问题排查实录

4.1 系统无法进入 suspend 的定位思路

现象：echo mem > /sys/power/state后系统没睡，或者睡了几秒又醒了。这时候第一步不是改代码，而是看wakeup_sources。

如果某个源的active列是 1，说明它当前正持有唤醒锁。找到它，然后去代码里搜这个源名字对应的pm_stay_awake调用点，检查是否有配对的pm_relax。我遇到过最隐蔽的一次是：驱动在中断上半部pm_stay_awake，计划在下半部pm_relax，但下半部因为某个条件提前 return 了，导致锁永远没释放。

如果所有源的active都是 0，但系统还是没睡，那问题可能不在唤醒源框架，而在pm_suspend的更上层——比如某个suspend_ops的valid回调返回了失败，或者有驱动在suspend回调里返回了-EBUSY。这时候要开pm_debug_messages内核参数，看 dmesg 里的 suspend 流程日志。

4.2 唤醒源计数泄漏的经典案例

计数泄漏的表现是：active_count一直涨，但active始终是 0，total_time也在涨。这说明激活和去激活是配对的，但激活次数异常多。常见原因有两个：

一是中断风暴。某个 GPIO 中断因为电平配置错误（比如该用边沿触发却配了电平触发），导致中断持续触发，每次触发都激活唤醒源。这种情况event_count也会同步暴涨。

二是轮询逻辑写错。驱动里用pm_stay_awake+schedule_delayed_work+pm_relax的模式做轮询，但 work 里又重新pm_stay_awake，形成自循环。这种问题看active_count的增长速率就能判断——如果每秒涨几十次，基本就是自循环。

排查技巧：用echo 0 > /sys/kernel/debug/wakeup_sources可以清零统计（部分内核支持），清零后观察一段时间，增量就是这段时间的真实活动。

4.3 常见问题速查表

5. 驱动开发中的实战注意事项

5.1 命名规范与生命周期管理

命名这件事看似小事，实则是团队协作的痛点。我建议统一用<驱动名>-<用途>的格式，比如i2c-touch-irq、usb-vbus-detect。这样在 debugfs 里一眼就能看出是谁。千万别用wakeup0、ws1这种，出了问题连自己都认不出来。

生命周期上，注册要在设备资源就绪之后，注销要在资源释放之前。中间如果有suspend/resume回调，注意resume里不要重复注册，suspend里也不要提前注销。我见过有人在suspend里注销、resume里重注册，结果resume失败时唤醒源就丢了，后续再也无法唤醒。

5.2 中断上下文中的激活策略

在中断处理函数里调用pm_stay_awake是常见做法，但要注意：中断上下文不能睡眠，所以必须用__pm_stay_awake这种不睡眠的版本，或者用pm_stay_awake但要确认它内部不会睡眠（实际上pm_stay_awake在原子上下文是安全的，它内部用的是自旋锁）。

更稳妥的模式是：中断里只做最小必要操作，然后schedule_work把实际处理放到工作队列，在工作队列里pm_stay_awake，处理完pm_relax。这样既避免了中断上下文的风险，又保证了唤醒源覆盖整个处理周期。

5.3 与 runtime PM 的配合

唤醒源框架和 runtime PM 是两套独立但相关的机制。runtime PM 管的是设备在系统运行时的电源状态，唤醒源管的是系统级 suspend 的阻止。一个设备可能同时使用两者：runtime PM 让设备空闲时进入低功耗，唤醒源保证有事件时系统不被挂起。

配合的关键点是：在 runtime resume 的回调里激活唤醒源，在 runtime suspend 的回调里释放。这样设备活跃时系统不会睡，设备空闲时系统才有机会进入 suspend。如果顺序反了，会出现设备已经 runtime suspend 但唤醒源还 active 的矛盾状态，导致系统永远睡不下去。

6. 从框架设计看功耗优化的整体思路

6.1 唤醒源只是功耗拼图的一块

把唤醒源框架吃透之后，你会发现它解决的是“谁在阻止睡眠”的问题，但功耗优化还有另外两块拼图：睡眠深度和唤醒频率。睡眠深度由suspend_ops和 CPU idle 驱动决定，唤醒频率则由唤醒源的事件密度反映。

一个健康的低功耗系统，应该是：大部分时间处于最深睡眠状态，唤醒源事件稀疏且每次处理时间短。如果prevent_suspend_time占比很高，说明系统根本没机会睡；如果active_count很高但每次时间短，说明唤醒太频繁，要考虑合并事件或降低轮询频率。

6.2 用数据驱动优化决策

我个人的习惯是，每做一个功耗优化，都先抓一份基线数据，改完再抓一份，用差值说话。具体指标就三个：prevent_suspend_time总量、active_count总量、系统实际 suspend 时间占比。前两个从 debugfs 拿，第三个可以从/sys/power/suspend_stats里的success和fail计数估算。

如果优化后prevent_suspend_time降了但 suspend 占比没升，说明瓶颈转移到了别处，可能是某个驱动的 suspend 回调太慢，或者唤醒事件依然频繁。这时候要回到wakeup_sources看event_count，找出还在频繁触发的源。

6.3 一个容易被忽视的细节：唤醒源的优先级

内核在决定是否进入 suspend 时，会检查所有唤醒源。但有些场景下，我们希望某个源能“否决”suspend，而另一些源只是“延迟”suspend。标准框架不直接提供优先级，但可以通过wakeup_count机制间接实现：在/sys/power/wakeup_count里写入一个值，如果实际活跃源数量超过这个值，suspend 就会被中止。

这个机制在 Android 的电源管理里用得很多，用来实现“有高优先级任务时不允许休眠”。在通用 Linux 上，你也可以用它来做简单的策略控制。写入前先读当前值，确认没有意外活跃源，再写入，然后触发 suspend。

# 读取当前活跃源数量 count=$(cat /sys/power/wakeup_count) # 写入该值，表示"如果活跃源不超过这个数才允许睡" echo $count > /sys/power/wakeup_count echo mem > /sys/power/state

这套流程在自动化测试里很实用，可以避免因为偶发唤醒源导致的测试误判。

7. 我踩过的几个坑和对应解法

第一个坑是在 probe 里注册唤醒源但忘了检查返回值。wakeup_source_register在内存紧张时可能返回 NULL，如果没检查就直接用，后面激活时会 oops。这个错误在压力测试下才暴露，平时很难发现。解法很简单，注册后必须判空。

第二个坑是在 remove 里先释放了设备结构再注销唤醒源。注销时框架会访问设备指针，如果设备已经释放，就是 use-after-free。正确顺序永远是先注销唤醒源，再释放设备相关资源。

第三个坑是误以为device_init_wakeup会自动注册唤醒源。实际上它只是设置dev->power.can_wakeup和wakeup标志，真正创建唤醒源是在设备注册到 PM Core 时由框架完成的。如果你在device_init_wakeup之后立刻去 debugfs 找，可能还看不到，要等设备完全注册。

第四个坑是用wakeup_source_register注册了但没在设备树里标wakeup-source。这种情况下，用户空间通过 sysfs 的wakeup节点无法控制它，因为dev->power.wakeup没被正确关联。要么补设备树属性，要么手动调用device_set_wakeup_capable。

这些坑的共同点是：框架的隐式行为比显式接口多。文档里不会写这些，只有实际调过、错过、修过，才会形成肌肉记忆。我现在写任何带唤醒能力的驱动，都会在 probe 和 remove 里加对称的日志，跑一遍 suspend/resume 循环，确认wakeup_sources里的计数符合预期，才敢提交。

最后分享一个我常用的验证手法：写一个简单的测试脚本，在系统空闲时连续触发 suspend 十次，每次记录wakeup_sources快照，最后对比十次快照里各源的active_count增量。如果某个源在没有任何外部事件的情况下增量不为零，那它就有问题。这个方法帮我抓到过好几个隐蔽的自激活 bug，比单次观察可靠得多。