企业官网建设流程全解析

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

第一次接触 wakeup source 的人，多半是在调试一个"设备明明没人用，电却掉得飞快"的板子。你打开/sys/kernel/debug/wakeup_sources，看到一长串名字和一堆数字，却不知道从哪看起。这个框架存在的意义，说白了就一句话：让系统知道"谁有资格把 CPU 从睡梦里叫醒"，并且记录下每一次唤醒的来龙去脉。

在嵌入式 Linux 和移动设备上，功耗是硬指标。系统进入 suspend 之后，绝大部分硬件断电、时钟停摆，只有少数几个模块还留着"耳朵"听外界动静——比如电源键、RTC 闹钟、USB 插入检测、WiFi 唤醒包。这些能触发唤醒的源头，就是 wakeup source。如果不管住它们，任何一个驱动随手申请一个中断就能把系统拽醒，那省电就无从谈起。

这套框架属于 PM Core（电源管理核心）的一部分，向上服务于 autosleep（自动休眠）机制，向下约束各个设备驱动。它要回答三个问题：谁可以唤醒系统、当前有没有人正在阻止休眠、每次唤醒是谁干的。把这三点搞清楚，你排查功耗问题就有了抓手。

我见过不少做嵌入式 Linux 项目的同学，能背出linux常用命令大全，能熟练linux系统安装python，但一碰到 suspend/resume 就抓瞎。原因就在于唤醒源这套东西平时不显山不露水，只有出问题的时候才跳出来。所以这篇我打算把框架从头到尾捋一遍，包括数据结构、注册流程、sysfs 接口、和 autosleep 的配合，以及我自己踩过的几个坑。

适合谁看？做嵌入式 Linux 驱动开发的、搞功耗优化的、准备linux面试题里电源管理相关问题的，以及想真正理解linux底层原理的运维和系统工程师。不需要你已经是内核高手，但至少得能看懂 C 结构体和基本的设备模型概念。

2. 核心数据结构与设计思路拆解

2.1 为什么要有 wakeup source 这个概念

在没有这套框架的年代，驱动想唤醒系统怎么办？直接调用enable_irq_wake()把中断设成唤醒源就完事了。问题是：没人统计、没人管理、没人负责。A 驱动开了唤醒，忘了关；B 驱动也开了一个；系统想休眠的时候，根本不知道到底还有多少设备处于"可唤醒"状态，只能硬着头皮睡，结果就是频繁被无关中断吵醒。

wakeup source 的核心设计思想是把"唤醒能力"抽象成一个可计数、可统计、可查询的对象。每个 wakeup source 有一个引用计数active_count，谁需要它保持唤醒能力就__pm_stay_awake()，用完了就__pm_relax()。当计数归零，这个源就不再阻止系统休眠。同时框架还记录event_count（唤醒事件次数）、wakeup_count（累计唤醒次数）、last_change（最后一次状态变化时间）等统计信息，方便事后分析。

这个设计有点像引用计数管理内存：谁用谁加，用完就减，减到零就释放。区别在于这里"释放"的是对系统休眠的阻止权。

2.2 关键结构体逐字段拆解

核心结构体是struct wakeup_source，定义在include/linux/pm_wakeup.h。我挑几个最关键的字段说：

struct wakeup_source { const char *name; // 名字，sysfs 里显示的就是它 struct list_head entry; // 挂到全局链表 struct wakeup_source *parent; // 父子关系，用于聚合统计 unsigned long flags; // 状态标志 spinlock_t lock; // 保护计数的自旋锁 unsigned long active_count; // 活跃引用计数 unsigned long event_count; // 事件计数 unsigned long wakeup_count; // 唤醒次数 ktime_t active_time; // 累计活跃时长 ktime_t total_time; // 累计总时长 ktime_t max_time; // 单次最长活跃时长 ktime_t last_time; // 上次状态变化时间 ... };

active_count是最重要的字段。它大于 0 表示这个源正在"阻止系统休眠"，等于 0 表示它当前不活跃。注意区分active_count和event_count：前者是引用计数，后者是事件次数。一个源可能被唤醒了很多次（event_count 高），但当前没人引用它（active_count 为 0）。

flags里有个WAKUP_SOURCE_IN_PROGRESS标志，表示正在处理唤醒事件，这个在调试竞态问题时很有用。还有WAKUP_SOURCE_AUTO_CREATED，标记这个源是框架自动创建的（比如设备注册时自动生成），而不是驱动手动创建的。

parent字段是后来加的，用于处理设备树里的父子设备关系。子设备的唤醒统计可以聚合到父设备上，这样你在 sysfs 里看父设备就能知道整个子系统的唤醒情况，不用一个个翻。

2.3 全局链表与锁的保护

所有 wakeup source 都挂在全局链表wakeup_sources上，由wakeup_sources_lock保护。这个锁是读写锁（rwlock），因为读操作（比如 sysfs 查询）远多于写操作（注册/注销）。

static LIST_HEAD(wakeup_sources); static DEFINE_RWLOCK(wakeup_sources_lock);

为什么用读写锁而不是普通自旋锁？因为wakeup_sources的读取非常频繁——每次系统尝试进入 suspend，都要遍历整个链表检查有没有活跃的源。用读写锁能让多个读者并发，只有注册和注销时才需要写锁独占。这个选择在高并发场景下能明显减少锁竞争。

不过要注意，active_count的增减用的是每个源自己的lock（自旋锁），而不是全局读写锁。这样设计是为了减少锁粒度：修改某个源的计数不需要锁住整个全局链表。全局锁只在链表结构变化（增删节点）时才需要。

3. 唤醒源的注册、注销与生命周期管理

3.1 手动注册：wakeup_source_register

驱动想创建一个唤醒源，最直接的方式是调用wakeup_source_register()：

struct wakeup_source *ws; ws = wakeup_source_register(dev, "my_device_wakeup"); if (!ws) return -ENOMEM;

第一个参数是关联的设备指针，可以为 NULL；第二个是名字，会出现在 sysfs 里。这个函数内部会分配内存、初始化结构体、把源挂到全局链表，并在 sysfs 里创建对应的目录和属性文件。

注册完之后，驱动在需要阻止休眠时调用__pm_stay_awake(ws)，处理完事件后调用__pm_relax(ws)。注意这两个函数是"内部"版本，不会触发 wakeup_count 的更新；对应的公开版本pm_stay_awake()和pm_relax()会额外处理一些统计和通知逻辑。在中断上下文里只能用带下划线的版本，因为它们不睡眠。

3.2 自动注册：设备树与 dev_pm 的联动

更多时候，你不需要手动注册。当设备通过设备模型注册，并且设备树里标记了wakeup-source属性，PM Core 会自动为这个设备创建一个 wakeup source。名字通常就是设备名。

my_device: my_device@12340000 { compatible = "vendor,my-device"; interrupt-parent = <&gic>; interrupts = <0 50 4>; wakeup-source; // 这一行让框架自动创建唤醒源 };

这个自动机制的好处是省事，坏处是名字可能不够直观，而且你没法在驱动里直接拿到struct wakeup_source指针去精细控制。所以实际项目里，如果需要对唤醒行为做精细管理，我还是建议手动注册，名字起得清楚一点，比如"wifi_wake"、"tp_irq_wake"这种一看就懂的。

3.3 注销与资源释放

驱动卸载或者设备移除时，必须调用wakeup_source_unregister(ws)。这个函数会把源从全局链表摘下来，释放 sysfs 节点，最后释放内存。

这里有个坑：如果注销时active_count还大于 0，说明还有人在引用这个源。框架会打印警告，但不会阻止注销。结果就是内存被释放了，但别处还拿着指针，后续__pm_relax()就会踩到已释放内存，典型的 use-after-free。我遇到过好几次这种崩溃，最后都是靠KASAN定位到某个驱动忘了配对 relax。

注意：注册和注销必须成对出现，且要保证注销前所有 stay_awake 都已经 relax。可以在注销前加一句WARN_ON(ws->active_count)做自检。

4. sysfs 接口与调试实战

4.1 /sys/kernel/debug/wakeup_sources 怎么读

这是排查功耗问题最重要的一个文件。它不在/sys/power下，而在 debugfs 里，所以得先挂载 debugfs：

mount -t debugfs none /sys/kernel/debug cat /sys/kernel/debug/wakeup_sources

输出大概长这样：

name active_count event_count wakeup_count expire_count active_since total_time max_time last_change prevent_suspend_time power_button 0 3 3 0 0 1234 567 890 0 wifi_wake 1 15 15 0 12345 67890 2345 67890 12345

各列含义：

排查思路很直接：先看 active_count 非零的源。如果系统进不了 suspend，八成就是某个源的 active_count 一直没归零。找到它，再去看对应的驱动代码，检查 stay_awake 和 relax 是否配对。

4.2 /sys/power/wakeup_count 与 autosleep 的配合

/sys/power/wakeup_count是另一个关键接口。它的值等于所有唤醒源event_count的总和。用户空间在写/sys/power/state进入 autosleep 之前，会先读一次 wakeup_count，然后把这个值写回去。如果写入的值和当前值不一致，说明期间有唤醒事件发生，写入会失败，系统就不进入休眠。

这个机制叫"竞态窗口保护"：从用户空间决定休眠到内核真正开始休眠之间，如果有中断进来，wakeup_count 会变化，写入失败，避免"刚决定睡就被吵醒"的尴尬。

# 典型的 autosleep 使用流程 echo mem > /sys/power/state # 或者用 autosleep echo 1 > /sys/power/autosleep # 开启自动休眠

开启 autosleep 后，只要没有活跃的 wakeup source，系统就会自动尝试进入 suspend。这就是为什么active_count的管理如此重要——它直接决定了系统能不能睡。

4.3 用 ftrace 追踪唤醒事件

sysfs 只能看结果，想看过程得用 ftrace。内核里有个wakeup_eventstracepoint，可以追踪每次唤醒的细节：

cd /sys/kernel/debug/tracing echo 1 > events/power/wakeup_source_activate/enable echo 1 > events/power/wakeup_source_deactivate/enable cat trace_pipe

这样你能实时看到哪个源被激活、哪个被释放，以及调用栈。定位"谁在偷偷唤醒系统"特别有效。我一般会配合trace-cmd用，把数据抓下来慢慢分析，比盯着 trace_pipe 刷屏舒服多了。

5. 与 autosleep、runtime PM 的协作关系

5.1 autosleep 的判定逻辑

autosleep 的核心逻辑在kernel/power/autosleep.c。它维护一个工作队列，当系统空闲时尝试进入 suspend。判定能不能睡的条件之一，就是所有 wakeup source 的 active_count 都为 0。

static bool pm_wakeup_pending(void) { // 检查是否有活跃的唤醒源 // 检查 wakeup_count 是否变化 ... }

如果某个源一直活跃，autosleep 就会一直重试，但每次都失败。这时候你会在 dmesg 里看到类似PM: Some devices failed to suspend或者active wakeup source: xxx的日志。看到这种日志，直接去查那个源就对了。

5.2 runtime PM 与系统 PM 的区别

很多人会把 runtime PM 和系统 suspend 搞混。简单说：runtime PM 是单个设备在不使用时进入低功耗，系统还在运行；系统 suspend 是整个系统进入低功耗。wakeup source 主要服务于后者，但两者有交互。

一个设备如果 runtime PM 处于 active 状态，它可能会持有 wakeup source，从而阻止系统 suspend。反过来，系统 suspend 时，所有设备都会被 runtime suspend。理解这个层次关系，才能理清"为什么设备明明 runtime suspend 了，系统还是睡不下去"这类问题。

5.3 唤醒源与设备树的 wakeup-source 属性

前面提过设备树里的wakeup-source属性。它的作用是在设备注册时自动创建唤醒源，并把设备的power.wakeup指针指向它。驱动可以通过device_may_wakeup(dev)判断当前是否允许这个设备唤醒系统。

if (device_may_wakeup(&pdev->dev)) enable_irq_wake(irq);

这个判断很重要：用户空间可以通过/sys/devices/.../power/wakeup文件开关某个设备的唤醒能力。驱动必须尊重这个设置，否则用户关了唤醒，设备还在偷偷唤醒，就是 bug。

6. 常见问题与排查技巧实录

6.1 系统无法进入 suspend 的排查流程

这是最高频的问题。我的排查顺序是：

1. 看 dmesg：搜索wakeup source、PM:、suspend关键词，通常会有明确提示。
2. 看 wakeup_sources：找 active_count 非零的源。
3. 看 wakeup_count：确认是否有事件在持续触发。
4. 用 ftrace：追踪 activate/deactivate 事件，看调用栈。

有一次我遇到一个 WiFi 驱动，active_count 一直是 1。查代码发现它在 probe 里调了pm_stay_awake()，但在 remove 里才 relax。结果设备一直不 remove，源就一直活跃。改成事件处理完就 relax 就好了。

6.2 active_count 泄漏的典型场景

active_count 泄漏基本就是 stay_awake 和 relax 不配对。常见场景：

• 错误路径忘了 relax：函数中间 return 了，没走到 relax。
• 中断里 stay，线程里 relax，但线程没跑：比如工作队列被取消。
• 多次 stay 只 relax 一次：引用计数是累加的，stay 两次就得 relax 两次。

排查方法：在__pm_stay_awake和__pm_relax里加 printk 打印调用栈，对比次数。或者用perf采样，看谁在频繁调用。

6.3 唤醒源名字冲突与统计混乱

如果两个设备用了同一个名字注册唤醒源，sysfs 里会出现两个同名条目，统计就乱了。框架本身不检查重名，所以起名字要带上设备标识，比如"wifi_wake"和"bt_wake"，别都用"wake"。

另外，自动创建的源名字就是设备名，如果设备树里节点名起得随意，sysfs 里也会很难看。建议设备树节点名规范一点。

6.4 常见问题速查表

6.5 几个我踩过的坑

坑一：在原子上下文调用会睡眠的函数。pm_stay_awake()内部可能拿 mutex，中断里只能用__pm_stay_awake()。我一开始没注意，在中断处理里调了公开版本，直接报 scheduling while atomic。

坑二：忘记处理 device_may_wakeup。用户通过 sysfs 关了唤醒，驱动还在 enable_irq_wake，结果就是用户以为关了，实际没关。这个在功耗测试时特别容易被误判。

坑三：autosleep 和手动 suspend 混用。同时开 autosleep 又手动写 state，行为会很奇怪。选一种方式就好，我一般调试时用手动，产品里用 autosleep。

坑四：wakeup_count 写入失败没处理。用户空间写 wakeup_count 失败是正常的（说明有事件），但有些脚本没检查返回值，以为睡了实际没睡，导致测试结果失真。

7. 从框架到实战的几点体会

把 wakeup source 框架吃透之后，你会发现它其实是 PM Core 里设计得比较优雅的一块。引用计数 + 全局链表 + sysfs 暴露，三件套组合起来，既保证了内核态的严谨，又给用户态留了足够的观测和控制手段。

实际做项目时，我的习惯是：每个可能唤醒系统的设备，注册一个名字清晰的唤醒源，在中断处理里 stay，在处理完成后 relax，并且严格检查 device_may_wakeup。同时在产品测试阶段，定期 dump/sys/kernel/debug/wakeup_sources，观察有没有异常的活跃源或事件计数。这套流程跑下来，功耗问题基本能在早期发现，不用等到用户投诉"待机掉电快"才去救火。

最后分享一个小技巧：如果你怀疑某个源在捣鬼，但又不想改驱动重新编译，可以直接在 sysfs 里操作。虽然不能直接改 active_count，但可以通过/sys/devices/.../power/wakeup关掉设备的唤醒能力，快速验证是不是它的问题。验证完再回去改代码，效率高很多。