Linux電源管理_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功能，由另外的巨集定義控制）：
1: static struct attribute * g[] = {
2: &state_attr.attr,
3: #ifdef CONFIG_PM_TRACE
4: &pm_trace_attr.attr,
5: &pm_trace_dev_match_attr.attr,
6: #endif
7: #ifdef CONFIG_PM_SLEEP
8: &pm_async_attr.attr,
9: &wakeup_count_attr.attr,
10: #ifdef CONFIG_PM_AUTOSLEEP
11: &autosleep_attr.attr,
12: #endif
13: #ifdef CONFIG_PM_WAKELOCKS
14: &wake_lock_attr.attr,
15: &wake_unlock_attr.attr,
16: #endif
17: #ifdef CONFIG_PM_DEBUG
18: &pm_test_attr.attr,
19: #endif
20: #ifdef CONFIG_PM_SLEEP_DEBUG
21: &pm_print_times_attr.attr,
22: #endif
23: #endif
24: #ifdef CONFIG_FREEZER
25: &pm_freeze_timeout_attr.attr,
26: #endif
27: NULL,
28: };
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的定義。
1: /* include\linux\pm_wakeup.h */
2: struct wakeup_source {
3: const char *name;
4: struct list_head entry;
5: spinlock_t lock;
6: struct timer_list timer;
7: unsigned long timer_expires;
8: ktime_t total_time;
9: ktime_t max_time;
10: ktime_t last_time;
11: ktime_t start_prevent_time;
12: ktime_t prevent_sleep_time;
13: unsigned long event_count;
14: unsigned long active_count;
15: unsigned long relax_count;
16: unsigned long expire_count;
17: unsigned long wakeup_count;
18: bool active:1;
19: bool autosleep_enabled:1;
20: };
因此，一個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位的整型數，以原子操作的形式，一起更新。這種設計巧妙的讓人叫絕，值得我們學習。具體如下：
1: /*
2: * Combined counters of registered wakeup events and wakeup events in progress.
3: * They need to be modified together atomically, so it's better to use one
4: * atomic variable to hold them both.
5: */
6: static atomic_t combined_event_count = ATOMIC_INIT(0);
7:
8: #define IN_PROGRESS_BITS (sizeof(int) * 4)
9: #define MAX_IN_PROGRESS ((1 << IN_PROGRESS_BITS) - 1)
10:
11: static void split_counters(unsigned int *cnt, unsigned int *inpr)
12: {
13: unsigned int comb = atomic_read(&combined_event_count);
14:
15: *cnt = (comb >> IN_PROGRESS_BITS);
16: *inpr = comb & MAX_IN_PROGRESS;
17: }
定義和讀取。
1: cec = atomic_add_return(MAX_IN_PROGRESS, &combined_event_count);
wakeup events in progress減1，registered wakeup events加1，這個語句簡直是美輪美奐，讀者可以仔細品味一下，絕對比看xxx片還過癮，哈哈。
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，為裝置驅動的常用介面）：
1: /* include/linux/pm_wakeup.h */
2: extern int device_wakeup_enable(struct device *dev);
3: extern int device_wakeup_disable(struct device *dev);
4: extern void device_set_wakeup_capable(struct device *dev, bool capable);
5: extern int device_init_wakeup(struct device *dev, bool val);
6: extern int device_set_wakeup_enable(struct device *dev, bool enable);
7: extern void pm_stay_awake(struct device *dev);
8: extern void pm_relax(struct device *dev);
9: extern void pm_wakeup_event(struct device *dev, unsigned int msec);
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
該介面位於在drivers/base/power/wakeup.c中，程式碼如下：
1: void device_set_wakeup_capable(struct device *dev, bool capable)
2: {
3: if (!!dev->power.can_wakeup == !!capa