電源統計資料 HAL

裝置子系統的電源通常會在實驗室環境中測量及記錄，以便瞭解各種穩定狀態，例如螢幕開啟或裝置處於閒置電源狀態時的情況。這項方法適用於持續耗電的子系統，或在實驗室環境中容易測量的條件下，但不適用於特定用途，例如螢幕顯示影片時。

IPower.hal 1.0 提供介面，可傳遞 電源提示，並回報子系統睡眠狀態指標的累積資料。在 Android 10 以上版本中，累積統計資料回報功能位於 IPowerStats.hal 電源統計資料收集 API 中，並提供擷取裝置上能源用量資料的方法。這會取代 IPower.hal 介面的累積統計資料收集部分，以便更清楚地區分功能。

IPowerStats 服務讀數並非定期。這些事件會在關鍵時刻發生，例如電池電量下降 1% 時。電池耗電量低時，讀取次數會減少，耗電量高時則會增加。資料可能會傳回伺服器，並用於分析和分類錯誤報告。這有助於我們持續降低耗電量並延長電池續航力。

IPower.hal 和 IPowerStats.hal

IPower.hal 和 IPowerStats.hal 介面皆可在 Android 10 上使用，但 IPower.hal 統計資料收集功能僅可透過 IPowerStats.hal 介面使用。IPowerStats.hal 功能包含 API，可取得並使用針對支援裝置的裝置端電量測量收集到的資料：

  • 針對低頻率 (getRailInfo) 和高頻率 (streamEnergyData) 用戶端執行軌道層級能源測量，並回報自啟動以來累積的能源。
  • 回報與每個支援的 PowerEntity 相關的資訊，這些資訊可供使用。PowerEntity 是影響裝置總耗電量的平台子系統、周邊裝置或電源領域。
  • 回報指定實體提供居住資料的電源實體狀態集合 (getPowerEntityStateInfo)，然後回報每個指定 PowerEntity 的累積資料。

IPowerStats.hal API 可供下列用戶端使用：

  • Statsd，用於收集每個電源線的電力消耗量指標。
  • Perfetto，以便將耗電量與 CPU 活動建立關聯。
  • Batterystats，以便使用測量資料改善電池歸因，而非根據 power_profile.xml. 中預先定義的常數估算電池耗電量

在 Android 10 以上版本中，裝置製造商可以選擇 IPower.hal 和 IPowerStats.hal 功能，但如果未實作 IPowerStats.hal，則所有用戶端都必須改用 IPower.hal。

IPowerStats.hal 實作選項

只有 IPower.hal 函式可在 Android 7 到 Android 9 之間的版本使用。已升級至 Android 10 的裝置必須具備硬體電源監控子系統，或其他可用於監控及記錄電源統計資料的工具。部分 SoC 會為您收集電源使用統計資料，您也可以透過軟體取得電源實體狀態停留資訊。只有在需要支援 getRailInfo()、getEnergyData() 和 streamEnergyData() 時，才需要電源監控硬體。

如果您在沒有電源監控硬體的情況下實作 IPowerStats.hal，getRailInfo(), getEnergyData() 和 streamEnergyData() 會傳回 NOT_SUPPORTED。同樣地，getPowerEntityInfo(), getPowerEntityStateInfo() 和 getPowerEntityStateResidencyData() 也可能會在未預期使用 NOT_SUPPORTED 時傳回 NOT_SUPPORTED。

軌道監控 API 傳回的資料範例包括：

  • 螢幕的電源軌耗用了 X µW。
  • 數據機的電源軌耗用了 Y µW。

子系統睡眠狀態 API 傳回的資料範例包括：

  • 數據機處於休眠狀態 X 毫秒。
  • SoC 處於電源收縮狀態 Y 毫秒。
  • GPU 處於暫停狀態的時間為 Z 毫秒。

使用硬體電源監控子系統

如果裝置設計含有硬體電源監控子系統，請建立單一 sysfs 節點，讓 PowerStats.hal 能夠剖析資料，或建立 ioctl 類型系統呼叫的集合，藉此實作 IPowerStats.hal。

您必須以可防止累加器溢位的方式實作核心驅動程式。使用的演算法取決於您獨特的硬體電源監控子系統設計，該設計必須提供瞬間和平均匯流排電壓和電流測量值。核心驅動程式必須以不會清除能量累積器的方式擷取這類資料，且必須保留自啟動以來每個子軌的累積能量資料，以 64 位元變數的形式，隨著每個累積器查詢的能量讀數遞增。

特定元件 (或選用的多個元件) 的統計資料必須位於單一節點中。雖然這不是 sysfs 的傳統用途 (通常會將每個節點限制為單一值)，但可確保所有資料一致。

設計指南

  • 從 sysfs 節點讀取或進行系統呼叫時，請保持低延遲 (最多 1 毫秒)。
  • 請確認支援統計資料功能不會明顯增加耗電量：
    • 請勿增加存取點 (AP) 和/或子系統喚醒，以便追蹤參數，例如在睡眠模式中花費的時間。
    • 盡可能在應用程式處理器和韌體之間轉移統計資料，並利用其他流量。
  • 必要時，子系統可能會使用下列驅動程式函式：
    • 在內部快取資料，以免產生延遲/喚醒，但會導致資料略為過時。
    • 在子系統處於休眠狀態時執行外推，以便在未喚醒子系統的情況下提供更新的休眠時間。

選擇元件、子系統和統計資料

選擇要收集 IPowerStats.hal 資料的元件或子系統時，請選取裝置上任何耗電量較高 (5 mA 以上) 或支援多種耗電模式的元件或子系統，例如：

  • 個別 SoC 子系統。
  • 部分或完全位於 SoC 外部的子系統，例如 Wi-Fi、影像處理器或安全性處理器。
  • 周邊裝置，例如高功率 LED 和攝影機。
  • 使用不同模式的電源域 (例如 SoC 整體的電源域)。

自訂

這項選用功能可自訂。設計用途並自訂用途：

  • 決定要評估哪些軌道，以及評估頻率。
  • 決定讀取資料的時機和解讀方式。
  • 根據資料決定採取哪些行動，以及何時採取行動。

驗證

VTS 測試可確保應用程式符合 Android 需求。IPowerStats.hal 中的註解可用於驗證裝置是否符合規定。

舉例來說，如果您呼叫 getRailInfo() 但未傳回任何內容，VTS 測試就會失敗，因為您沒有收到監控的軌道資訊，或是傳回的狀態為 SUCCESS。同樣地，如果您收到軌道資訊，但隨附 NON_SUPPORTED 或 FILE_SYSTEM_ERROR 回應，這也是失敗。VTS 會使用 IPower.hal 和 IPowerStats.hal 註解中的規定，驗證 HAL 檔案是否遵循裝置製造商規格。以下是 VTS 測試中使用的註解範例：

/**
* Rail information:
* Reports information related to the rails being monitored.
*
* @return rails Information about monitored rails.
* @return status SUCCESS on success or NOT_SUPPORTED if
* feature is not enabled or FILESYSTEM_ERROR on filesystem nodes
* access error.
*/
getRailInfo()
generates(vec<e;RailInfo>e; rails, Status status);