為支援車輛專屬的電源管理功能，Android 提供 CarPowerManagementService 服務和 CarPowerManager 介面。
狀態轉換是由車輛主控制單元 (VMCU) 觸發。如要與 VMCU 通訊，整合業者必須實作多個元件。整合者負責整合車輛硬體抽象層 (VHAL) 和核心實作項目。整合商也必須負責停用喚醒來源，並確保關機不會無限期延後。
術語
本文件中會使用以下術語：
suspend() 和 shutdown() 的最終呼叫。系統設計
本節說明 AAOS 如何代表應用程式處理器的電源狀態，以及哪些模組會實作電源管理系統。本資料也說明這些模組如何搭配運作，以及狀態轉換通常如何發生。
車輛電源狀態機器
AAOS 會使用狀態機器來代表無線基地台的電源狀態。狀態機提供下列狀態：
圖 1. 車輛電源狀態機器。
最常見的轉場效果會以藍色標示。以下是狀態和常見的轉換：
- 暫停至 RAM：車輛和 SoC 已關閉，沒有任何程式碼正在執行。維持 SoC RAM 的電源。
- 等待 VHAL。當駕駛者與車輛互動時 (例如開車門)，VMCU 會為 SoC 供電。AAOS 會從暫停至 RAM 的狀態中復原，並進入等待 VHAL 的狀態，等待與 VHAL 協調。
- 已開啟。VHAL 會指示 AAOS 進入開啟狀態。在這個狀態下，AAOS 會完全執行並與駕駛員互動。
- Shutdown Prepare。駕駛人完成行車後，VHAL 會通知 AAOS 進入關機準備階段。在這個狀態下，螢幕和音訊會關閉，且 AAOS 不會與駕駛員互動。Android 系統仍在執行，可免費更新應用程式和 Android 系統。更新 (如有) 完成後，Android 系統會進入「等待 VHAL 完成」狀態。
- 等待 VHAL 完成。此時，AAOS 會通知 VHAL 已準備好關機。VMCU 應將 SoC 置於深度睡眠狀態，並從應用程式處理器移除電源。此時 AAOS 處於「暫停至 RAM」狀態，但沒有任何程式碼正在執行。
電源管理模組
電源管理系統由下列模組組成：
| 模組名稱 | 說明 |
|---|---|
| CarPowerManager | Java 或 C++ API。 |
| CarPowerManagementService | 協調電源狀態轉換。 |
| CarPowerPolicyDaemon | 與原生電源政策用戶端通訊。 |
| 車用 HAL | 與 VMCU 的介面。 |
| 核心 | 暫停至 RAM 或磁碟實作。 |
深層睡眠/休眠功能 (將 Android 暫停至 RAM/磁碟) 是在核心中實作。這項功能會以位於 /sys/power/state 的特殊檔案形式提供給使用者空間。將 mem 或 disk 寫入此檔案，即可暫停 AAOS。
CPMS 會協調電源狀態與其他服務和 HAL。CPMS 會實作上述狀態機器，並在發生電源狀態轉換時，向每個觀察器傳送通知。這項服務也會使用 VHAL 將訊息傳送至硬體。
在 CPMS 接管之前，CPPD 會管理電源政策。並向原生事件監聽器傳送電源政策變更通知。
部分屬性是在 VHAL 中定義。為了與 VMCU 通訊，CPMS 會讀取及寫入這些屬性。應用程式可使用 CPM 中定義的介面，監控電源狀態變更。這個介面也能讓應用程式註冊電源政策事件監聽器。這個 API 可從 Java 呼叫，並附加 @hide / @System API 註解，也就是說，只有特權應用程式可使用。下圖說明這些模組、應用程式和服務之間的關係：
圖 2. 電源元件參考圖表。
訊息序列
上一節說明瞭組成電源管理系統的模組。本節將透過「進入深層睡眠狀態」和「退出深層睡眠狀態」的範例說明模組和應用程式如何進行通訊：
進入熟睡
只有 VMCU 可以啟動深度睡眠模式。啟動深度睡眠後，VMCU 會透過 VHAL 傳送通知給 CPMS。CPMS 會將狀態變更為 SHUTDOWN PREPARE，並透過呼叫 onStateChanged() 方法 (使用 CPM 提供的新狀態 ID)，將此狀態轉換廣播給所有觀察者 (監控 CPMS 的應用程式和服務)。
CPM 會在應用程式/服務與 CPMS 之間進行調解。應用程式/服務的 onStateChanged() 方法會在 CPM 的 onStateChanged() 方法中同步叫用。大多數應用程式和服務都必須在這個呼叫結束前完成準備作業。特權服務可在傳回 PRE_SHUTDOWN_PREPARE、SUSPEND_ENTER 和 POST_SUSPEND_ENTER 後，以非同步方式繼續準備作業。在這種情況下，特權服務應在準備完成時，對提供的 CompletablePowerStateChangeFuture 物件呼叫 complete()。請注意，SHUTDOWN_PREPARE 不支援非同步準備作業。在 DEEP_SLEEP_ENTRY 傳送至 VHAL 之前，CPMS 會定期將關機延後要求傳送至 VHAL。
當所有 CPM 物件都已完成關機準備作業後，CPMS 會將 AP_POWER_STATE_REPORT 傳送至 VHAL，然後通知 VMCU 表示 AP 已準備好暫停。CPMS 也會呼叫其暫停方法，以便暫停核心。
以下說明上述順序：
圖 3. 進入深層睡眠。
由 CPM 提供的程式設計介面
本節說明 CPM 為系統應用程式和服務提供的 Java API。這個 API 可讓系統軟體執行以下操作：
- 監控無線基地台的電源狀態變更。
- 套用電源政策。
請按照下列步驟呼叫 CPM 提供的 API：
- 如要取得 CPM 例項，請呼叫 Car API。
- 對步驟 1 建立的物件呼叫適當方法。
建立 CarPowerManager 物件
如要建立 CPM 物件，請呼叫 Car 物件的 getCarManager() 方法。這個方法是用來建立 CPM 物件的外觀。指定 android.car.Car.POWER_SERVICE 做為建立千次曝光出價物件的引數。
Car car = Car.createCar(this); CarPowerManager powerManager = (CarPowerManager) car.getCarManager(android.car.Car.POWER_SERVICE);
CarPowerStateListener 和註冊
系統應用程式和服務可以實作 CarPowerManager.CarPowerStateListener，接收電源狀態變更通知。這個介面定義了一個方法 onStateChanged()，這是在 CPMS 的電源狀態變更時，系統會叫用的回呼函式。以下範例定義了實作介面的新匿名類別：
private final CarPowerManager.CarPowerStateListener powerListener = new CarPowerManager.CarPowerStateListener () { @Override public void onStateChanged(int state) { Log.i(TAG, "onStateChanged() state = " + state); } };
如要指示這個監聽器物件監控電源狀態轉換，請建立新的執行緒，並將監聽器和這個執行緒註冊至 CPM 物件：
executor = new ThreadPerTaskExecutor(); powerManager.setListener(powerListener, executor);
當電源狀態變更時，系統會以代表新電源狀態的值，叫用事件監聽器物件的 onStateChanged() 方法。實際值和電源狀態之間的關聯在 CarPowerManager 中定義，如下表所示：
| 名稱 | 說明 |
|---|---|
| STATE_ON | 進入開啟狀態。系統已全面運作。 |
| STATE_SHUTDOWN_CANCELLED | 系統會取消關機，並將電源狀態還原為正常狀態。 |
| STATE_SHUTDOWN_ENTER | 應用程式應會清理並準備關閉。 |
| STATE_POST_SHUTDOWN_ENTER | 關機的準備工作已完成，VMCU 已準備好關機。進入關機狀態。 |
| STATE_PRE_SHUTDOWN_PREPARE | 系統要求關機程序，但 CPMS 尚未啟動程序。螢幕和音訊仍在運作 |
| STATE_SHUTDOWN_PREPARE | 車庫模式可能會在這個期間運作。 |
| STATE_SUSPEND_ENTER | 應用程式應清理並準備進入暫停至 RAM 的狀態。 |
| STATE_POST_SUSPEND_ENTER | 已完成暫停至 RAM 的準備作業，且 VMCU 已準備好執行暫停至 RAM 的作業。進入暫停狀態。 |
| STATE_SUSPEND_EXIT | 從暫停狀態喚醒，或從已取消的暫停狀態恢復。 |
| STATE_HIBERNATION_ENTER | 應用程式應會清理並準備進入休眠狀態。 |
| STATE_POST_HIBERNATION_ENTER | 休眠模式的準備作業已完成，VMCU 已準備好進入休眠狀態。 |
| STATE_HIBERNATION_EXIT | 從休眠狀態喚醒或從取消的休眠狀態恢復。 |
| STATE_WAIT_FOR_VHAL | 系統正在啟動，但會先等待與 VHAL 建立通訊，再進入開啟狀態。 |
取消註冊 CarPowerStateListener
如要取消註冊已註冊至 CPM 的所有監聽器物件，請呼叫 clearListener 方法：
powerManager.clearListener();
在 Android 實作中整合系統
整合商負責處理下列項目：
- 實作核心介面，以便暫停 Android。
- 實作 VHAL 函式以便：
- 將車輛的暫停或關機作業啟動事件傳播至 Android。
- 從 Android 裝置傳送關機就緒訊息給車輛。
- 透過 Linux 核心介面啟動 Android 關機或暫停作業。
- 請確認裝置處於休眠狀態時，所有喚醒來源都已停用。
- 請確保應用程式能快速關閉，以免無限期延遲關機程序。
- 確保 BSP 會根據電源政策開啟 (或關閉) 裝置元件，以免封鎖休眠或待機模式
核心介面：/sys/power/state
當應用程式或服務將 mem (用於暫停至 RAM) 或 disk (用於暫停至磁碟) 寫入位於 /sys/power/state 的檔案時，AAOS 會將裝置置於暫停模式。整合者必須提供監控此檔案的函式，並將 Linux 置於暫停電源狀態。這個函式可能會將 GPIO 傳送至 VMCU，通知 VMCU 裝置已完全關閉。整合器也負責移除 VHAL 將最終訊息傳送至 VMCU 和系統進入暫停或關機模式之間的任何競爭條件。
VHAL 責任
VHAL 會在車輛網路和 Android 之間提供介面。VHAL：
- 將車輛的暫停或關機作業啟動事件傳播至 Android。
- 從 Android 傳送關機就緒訊息至車輛。
- 透過 Linux 核心介面啟動 Android 關機或暫停作業。
當 CPMS 通知 VHAL 已準備好關機時，VHAL 會將關機就緒訊息傳送至 VMCU。一般而言，UART、SPI 和 USB 等晶片上周邊會傳送訊息。訊息傳送後，CPMS 會呼叫核心指令，以暫停或關閉裝置。在執行這項操作之前，VHAL 或 BSP 可能會切換 GPIO，以便指示 VMCU 安全地移除裝置電源。
VHAL 必須支援下列屬性，以便透過 VHAL 控管電源管理：
| 名稱 | 說明 |
|---|---|
| AP_POWER_STATE_REPORT | Android 會使用此屬性，透過 VehicleApPowerStateReport 列舉值向 VMCU 回報狀態轉換。 |
| AP_POWER_STATE_REQ | VMCU 會使用這個屬性，以便指示 Android 使用 VehicleApPowerStateReq 列舉值，轉換為不同的電源狀態。 |
AP_POWER_STATE_REPORT
使用這項資源回報 Android 目前的電源管理狀態。這個屬性包含兩個整數：
int32Values[0]：目前狀態的 VehicleApPowerStateReport 列舉。int32Values[1]：延遲或休眠或關機的時間 (以毫秒為單位)。這個值的含義取決於第一個值。
第一個值可以是下列其中一個值。VehicleApPowerStateReport.aidl 包含更詳細的說明，這些說明會儲存在 hardware/interfaces/automotive/vehicle/aidl/android/hardware/automotive/vehicle 中。
| 值名稱 | 說明 | 第二個值 |
|---|---|---|
| WAIT_FOR_VHAL | AP 正在啟動，需要與 VHAL 建立通訊。 | |
| DEEP_SLEEP_ENTRY | AP 正在進入深層睡眠狀態。VMCU 應在第二個值中指定的時間過後，將 AP 重新開啟。 | 必須設定 |
| DEEP_SLEEP_EXIT | AP 正在退出深層睡眠狀態。 | |
| HIBERNATION_ENTRY | AP 正在進入休眠狀態。VMCU 應在第二個值中指定的時間過後，將 AP 重新開啟。 | 必須設定 |
| HIBERNATION_EXIT | AP 正在退出休眠狀態。 | |
| SHUTDOWN_POSTPONE | Android 尚未準備好關機。VMCU 應等待第二個值指定的時間，再關閉 AP。Android 可能會透過發出額外的 SHUTDOWN_POSTPONE 報告，要求額外延後。 | 必須設定 |
| SHUTDOWN_PREPARE | Android 正在準備關機。 | 必須設定 |
| SHUTDOWN_START | AP 已準備好關機。VMCU 應在第二個值中指定的時間過後，將 AP 重新開啟。(VMCU 不必支援定時開啟功能)。 | 必須設定 |
| SHUTDOWN_CANCELLED | Android 會停止關機準備程序，並繼續執行 WAIT_FOR_VHAL。 | |
| 開啟 | Android 正常運作。 |
狀態可以自行設定，也可以透過 VMCU 回應要求。
AP_POWER_STATE_REQ
VMCU 會傳送這個屬性，將 Android 切換至不同的電源狀態，並包含兩個整數：
int32Values[0]：VehicleApPowerStateReq列舉值，代表要轉換至的新狀態。int32Values[1]：VehicleApPowerStateShutdownParam列舉值。這個值只會傳送SHUTDOWN_PREPARE訊息，並將其中的選項傳送至 Android。
第一個整數值代表 Android 要轉換至的新狀態。語意是在 VehicleApPowerStateReq.aidl 中定義，並在下方提供：
| 值名稱 | 說明 |
|---|---|
| 開啟 | AP 應開始全面運作。 |
| SHUTDOWN_PREPARE | AP 應準備關機。第二個值表示是否允許存取點延遲關機，以及存取點是否應關機或進入深度休眠狀態。 |
| CANCEL_SHUTDOWN | AP 應停止準備關機，並準備開機。 |
| 已完成 | AP 即將關閉或暫停。 |
VehicleApPowerStateShutdownParam 是在 VehicleApPowerStateShutdownParam.aidl 中定義的。這個列舉包含以下元素：
| 值名稱 | 說明 |
|---|---|
| CAN_SLEEP | AP 可以進入深層睡眠狀態，而非完全關閉。允許延後。 |
| CAN_HIBERNATE | AP 可以進入休眠狀態，而非完全關機。允許延後。 |
| SHUTDOWN_ONLY | AP 應會關閉。允許延後。不允許深層睡眠。 |
| SLEEP_IMMEDIATELY | AP 可以進入深層睡眠狀態，但必須立即進入睡眠或關機狀態。不允許延後。 |
| HIBERNATE_IMMEDIATELY | AP 可以進入「暫停至磁碟」狀態，但必須立即進入休眠或關機狀態。不允許延後。 |
| SHUTDOWN_IMMEDIATELY | AP 必須立即關閉。不允許延後。不允許深層睡眠。 |
喚醒來源
整合者必須在裝置處於暫停模式時，停用適當的喚醒來源。常見的喚醒來源包括心跳、數據機、Wi-Fi 和藍牙。唯一有效的喚醒來源必須是 VMCU 的中斷，才能喚醒 SoC。這項假設是指 VMCU 可以監聽數據機的遠端喚醒事件 (例如遠端引擎啟動)。如果這項功能已推送至 AP，則必須新增其他喚醒來源，才能服務數據機。
應用程式
原始設備製造商 (OEM) 必須謹慎編寫應用程式，以便快速關閉應用程式，而不會無限期延遲程序。
附錄
原始碼樹狀結構中的目錄
| 滿足 | Directory |
|---|---|
| CarPowerManager 相關程式碼。 | packages/services/Car/car-lib/src/android/car/hardware/power |
| CarPowerManagementService 等。 | packages/services/Car/service/src/com/android/car/power |
處理 VHAL 的服務，例如 VehicleHal 和 HAlClient。 |
packages/services/Car/service/src/com/android/car/hal |
| VHAL 介面和屬性定義。 | hardware/interfaces/automotive/vehicle/aidl/android/hardware/automotive/vehicle/ |
範例應用程式，可提供有關 CarPowerManager 的相關資訊 |
packages/services/Car/tests/EmbeddedKitchenSinkApp/src/com/google/android/car/kitchensink |
類別圖
這張類別圖表顯示電源管理系統中的 Java 類別和介面：
圖 4. 電源類別圖表。
物件關係
圖 5 說明哪些物件有其他物件的參照。邊緣表示來源物件保留目標物件的參照。例如，VehicleHAL 有 PropertyHalService 物件的參照。
圖 5. 物件參照圖。