Linux电源管理(7)_Wakeup events framework

1. 前言

本文继续“Linux电源管理(6)_Generic PM之Suspend功能”中有关suspend同步以及PM wakeup的话题。这个话题，是近几年Linux kernel最具争议的话题之一，在国外Linux开发论坛，经常可以看到围绕该话题的辩论。辩论的时间跨度和空间跨度可以持续很长，且无法达成一致。

wakeup events framework是这个话题的一个临时性的解决方案，包括wake lock、wakeup count、autosleep等机制。它们就是本文的话题。

2. wakeup events framework要解决的问题

我们知道，系统处于suspend状态，可通过wakeup events唤醒。具体的wakeup events可以是按键按下，可以是充电器插入，等等。但是，如果在suspend的过程中，产生了wakeup events，怎么办？答案很肯定，"wakeup"系统。由于此时系统没有真正suspend，所以这的"wakeup"是个假动作，实际上只是终止suspend。

但由于系统在suspend的过程中，会进行process freeze、 device suspend等操作，而这些操作可能导致内核或用户空间程序不能及时获取wakeup events，从而使系统不能正确wakeup，这就是wakeup events framework要解决的问题：system suspend和system wakeup events之间的同步问题。

3. wakeup events framework的功能总结

仔细推敲一下，上面所讲的同步问题包括两种情况：

情况1：内核空间的同步

wakeup events产生后，通常是以中断的形式通知device driver。driver会处理events，处理的过程中，系统不能suspend。

注1：同步问题只存在于中断开启的情况，因为若中断关闭，就不会产生wakeup events，也就不存在同步的概念。

情况2：用户空间的同步

一般情况下，driver对wakeup events处理后，会交给用户空间程序继续处理，处理的过程，也不允许suspend。这又可以分为两种情况：

1）进行后续处理的用户进程，根本没有机会被调度，即该wakeup events无法上报到用户空间。

2）进行后续处理的用户进程被调度，处理的过程中（以及处理结束后，决定终止suspend操作），系统不能suspend。

因此，wakeup events framework就包括3大功能：

解决内核空间同步问题（framework的核心功能）；

解决用户空间同步问题的情景1（wakeup count功能）；

解决用户空间同步问题的情景2（wake lock功能） 。

注2：

用户空间同步的两种情况，咋一看，非常合乎情理，kernel你得好好处理！但事实上，该同步问题牵涉到了另外一个比较有争议的话题：日常的电源管理机制。是否要基于suspend实现？系统何时进入低功耗状态，应该由谁决定？kernel还是用户空间程序？

这最终会决定是否存在用空间同步问题。但是，在当前这个时间点，对这个话题，Linux kernel developers和Android developers持相反的观点。这也造成了wakeup events framework在实现上的撕裂。Kernel的本意是不愿处理用户空间同步问题的，但为了兼容Android平台，不得不增加相关的功能（Wakeup count和Wake lock）。

蜗蜗会在下一篇文章和大家探讨该话题，本文就先focus在wakeup events framework上。

4. wakeup events framework architecture

下面图片描述了wakeup events framework的architecture：

图片中红色边框的block是wakeup events相关的block：

1）wakeup events framework core，在drivers/base/power/wakeup.c中实现，提供了wakeup events framework的核心功能，包括：

抽象wakeup source和wakeup event的概念；

向各个device driver提供wakeup source的注册、使能等接口；

向各个device driver提供wakeup event的上报、停止等接口；

向上层的PM core（包括wakeup count、auto sleep、suspend、hibernate等模块）提供wakeup event的查询接口，以判断是否可以suspend、是否需要终止正在进行的suspend。

2）wakeup events framework sysfs，将设备的wakeup信息，以sysfs的形式提供到用户空间，供用户空间程序查询、配置。在drivers/base/power/sysfs.c中实现

3）wake lock/unlock，为了兼容Android旧的wakeup lock机制而留下的一个后门，扩展wakeup events framework的功能，允许用户空间程序报告/停止wakeup events。换句话说，该后门允许用户空间的任一程序决定系统是否可以休眠。

4）wakeup count，基于wakeup events framework，解决用户空间同步的问题。

5）auto sleep，允许系统在没有活动时（即一段时间内，没有产生wakeup event），自动休眠。

注3：在Linux kernel看来，power是系统的核心资源，不应开放给用户程序随意访问（wake lock机制违背了这个原则）。而在运行时的电源管理过程中，系统何时进入低功耗状态，也不是用户空间程序能决定的（auto sleep中枪了）。因此，kernel对上述功能的支持，非常的不乐意，我们可以从kernel/power/main.c中sysfs attribute文件窥见一斑（只要定义了PM_SLEEP，就一定支持wakeup count功能，但autosleep和wake lock功能，由另外的宏定义控制）：

static struct attribute * g[] = {
	&state_attr.attr,
#ifdef CONFIG_PM_TRACE
	&pm_trace_attr.attr,
	&pm_trace_dev_match_attr.attr,
#endif
#ifdef CONFIG_PM_SLEEP
	&pm_async_attr.attr,
	&wakeup_count_attr.attr,
#ifdef CONFIG_SUSPEND
	&mem_sleep_attr.attr,
	&sync_on_suspend_attr.attr,
#endif
#ifdef CONFIG_PM_AUTOSLEEP
	&autosleep_attr.attr,
#endif
#ifdef CONFIG_PM_WAKELOCKS
	&wake_lock_attr.attr,
	&wake_unlock_attr.attr,
#endif
#ifdef CONFIG_PM_SLEEP_DEBUG
	&pm_test_attr.attr,
	&pm_print_times_attr.attr,
	&pm_wakeup_irq_attr.attr,
	&pm_debug_messages_attr.attr,
#endif
#endif
#ifdef CONFIG_FREEZER
	&pm_freeze_timeout_attr.attr,
#endif
	NULL,
};

5. 代码分析

5.1 wakeup source和wakeup event

在kernel中，可以唤醒系统的只有设备(struct device)，但并不是每个设备都具备唤醒功能，那些具有唤醒功能的设备称作wakeup source。是时候回到这篇文章中了（Linux设备模型(5)_device和device driver），在那里，介绍struct device结构时，涉及到一个struct dev_pm_info类型的power变量，蜗蜗说留待后面的专题讲解。我们再回忆一下struct device结构：

   1: struct device {
   2:         ...
   3:         struct dev_pm_info      power;
   4:         ...
   5: };

该结构中有一个power变量，保存了和wakeup event相关的信息，让我们接着看一下struct dev_pm_info数据结构（只保留和本文有关的内容）：

   1: struct dev_pm_info {
   2:         ...
   3:         unsigned int            can_wakeup:1;
   4:         ...
   5: #ifdef CONFIG_PM_SLEEP
   6:         ...
   7:         struct wakeup_source    *wakeup;
   8:         ...
   9: #else
  10:         unsigned int            should_wakeup:1;
  11: #endif
  12: };

can_wakeup，标识本设备是否具有唤醒能力。只有具备唤醒能力的设备，才会在sysfs中有一个power目录，用于提供所有的wakeup信息，这些信息是以struct wakeup_source的形式组织起来的。也就是上面wakeup指针。具体有哪些信息呢？让我们看看struct wakeup_source的定义。

/*include/linux/pm_wakeup.h*/
struct wakeup_source {
	const char 		*name;
	int			id;
	struct list_head	entry;
	spinlock_t		lock;
	struct wake_irq		*wakeirq;
	struct timer_list	timer;
	unsigned long		timer_expires;
	ktime_t total_time;
	ktime_t max_time;
	ktime_t last_time;
	ktime_t start_prevent_time;
	ktime_t prevent_sleep_time;
	unsigned long		event_count;
	unsigned long		active_count;
	unsigned long		relax_count;
	unsigned long		expire_count;
	unsigned long		wakeup_count;
	struct device		*dev;
	bool			active:1;
	bool			autosleep_enabled:1;
};

因此，一个wakeup source代表了一个具有唤醒能力的设备，也称该设备为一个wakeup source。该结构中各个字段的意义如下：

name，该wakeup source的名称，一般为对应的device name（有个例外，就是wakelock）；

entery，用于将所有的wakeup source挂在一个链表中；

timer、timer_expires，一个wakeup source产生了wakeup event，称作wakeup source activate，wakeup event处理完毕后（不再需要系统为此保持active），称作deactivate。activate和deactivate的操作可以由driver亲自设置，也可以在activate时，指定一个timeout时间，时间到达后，由wakeup events framework自动将其设置为deactivate状态。这里的timer以及expires时间，就是用来实现该功能；

total_time，该wakeup source处于activate状态的总时间（可以指示该wakeup source对应的设备的繁忙程度、耗电等级）；

max_time，该wakeup source持续处于activate状态的最大时间（越长越不合理）；

last_time，该wakeup source上次active的开始时间；

start_prevent_time，该wakeup source开始阻止系统自动睡眠（auto sleep）的时间点；

prevent_sleep_time，该wakeup source阻止系统自动睡眠的总时间；

event_count，wakeup source上报的event个数；

active_count，wakeup source activate的次数；

relax_count， wakeup source deactivate的次数；

expire_count，wakeup source timeout到达的次数；

wakeup_count，wakeup source终止suspend过程的次数；

active，wakeup source的activate状态；

autosleep_enabled，记录系统auto sleep的使能状态（每个wakeup source都重复记录这样一个状态，这种设计真实不敢恭维！）。

wakeup source代表一个具有唤醒能力的设备，该设备产生的可以唤醒系统的事件，就称作wakeup event。当wakeup source产生wakeup event时，需要将wakeup source切换为activate状态；当wakeup event处理完毕后，要切换为deactivate状态。因此，我们再来理解一下几个wakeup source比较混淆的变量：event_count, active_count和wakeup_count：

event_count，wakeup source产生的wakeup event的个数；

active_count，产生wakeup event时，wakeup source需要切换到activate状态。但并不是每次都要切换，因此有可能已经处于activate状态了。因此active_count可能小于event_count，换句话说，很有可能在前一个wakeup event没被处理完时，又产生了一个。这从一定程度上反映了wakeup source所代表的设备的繁忙程度；

wakeup_count，wakeup source在suspend过程中产生wakeup event的话，就会终止suspend过程，该变量记录了wakeup source终止suspend过程的次数（如果发现系统总是suspend失败，检查一下各个wakeup source的该变量，就可以知道问题出在谁身上了）。

5.2 几个counters

在drivers/base/power/wakeup.c中，有几个比较重要的计数器，是wakeup events framework的实现基础，包括：

1）registered wakeup events和saved_count

记录了系统运行以来产生的所有wakeup event的个数，在wakeup source上报event时加1。

这个counter对解决用户空间同步问题很有帮助，因为一般情况下（无论是用户程序主动suspend，还是auto sleep），由专门的进程（或线程）触发suspend。当这个进程判断系统满足suspend条件，决定suspend时，会记录一个counter值(saved_count)。在后面suspend的过程中，如果系统发现counter有变，则说明系统产生了新的wakeup event，这样就可以终止suspend。

该功能即是wakeup count功能，会在后面更详细的说明。

2）wakeup events in progress

记录正在处理的event个数。

当wakeup source产生wakeup event时，会通过wakeup events framework提供的接口将wakeup source设置为activate状态。当该event处理结束后，设置为deactivate状态。activate到deactivate的区间，表示该event正在被处理。

当系统中有任何正在被处理的wakeup event时，则不允许suspend。如果suspend正在进行，则要终止。

思考一个问题：registered wakeup events在什么时候增加？答案是在wakeup events in progress减小时，因为已经完整的处理完一个event了，可以记录在案了。

基于这种特性，kernel将它俩合并成一个32位的整型数，以原子操作的形式，一起更新。这种设计巧妙的让人叫绝，值得我们学习。具体如下：

/*
 * Combined counters of registered wakeup events and wakeup events in progress.
 * They need to be modified together atomically, so it's better to use one
 * atomic variable to hold them both.
 */
static atomic_t combined_event_count = ATOMIC_INIT(0);

#define IN_PROGRESS_BITS	(sizeof(int) * 4)
#define MAX_IN_PROGRESS		((1 << IN_PROGRESS_BITS) - 1)

static void split_counters(unsigned int *cnt, unsigned int *inpr)
{
	unsigned int comb = atomic_read(&combined_event_count);

	*cnt = (comb >> IN_PROGRESS_BITS);
	*inpr = comb & MAX_IN_PROGRESS;
}

定义和读取。

  1: cec = atomic_add_return(MAX_IN_PROGRESS, &combined_event_count);

   1: cec = atomic_inc_return(&combined_event_count);

wakeup events in progress加1。

5.3 wakeup events framework的核心功能

wakeup events framework的核心功能体现在它向底层的设备驱动所提供的用于上报wakeup event的接口，这些接口根据操作对象可分为两类，具体如下。

类型一（操作对象为wakeup source，编写设备驱动时，一般不会直接使用）：

   1: /* include/linux/pm_wakeup.h */
   2: extern void __pm_stay_awake(struct wakeup_source *ws);
   3: extern void __pm_relax(struct wakeup_source *ws);
   4: extern void __pm_wakeup_event(struct wakeup_source *ws, unsigned int msec);

__pm_stay_awake，通知PM core，ws产生了wakeup event，且正在处理，因此不允许系统suspend（stay awake）；

__pm_relax，通知PM core，ws没有正在处理的wakeup event，允许系统suspend（relax）；

__pm_wakeup_event，为上边两个接口的功能组合，通知PM core，ws产生了wakeup event，会在msec毫秒内处理结束（wakeup events framework自动relax）。

注4：__pm_stay_awake和__pm_relax应成对调用。
注5：上面3个接口，均可以在中断上下文调用。

类型二（操作对象为device，为设备驱动的常用接口）：

extern int device_wakeup_enable(struct device *dev);
extern int device_wakeup_disable(struct device *dev);
extern void device_set_wakeup_capable(struct device *dev, bool capable);
extern int device_set_wakeup_enable(struct device *dev, bool enable);
extern void pm_stay_awake(struct device *dev);
extern void pm_relax(struct device *dev);
extern void pm_wakeup_ws_event(struct wakeup_source *ws, unsigned int msec, bool hard);
extern void pm_wakeup_dev_event(struct device *dev, unsigned int msec, bool hard);

device_set_wakeup_capable，设置dev的can_wakeup标志（enable或disable，可参考5.1小节），并增加或移除该设备在sysfs相关的power文件；

device_wakeup_enable/device_wakeup_disable/device_set_wakeup_enable，对于can_wakeup的设备，使能或者禁止wakeup功能。主要是对struct wakeup_source结构的相关操作；

device_init_wakeup，设置dev的can_wakeup标志，若是enable，同时调用device_wakeup_enable使能wakeup功能；

pm_stay_awake、pm_relax、pm_wakeup_event，直接调用上面的wakeup source操作接口，操作device的struct wakeup_source变量，处理wakeup events。

5.3.1 device_set_wakeup_capable

/**
 * device_set_wakeup_capable - 设置/重置设备的唤醒能力标志。
 * @dev: 要处理的设备。
 * @capable: 指定 @dev 是否具有从睡眠中唤醒系统的能力。
 *
 * 如果 @capable 被设置为真，设置 @dev 的 power.can_wakeup 标志，并将与其唤醒相关的属性添加到 sysfs 中。
 * 否则，取消 @dev 的 power.can_wakeup 标志，并从 sysfs 中移除与其唤醒相关的属性。
 *
 * 此函数可能会休眠，不能从任何不允许休眠的上下文中调用。
 */
void device_set_wakeup_capable(struct device *dev, bool capable)
{
	// 检查设备的唤醒能力标志是否需要更改，如果不需要，则直接返回
	if (!!dev->power.can_wakeup == !!capable)
		return;

	// 更新设备的唤醒能力标志
	dev->power.can_wakeup = capable;

	// 如果设备已注册且 power.entry 列表不为空
	if (device_is_registered(dev) && !list_empty(&dev->power.entry)) {
		// 如果设备具有唤醒能力，则向 sysfs 添加唤醒相关的属性
		if (capable) {
			int ret = wakeup_sysfs_add(dev);

			if (ret)
				dev_info(dev, "Wakeup sysfs attributes not added\n");
		} else {
			// 否则，从 sysfs 中移除与唤醒相关的属性
			wakeup_sysfs_remove(dev);
		}
	}
}

函数 device_set_wakeup_capable 用于设置或重置设备的唤醒能力标志。通过传入的 capable 参数指定设备是否具有从睡眠中唤醒系统的能力。

函数首先检查设备的唤醒能力标志是否需要更改，如果不需要，则直接返回。然后，更新设备的 power.can_wakeup 标志，以反映设备的唤醒能力。

如果设备已经注册并且 power.entry 列表不为空，函数将根据设备的唤醒能力来添加或移除与唤醒相关的属性。如果设备具有唤醒能力，则调用 wakeup_sysfs_add 函数向 sysfs 中添加唤醒相关的属性。如果添加属性失败，会打印一条错误消息。如果设备不具有唤醒能力，则调用 wakeup_sysfs_remove 函数从 sysfs 中移除与唤醒相关的属性。

这段代码的作用是管理设备的唤醒能力标志和相关的属性，通过设置或重置设备的唤醒能力标志，来控制是否在 sysfs 中添加或移除唤醒相关的属性。唤醒能力标志的更新和属性的添加/移除是在设备注册且 power.entry 列表不为空的情况下进行的。函数的注释提醒了该函数可能会休眠，因此不能从不允许休眠的上下文中调用。

wakeup_sysfs_add/wakeup_sysfs_remove位于drivers/base/power/sysfs.c中，对wakeup events framework来说，主要包括如下的attribute文件：

static struct attribute *wakeup_attrs[] = {
#ifdef CONFIG_PM_SLEEP
	&dev_attr_wakeup.attr,
	&dev_attr_wakeup_count.attr,
	&dev_attr_wakeup_active_count.attr,
	&dev_attr_wakeup_abort_count.attr,
	&dev_attr_wakeup_expire_count.attr,
	&dev_attr_wakeup_active.attr,
	&dev_attr_wakeup_total_time_ms.attr,
	&dev_attr_wakeup_max_time_ms.attr,
	&dev_attr_wakeup_last_time_ms.attr,
#ifdef CONFIG_PM_AUTOSLEEP
	&dev_attr_wakeup_prevent_sleep_time_ms.attr,
#endif
#endif
	NULL,
};

1）wakeup

读，获得设备wakeup功能的使能状态，返回"enabled"或"disabled"字符串。

写，更改设备wakeup功能的使能状态，根据写入的字符串（“enabled"或"disabled”），调用device_set_wakeup_enable接口完成实际的状态切换。

设备wakeup功能是否使能，取决于设备的can_wakeup标志，以及设备是否注册有相应的struct wakeup_source指针。即can wakeup和may wakeup，如下：

   1: /*
   2:  * Changes to device_may_wakeup take effect on the next pm state change.
   3:  */
   4:  
   5: static inline bool device_can_wakeup(struct device *dev)
   6: {
   7:         return dev->power.can_wakeup;
   8: }
   9:  
  10: static inline bool device_may_wakeup(struct device *dev)
  11: {
  12:         return dev->power.can_wakeup && !!dev->power.wakeup;
  13: }

2）wakeup_count

只读，获取dev->power.wakeup->wakeup_count。

static ssize_t wakeup_count_show(struct device *dev,
				 struct device_attribute *attr, char *buf)
{
	unsigned long count;
	bool enabled = false;

	spin_lock_irq(&dev->power.lock);
	if (dev->power.wakeup) {
		count = dev->power.wakeup->wakeup_count;
		enabled = true;
	}
	spin_unlock_irq(&dev->power.lock);

	if (!enabled)
		return sysfs_emit(buf, "\n");
	return sysfs_emit(buf, "%lu\n", count);
}

static DEVICE_ATTR_RO(wakeup_count);

3）wakeup_active_count，只读，获取dev->power.wakeup->active_count值。

4）wakeup_abort_count，只读，获取dev->power.wakeup->wakeup_count值。

5）wakeup_expire_count，只读，获dev->power.wakeup->expire_count取值。

6）wakeup_active，只读，获取dev->power.wakeup->active值。

7）wakeup_total_time_ms，只读，获取dev->power.wakeup->total_time值，单位为ms。

8）wakeup_max_time_ms，只读，获dev->power.wakeup->max_time取值，单位为ms。

9）wakeup_last_time_ms，只读，获dev->power.wakeup->last_time取值，单位为ms。

10）wakeup_prevent_sleep_time_ms，只读，获取dev->power.wakeup->prevent_sleep_time值，单位为ms。

注6：阅读上述代码时，我们可以看到很多类似“!!dev->power.can_wakeup == !!capable”的、带有两个“！”操作符的语句，是为了保证最后的操作对象非0即1。这从侧面反映了内核开发者的严谨程度，值得我们学习。

5.3.2 device_wakeup_enable/device_wakeup_disable/device_set_wakeup_enable

/**
 * device_wakeup_enable - 启用给定设备作为唤醒源。
 * @dev: 要处理的设备。
 *
 * 创建一个唤醒源对象，将其注册并附加到 @dev 上。
 */
int device_wakeup_enable(struct device *dev)
{
	struct wakeup_source *ws;
	int ret;

	// 检查设备和设备的唤醒能力是否有效，如果无效则返回错误
	if (!dev || !dev->power.can_wakeup)
		return -EINVAL;

	// 如果当前系统状态不是 PM_SUSPEND_ON（系统挂起状态），打印警告信息
	if (pm_suspend_target_state != PM_SUSPEND_ON)
		dev_dbg(dev, "Suspicious %s() during system transition!\n", __func__);

	// 创建一个唤醒源对象并将其注册到系统中
	ws = wakeup_source_register(dev, dev_name(dev));
	if (!ws)
		return -ENOMEM;

	// 将唤醒源对象附加到设备上
	ret = device_wakeup_attach(dev, ws);
	if (ret)
		wakeup_source_unregister(ws);

	return ret;
}
EXPORT_SYMBOL_GPL(device_wakeup_enable);

该代码段定义了一个名为 device_wakeup_enable 的函数，用于启用给定设备作为唤醒源。

函数首先检查设备和设备的唤醒能力是否有效，如果无效则返回错误。然后，检查当前系统状态是否为 PM_SUSPEND_ON（系统挂起状态），如果不是，则打印一条警告信息。

接下来，函数创建一个唤醒源对象 ws 并将其注册到系统中，使用设备的名称作为唤醒源的名称。

然后，函数将唤醒源对象附加到设备上，使用 device_wakeup_attach 函数完成此操作。如果附加失败，函数将注销唤醒源对象并返回错误。

wakeup_source_register接口的实现也比较简单，会先后调用wakeup_source_create、wakeup_source_prepare、wakeup_source_add等接口，所做的工作包括分配struct wakeup_source变量所需的内存空间、初始化内部变量、将新建的wakeup source添加到名称为wakeup_sources的全局链表中、等等。

device_wakeup_attach接口更为直观，不过有一点我们要关注，如果设备的dev->power.wakeup非空，也就是说之前已经有一个wakeup source了，是不允许再enable了的，会报错返回。

5.3.3 pm_stay_awake

当设备有wakeup event正在处理时，需要调用该接口通知PM core，该接口的实现如下：

/**
 * pm_stay_awake - 通知 PM 核心正在处理唤醒事件。
 * @dev: 相关联唤醒事件的设备。
 *
 * 通过调用 __pm_stay_awake 函数，通知 PM 核心有一个唤醒事件（由 @dev 指示）。
 *
 * 在检测到唤醒事件后，如果接下来会直接调用 pm_relax() 来处理事件（可能将事件传递给用户空间进行进一步处理），
 * 则调用此函数。
 */
void pm_stay_awake(struct device *dev)
{
	unsigned long flags;

	if (!dev)
		return;

	spin_lock_irqsave(&dev->power.lock, flags);
	// 通过调用 __pm_stay_awake 函数来通知 PM 核心有一个唤醒事件
	__pm_stay_awake(dev->power.wakeup);
	spin_unlock_irqrestore(&dev->power.lock, flags);
}
EXPORT_SYMBOL_GPL(pm_stay_awake);

直接调用__pm_stay_awake，这也是本文的index里没有该接口的原因。接着看代码。

/**
 * __pm_stay_awake - Notify the PM core of a wakeup event.
 * @ws: Wakeup source object associated with the source of the event.
 *
 * This function is used to notify the PM core of a wakeup event. It takes a
 * wakeup source object (@ws) as a parameter, which is associated with the
 * source of the event.
 *
 * It is safe to call this function from interrupt context.
 */
void __pm_stay_awake(struct wakeup_source *ws)
{
	unsigned long flags;

	if (!ws)
		return;

	spin_lock_irqsave(&ws->lock, flags);  // Acquire a spin lock to protect the wakeup source object

	wakeup_source_report_event(ws, false);  // Report the wakeup event to the PM core
	del_timer(&ws->timer);  // Delete the timer associated with the wakeup source
	ws->timer_expires = 0;  // Reset the timer expiration value

	spin_unlock_irqrestore(&ws->lock, flags);  // Release the spin lock
}
EXPORT_SYMBOL_GPL(__pm_stay_awake);

由于pm_stay_awake报告的event需要经过pm_relax主动停止，因此就不再需要timer，所以__pm_stay_awake实现是直接调用wakeup_source_report_event，然后停止timer。接着看代码：

/**
 * wakeup_source_report_event - Report a wakeup event using the given source.
 * @ws: Wakeup source to report the event for.
 * @hard: If set, abort suspends in progress and wake up from suspend-to-idle.
 *
 * This function is used to report a wakeup event using the provided wakeup source (@ws).
 * The function increments the event count of the wakeup source. If events checking is
 * enabled, it also increments the wakeup count. If the wakeup source is not active,
 * it activates the wakeup source. If the @hard flag is set, it triggers a system wakeup.
 */
static void wakeup_source_report_event(struct wakeup_source *ws, bool hard)
{
	ws->event_count++;  // Increment the event count of the wakeup source

	/* This is racy, but the counter is approximate anyway. */
	if (events_check_enabled)
		ws->wakeup_count++;  // Increment the wakeup count if events checking is enabled

	if (!ws->active)
		wakeup_source_activate(ws);  // Activate the wakeup source if it's not already active

	if (hard)
		pm_system_wakeup();  // Trigger a system wakeup if the @hard flag is set
}

该函数用于报告使用给定的唤醒源（ws）的唤醒事件。它执行以下操作：

增加唤醒源的事件计数。
如果启用了事件检查，增加唤醒计数。
如果唤醒源未激活，则激活唤醒源。
如果设置了hard标志，触发系统唤醒。
该函数通过更新相关计数并触发适当的操作来处理唤醒事件。

/**
 * wakeup_source_activate - 将给定的唤醒源标记为活动状态。
 * @ws: 要处理的唤醒源。
 *
 * 更新唤醒源（@ws）的统计信息，并在唤醒源刚刚被激活时通知PM核心该事件，通过增加正在处理的唤醒事件计数器。
 */
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++;  // 增加唤醒源的活动计数
	ws->last_time = ktime_get();  // 更新最后活动时间
	if (ws->autosleep_enabled)
		ws->start_prevent_time = ws->last_time;  // 如果启用了自动休眠，更新阻止休眠的起始时间

	/* 增加正在处理的事件计数器。 */
	cec = atomic_inc_return(&combined_event_count);

	trace_wakeup_source_activate(ws->name, cec);  // 跟踪唤醒源的激活事件
}

函数wakeup_source_activate的作用是将给定的唤醒源(@ws)标记为活动状态。它更新唤醒源的统计信息，增加活动计数，记录最后的活动时间，并且如果启用了自动休眠，记录阻止休眠的起始时间。

此外，它还增加正在处理的唤醒事件计数器。函数通过调用trace_wakeup_source_activate来跟踪唤醒源的激活事件。

注意：由于没有提供wakeup_source_not_registered和trace_wakeup_source_activate函数的具体实现，仅凭此代码片段无法确定它们的具体行为和影响。

5.3.4 pm_relax

pm_relax和pm_stay_awake成对出现，用于在event处理结束后通知PM core，其实现如下：

   1: /**
   2:  * pm_relax - Notify the PM core that processing of a wakeup event has ended.
   3:  * @dev: Device that signaled the event.
   4:  *
   5:  * Execute __pm_relax() for the @dev's wakeup source object.
   6:  */
   7: void pm_relax(struct device *dev)
   8: {
   9:         unsigned long flags;
  10:  
  11:         if (!dev)
  12:                 return;
  13:  
  14:         spin_lock_irqsave(&dev->power.lock, flags);
  15:         __pm_relax(dev->power.wakeup);
  16:         spin_unlock_irqrestore(&dev->power.lock, flags);
  17: }

**
 * __pm_relax - Notify the PM core that processing of a wakeup event has ended.
 * @ws: Wakeup source object associated with the source of the event.
 *
 * Call this function for wakeup events whose processing started with calling
 * __pm_stay_awake().
 *
 * It is safe to call it from interrupt context.
 */
void __pm_relax(struct wakeup_source *ws)
{
	unsigned long flags;

	if (!ws)
		return;

	spin_lock_irqsave(&ws->lock, flags);
	if (ws->active)
		wakeup_source_deactivate(ws);
	spin_unlock_irqrestore(&ws->lock, flags);
}
EXPORT_SYMBOL_GPL(__pm_relax);

如果该wakeup source处于active状态，调用wakeup_source_deactivate接口，deactivate之。deactivate接口和activate接口一样，是wakeup events framework的核心逻辑，如下：

/**
 * wakeup_source_deactivate - Mark given wakeup source as inactive.
 * @ws: Wakeup source to handle.
 *
 * Update the @ws' statistics and notify the PM core that the wakeup source has
 * become inactive by decrementing the counter of wakeup events being processed
 * and incrementing the counter of registered wakeup events.
 */
static void wakeup_source_deactivate(struct wakeup_source *ws)
{
	unsigned int cnt, inpr, cec;
	ktime_t duration;
	ktime_t now;

	ws->relax_count++;
	/*
	 * __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)
		update_prevent_sleep_time(ws, now);

	/*
	 * Increment the counter of registered wakeup events and decrement the
	 * counter of wakeup events in progress simultaneously.
	 */
	cec = atomic_add_return(MAX_IN_PROGRESS, &combined_event_count);
	trace_wakeup_source_deactivate(ws->name, cec);

	split_counters(&cnt, &inpr);
	if (!inpr && waitqueue_active(&wakeup_count_wait_queue))
		wake_up(&wakeup_count_wait_queue);
}

a）relax_count加1（如果relax_count和active_count不等，则说明有重复调用，要退出）。

b）清除active标记。

c）更新total_time、max_time、last_time等变量。

d）如果使能auto sleep，更新相关的变量（后面再详细描述）。

e）再欣赏一下艺术，wakeup events in progress减1，registered wakeup events加1。

f）wakeup count相关的处理，后面再详细说明。

5.3.5 pm_wakeup_event

pm_wakeup_event是pm_stay_awake和pm_relax的组合版，在上报event时，指定一个timeout时间，timeout后，自动relax，一般用于不知道何时能处理完成的场景。该接口比较简单，就不一一描述了

5.3.6 pm_wakeup_pending

drivers产生的wakeup events，最终要上报到PM core，PM core会根据这些events，决定是否要终止suspend过程。这表现在suspend过程中频繁调用pm_wakeup_pending接口上（可参考“Linux电源管理(6)_Generic PM之Suspend功能”）。该接口的实现如下：

/**
 * pm_wakeup_pending - 检查正在进行的电源转换是否应该中止。
 *
 * 将当前注册的唤醒事件数量与过去保存的数量进行比较，如果自从存储旧值以来注册了新的唤醒事件，或者当前正在处理的唤醒事件数量与零不同，返回true。
 */
bool pm_wakeup_pending(void)
{
	unsigned long flags;
	bool ret = false;
	char suspend_abort[MAX_SUSPEND_ABORT_LEN];

	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();  // 打印当前活动的唤醒源信息
		pm_get_active_wakeup_sources(suspend_abort,
					     MAX_SUSPEND_ABORT_LEN);  // 获取活动的唤醒源信息
		log_suspend_abort_reason(suspend_abort);  // 记录挂起中止的原因
		pr_info("PM: %s\n", suspend_abort);  // 打印挂起中止的原因
	}

	return ret || atomic_read(&pm_abort_suspend) > 0;  // 如果有待处理的唤醒事件或挂起操作被中止，则返回true
}
EXPORT_SYMBOL_GPL(pm_wakeup_pending);

5.4 wakeup count、wake lock和auto sleep

这篇文章写的有点长了，不能继续了，这几个功能，会接下来的文章中继续分析。

参考连接： http://www.wowotech.net/pm_subsystem/wakeup_events_framework.html