感應器多 HAL

Sensors Multi-HAL 是一種架構，可讓感應器 HAL 與其他感應器 HAL 一併執行。Sensors Multi-HAL 會動態載入以供應商分區中的動態程式庫形式儲存的感應器子 HAL，並為其提供可處理發布事件，以及取得及釋出喚醒鎖的回呼物件。感應器子 HAL 是感應器 HAL，已建構至供應商分區的共用物件，並由多 HAL 架構使用。這些子 HAL 不會彼此依賴，也不會依賴包含處理程序主要函式的多 HAL 程式碼。

Sensors Multi-HAL 2.1 適用於搭載 Android 11 以上版本的裝置，是 Sensors Multi-HAL 2.0 的迭代版本，可支援載入可公開鉸鏈角度感應器類型的子 HAL。如要支援此感應器類型，子 HAL 必須使用 2.1 子 HAL 標頭中定義的子 HAL API。

如果裝置搭載 Android 13 以上版本，且使用 Sensors AIDL HAL，您可以使用多 HAL 修補層，啟用多 HAL 功能。如需實作詳細資訊，請參閱「使用 Sensors Multi-HAL 搭配 Sensors AIDL HAL」。

Sensors Multi-HAL 2 與 Sensors HAL 2 的差異

在搭載 Android 10 以上版本的裝置上，可使用 Sensors Multi-HAL 2，這項技術在 Sensors HAL 2 之上引入多個抽象概念，可讓您更輕鬆地與 HAL API 互動。Sensors Multi-HAL 2 會導入 HalProxy 類別，用於處理 Sensors HAL 2 介面和 V2_1/SubHal (或 V2_0/SubHal) 介面，讓 HalProxy 與子 HAL 互動。

ISensorsSubHal 介面與 2.1/ISensors.hal (或 2.0/ISensors.hal) 介面有以下差異：

  • 初始化方法會傳遞 IHalProxyCallback 類別，而非兩個 FMQ 和 ISensorsCallback。
  • 子 HAL 必須實作偵錯函式，才能在錯誤報告中提供偵錯資訊。
  • 子 HAL 必須實作名稱函式，才能將已載入的子 HAL 與其他子 HAL 區分開來。

Sensors Multi-HAL 2 和 Sensors HAL 2 的主要差異在於初始化函式。IHalProxyCallback 介面不提供 FMQ，而是提供兩種方法，一種方法可將感應器事件發布至感應器架構，另一種方法則可建立喚醒鎖定。在幕後，Sensors Multi-HAL 會管理與 FMQ 的所有互動，確保所有子 HAL 都能及時收到感應器事件。強烈建議子 HAL 使用 createScopedWakelock 方法，將喚醒鎖定逾時的負擔委派給 Sensors Multi-HAL，並將喚醒鎖定用途集中在整個 Sensors Multi-HAL 的一個常見喚醒鎖定上，藉此減少鎖定和解鎖的呼叫。

Sensors Multi-HAL 2 也內建了一些安全功能。它會處理感應器 FMQ 已滿的情況，或是 Android 感應器架構重新啟動且需要重設感應器狀態的情況。此外，當事件發布至 HalProxy 類別，但感應器架構無法立即接受事件時，Sensors Multi-HAL 可以將事件移至背景執行緒，以便在等待事件發布時，讓所有子 HAL 繼續執行工作。

原始碼和參考實作

所有 Sensors Multi-HAL 程式碼皆可在 hardware/interfaces/sensors/common/default/2.X/multihal/ 中使用。以下提供一些資源的指標。

實作

本節說明如何在下列情況下實作 Sensors Multi-HAL：

搭配使用 Sensors AIDL HAL 和 Sensors Multi-HAL

如要讓 Sensors AIDL HAL 支援多 HAL 功能，請匯入 AIDL Multi-HAL 墊片層模組，位於 hardware/interfaces/sensors/aidl/default/multihal/。這個模組會處理 AIDL 和 HIDL 感應器 HAL 定義類型之間的轉換，並在 實作感應器多重 HAL 2.1 中所述的多重 HAL 介面周圍定義包裝函式。AIDL 多重 HAL 墊片層與實作 Sensors Multi-HAL 2.1 的裝置相容。

AIDL 多重 HAL 墊片層可讓您在 Sensors AIDL HAL 中公開頭部追蹤器和有限軸 IMU 感應器類型。如要使用 AIDL HAL 介面定義的這些感應器類型，請在 getSensorsList_2_1() 實作中設定 SensorInfo 結構體中的 type 欄位。這是安全的做法，因為 AIDL 和 HIDL 感應器 HAL 的整數支援感應器類型欄位不會重疊。

實作 Sensors Multi-HAL 2.1

如要在新裝置上實作 Sensors Multi-HAL 2.1，請按照下列步驟操作：

  1. 按照 SubHal.h 所述，實作 ISensorsSubHal 介面。
  2. 在 SubHal.h 中實作 sensorsHalGetSubHal_2_1 方法。

  3. 新增 cc_library_shared 目標，以建構新實作的子 HAL。新增目標時：

    1. 請確認目標已推送至裝置供應商分區的某處。
    2. 在位於 /vendor/etc/sensors/hals.conf 的設定檔中，在新行中新增程式庫的路徑。視需要建立 hals.conf 檔案。

    如需建構子 HAL 程式庫的範例 Android.bp 項目，請參閱 hardware/interfaces/sensors/common/default/2.X/multihal/tests/Android.bp。

  4. 從 manifest.xml 檔案中移除所有 android.hardware.sensors 項目，該檔案包含裝置支援的 HAL 清單。

  5. 從 device.mk 檔案中移除所有 android.hardware.sensors 服務和 service.rc 檔案，並將 android.hardware.sensors@2.1-service.multihal 和 android.hardware.sensors@2.1-service.multihal.rc 新增至 PRODUCT_PACKAGES。

在啟動時，HalProxy 會啟動並尋找新實作的子 HAL，然後呼叫 sensorsHalGetSubHal_2_1 來初始化。

從 Sensors Multi-HAL 2.0 移植至 Multi-HAL 2.1

如要從 Multi-HAL 2.0 移植至 Multi-HAL 2.1，請實作 SubHal 介面，並重新編譯子 HAL。

以下是 2.0 和 2.1 版 SubHal 介面之間的差異：

  • IHalProxyCallback 會使用 ISensors.hal 規格 2.1 版中建立的類型。
  • initialize() 函式會傳遞新的 IHalProxyCallback，而非 2.0 SubHal 介面的 SubHal
  • 子 HAL 必須實作 getSensorsList_2_1 和 injectSensorData_2_1，而非 getSensorsList 和 injectSensorData，因為這些方法使用 ISensors.hal 規格 2.1 版新增的新類型。
  • 子 HAL 必須公開 sensorsHalGetSubHal_2_1，而非 sensorsHalGetSubHal，才能讓 Multi-HAL 將其視為 2.1 版子 HAL。

從 Sensors HAL 2.0 移植

從 Sensors HAL 2.0 升級至 Sensors Multi-HAL 2.0 時，請確認 HAL 實作符合下列規定。

初始化 HAL

Sensors HAL 2.0 提供初始化函式，可讓感應器服務傳遞 FMQ 和動態感應器回呼。在 Sensors Multi-HAL 2.0 中，initialize() 函式會傳遞單一回呼，該回呼必須用於發布感應器事件、取得喚醒鎖定，以及通知動態感應器連線和中斷連線。

將感應器事件張貼至 Multi-HAL 實作

當感應器事件可用時，子 HAL 必須將感應器事件寫入 IHalProxyCallback，而非透過 FMQ 發布感應器事件。

WAKE_UP 事件

在 Sensors HAL 2.0 中，HAL 可管理喚醒鎖定功能的實作方式。在 Sensors Multi-HAL 2.0 中，子 HAL 可讓 Multi-HAL 實作項目管理喚醒鎖定，並可透過叫用 createScopedWakelock 要求取得喚醒鎖定。將喚醒事件發布至多重 HAL 實作時，必須取得並將鎖定的醒鎖範圍傳遞至 postEvents。

動態感應器

根據 Sensors Multi-HAL 2.0 的規定，每當動態感應器連線發生變更時，就會呼叫 IHalProxyCallback 中的 onDynamicSensorsConnected 和 onDynamicSensorsDisconnected。這些回呼可用於透過 initialize() 函式提供的 IHalProxyCallback 指標。

從 Sensors HAL 1.0 移植

從 Sensors HAL 1.0 升級至 Sensors Multi-HAL 2.0 時，請確認 HAL 實作符合下列規定。

初始化 HAL

必須支援 initialize() 函式，才能在子 HAL 和多 HAL 實作之間建立回呼。

公開可用的感應器

在 Sensors Multi-HAL 2.0 中，getSensorsList() 函式必須在單一裝置啟動期間傳回相同的值，即使跨越感應器 HAL 重新啟動也一樣。這樣一來，如果系統伺服器重新啟動，架構就能嘗試重新建立感應器連線。裝置重新啟動後，getSensorsList() 傳回的值可能會變更。

將感應器事件張貼至 Multi-HAL 實作

在 Sensors HAL 2.0 中，如果感應器事件可用，子 HAL 必須主動將感應器事件寫入 IHalProxyCallback，而非等待 poll() 的呼叫。

WAKE_UP 事件

在 Sensors HAL 1.0 中，HAL 可以管理喚醒鎖定功能的實作方式。在 Sensors Multi-HAL 2.0 中，子 HAL 可讓 Multi-HAL 實作項目管理喚醒鎖定，並可透過叫用 createScopedWakelock 要求取得喚醒鎖定。將喚醒事件發布至多重 HAL 實作時，必須取得並將鎖定的醒鎖範圍傳遞至 postEvents。

動態感應器

在 Sensors HAL 1.0 中，動態感應器會透過 poll() 函式傳回。根據 Sensors Multi-HAL 2.0 的規定，每當動態感應器連線發生變更時，就會呼叫 IHalProxyCallback 中的 onDynamicSensorsConnected 和 onDynamicSensorsDisconnected。這些回呼可用於透過 initialize() 函式提供的 IHalProxyCallback 指標。

從 Sensors Multi-HAL 1.0 移植

如要從 Sensors Multi-HAL 1.0 移植現有實作項目，請按照下列步驟操作。

  1. 請確認感應器 HAL 設定位於 /vendor/etc/sensors/hals.conf。這可能會涉及移動位於 /system/etc/sensors/hals.conf 的檔案。
  2. 請移除任何參照 hardware/hardware.h 和 hardware/sensors.h 的內容，因為 HAL 2.0 不支援這些項目。
  3. 請參閱「從 Sensors Hal 1.0 移植」一文，瞭解如何移植子 HAL。
  4. 按照「實作 Sensors Mutli-HAL 2.0」一節中的步驟 3 和 4，將 Sensors Multi-HAL 2.0 設為指定的 HAL。

驗證

執行 VTS

將一或多個子 HAL 與 Sensors Multi-Hal 2.1 整合後，請使用供應商測試套件 (VTS)，確保子 HAL 實作符合 Sensors HAL 介面設定的所有需求。

如要在主機上設定 VTS 時，只執行感應器 VTS 測試，請執行下列指令：

vts-tradefed run commandAndExit vts \
    --skip-all-system-status-check \
    --primary-abi-only \
    --skip-preconditions \
    --module VtsHalSensorsV2_0Target && \
  vts-tradefed run commandAndExit vts \
    --skip-all-system-status-check \
    --primary-abi-only \
    --skip-preconditions \
    --module VtsHalSensorsV2_1Target

如果您執行 AIDL 多 HAL 墊片層，請執行 VtsAidlHalSensorsTargetTest。

vts-tradefed run commandAndExit vts \
    --skip-all-system-status-check \
    --primary-abi-only \
    --skip-preconditions \
    --module VtsAidlHalSensorsTargetTest

執行單元測試

HalProxy_test.cpp 中的單元測試會使用假的子 HAL 測試 HalProxy，這些假的子 HAL 會在單元測試中例項化，且不會動態載入。建立新的子 HAL 時，這些測試應可做為指南，說明如何新增單元測試，驗證新子 HAL 是否已正確實作。

如要執行測試，請執行下列指令：

cd $ANDROID_BUILD_TOP/hardware/interfaces/sensors/common/default/2.X/multihal/tests
atest

使用假的子 HAL 進行測試

虛假子 HAL 是 ISensorsSubHal 介面的虛擬實作項目。子 HAL 會公開不同的感應器清單。感應器啟用後，會根據特定感應器要求中指定的間隔，定期將自動產生的感應器事件發布至 HalProxy。

假的子 HAL 可用於測試完整的多 HAL 程式碼如何與系統中載入的其他子 HAL 搭配運作，並測試 Sensors 多 HAL 程式碼的各個面向。

hardware/interfaces/sensors/common/default/2.X/multihal/tests/fake_subhal/ 提供兩個假的子 HAL。

如要建構並將假的子 HAL 推送至裝置，請執行下列步驟：

  1. 執行下列指令，建構並將三個不同的假冒子 HAL 推送至裝置：

    $ANDROID_BUILD_TOP/hardware/interfaces/sensors/common/default/2.X/multihal/tests/
mma
adb push \
  $ANDROID_BUILD_TOP/out/target/product/<device>/symbols/vendor/lib64/android.hardware.sensors@2.X-fakesubhal-config1.so \
  /vendor/lib64/android.hardware.sensors@2.X-fakesubhal-config1.so
adb push \
  $ANDROID_BUILD_TOP/out/target/product/<device>/symbols/vendor/lib64/android.hardware.sensors@2.X-fakesubhal-config2.so \
  /vendor/lib64/android.hardware.sensors@2.X-fakesubhal-config2.so
adb push \
  $ANDROID_BUILD_TOP/out/target/product/<device>/symbols/vendor/lib64/android.hardware.sensors@2.X-fakesubhal-config3.so \
  /vendor/lib64/android.hardware.sensors@2.X-fakesubhal-config3.so

  2. 使用假的子 HAL 路徑，更新 /vendor/etc/sensors/hals.conf 中的感應器 HAL 設定。

    /vendor/lib64/android.hardware.sensors@2.X-fakesubhal-config1.so
/vendor/lib64/android.hardware.sensors@2.X-fakesubhal-config2.so
/vendor/lib64/android.hardware.sensors@2.X-fakesubhal-config3.so

  3. 重新啟動 HalProxy，並載入設定檔中列出的新子 HAL。

    adb shell stop
adb shell start

偵錯

開發人員可以使用 lshal 指令對架構進行偵錯。如要要求 Sensors HAL 的偵錯輸出內容，請執行下列指令：

adb root
adb shell lshal debug android.hardware.sensors@2.1::ISensors/default

接著，系統會將 HalProxy 及其子 HAL 的目前狀態資訊輸出至終端機。以下是 HalProxy 物件和假的子 HAL 的指令輸出範例。

Internal values:
  Threads are running: true
  Wakelock timeout start time: 200 ms ago
  Wakelock timeout reset time: 73208 ms ago
  Wakelock ref count: 0
  # of events on pending write queue: 0
  # of non-dynamic sensors across all subhals: 8
  # of dynamic sensors across all subhals: 0
SubHals (2):
  Name: FakeSubHal-OnChange
  Debug dump:
Available sensors:
Name: Ambient Temp Sensor
Min delay: 40000
Flags: 2
Name: Light Sensor
Min delay: 200000
Flags: 2
Name: Proximity Sensor
Min delay: 200000
Flags: 3
Name: Relative Humidity Sensor
Min delay: 40000
Flags: 2
  Name: FakeSubHal-OnChange
  Debug dump:
Available sensors:
Name: Ambient Temp Sensor
Min delay: 40000
Flags: 2
Name: Light Sensor
Min delay: 200000
Flags: 2
Name: Proximity Sensor
Min delay: 200000
Flags: 3
Name: Relative Humidity Sensor
Min delay: 40000
Flags: 2

如果 # of events on pending write queue 指定的數字為大數字 (1000 以上)，表示有許多事件待寫入至感應器架構。這表示感應器服務發生死結或已停止運作，且未處理感應器事件，或是最近從子 HAL 發布大量感應器事件。

如果 Wake Lock 參照計數大於 0，表示 HalProxy 已取得 Wake Lock。只有在 ScopedWakelock 有意保留，或是喚醒事件已傳送至 HalProxy，但未經由感應器架構處理的情況下，才應大於 0。

傳遞至 HalProxy 偵錯方法的檔案描述元會傳遞至每個子 HAL，因此開發人員必須將偵錯方法實作為 ISensorsSubHal 介面的一部分。