感應器 AIDL HAL

感應器硬體抽象層 (HAL) 是 Android 感應器架構和裝置的感應器，例如加速計或 陀螺儀。感應器 HAL 會定義必須實作的函式 讓架構控制感應器

感應器 AIDL HAL 適用於 Android 13， 。感應器 AIDL HAL 感應器 HAL 2.1 AIDL HAL 介面和 呈現頭部追蹤器和有限軸的 IMU 感應器類型。

AIDL HAL 介面

感應器 AIDL HAL 的主要說明文件來源為 HAL 定義 hardware/interfaces/sensors/aidl/android/hardware/sensors/ISensors.aidl。

導入感應器 AIDL HAL

如要導入感應器 AIDL HAL，物件必須擴充 ISensors 並實作 hardware/interfaces/sensors/aidl/android/hardware/sensors/ISensors.aidl。

初始化 HAL

感應器 HAL 必須先由 Android 感應器架構初始化 。架構會呼叫 initialize() 函式來提供三個 參數提供給感應器 HAL：兩個 FMQ 描述元，以及一個指向 ISensorsCallback 物件。

HAL 會使用第一個描述元建立用於寫入感應器的事件 FMQ 將事件加入架構HAL 會使用第二個描述元建立 Wake 鎖定 FMQ 在 HAL 為「WAKE_UP」釋出 Wake Lock 時執行同步處理作業 感應器事件HAL 必須儲存指標至 ISensorsCallback 物件， 能叫用任何必要的回呼函式。

initialize() 函式必須是初始化時呼叫的第一個函式 感應器 HAL

公開可用的感應器

如要取得裝置上所有可用的靜態感應器清單，請使用 getSensorsList() 函式。這個函式會傳回感應器清單 分別以帳號代碼識別。不得變更特定感應器的控點 物件在託管感應器 HAL 的重新啟動程序時帳號代碼可能會有變動 裝置重新啟動以及系統伺服器重新啟動時

如果多個感應器共用相同的感應器類型和喚醒屬性，則 清單中的第一個感應器稱為 default 感應器，並傳回 使用 getDefaultSensor(int sensorType, bool wakeUp) 的應用程式 函式。

感應器清單的穩定性

感應器 HAL 重新啟動後 (如果 getSensorsList() 傳回的資料) 表示與 架構會觸發系統重新啟動 Android 執行階段。感應器清單的重大變化包括 含有指定帳號代碼的感應器遺失、屬性已變更，或是有新的 感應器雖然重新啟動 Android 執行階段會中斷 由於 Android 架構無法再符合使用者的要求 在測試期間，靜態 (非動態) 感應器在 應用程式的生命週期這也可以防止架構重新建立 應用程式發出的主動感應器要求。因此，建議 HAL 供應商 可防止性感應器清單發生變更。

為確保感應器能穩定地處理，HAL 必須以確定性的方式對應指定的 並將裝置內的實體感應器與相應控制代碼接上。雖然沒有具體的導入作業 由感應器 HAL 介面強制執行，開發人員有許多選項 以符合這項條件

舉例來說，只要使用各個感應器的組合，就能排序感應器清單 固定屬性，例如廠商、型號和感應器類型另一個做法是 原因是裝置的靜態感應器集固定在硬體中，因此 HAL 需知道所有預期的感應器何時完成初始化 從 getSensorsList() 傳回。這份清單 可將感應器編譯為 HAL 二進位檔，或儲存在 並使用外觀順序 才能導出穩定的控點雖然最佳解決方案取決於 HAL 的 具體的實作細節，關鍵要求是感應器會 HAL 重新啟動時不會改變

設定感應器

啟用感應器前，必須先設定取樣功能 使用 batch() 函式，分析時間範圍和最長報表延遲時間。

隨時都能使用 batch() 重新設定感應器，無須安裝 導致感應器資料遺失

取樣期間

取樣期間的意義會因感應器類型而異 設定中：

• 連續：感應器事件會以連續速率產生。
• 變更時：事件產生速度不會比取樣期間更快，且可能會 發生率低於取樣期間 (如果測量值) 它不會有任何改變
• 單一：略過取樣期間。
• 特殊：如需更多詳細資訊，請參閱 感應器類型。

瞭解取樣期間與感應器的互動方式 報表模式，請參閱「報表模式」。

最大報表延遲時間

報表延遲時間上限，則是以奈秒為單位 事件可能會延遲並儲存在硬體 FIFO 之後 在 SoC 處於喚醒狀態時透過 HAL 回報事件 FMQ

如果這個值為 0，表示必須在發生事件時立即回報 進行測量，例如完全跳過 FIFO，或是盡快清空 FIFO FIFO 偵測到感應器發出的一個事件

舉例來說，以 50 Hz 的加速計啟動，而且回報上限 延遲時間 在 SoC 喚醒時，零觸發條件每秒會中斷 50 次。

如果最大回報延遲時間大於零，感應器事件不會 就必須在系統偵測到。活動可暫時顯示 並批次回報 延遲時間可能會超過報表延遲時間上限自 然後一次記錄並傳回前一個批次這樣可減少 中斷傳送至 SoC，並讓 SoC 切換到低耗電模式 並等待感應器擷取資料及批次處理資料。

每個事件都有相關的時間戳記。延後 應該不會影響事件的時間戳記。時間戳記須為 準確且符合事件實際發生的時間 。

想進一步瞭解如何透過 將報表延遲時間上限設為零，請參閱批次處理。

啟用感應器

這個架構使用 activate() 函式啟用及停用感應器。 必須先設定感應器，才能啟用感應器 使用 batch()。

停用感應器後，該感應器的其他感應器事件不得再發生 寫入活動 FMQ

清除感應器

如果將感應器設為批次處理感應器資料，架構就能強制 呼叫 flush() 可立即清除批次感應器事件。這會導致 指定的感應器處理常式批次處理感應器事件 寫入活動 FMQ感應器 HAL 必須附加一個清除完成事件 例外狀況 (因為呼叫 flush()。

清除作業以非同步方式進行，也就是說，此函式必須傳回 )。 如果實作項目針對多個感應器使用單一 FIFO，該 FIFO 就會是 且只會為指定的感應器新增清除完成事件。

如果指定的感應器沒有 FIFO (無法進行緩衝處理)，或 FIFO 在呼叫時空白，flush() 仍必須成功並傳送清除 觸發事件的完整事件除了單一鏡頭之外，所有感應器都會採用這項設定 感應器。

如果針對一次性感應器呼叫 flush()，則 flush() 必須傳回 BAD_VALUE，而不是產生清除完整事件。

將感應器事件寫入 FMQ

感應器 HAL 會使用事件 FMQ 將感應器事件推送到 Android 感應器架構

活動 FMQ 是同步的 FMQ，也就是說 向 FMQ 傳送事件時， 其二是權限，定義可執行的操作 例如讀取或寫入在這種情況下，HAL 應決定是否寫入目前的集合 將事件視為兩個小型事件群組，或用於寫入所有事件 因為有足夠空間時 就能整合在一起

當感應器 HAL 將所需數量的感應器事件寫入 事件 FMQ 時，感應器 HAL 必須通知架構，表示事件已 將 EventQueueFlagBits::READ_AND_PROCESS 位元寫入事件 FMQ 的 EventFlag::wake 函式。事件旗標可從事件 FMQ 建立 使用EventFlag::createEventFlag和事件 FMQ 的getEventFlagWord() 函式。

感應器 AIDL HAL 可支援事件 FMQ 的 write 和 writeBlocking。 預設實作方式提供使用 write 的參照。如果 如果使用 writeBlocking 函式，則 readNotification 旗標必須設為 EventQueueFlagBits::EVENTS_READ，由架構在讀取時設定 事件。寫入通知旗標必須設為 EventQueueFlagBits::READ_AND_PROCESS，用於通知事件相關架構 。

WAKE_UP 事件

WAKE_UP 事件是會導致應用程式處理器 (AP) 的感應器事件 立即喚醒並處理事件。每當寫入 WAKE_UP 事件時 偵測事件 FMQ 時，感應器 HAL 必須保護 Wake Lock，確保 在架構可以處理事件之前，系統都處於喚醒狀態。收到 WAKE_UP 事件，架構會保護自己的 Wake Lock，讓 感應器 HAL 即可釋放 Wake Lock。在感應器 HAL 時同步 放開 Wake Lock FMQ

感應器 HAL 必須讀取 Wake Lock FMQ 才能判斷「WAKE_UP」的數量 管理架構處理過的事件HAL 應該只釋放其 Wake Lock 如果未處理的 WAKE_UP 事件總數為零，則適用於 WAKE_UP 事件。 處理感應器事件後，此架構會計算已發生 標示為 WAKE_UP 事件，並將這個數字寫回 Wake Lock FMQ。

架構會設定 WakeLockQueueFlagBits::DATA_WRITTEN 寫入功能 Wake Lock FMQ 播放通知。

動態感應器

動態感應器不是實際位於裝置的一部分，但可以 做為裝置的輸入來源，例如帶有加速計的遊戲手把。

動態感應器連接後，onDynamicSensorConnected 必須從感應器 HAL 呼叫 ISensorsCallback。這會通知 新的動態感應器架構，並讓感應器能控制 感應器事件，並要求用戶端使用感應器的事件。

同樣地，當動態感應器中斷連線時， 必須呼叫 ISensorsCallback 中的 onDynamicSensorDisconnected 函式，才能 該架構可移除任何已不再提供的感應器。

直接管道

直接管道是寫入感應器事件的一種作業方法 特定記憶體，而不是讓事件 FMQ 略過 Android 感應器 架構。註冊直接通道的用戶端必須讀取感應器事件 直接從用於建立直接通道的記憶體中取得 以便透過架構接收感應器事件configDirectReport() 函式與 batch() 相似，用於一般作業，並將 檢舉管道。

registerDirectChannel() 和 unregisterDirectChannel() 函式會建立 或刪除新的直接頻道

作業模式

setOperationMode() 函式可讓架構設定感應器 ，這樣架構才能將感應器資料插入感應器這對於使用者 尤其是架構底下的演算法

injectSensorData() 函式通常用於推送作業 新增至感應器 HAL這個函式也可用於插入感應器 擷取到特定感應器中的資料

驗證

如要驗證感應器 HAL 的實作情況，請執行感應器 CTS 和 VTS 測試。

CTS 測試

感應器 CTS 測試同時存在於自動化 CTS 測試和手動 CTS Verifier 中 應用程式。

自動測試位於 cts/tests/sensor/src/android/hardware/cts。 這些測試可驗證感應器的標準功能，例如啟用 例如感應器、批次處理和感應器事件發生率

CTS 驗證器測試位於 cts/apps/CtsVerifier/src/com/android/cts/verifier/sensors。 這些測試必須由測試作業人員手動輸入，並確保感應器 準確回報值

要確保受測試的裝置可通過測試，就必須通過 CTS 測試 符合所有 CDD 要求。

VTS 測試

感應器 AIDL HAL 的 VTS 測試位於 hardware/interfaces/sensors/aidl/vts/， 這些測試可確保感應器 HAL 已正確實作 已確實滿足 ISensors.aidl 和 ISensorsCallback.aidl 的要求。

初始化 HAL

必須支援 initialize() 函式，才能在 不僅如此

公開可用的感應器

在感應器 AIDL HAL 中，getSensorsList() 函式必須傳回相同的值 也會同步執行這些動作新規定 getSensorsList() 函式必須在測試期間傳回相同的值 存取單一裝置，甚至在感測器 HAL 重新啟動後 也能繼續啟動這樣一來 如果系統伺服器，嘗試重新建立感應器連線的架構 就會重新啟動。裝置之後，getSensorsList() 傳回的值可能會有所變更 就會重新啟動。

將感應器事件寫入 FMQ

在感應器 AIDL HAL 中，感應器不必等待系統呼叫 poll() HAL 必須在每次感應器事件時，主動將感應器事件寫入事件 FMQ 可以使用。HAL 也負責將正確的位元寫入 EventFlag 會在架構內進行 FMQ 讀取。

WAKE_UP 事件

在感應器 HAL 1.0 中，HAL 能夠釋放任何 WAKE_UP 的 Wake Lock 事件 (WAKE_UP 發布至 poll() 之後) 任何後續呼叫的事件 poll()，因為這代表架構已處理所有感應器 而且已視需要取得 Wake Lock所以在 Sensors AIDL 中 HAL 不再收到架構處理事件的通知 Wake Lock FMQ 可讓該架構與 FMQ 通訊 HAL (處理 WAKE_UP 事件時)。

在感應器 AIDL HAL 中，由感應器 HAL 保護的 Wake Lock，時間長度為 WAKE_UP 事件的開頭必須是 SensorsHAL_WAKEUP。

動態感應器

系統已使用 HAL 1.0 感應器中的 poll() 函式傳回動態感應器。 如要使用感應器 AIDL HAL，onDynamicSensorsConnected 和 ISensorsCallback 中的 onDynamicSensorsDisconnected 會在每次動態產生時呼叫 感應器連線變更。這些回呼可在 透過 initialize() 函式提供的 ISensorsCallback 指標。

作業模式

必須支援 WAKE_UP 感應器的 DATA_INJECTION 模式。

支援多種 HAL

感應器 AIDL HAL 支援使用 感應器多 HAL 架構。適用對象 實作詳細資料，請參閱 從感應器 HAL 2.1 移植。