傳感器 HAL 2

傳感器硬件抽象層 (HAL) 是 Android 傳感器框架和設備傳感器(例如加速度計或陀螺儀)之間的接口。傳感器 HAL 定義了必須實現以允許框架控制傳感器的功能。

Sensors HAL 2.0 適用於 Android 10 及更高版本,適用於新設備和升級設備。傳感器HAL 2.0基於傳感器HAL 1.0但有幾個關鍵的差異,這防止它被向後兼容。傳感器HAL 2.0用途快速消息隊列(FMQs)發送傳感器事件從HAL裝入Android傳感器框架。

Sensors HAL 2.1 適用於 Android 11 及更高版本,適用於新設備和升級設備。傳感器HAL 2.1是傳感器HAL 2.0的迭代暴露所述HINGE_ANGLE傳感器類型和更新的各種方法以接受HINGE_ANGLE類型。

HAL 2.1 接口

文檔的用於傳感器HAL 2.1的主要來源是在HAL定義內的硬件/接口/傳感器/ 2.1 / ISensors.hal 。如果有這個頁面之間的需求衝突ISensors.hal ,使用在要求ISensors.hal

HAL 2.0 接口

文檔的用於傳感器HAL 2.0的主要來源是在HAL定義內的硬件/接口/傳感器/ 2.0 / ISensors.hal 。如果有這個頁面之間的需求衝突ISensors.hal ,使用在要求ISensors.hal

實施傳感器 HAL 2.0 和 HAL 2.1

為了實現傳感器HAL 2.0或2.1,對象必須擴展ISensors接口和實現中所定義的所有功能。 2.0/ISensors.hal2.1/ISensors.hal

初始化 HAL

傳感器 HAL 必須由 Android 傳感器框架初始化才能使用。框架調用initialize()為2.0 HAL函數和initialize_2_1()函數用於HAL 2.1提供三個參數的傳感器HAL:二FMQ描述符和一個指針到一個ISensorsCallback對象。

HAL 使用第一個描述符來創建用於將傳感器事件寫入框架的事件 FMQ。該HAL使用第二描述符創建喚醒鎖定FMQ使用時HAL釋放其喚醒鎖同步WAKE_UP傳感器事件。的HAL必須的指針保存到ISensorsCallback對象,以便進行必要的回調函數可以被調用。

initialize()initialize_2_1()函數必須初始化傳感器HAL時調用的第一功能。

暴露可用的傳感器

為了讓所有的設備的可用靜態傳感器的列表,使用getSensorsList()對HAL 2.0和功能getSensorsList_2_1()對HAL 2.1功能。此函數返回一個傳感器列表,每個傳感器都由其句柄唯一標識。當承載傳感器 HAL 的進程重新啟動時,給定傳感器的句柄不得更改。句柄可能會隨著設備重啟和系統服務器重啟而改變。

如果幾個傳感器共享相同的傳感器類型和喚醒屬性,則該列表中的第一傳感器被稱為默認傳感器和返回到利用所述應用程序getDefaultSensor(int sensorType, bool wakeUp)功能。

傳感器列表的穩定性

一個傳感器HAL重啟之後,如果返回的數據getSensorsList()getSensorsList_2_1()表示相比於重新啟動之前檢索到的傳感器列表中的顯著變化,框架觸發的Android運行時的重新啟動。傳感器列表的重大變化包括具有給定句柄的傳感器缺失或屬性更改的情況,或者引入了新傳感器的情況。儘管重新啟動 Android 運行時會對用戶造成乾擾,但這是必需的,因為 Android 框架無法再滿足 Android API 約定,即靜態(非動態)傳感器在應用程序的生命週期內不會發生變化。這也可能會阻止框架重新建立應用程序發出的活動傳感器請求。因此,建議 HAL 供應商防止可避免的傳感器列表更改。

為確保穩定的傳感器句柄,HAL 必須確定性地將設備中的給定物理傳感器映射到其句柄。儘管 Sensors HAL 接口沒有強制要求特定的實現,但開發人員有許多選項可以滿足此要求。

例如,可以使用每個傳感器的固定屬性(例如供應商、型號和傳感器類型)的組合對傳感器列表進行排序。另一種方法依賴於一個事實,即設備的靜態傳感器集是固定的硬件,所以HAL需要當所有預期的傳感器已經完成初始化從返回之前知道getSensorsList()getSensorsList_2_1()這個預期的傳感器列表可以編譯成 HAL 二進製文件或存儲在文件系統的配置文件中,出現的順序可以用於派生穩定句柄。儘管最佳解決方案取決於您的 HAL 的具體實現細節,但關鍵要求是傳感器句柄在 HAL 重新啟動時不會發生變化。

配置傳感器

一個傳感器被激活之前,該傳感器必須以採樣週期和最大延遲報告使用被配置batch()函數。

傳感器必須能夠在任何時候通過重新配置batch()不包括傳感器數據的丟失。

採樣期

根據正在配置的傳感器類型,採樣週期具有不同的含義:

  • 連續:傳感器事件以連續速率生成。
  • On-change:事件的生成速度不會比採樣週期快,如果測量值沒有變化,事件的生成速度可能會慢於採樣週期。
  • 一次性:忽略採樣週期。
  • 特別聲明:欲了解更多詳情,請參閱傳感器類型

要了解一個採樣週期和傳感器的報告模式,看之間的相互作用報告模式

最大報告延遲

最大報告延遲設置了在 SoC 處於喚醒狀態時,事件在通過 HAL 寫入事件 FMQ 之前可以延遲並存儲在硬件 FIFO 中的最長時間(以納秒為單位)。

零值表示必須在測量後立即報告事件,要么完全跳過 FIFO,要么在 FIFO 中出現來自傳感器的一個事件時立即清空 FIFO。

例如,當 SoC 喚醒時,以 50 Hz 激活且最大報告延遲為零的加速度計每秒觸發 50 次中斷。

當最大報告延遲大於零時,無需在檢測到傳感器事件後立即報告。事件可以臨時存儲在硬件 FIFO 中並批量報告,只要沒有事件延遲超過最大報告延遲。自上一批以來的所有事件都會被記錄並立即返回。這減少了發送到 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()函數。

傳感器HAL 2.0 / 2.1同時支持writewriteBlocking在事件FMQ。默認實現提供了使用參考write 。如果writeBlocking使用功能, readNotification標誌必須設置為EventQueueFlagBits::EVENTS_READ ,這是由框架集時,它讀取事件FMQ事件。寫通知標誌必須設置為EventQueueFlagBits::READ_AND_PROCESS ,該通知事件已被寫入事件FMQ的框架。

WAKE_UP 事件

WAKE_UP事件是導致應用處理器(AP)來喚醒,並立即處理該事件傳感器事件。每當WAKE_UP事件被寫入事件FMQ,傳感器HAL必須確保喚醒鎖,以確保系統保持清醒,直到該框架可以處理該事件。一旦接收到WAKE_UP事件,該框架確保自己的喚醒鎖,允許傳感器HAL釋放其喚醒鎖。要在傳感器 HAL 釋放其喚醒鎖時進行同步,請使用喚醒鎖 FMQ。

該傳感器HAL必須讀取喚醒鎖定FMQ確定的數量WAKE_UP ,該框架已處理的事件。該HAL應該只釋放其身後鎖WAKE_UP事件,如果未處理總數WAKE_UP事件為零。處理傳感器事件後,框架計數標記為事件的數量WAKE_UP事件,並寫入這個號碼回喚醒鎖FMQ。

該框架設置WakeLockQueueFlagBits::DATA_WRITTEN在喚醒鎖定FMQ寫通知時,它會將數據寫入喚醒鎖FMQ。

動態傳感器

動態傳感器是物理上不屬於設備但可用作設備輸入的傳感器,例如帶有加速度計的遊戲手柄。

當動態傳感器連接,所述onDynamicSensorConnected在功能ISensorsCallback必須從傳感器HAL被調用。這會通知新動態傳感器的框架,並允許通過框架控制傳感器並讓客戶端使用傳感器的事件。

類似地,當一個動態傳感器斷開,則onDynamicSensorDisconnected在功能ISensorsCallback必須被調用,使得框架可以刪除任何傳感器,其不再可用。

直接渠道

直接通道是一種操作方法,其中傳感器事件被寫入特定內存而不是繞過 Android 傳感器框架寫入事件 FMQ。註冊直接通道的客戶端必須直接從用於創建直接通道的內存中讀取傳感器事件,並且不會通過框架接收傳感器事件。所述configDirectReport()函數類似於batch()用於正常操作和配置直接報告信道。

所述registerDirectChannel()unregisterDirectChannel()函數創建或銷毀一個新的直接通道。

操作模式

所述setOperationMode()函數允許框架來配置的傳感器,使得框架可以注入傳感器數據到傳感器。這對於測試很有用,尤其是對於存在於框架之下的算法。

所述injectSensorData()在HAL 2.0和功能injectSensorsData_2_1()在HAL 2.0功能通常用於操作參數推入傳感器HAL。該函數還可用於將傳感器事件注入特定傳感器。

驗證

要驗證傳感器 HAL 的實施,請運行傳感器 CTS 和 VTS 測試。

CTS 測試

傳感器 CTS 測試存在於自動 CTS 測試和手動 CTS 驗證器應用程序中。

自動化測試位於CTS /測試/傳感器/ SRC /機器人/硬件/ CTS 。這些測試驗證傳感器的標準功能,例如激活傳感器、批處理和傳感器事件率。

在CTS驗證測試位於CTS /應用/ CtsVerifier / src目錄/ COM /安卓/ CTS /驗證/傳感器。這些測試需要測試操作員的手動輸入,並確保傳感器報告準確的值。

通過 CTS 測試對於確保被測設備滿足所有 CDD 要求至關重要。

VTS 測試

對於傳感器HAL 2.0 VTS測試位於硬件/接口/傳感器/ 2.0 / VTS 。對於傳感器HAL 2.1 VTS測試位於硬件/接口/傳感器/ 2.1 / VTS 。這些測試確保傳感器HAL的正常實施和內所有要求ISensors.halISensorsCallback.hal適當滿足。

從 2.0 升級到傳感器 HAL 2.1

當升級到傳感器HAL 2.1 2.0,您的HAL實現必須包括initialize_2_1() getSensorsList_2_1()injectSensorsData_2_1()方法,與HAL 2.1類型在一起。這些方法必須滿足上述 HAL 2.0 概述的相同要求。

由於次要版本 HAL 必須支持以前 HAL 的所有功能,因此 2.1 HAL 必須支持初始化為 2.0 HAL。為避免支持兩個 HAL 版本的複雜性,強烈建議使用 Multi-HAL 2.1。

對於如何實現自己的傳感器2.1 HAL示例,請參見Sensors.h

從 1.0 升級到傳感器 HAL 2.0

從 1.0 升級到 Sensors HAL 2.0 時,請確保您的 HAL 實施滿足以下要求。

初始化 HAL

initialize()函數必須支持建立框架和HAL之間FMQs。

暴露可用的傳感器

在傳感器HAL 2.0中, getSensorsList()函數必須在單個設備引導過程中返回相同的值,甚至可以跨傳感器HAL重新啟動。所述的新要求getSensorsList()函數是它必須在單個設備引導過程中返回相同的值,甚至可以跨傳感器HAL重新啟動。這允許框架在系統服務器重新啟動時嘗試重新建立傳感器連接。返回的值getSensorsList()可以在設備執行在重新啟動之後發生變化。

將傳感器事件寫入 FMQ

與其等待poll()被調用,在傳感器HAL 2.0,傳感器HAL必須主動寫傳感器事件記錄到事件FMQ每當傳感器事件是可用的。該HAL還負責編寫正確的位EventFlag ,以引起FMQ框架內讀取。

WAKE_UP 事件

在傳感器HAL 1.0時,HAL是能夠釋放其喚醒鎖任何WAKE_UP上任何後續呼叫事件poll()之後的WAKE_UP被張貼到poll()因為這表明,框架已經處理了所有的傳感器事件和已經得到的如有必要,喚醒鎖。因為,在傳感器HAL 2.0中,HAL不再當框架已處理寫入FMQ事件都知道,喚醒鎖定FMQ允許的框架內進行溝通時已經處理了HAL WAKE_UP事件。

在傳感器HAL 2.0,之後鎖定由傳感器HAL為確保WAKE_UP事件必須以SensorsHAL_WAKEUP

動態傳感器

使用被送回動態傳感器poll()在傳感器HAL 1.0功能。傳感器HAL 2.0要求onDynamicSensorsConnectedonDynamicSensorsDisconnectedISensorsCallback稱為每當動態傳感器連接的變化。這些回調可用作為一部分ISensorsCallback即通過提供指針initialize()函數。

操作模式

所述DATA_INJECTION為模式WAKE_UP傳感器必須在傳感器HAL 2.0的支持。

多 HAL 支持

傳感器HAL 2.0和2.1支持多HAL使用傳感器多HAL框架。對於實施細節,請參見移植來自傳感器的HAL 1.0