企业官网建设流程全解析

1. 为什么唤醒源（wakeup source）不是“开关”，而是内核功耗管理的神经末梢？

在 Linux 内核功耗子系统中，wakeup source这个词常被初学者误读为“一个能唤醒系统的硬件开关”——就像按一下电源键，机器就亮了。这种理解看似直观，实则掩盖了它在整个功耗架构中真正扮演的角色：它是内核对“外部扰动”的感知接口、决策依据与状态锚点，是功耗策略能否落地的神经末梢，而非执行器本身。

我第一次在某嵌入式项目中调试休眠失败问题时，就栽在这个认知偏差上。当时设备在 suspend-to-RAM 后总在 3~5 秒内自动唤醒，dmesg里只有一行模糊提示：PM: wake up source: xxx triggered。我立刻去查xxx对应的硬件手册，翻遍中断寄存器配置、GPIO 上拉下拉、时钟门控……折腾两天无果。直到某天深夜重读drivers/base/power/wakeup.c的注释，才猛然意识到：触发唤醒的从来不是硬件本身，而是内核中那个被注册、被标记、被计数、被检查的struct wakeup_source实例。硬件只是“事件源”，而wakeup_source是内核为该事件源建立的“数字身份档案”。

这个档案里存的不是电压值或引脚号，而是三类关键信息：

• 活性状态（active state）：当前是否处于“活跃待命”状态（.active字段），由__pm_stay_awake()/__pm_relax()控制；
• 唤醒抑制能力（wakeup ability）：是否具备唤醒能力（.wakeup_count是否非零，.ignore_children如何影响级联判断）；
• 生命周期归属（ownership）：属于哪个设备驱动？哪个子系统？是否被 sysfs 暴露？其name和dev_name是否唯一可追溯？

正是这套机制，让内核能在进入深度睡眠前，做一次原子级的“全员点名”：所有wakeup_source实例必须处于 inactive 状态，且无 pending 唤醒事件，才能允许enter_state()执行。它不直接控制硬件，却通过device_set_wakeup_enable(dev, true)这样的 API，把驱动层对硬件唤醒能力的使能请求，翻译成对wakeup_source结构体字段的设置，并最终映射到irq_set_irq_wake()或pm_runtime_allow()等底层操作。

提示：wakeup_source不是 IRQ handler，也不是中断服务程序。它不处理数据，不解析协议，不响应电平变化。它的全部职责，就是记录“谁想叫醒我”以及“现在能不能叫醒”。这正是它被称为“框架”而非“驱动”的根本原因——它提供的是元数据管理范式，而非功能实现。

这种设计带来两个关键优势：一是解耦。设备驱动只需调用标准 API 注册/激活/释放自己的wakeup_source，无需关心 PM core 如何汇总、如何排序、如何与 cpuidle 协同；二是可观测。通过/sys/power/wakeup*接口，运维人员可实时看到每个唤醒源的active_count、event_count、wakeup_count、expire_count四个核心计数器，从而精准定位“谁在偷偷拉高系统功耗”。比如event_count != wakeup_count就意味着有事件被丢弃（通常因wakeup_source处于 inactive 状态时收到中断），这是诊断“唤醒丢失”类问题的第一线索。

所以，梳理wakeup source框架，本质是梳理内核如何将物理世界的异步事件，转化为可审计、可抑制、可追溯的软件状态机。它不是功耗管理的终点，而是所有深度睡眠策略得以安全执行的起点。

2. 从struct wakeup_source到/sys/power/wakeup*：一个唤醒源的全生命周期

要真正掌握wakeup source，必须亲手走一遍它从代码定义到用户空间可见的完整链路。这不是简单的“注册-使用-注销”三步曲，而是一套包含内存管理、引用计数、sysfs 绑定、状态同步的精密协作流程。下面以一个典型的 I2C 触摸芯片驱动为例，还原其wakeup_source的诞生、活跃与消亡。

2.1 初始化：静态定义与动态分配的双重路径

内核中wakeup_source的创建有两种主流方式：

方式一：静态定义（适用于固定设备，如 RTC、Power Key）

// drivers/rtc/class.c static struct wakeup_source rtc_wake_lock = { .name = "rtc", };

这种方式简单直接，rtc_wake_lock在编译期就分配好内存，name字段硬编码。但缺点明显：无法携带设备指针，难以与struct device关联，在需要区分多个同类设备（如双触摸屏）时失效。

方式二：动态分配（驱动开发推荐）

// drivers/input/touchscreen/ft6x06_ts.c static int ft6x06_ts_probe(struct i2c_client *client, const struct i2c_device_id *id) { struct ft6x06_ts_data *data; int ret; data = devm_kzalloc(&client->dev, sizeof(*data), GFP_KERNEL); if (!data) return -ENOMEM; // 关键：为该具体设备实例分配专属 wakeup_source >__pm_stay_awake(data->ws);

这个函数远非简单地置位一个标志。它执行以下原子操作：

1. 获取ws->lock自旋锁（防止多核并发修改）；
2. 检查ws->active：若已为true，则active_count++并返回；
3. 若为false，则：
   • active_count = 1；
   • event_count++（记录本次唤醒事件）；
   • wakeup_count++（记录本次有效唤醒请求）；
   • last_time = ktime_get()（打时间戳，用于超时判断）；
   • ws->active = true；
4. 解锁并返回。

整个过程在单次 CPU 原子上下文中完成，确保active_count和event_count的严格一致性。这也是为什么不能用普通变量加锁模拟——wakeup_source的状态变更必须与pm_wakeup_pending()的判断逻辑完全同步。

2.3 用户空间接口：/sys/power/wakeup*的四个计数器真相

一旦wakeup_source注册成功，/sys/power/下即出现对应文件：

$ ls /sys/power/wakeup* /sys/power/wakeup_count /sys/power/wakeup_stats $ cat /sys/power/wakeup_count 128

wakeup_count是全局计数器，表示自系统启动以来，所有wakeup_source触发的唤醒事件总数。但它不告诉你“谁触发的”。真正的诊断入口是/sys/power/wakeup_stats—— 它是一个虚拟文件，内容动态生成：

# cat /sys/power/wakeup_stats <name> <active_count> <event_count> <wakeup_count> <expire_count> ft6x06_ts 0 128 128 0 rtc 0 1 1 0 usb-hub 1 3 3 0

这四列含义如下：

• active_count：当前处于active状态的次数（即__pm_stay_awake()被调用但尚未__pm_relax()的净次数）。值为 0 表示该源当前不阻止休眠。
• event_count：该源收到的所有事件总数（包括被忽略的）。
• wakeup_count：该源成功触发唤醒的次数（即event_count中，active为true时发生的部分）。
• expire_count：该源因超时（wakeup_source_set_timeout()设置）而自动relax的次数。

关键经验：当event_count > wakeup_count时，说明有事件在active为false时到达，被内核静默丢弃。此时需检查驱动是否在中断 handler 中过早调用__pm_relax()，或wakeup_source生命周期管理有误。我曾在一个音频 codec 驱动中发现，__pm_relax()被放在了irq_handler末尾，而实际业务逻辑（如 DMA 缓冲区填充）还在进行，导致后续中断到来时ws已 inactive，event_count持续增长但wakeup_count不变，系统休眠后音频流中断。

2.4 销毁：wakeup_source_unregister()的隐式依赖

设备卸载时，必须显式注销：

static int ft6x06_ts_remove(struct i2c_client *client) { struct ft6x06_ts_data *data = i2c_get_clientdata(client); if (data->ws) { wakeup_source_unregister(data->ws); // 关键！ >bool pm_wakeup_pending(void) { // 第一道红线：检查全局 pending 标志 if (events_check_enabled && pm_wakeup_pending_global()) return true; // 第二道红线：遍历所有 wakeup_source，检查其 active 状态 list_for_each_entry(ws, &wakeup_sources, entry) { if (wakeup_source_is_active(ws)) return true; } // 第三道红线：检查 timer_list 中是否有 pending 的 wakeup timer if (timer_pending(&wakeup_timer)) return true; return false; }

第一道红线：pm_wakeup_pending_global()
这是一个快速路径检查。内核维护一个全局原子变量pm_wakeup_pending，任何wakeup_source在__pm_stay_awake()成功后，都会通过atomic_inc(&pm_wakeup_pending)置位。这避免了每次休眠都遍历长链表。但该变量是“乐观估计”，可能因 race condition 产生误报（即active_count已降为 0，但pm_wakeup_pending未及时清零），因此必须配合第二道红线精检。

第二道红线：wakeup_source_is_active(ws)
这才是真正的判决依据。它检查ws->active字段是否为true。但注意，active为true并不绝对意味着“正在阻止休眠”，还需结合ws->has_timeout和ws->timer_expires判断是否已超时。wakeup_source_is_active()内部会：

• 若ws->has_timeout == true，则检查ktime_after(ktime_get(), ws->timer_expires)；
• 若已超时，则自动调用__pm_relax(ws)，ws->active置为false，并atomic_dec(&pm_wakeup_pending)；
• 最终返回ws->active的当前值。

第三道红线：wakeup_timer
这是一个特殊的struct timer_list，用于实现wakeup_source_set_timeout()功能。当某个wakeup_source设置了超时（如触摸屏希望在 30 秒无操作后自动允许休眠），内核会启动此 timer。timer_pending()检查其是否仍在运行。若pending，说明有一个超时事件即将发生，系统必须等待或取消休眠。

实操心得：在调试休眠卡死问题时，pm_wakeup_pending()返回true是最常见现象。此时不要急于看dmesg，而应先执行：

cat /sys/power/wakeup_stats | awk '$2 > 0 {print}'

这条命令会精确列出所有active_count > 0的唤醒源。90% 的问题，答案就在这里。我曾遇到一个案例，wakeup_stats显示usb-hub的active_count=1，但usb-hub驱动代码中并无显式__pm_stay_awake()。最终发现是 USB PHY 驱动在phy_init()中错误地注册了一个永不relax的wakeup_source，导致 hub 子系统永远无法进入低功耗。

3.2wakeup_source的“被动激活”：device_may_wakeup()的隐藏逻辑

除了驱动主动调用__pm_stay_awake()，wakeup_source还有一种“被动激活”模式，由device_may_wakeup()函数触发。该函数在pm_runtime_suspend()和pm_suspend()前被调用，其逻辑是：

bool device_may_wakeup(struct device *dev) { return dev->power.can_wakeup && device_wakeup_enabled(dev); }

• dev->power.can_wakeup：由device_set_wakeup_capable(dev, true)设置，表示该设备硬件上具备唤醒能力（如支持 Wake-on-LAN 的网卡）；
• device_wakeup_enabled(dev)：检查dev->power.wakeup是否非空，且其ws->active为true。

如果两者皆为true，则pm_wakeup_pending()会认为该设备是一个潜在唤醒源，并在休眠前强制检查其wakeup_source状态。这意味着，即使驱动从未调用__pm_stay_awake()，只要can_wakeup和wakeup_enabled同时为true，该设备就拥有了“否决权”。

这个设计的初衷是支持“硬件唤醒”场景：例如，一个 USB 键盘被配置为Wake-on-Keypress，当用户按下任意键，硬件自身产生中断，无需 CPU 运行即可触发唤醒。此时，wakeup_source的作用是告诉内核：“这个设备被允许从硬件层面唤醒我，所以请确保我的唤醒路径（如 USB controller 时钟）在休眠时保持供电”。

注意陷阱：device_set_wakeup_capable()和device_set_wakeup_enable()必须成对使用。前者声明能力，后者启用策略。若只调用前者而未调用后者，则device_wakeup_enabled()返回false，wakeup_source不生效；若只调用后者而未调用前者，则device_may_wakeup()返回false，同样无效。某次调试 Wi-Fi 模块唤醒失败，最终发现wlan0的can_wakeup为false，原因是platform_device的dev->power.can_wakeup未在probe中初始化，需手动调用device_set_wakeup_capable(&pdev->dev, true)。

4. 深度实践：用wakeup_source框架诊断并修复一个真实的“假唤醒”问题

理论终需落地。下面复现一个我在某工业网关项目中解决的真实问题：设备在mem休眠后，约 12 秒左右自动唤醒，dmesg仅显示PM: wake up source: mmc0 triggered，但wakeup_stats中mmc0的active_count始终为 0。这是一个典型的“假唤醒”（False Wakeup）——硬件确实产生了中断，但内核并未将其归因于mmc0的wakeup_source，导致诊断信息缺失。

4.1 现象复现与初步排查

首先确认休眠行为：

# 禁用所有非必要唤醒源 for w in $(ls /sys/devices/*/power/wakeup 2>/dev/null); do echo disabled > $w done # 仅启用 mmc0 echo enabled > /sys/devices/platform/soc/12340000.mmc/power/wakeup # 执行休眠 echo mem > /sys/power/state # 约12秒后自动唤醒

dmesg输出：

[ 123.456789] PM: suspend entry (mem) [ 123.456890] PM: Syncing filesystems ... done. [ 123.456901] Freezing user space processes ... (elapsed 0.001 seconds) done. [ 123.456912] OOM killer disabled. [ 123.456923] Freezing remaining freezable tasks ... (elapsed 0.001 seconds) done. [ 123.456934] PM: suspend devices took 0.012 seconds [ 123.456945] PM: wake up source: mmc0 triggered [ 123.456956] PM: resume devices took 0.008 seconds

但/sys/power/wakeup_stats显示：

mmc0 0 0 0 0

矛盾点清晰：dmesg说mmc0触发了唤醒，但wakeup_stats说它从未活跃过。这说明mmc0的wakeup_source未被正确关联或未被pm_wakeup_pending()捕获。

4.2 源码级追踪：定位wakeup_source的注册时机

查阅drivers/mmc/host/sdhci-of-at91.c（该网关使用的 SDHCI 驱动），发现其sdhci_at91_probe()中：

static int sdhci_at91_probe(struct platform_device *pdev) { struct sdhci_host *host; int ret; host = sdhci_pltfm_init(pdev, &sdhci_at91_pdata, sizeof(*pdata)); if (IS_ERR(host)) return PTR_ERR(host); // 关键：此处注册 wakeup_source host->mmc->parent->power.wakeup = wakeup_source_register( host->mmc->parent, "sdhci-at91"); ... }

host->mmc->parent是platform_device，其dev_name为"12340000.mmc"，与dmesg中的mmc0不符。dmesg中的mmc0是mmc子系统为struct mmc_host分配的名称，而wakeup_source注册在platform_device上。这导致dmesg的打印逻辑（在mmc_power_off()中）使用了mmc_hostname(host)，而wakeup_source的name是"sdhci-at91"，二者不一致，造成认知混淆。

4.3 根本原因：wakeup_source未被mmc子系统正确激活

进一步跟踪mmc_power_off()流程，发现其在关闭 MMC 电源前，会调用：

if (mmc_card_can_wakeup(host->card) && device_may_wakeup(mmc_dev(host))) { __pm_stay_awake(host->parent->power.wakeup); }

host->parent即platform_device，其power.wakeup正是我们注册的wakeup_source。但mmc_card_can_wakeup()返回false，因为host->card->pm_flags未设置MMC_PM_KEEP_POWER。而device_may_wakeup(mmc_dev(host))也返回false，因为mmc_dev(host)（即struct device对应mmc0）的power.wakeup为NULL——mmc子系统并未为mmc0设备注册自己的wakeup_source！

mmc子系统默认只在mmc_add_host()中为host->parent（platform device）注册wakeup_source，而mmc0作为逻辑设备，其wakeup_source需要驱动显式管理。但该驱动未做此操作。

4.4 修复方案：双wakeup_source策略与超时控制

解决方案分两步：

步骤一：为mmc0逻辑设备注册专属wakeup_source
在sdhci_at91_probe()中，mmc_add_host()后添加：

// 为 mmc0 设备注册 wakeup_source host->mmc->parent->power.wakeup = wakeup_source_register( &host->mmc->class_dev, "mmc0"); // class_dev 即 mmc0 设备 if (!host->mmc->parent->power.wakeup) { dev_err(mmc_dev(host), "Failed to register mmc0 wakeup source\n"); }

步骤二：在中断 handler 中精准控制active状态
sdhci_at91的中断 handler (sdhci_at91_irq) 中，检测到卡插入/弹出事件时：

static irqreturn_t sdhci_at91_irq(int irq, void *dev_id) { struct sdhci_host *host = dev_id; u32 intmask; intmask = sdhci_readl(host, SDHCI_INT_STATUS); if (!intmask) return IRQ_NONE; if (intmask & SDHCI_INT_CARD_INSERT) { __pm_stay_awake(host->mmc->parent->power.wakeup); // 启动 30 秒超时，避免长期阻塞休眠 wakeup_source_set_timeout(host->mmc->parent->power.wakeup, 30 * HZ); } else if (intmask & SDHCI_INT_CARD_REMOVE) { __pm_relax(host->mmc->parent->power.wakeup); } sdhci_writel(host, intmask, SDHCI_INT_STATUS); return IRQ_HANDLED; }

验证效果：
修复后再次休眠：

# 查看 stats cat /sys/power/wakeup_stats | grep mmc0 mmc0 0 1 1 0

event_count和wakeup_count均为 1，且active_count=0，说明事件被正确捕获并处理。dmesg中的mmc0与wakeup_stats中的mmc0完全对应，诊断闭环。

关键经验总结：

1. 名称一致性是诊断前提：dmesg打印的name必须与wakeup_source_register()的第一个参数严格一致，否则wakeup_stats无法匹配。
2. 逻辑设备与物理设备分离：mmc0是逻辑设备，12340000.mmc是物理设备，它们的wakeup_source应独立管理，各自承担不同职责（逻辑设备响应业务事件，物理设备响应硬件能力）。
3. 超时是安全底线：任何__pm_stay_awake()都应配套wakeup_source_set_timeout()，避免因驱动 bug 导致系统永久无法休眠。12 秒的“假唤醒”间隔，正是该网关mmc子系统默认的CARD_INSERT超时值，暴露了未设超时的风险。

这个案例印证了wakeup source框架的核心价值：它不创造唤醒能力，而是将分散的硬件事件、驱动逻辑、内核策略，统一到一个可编程、可审计、可干预的状态模型中。掌握它，就掌握了 Linux 功耗管理的脉搏。