感應器多 HAL

感應器多重 HAL 是一種架構，可讓感應器 HAL 與其他感應器 HAL 一併執行。感應器 Multi-HAL 會動態載入感應器子 HAL，這些子 HAL 儲存在供應商分割區中做為動態程式庫，並提供可處理發布事件、取得及釋放喚醒鎖定的回呼物件。感應器子 HAL 是感應器 HAL，內建於供應商分割區的共用物件，且由多重 HAL 架構使用。這些子 HAL 不會相互依附，也不會依附於包含程序主要函式的多重 HAL 程式碼。

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

如果裝置搭載 Android 13 以上版本，並使用 Sensors AIDL HAL，您可以透過多重 HAL 墊片層啟用多重 HAL 功能。如需實作詳細資料，請參閱「搭配感應器 AIDL HAL 使用感應器 Multi-HAL」。

感應器 Multi-HAL 2 與感應器 HAL 2 的差異

感應器 Multi-HAL 2 適用於搭載 Android 10 以上版本的裝置，在感應器 HAL 2 的基礎上導入多項抽象化功能，方便與 HAL API 互動。感應器 Multi-HAL 2 導入 HalProxy 類別，用於處理感應器 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：一種是將感應器事件發布至感應器架構，另一種是建立喚醒鎖定。在幕後，感應器多重 HAL 會管理與 FMQ 的所有互動，確保所有子 HAL 的感應器事件都能及時傳送。強烈建議子 HAL 使用 createScopedWakelock 方法，將喚醒鎖定逾時的負擔委派給感應器 Multi-HAL，並將喚醒鎖定用量集中到整個感應器 Multi-HAL 的一個通用喚醒鎖定，盡量減少鎖定和解鎖呼叫。

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

原始碼和參考實作

所有感應器 Multi-HAL 程式碼都位於 hardware/interfaces/sensors/common/default/2.X/multihal/。以下提供一些資源的指標。

• HalProxy.h： HalProxy 物件是由感應器多重 HAL 例項化，並負責將資料從子 HAL 傳遞至感應器架構。
• HalProxy.cpp： HalProxy 包含在子 HAL 和感應器架構之間多工處理通訊所需的所有邏輯。

• SubHal.h：ISensorsSubHal 介面定義子 HAL 必須遵循的介面，才能與 HalProxy 相容。子 HAL 會實作初始化方法，以便將 HalProxyCallback 物件用於 postEvents 和 createScopedWakelock。

  如果是 Multi-HAL 2.0 實作項目，請使用 SubHal.h 的 2.0 版。

• hardware/interfaces/sensors/common/default/2.X/multihal/tests/： 這些單元測試會驗證 HalProxy 實作項目。

• hardware/interfaces/sensors/common/default/2.X/multihal/tests/fake_subhal/：這個範例子 HAL 實作會使用虛擬感應器產生虛擬資料。有助於測試裝置上多個子 HAL 的互動情形。

實作

本節說明如何在下列情況中實作感應器 Multi-HAL：

• 使用感應器多重 HAL 和感應器 AIDL HAL
• 實作感應器 Multi-HAL 2.1
• 從 Sensors Multi-HAL 2.0 移植到 Multi-HAL 2.1
• 從感應器 HAL 2.0 移植
• 從感應器 HAL 1.0 移植
• 從 Sensors Multi-HAL 1.0 移植

搭配使用感應器 AIDL HAL 與感應器 Multi-HAL

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

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

導入感應器 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 初始化。

從感應器 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 介面中的 IHalProxyCallback
• 子 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

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

將感應器事件發布至 Multi-HAL 實作

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

WAKE_UP 事件

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

動態感應器

感應器 Multi-HAL 2.0 要求在動態感應器連線變更時，呼叫 IHalProxyCallback 中的 onDynamicSensorsConnected 和 onDynamicSensorsDisconnected。這些回呼會透過 initialize() 函式提供的 IHalProxyCallback 指標提供。

感應器 HAL 1.0 的通訊埠

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

初始化 HAL

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

公開可用的感應器

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

將感應器事件發布至 Multi-HAL 實作

在 Sensors HAL 2.0 中，子 HAL 必須主動將感應器事件寫入 IHalProxyCallback，而不是等待呼叫 poll()。

WAKE_UP 事件

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

動態感應器

在 Sensors HAL 1.0 中，動態感應器會透過 poll() 函式傳回。 感應器 Multi-HAL 2.0 要求在動態感應器連線變更時，呼叫 IHalProxyCallback 中的 onDynamicSensorsConnected 和 onDynamicSensorsDisconnected。這些回呼會透過 initialize() 函式提供的 IHalProxyCallback 指標提供。

感應器 Multi-HAL 1.0 的通訊埠

如要從感應器多重 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. 如「從感應器 HAL 1.0 移植」一文所述，移植子 HAL。
4. 按照「實作 Sensors Multi-HAL 2.0」一節中的步驟 3 和 4，將 Sensors Multi-HAL 2.0 設為指定 HAL。

驗證

執行 VTS

將一或多個子 HAL 與 Sensors Multi-Hal 2.1 整合後，請使用 Vendor Test Suite (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 Multi-HAL shim 層，請執行 VtsAidlHalSensorsTargetTest。

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

執行單元測試

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

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

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

使用虛擬子 HAL 進行測試

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

偽造的子 HAL 可用於測試完整的 Multi-HAL 程式碼如何與載入系統的其他子 HAL 搭配運作，以及測試感應器 Multi-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. 在 /vendor/etc/sensors/hals.conf 更新感應器 HAL 設定，並使用虛擬子 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 指令偵錯架構。如要要求感應器 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 發布了大量感應器事件。

如果喚醒鎖定參照計數大於 0，表示 HalProxy 已取得喚醒鎖定。只有在刻意保留 ScopedWakelock，或喚醒事件已傳送至 HalProxy 但尚未由感應器架構處理時，這個值才應大於 0。

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