Wakeup Source框架设计与实现

技术分享 2年前 (2024-06-08) 0 999+

Wakeup Source 为系统组件提供了投票机制，以便低功耗子系统判断当前是否可以进入休眠。

Wakeup Source(后简称：WS) 模块可与内核中的其他模块或者上层服务交互，并最终体现在对睡眠锁的控制上。

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<id>/,便于获取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<id>/ 			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<id>/ 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 sourcen")) 		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 suspendn"); 		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/<dev_name>/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<id>/
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/<dev_name>/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