Wakeup Source 为系统组件提供了投票机制，以便低功耗子系统判断当前是否可以进入休眠。
Wakeup Source(后简称：WS) 模块可与内核中的其他模块或者上层服务交互，并最终体现在对睡眠锁的控制上。
注：本文是基于内核kernel-5.10展开，分析基于32位系统，若是64位系统，则combined_event_count会被拆分成2个32位分别来纪录唤醒事件的总数和正在处理中的唤醒事件的总数
1. 模块功能说明
WS的处理逻辑基本上是围绕 combined_event_count 变量展开的，这个变量高16位记录系统已处理的所有的唤醒事件总数，低16位记录在处理中的唤醒事件总数。每次持锁时，处理中的唤醒事件记录（低16位）会加1；每次释放锁时，处理中的唤醒事件记录（低16位）会减1，同时已处理的唤醒事件记录（高16位）会加1。
对于每次系统能否进入休眠，通过判断是否有正在处理中的唤醒事件（低16位）来决定。该模块实现主要的功能：
- 持锁和释放锁
- 注册和注销锁
- 查询激活状态锁个数
2. 主要数据结构
2.1 wakeup_source 结构体
@include/linux/pm_wakeup.h
/**
* struct wakeup_source - Representation of wakeup sources
*
* @name: Name of the wakeup source
* @id: Wakeup source id
* @entry: Wakeup source list entry
* @lock: Wakeup source lock
* @wakeirq: Optional device specific wakeirq
* @timer: Wakeup timer list
* @timer_expires: Wakeup timer expiration
* @total_time: Total time this wakeup source has been active.
* @max_time: Maximum time this wakeup source has been continuously active.
* @last_time: Monotonic clock when the wakeup source's was touched last time.
* @prevent_sleep_time: Total time this source has been preventing autosleep.
* @event_count: Number of signaled wakeup events.
* @active_count: Number of times the wakeup source was activated.
* @relax_count: Number of times the wakeup source was deactivated.
* @expire_count: Number of times the wakeup source's timeout has expired.
* @wakeup_count: Number of times the wakeup source might abort suspend.
* @dev: Struct device for sysfs statistics about the wakeup source.
* @active: Status of the wakeup source.
* @autosleep_enabled: Autosleep is active, so update @prevent_sleep_time.
*/
struct wakeup_source {
const char *name; //ws 名称
int id; //WS系统给本ws分配的ID
struct list_head entry; //用于把本ws节点维护到WS系统的全局链表中
spinlock_t lock;
struct wake_irq *wakeirq; //与本ws节点绑定的唤醒中断相关的结构体，用户可自行把指定中断与ws绑定
struct timer_list timer; //超时锁使用，如定义本ws为超时锁，指定在一定时间后释放锁
unsigned long timer_expires;//超时锁超时时间
ktime_t total_time; //本ws激活的总时长
ktime_t max_time; //在ws激活历史中，最长一次的激活时间
ktime_t last_time; //最后一次访问本ws的时间
ktime_t start_prevent_time; //本ws最近一次阻止autosleep进入休眠的时间戳
ktime_t prevent_sleep_time; //因本ws导致的阻止autosleep进入休眠的总时间
unsigned long event_count; //事件次数，本ws被持锁（不考虑是否已持锁），则加1并作记录
unsigned long active_count;//激活次数，本ws仅在首次持锁（激活）时加1（已持锁则不加1，锁释放后再次持锁则加1）
unsigned long relax_count; //释放次数，与 active_count 相对
unsigned long expire_count; //超时锁超时次数
unsigned long wakeup_count; //与event_count一样，但受events_check_enabled 使能标记控制
struct device *dev; //与本ws绑定的设备
bool active:1; //标记是否处于激活状态
bool autosleep_enabled:1; //标记是否使能autosleep
};
2.2 核心变量
2.2.1 combined_event_count 变量
static atomic_t combined_event_count = ATOMIC_INIT(0);
该变量是1个组合计数变量，高16位记录唤醒事件的总数，低16位记录正在处理中的唤醒事件的总数。系统根据低16位（正在处理中的唤醒事件）来判断是否可以进入休眠。
2.2.2 wakeup_sources 变量
static LIST_HEAD(wakeup_sources);
所有通过调用 wakeup_source_register()注册的ws全部维护在此链表中，以便系统进行维护。
2.3 主要函数分析
Wakeup Source 对外提供的主要接口：
wakeup_source_register()与wakeup_source_unregister()分别用于注册与注销一个ws__pm_stay_awake()与__pm_relax()，针对ws类型对象提供持锁与释放锁接口- (
device_set_wakeup_capable()+device_wakeup_enable()/device_wakeup_disable()/device_set_wakeup_enable()）/device_init_wakeup()给设备配置是否支持唤醒以及注册/注销ws的接口 pm_stay_awake()与pm_relax()，针对device类型对象提供持锁与释放锁接口
2.3.1 wakeup_source_register()/wakeup_source_unregister() 接口
wakeup_source_register()函数为dev设备创建ws，并将创建的ws添加到全局链表wakeup_sources中，方便后续维护,并在sysfs系统中创建节点/sys/class/wakeup/wakeup,便于获取ws相关信息。
@drivers/base/power/wakeup.c
/**
* wakeup_source_register - Create wakeup source and add it to the list.
* @dev: Device this wakeup source is associated with (or NULL if virtual).
* @name: Name of the wakeup source to register.
*/
struct wakeup_source *wakeup_source_register(struct device *dev,
const char *name)
{
struct wakeup_source *ws;
int ret;
ws = wakeup_source_create(name); //分配内存，设置ws的name和id
if (ws) {
if (!dev || device_is_registered(dev)) {
//在sysfs下为该ws创建dev, /sys/class/wakeup/wakeup/
ret = wakeup_source_sysfs_add(dev, ws);
if (ret) {
wakeup_source_free(ws);
return NULL;
}
}
wakeup_source_add(ws); //设置超时回调函数并将ws添加到wakeup_sources链表
}
return ws;
}
@drivers/base/power/wakeup_stats.c
static struct device *wakeup_source_device_create(struct device *parent,
struct wakeup_source *ws)
{
struct device *dev = NULL;
int retval = -ENODEV;
dev = kzalloc(sizeof(*dev), GFP_KERNEL);
device_initialize(dev);
dev->devt = MKDEV(0, 0);
dev->class = wakeup_class; //ws dev挂于wakeup类
dev->parent = parent;
dev->groups = wakeup_source_groups;
dev->release = device_create_release;
dev_set_drvdata(dev, ws);
device_set_pm_not_required(dev);
retval = kobject_set_name(&dev->kobj, "wakeup%d", ws->id);
retval = device_add(dev);
return dev;
}
//ws dev存在的属性： /sys/class/wakeup/wakeup/
static struct attribute *wakeup_source_attrs[] = {
&dev_attr_name.attr, //RO, ws 名称
&dev_attr_active_count.attr, //RO, 激活次数
&dev_attr_event_count.attr, //RO, 持锁次数
&dev_attr_wakeup_count.attr, //RO, 同event_count，但受events_check_enabled使能标记
&dev_attr_expire_count.attr, //RO, 超时次数
&dev_attr_active_time_ms.attr, //RO, 如当前处于激活状态，显示已激活时间
&dev_attr_total_time_ms.attr, //RO, 总激活时间
&dev_attr_max_time_ms.attr, //RO, 最长激活时间
&dev_attr_last_change_ms.attr, //RO, 最近一次激活时的时间戳
&dev_attr_prevent_suspend_time_ms.attr, //RO, 阻止autosleep进入休眠的总时间
NULL,
};
ATTRIBUTE_GROUPS(wakeup_source);
wakeup_source_unregister() 接口删除了已注册的ws，移除了sysfs系统中的节点并释放占用的系统资源。
@drivers/base/power/wakeup.c
void wakeup_source_unregister(struct wakeup_source *ws)
{
if (ws) {
wakeup_source_remove(ws); //从wakeup_sources队列移除并删除其定时器
if (ws->dev)
wakeup_source_sysfs_remove(ws);//移除该ws在sysfs系统中的信息
wakeup_source_destroy(ws);
}
}
void wakeup_source_destroy(struct wakeup_source *ws)
{
__pm_relax(ws); //释放该ws
wakeup_source_record(ws);//如果该ws被持锁过，则将其记录叠加到deleted_ws这个ws上
wakeup_source_free(ws);//释放内存资源
}
static struct wakeup_source deleted_ws = {//用于保存已移除ws的记录
.name = "deleted",
.lock = __SPIN_LOCK_UNLOCKED(deleted_ws.lock),
};
static void wakeup_source_record(struct wakeup_source *ws)
{
unsigned long flags;
spin_lock_irqsave(&deleted_ws.lock, flags);
if (ws->event_count) {//如果该ws被持锁过，则将记录都叠加到deleted_ws这个ws上
deleted_ws.total_time =
ktime_add(deleted_ws.total_time, ws->total_time);
deleted_ws.prevent_sleep_time =
ktime_add(deleted_ws.prevent_sleep_time,
ws->prevent_sleep_time);
deleted_ws.max_time =
ktime_compare(deleted_ws.max_time, ws->max_time) > 0 ?
deleted_ws.max_time : ws->max_time;
deleted_ws.event_count += ws->event_count;
deleted_ws.active_count += ws->active_count;
deleted_ws.relax_count += ws->relax_count;
deleted_ws.expire_count += ws->expire_count;
deleted_ws.wakeup_count += ws->wakeup_count;
}
spin_unlock_irqrestore(&deleted_ws.lock, flags);
}
2.3.2 __pm_stay_awake()/__pm_relax() 接口
__pm_stay_awake() 用于上锁ws来阻止系统休眠。
@drivers/base/power/wakeup.c
void __pm_stay_awake(struct wakeup_source *ws)
{
unsigned long flags;
if (!ws)
return;
spin_lock_irqsave(&ws->lock, flags);
wakeup_source_report_event(ws, false);//纪录该ws的信息
del_timer(&ws->timer);
ws->timer_expires = 0;
spin_unlock_irqrestore(&ws->lock, flags);
}
static void wakeup_source_report_event(struct wakeup_source *ws, bool hard)
{
ws->event_count++; //持锁次数加1
/* This is racy, but the counter is approximate anyway. */
if (events_check_enabled)
ws->wakeup_count++;
if (!ws->active) //ws还未激活情况下，激活ws
wakeup_source_activate(ws);
if (hard) //如果需要，可以强制阻止系统休眠
pm_system_wakeup();
}
static void wakeup_source_activate(struct wakeup_source *ws)
{
unsigned int cec;
if (WARN_ONCE(wakeup_source_not_registered(ws),
"unregistered wakeup source\n"))
return;
ws->active = true;
ws->active_count++; //激活次数加1
ws->last_time = ktime_get(); //纪录最后操作该锁的时间戳
if (ws->autosleep_enabled) //如果autosleep已使能，则记录该ws阻止休眠时时间戳
ws->start_prevent_time = ws->last_time;
/* Increment the counter of events in progress. */
cec = atomic_inc_return(&combined_event_count); //combined_event_count低16位加1
trace_wakeup_source_activate(ws->name, cec);
}
__pm_relax() 用于将持有的睡眠锁释放掉，并在检测到combined_event_count低16位为0（表示当前没有在处理的ws）时会触发wakeup_count_wait_queue等待队列运行，如果工作队列满足睡眠条件，则继续进入睡眠流程，该机制是通过pm_get_wakeup_count()接口与autosleep配合使用的
@drivers/base/power/wakeup.c
void __pm_relax(struct wakeup_source *ws)
{
unsigned long flags;
if (!ws)
return;
spin_lock_irqsave(&ws->lock, flags);
if (ws->active) //如果ws已激活，则去激活该ws
wakeup_source_deactivate(ws);
spin_unlock_irqrestore(&ws->lock, flags);
}
static void wakeup_source_deactivate(struct wakeup_source *ws)
{
unsigned int cnt, inpr, cec;
ktime_t duration;
ktime_t now;
ws->relax_count++; //释放次数加1
/*
* __pm_relax() may be called directly or from a timer function.
* If it is called directly right after the timer function has been
* started, but before the timer function calls __pm_relax(), it is
* possible that __pm_stay_awake() will be called in the meantime and
* will set ws->active. Then, ws->active may be cleared immediately
* by the __pm_relax() called from the timer function, but in such a
* case ws->relax_count will be different from ws->active_count.
*/
if (ws->relax_count != ws->active_count) {
ws->relax_count--; //未解决定时锁与主动调用释放锁并发操作时出现冲突做的处理
return;
}
ws->active = false;
now = ktime_get();
duration = ktime_sub(now, ws->last_time);
ws->total_time = ktime_add(ws->total_time, duration); //叠加总的持锁时间
if (ktime_to_ns(duration) > ktime_to_ns(ws->max_time))
ws->max_time = duration; //更新最长持锁时间
ws->last_time = now; //纪录最后操作该锁的时间戳
del_timer(&ws->timer);
ws->timer_expires = 0;
if (ws->autosleep_enabled)//如果autosleep已使能，更新该ws阻止系统休眠的时长
update_prevent_sleep_time(ws, now);
/*
* Increment the counter of registered wakeup events and decrement the
* couter of wakeup events in progress simultaneously.
*/
cec = atomic_add_return(MAX_IN_PROGRESS, &combined_event_count);//combined_event_count高16位加1
trace_wakeup_source_deactivate(ws->name, cec);
split_counters(&cnt, &inpr);//拆分出combined_event_count高16位和低16位
if (!inpr && waitqueue_active(&wakeup_count_wait_queue))//如果该ws已经无正在处理的唤醒事件，则通知PM core
wake_up(&wakeup_count_wait_queue);
}
注：同个ws连续使用多次__pm_stay_awake()或__pm_relax()只会增加/减少一次combined_event_count低16位（表示正在处理中的事件总数），只要__pm_relax()被调用就会释放锁。
2.3.3 pm_get_wakeup_count()接口
该函数主要是获取已处理的wakeup event数量（combined_event_count高16位）与正在处理的wakeup event数量是否为0（combined_event_count低16位）。
bool pm_get_wakeup_count(unsigned int *count, bool block)
{
unsigned int cnt, inpr;
if (block) {
DEFINE_WAIT(wait); //定义名为wait的等待队列入口
for (;;) {
prepare_to_wait(&wakeup_count_wait_queue, &wait,
TASK_INTERRUPTIBLE); //准备 wakeup_count_wait_queue 等待队列
split_counters(&cnt, &inpr);
if (inpr == 0 || signal_pending(current))
break;
pm_print_active_wakeup_sources();
schedule(); //调度到其他线程
}
//__pm_relax() 里wake_up(&wakeup_count_wait_queue);会触发调度到此处
finish_wait(&wakeup_count_wait_queue, &wait);
}
split_counters(&cnt, &inpr);
*count = cnt;
return !inpr; //返回0表示有待处理事件，返回1表示无待处理事件
}
1.如果入参
block为0，则仅仅对入参count赋值当前已处理的wakeup event总数，并返回当前是否有待处理wakeup event(返回0表示有待处理事件，返回1表示无待处理事件)。
2.如果入参block为1，则需要一直等到待处理事件为0（combined_event_count低16位为0）或者当前挂起进程有事件需要处理时才退出。该处理分支的wait等待队列会在__pm_relax()满足睡眠条件时触发调度运行，即finish_wait().
2.3.4 pm_wakeup_pending() 接口
该函数的功能是确认当前是否满足休眠条件，返回true表示可以休眠，false表示不可休眠。
bool pm_wakeup_pending(void)
{
unsigned long flags;
bool ret = false;
raw_spin_lock_irqsave(&events_lock, flags);
if (events_check_enabled) {
unsigned int cnt, inpr;
split_counters(&cnt, &inpr);
ret = (cnt != saved_count || inpr > 0);
events_check_enabled = !ret;
}
raw_spin_unlock_irqrestore(&events_lock, flags);
if (ret) {
pm_pr_dbg("Wakeup pending, aborting suspend\n");
pm_print_active_wakeup_sources();
}
return ret || atomic_read(&pm_abort_suspend) > 0;
}
判断允许休眠的依据：
1.已处理的wakeup event数量与已记录的数量（saved_count）一致，且
2.待处理的wakeup event数量为0，且
3.原子量pm_abort_suspend为0（该值大于0表示睡眠流程中出现了唤醒中断或事件，唤醒事件通过调用pm_system_wakeup()来给pm_abort_suspend加1操作。）
2.3.5 device与wakeup_source关联处理的接口
kernel抽象出的device数据结构存放着power manager相关的信息，其中就存放着wakeup source数据结构，如下：
//代码格式错误，仅为呈现数据结构，请忽略格式。
struct device {
// @power: For device power management.
struct dev_pm_info power {
unsigned int can_wakeup:1; //需置1才允许使用wakeup source
struct wakeup_source *wakeup;
};
};
wakeup source框架中为此提供了大量相关的接口直接操作某个dev的ws，接口如下：
-
int device_wakeup_enable(struct device *dev)：注册设备的wakeup source
1.以dev名注册个ws，并指定该ws dev的parent为当前dev
2.将注册的ws关联到dev->power.wakeup，如果存在wakeirq，也会一起绑定到该ws上。 -
int device_wakeup_disable(struct device *dev)：注销设备的wakeup source
1.取消已注册的ws与dev->power.wakeup的关联
2.注销ws -
void device_set_wakeup_capable(struct device *dev, bool capable)：设置设备是否支持wakeup source
1.设置dev->power.can_wakeup
2.如果设备支持wakeup，则为其创建属性文件（位于/sys/devices//power/下）；如果设备不支持wakeup，则不会移除相关属性文件。
static struct attribute *wakeup_attrs[] = {
#ifdef CONFIG_PM_SLEEP
&dev_attr_wakeup.attr, //RW，可写入enabled/disabled动态配置是否支持wakeup
&dev_attr_wakeup_count.attr, //RO, 读取该dev ws的wakeup_count
&dev_attr_wakeup_active_count.attr, //RO, 读取该dev ws的active_count
&dev_attr_wakeup_abort_count.attr, //RO, 读取该dev ws的wakeup_count
&dev_attr_wakeup_expire_count.attr, //RO, 读取该dev ws的expire_count
&dev_attr_wakeup_active.attr, //RO, 读取该dev ws的active状态
&dev_attr_wakeup_total_time_ms.attr, //RO, 读取该dev ws的total_time
&dev_attr_wakeup_max_time_ms.attr, //RO, 读取该dev ws的max_time
&dev_attr_wakeup_last_time_ms.attr, //RO, 读取该dev ws的last_time
#ifdef CONFIG_PM_AUTOSLEEP
&dev_attr_wakeup_prevent_sleep_time_ms.attr, //RO, 读取该dev ws的prevent_sleep_time
#endif
#endif
NULL,
};
int device_init_wakeup(struct device *dev, bool enable)：一步到位直接配置是否支持wakeup并且注册/注销ws
int device_init_wakeup(struct device *dev, bool enable)
{
int ret = 0;
if (enable) {
device_set_wakeup_capable(dev, true);
ret = device_wakeup_enable(dev);
} else {
device_wakeup_disable(dev);
device_set_wakeup_capable(dev, false);
}
return ret;
}
int device_set_wakeup_enable(struct device *dev, bool enable)：设置设备是否能通过ws唤醒系统，注册/注销ws
int device_set_wakeup_enable(struct device *dev, bool enable)
{
return enable ? device_wakeup_enable(dev) : device_wakeup_disable(dev);
}
-
void pm_stay_awake(struct device *dev)：持锁设备的ws，不让设备休眠，实际是调用__pm_stay_awake(dev->power.wakeup);实现 -
void pm_relax(struct device *dev)：释放设备的ws，允许设备休眠，实际是调用__pm_relax(dev->power.wakeup);实现
总结：
1.device_set_wakeup_capable()用于设置是否支持wakeup，并提供属性节点，便于调试
2.device_wakeup_enable()/device_wakeup_disable()/device_set_wakeup_enable()主要是注册/注销设备ws，需在device_set_wakeup_capable()为enabled的前提下才能使用。
3.device_init_wakeup()通常使用在默认支持wakeup的device上，在probe/remove时分别enable/disable。
4.pm_stay_awake()/pm_relax()主要是持有/释放ws锁，阻止/允许系统休眠
3. 主要工作时序
1）device或者其他需要上锁的模块调用device_init_wakeup()/wakeup_source_register()来注册ws
2）在处理业务时，为了防止系统进入睡眠流程，设备或模块可以通过调用pm_stay_awake()/__pm_stay_awake()来持锁ws阻止休眠
3）当业务处理完成后，设备或模块可以调用pm_relax()/__pm_relax()来释放ws允许系统休眠
4）在__pm_relax()释放锁时，会检查当前是否有正在处理的持锁事件，如果没有，则触发wakeup_count_wait_queue
5)wakeup_count_wait_queue所在的pm_get_wakeup_count()接口会返回到autosleep的工作队列中继续走休眠流程
4. 调试节点
-
获取所有wakeup source信息节点:
cat /d/wakeup_sources
列出所有wakeup_source当前的信息，包括：name，active_count，event_count，wakeup_count，expire_count，active_since，total_time，max_time，last_change，prevent_suspend_time。
注：代码实现在@drivers/base/power/wakeup.c
-
从wakeup类下获取某个ws的信息:
/sys/class/wakeup/wakeup/
wakeup类下汇总了所有已注册的ws，该节点下存在属性：name, active_count, event_count, wakeup_count，expire_count, active_time_ms, total_time_ms, max_time_ms, last_change_ms, prevent_suspend_time_ms。
注：代码实现在@drivers/base/power/wakeup_stats.c
-
从device节点下获取该设备的ws信息：
/sys/devices//power/
该节点存在如下属性信息：wakeup（是否支持唤醒），wakeup_count， wakeup_active_count, wakeup_abort_count, wakeup_expire_count, wakeup_active, wakeup_total_time_ms, max_time_ms, last_time_ms, prevent_sleep_time_ms。
注：代码实现在@drivers/base/power/sysfs.c
