Multi-HAL Sensor

Sensors Multi-HAL adalah framework yang memungkinkan HAL sensor berjalan bersama HAL sensor lainnya. Sensors Multi-HAL memuat sub-HAL sensor secara dinamis yang disimpan sebagai library dinamis di partisi vendor dan memberinya objek callback yang dapat menangani peristiwa posting dan memperoleh serta melepaskan penguncian layar saat aktif. Sub-HAL sensor adalah HAL sensor yang dibuat ke dalam objek bersama di partisi vendor dan digunakan oleh framework multi-HAL. Sub-HAL ini tidak bergantung satu sama lain atau pada kode multi-HAL yang berisi fungsi utama untuk proses tersebut.

Sensors Multi-HAL 2.1, yang tersedia di perangkat yang menjalankan Android 11 atau yang lebih tinggi, adalah iterasi Sensors Multi-HAL 2.0 yang mendukung pemuatan sub-HAL yang dapat mengekspos jenis sensor sudut engsel. Untuk mendukung jenis sensor ini, sub-HAL harus menggunakan sub-HAL API yang ditentukan di header SubHal 2.1.

Untuk perangkat yang menjalankan Android 13 atau yang lebih tinggi yang menggunakan Sensors AIDL HAL, Anda dapat menggunakan lapisan shim multi-HAL untuk mengaktifkan kemampuan multi-HAL. Untuk mengetahui detail penerapan, lihat Menggunakan Sensors Multi-HAL dengan Sensors AIDL HAL.

Perbedaan antara Sensors Multi-HAL 2 dan Sensors HAL 2

Sensors Multi-HAL 2, yang tersedia di perangkat yang menjalankan Android 10 atau yang lebih tinggi, memperkenalkan beberapa abstraksi di atas Sensors HAL 2 untuk memudahkan interaksi dengan HAL API. Sensors Multi-HAL 2 memperkenalkan class HalProxy untuk menangani penerapan antarmuka Sensors HAL 2 dan antarmuka V2_1/SubHal (atau V2_0/SubHal) untuk memungkinkan HalProxy berinteraksi dengan sub-HAL.

Antarmuka ISensorsSubHal berbeda dengan antarmuka 2.1/ISensors.hal (atau 2.0/ISensors.hal) dengan cara berikut:

  • Metode inisialisasi meneruskan class IHalProxyCallback, bukan dua FMQ dan ISensorsCallback.
  • Sub-HAL harus menerapkan fungsi debug untuk memberikan informasi proses debug dalam laporan bug.
  • Sub-HAL harus menerapkan fungsi nama sehingga sub-HAL yang dimuat dapat dibedakan dari sub-HAL lainnya.

Perbedaan utama antara Sensors Multi-HAL 2 dan Sensors HAL 2 terletak pada fungsi inisialisasi. Daripada menyediakan FMQ, antarmuka IHalProxyCallback menyediakan dua metode, satu metode untuk memposting peristiwa sensor ke framework sensor dan satu metode untuk membuat wake lock. Di balik layar, Sensors Multi-HAL mengelola semua interaksi dengan FMQ untuk memastikan pengiriman peristiwa sensor tepat waktu untuk semua sub-HAL. Sebaiknya sub-HAL menggunakan metode createScopedWakelock untuk mendelegasikan beban waktu tunggu penguncian layar saat aktif ke Sensors Multi-HAL dan memusatkan penggunaan penguncian layar saat aktif ke satu penguncian layar saat aktif umum untuk seluruh Sensors Multi-HAL, yang meminimalkan panggilan penguncian dan pembukaan kunci.

Sensors Multi-HAL 2 juga memiliki beberapa fitur keamanan bawaan. Fitur ini menangani situasi saat FMQ sensor penuh atau saat framework sensor Android dimulai ulang dan status sensor perlu direset. Selain itu, saat peristiwa diposting ke class HalProxy, tetapi framework sensor tidak dapat segera menerima peristiwa tersebut, Sensors Multi-HAL dapat memindahkan peristiwa ke thread latar belakang untuk memungkinkan pekerjaan dilanjutkan di semua sub-HAL sambil menunggu peristiwa diposting.

Kode sumber dan penerapan referensi

Semua kode Sensors Multi-HAL tersedia di hardware/interfaces/sensors/common/default/2.X/multihal/. Berikut adalah pointer ke beberapa resource.

  • HalProxy.h: Objek HalProxy dibuat instance-nya oleh multi-HAL Sensor dan menangani penerusan data dari sub-HAL ke framework sensor.
  • HalProxy.cpp: Penerapan HalProxy berisi semua logika yang diperlukan untuk melakukan multipleks komunikasi antara sub-HAL dan framework sensor.

  • SubHal.h: Antarmuka ISensorsSubHal menentukan antarmuka yang harus diikuti sub-HAL agar kompatibel dengan HalProxy. Sub-HAL menerapkan metode inisialisasi sehingga objek HalProxyCallback dapat digunakan untuk postEvents dan createScopedWakelock.

    Untuk penerapan Multi-HAL 2.0, gunakan versi 2.0 dari SubHal.h.

  • hardware/interfaces/sensors/common/default/2.X/multihal/tests/: Pengujian unit ini memverifikasi penerapan HalProxy.

  • hardware/interfaces/sensors/common/default/2.X/multihal/tests/fake_subhal/: Contoh penerapan sub-HAL ini menggunakan sensor palsu untuk menghasilkan data palsu. Berguna untuk menguji interaksi beberapa sub-HAL di perangkat.

Penerapan

Bagian ini menjelaskan cara menerapkan Sensors Multi-HAL dalam situasi berikut:

Menggunakan Sensors Multi-HAL dengan Sensors AIDL HAL

Untuk mengaktifkan kemampuan multi-HAL dengan Sensors AIDL HAL, impor modul lapisan shim Multi-HAL AIDL, yang ditemukan di hardware/interfaces/sensors/aidl/default/multihal/. Modul ini menangani konversi antara jenis definisi HAL sensor AIDL dan HIDL serta menentukan wrapper di sekitar antarmuka multi-HAL yang dijelaskan dalam Menerapkan Sensors Multi-HAL 2.1. Lapisan shim multi-HAL AIDL kompatibel dengan perangkat yang menerapkan Sensors Multi-HAL 2.1.

Lapisan shim multi-HAL AIDL memungkinkan Anda mengekspos jenis sensor pelacak kepala dan IMU sumbu terbatas di Sensors AIDL HAL. Untuk menggunakan jenis sensor yang ditentukan oleh antarmuka AIDL HAL, tetapkan kolom type dalam struct SensorInfo di penerapan getSensorsList_2_1(). Hal ini aman karena kolom jenis sensor yang didukung bilangan bulat dari sensor HAL AIDL dan HIDL tidak tumpang-tindih.

Menerapkan Sensors Multi-HAL 2.1

Untuk menerapkan Sensors Multi-HAL 2.1 di perangkat baru, ikuti langkah-langkah berikut:

  1. Terapkan antarmuka ISensorsSubHal seperti yang dijelaskan di SubHal.h.
  2. Terapkan metode sensorsHalGetSubHal_2_1 di SubHal.h.

  3. Tambahkan target cc_library_shared untuk membuat sub-HAL yang baru diterapkan. Saat menambahkan target:

    1. Pastikan target didorong ke suatu tempat di partisi vendor perangkat.
    2. Di file konfigurasi yang terletak di /vendor/etc/sensors/hals.conf, tambahkan jalur ke library di baris baru. Jika perlu, buat file hals.conf.

    Untuk contoh Android.bp entri untuk membuat library sub-HAL, lihat hardware/interfaces/sensors/common/default/2.X/multihal/tests/Android.bp.

  4. Hapus semua entri android.hardware.sensors dari file manifest.xml, yang berisi daftar HAL yang didukung di perangkat.

  5. Hapus semua file layanan android.hardware.sensors dan service.rc dari file device.mk dan tambahkan android.hardware.sensors@2.1-service.multihal dan android.hardware.sensors@2.1-service.multihal.rc ke PRODUCT_PACKAGES.

Saat booting, HalProxy dimulai, mencari sub-HAL yang baru diterapkan, dan melakukan inisialisasi dengan memanggil sensorsHalGetSubHal_2_1.

Melakukan porting dari Sensors Multi-HAL 2.0 ke Multi-HAL 2.1

Untuk melakukan porting dari Multi-HAL 2.0 ke Multi-HAL 2.1, terapkan SubHal antarmuka dan kompilasi ulang sub-HAL Anda.

Berikut adalah perbedaan antara antarmuka SubHal 2.0 dan 2.1:

  • IHalProxyCallback menggunakan jenis yang dibuat dalam spesifikasi ISensors.hal versi 2.1.
  • Fungsi initialize() meneruskan yang baru IHalProxyCallback bukan yang dari antarmuka SubHal 2.0
  • Sub-HAL harus menerapkan getSensorsList_2_1 dan injectSensorData_2_1 bukan getSensorsList dan injectSensorData karena metode ini menggunakan jenis baru yang ditambahkan dalam spesifikasi ISensors.hal versi 2.1.
  • Sub-HAL harus mengekspos sensorsHalGetSubHal_2_1 daripada sensorsHalGetSubHal agar Multi-HAL memperlakukannya sebagai sub-HAL versi 2.1.

Melakukan porting dari Sensors HAL 2.0

Saat mengupgrade ke Sensors Multi-HAL 2.0 dari Sensors HAL 2.0, pastikan penerapan HAL memenuhi persyaratan berikut.

Menginisialisasi HAL

Sensors HAL 2.0 memiliki fungsi inisialisasi yang memungkinkan layanan sensor meneruskan FMQ dan callback sensor dinamis. Di Sensors Multi-HAL 2.0, fungsi initialize() meneruskan satu callback yang harus digunakan untuk memposting peristiwa sensor, mendapatkan wake lock, dan memberi tahu koneksi dan pemutusan koneksi sensor dinamis.

Memposting peristiwa sensor ke penerapan Multi-HAL

Daripada memposting peristiwa sensor melalui FMQ, sub-HAL harus menulis peristiwa sensor ke IHalProxyCallback saat peristiwa sensor tersedia.

Peristiwa WAKE_UP

Di Sensors HAL 2.0, HAL dapat mengelola penguncian layar saat aktif untuk penerapannya. Di Sensors Multi-HAL 2.0, sub-HAL memungkinkan penerapan Multi-HAL mengelola penguncian layar saat aktif dan dapat meminta penguncian layar saat aktif diperoleh dengan memanggil createScopedWakelock. Wake lock cakupan yang terkunci harus diperoleh dan diteruskan ke postEvents saat memposting peristiwa bangun ke penerapan Multi-HAL.

Sensor dinamis

Sensors Multi-HAL 2.0 mengharuskan onDynamicSensorsConnected dan onDynamicSensorsDisconnected di IHalProxyCallback dipanggil setiap kali koneksi sensor dinamis berubah. Callback ini tersedia sebagai bagian dari pointer IHalProxyCallback yang disediakan melalui fungsi initialize().

Melakukan porting dari Sensors HAL 1.0

Saat mengupgrade ke Sensors Multi-HAL 2.0 dari Sensors HAL 1.0, pastikan penerapan HAL memenuhi persyaratan berikut.

Menginisialisasi HAL

Fungsi initialize() harus didukung untuk membuat callback antara sub-HAL dan penerapan Multi-HAL.

Mengekspos sensor yang tersedia

Di Sensors Multi-HAL 2.0, fungsi getSensorsList() harus menampilkan nilai yang sama selama satu booting perangkat, bahkan di seluruh sensor HAL dimulai ulang. Hal ini memungkinkan framework mencoba membangun kembali koneksi sensor jika server sistem dimulai ulang. Nilai yang ditampilkan oleh getSensorsList() dapat berubah setelah perangkat melakukan reboot.

Memposting peristiwa sensor ke penerapan Multi-HAL

Di Sensors HAL 2.0, daripada menunggu poll() dipanggil, sub-HAL harus secara proaktif menulis peristiwa sensor ke IHalProxyCallback setiap kali peristiwa sensor tersedia.

Peristiwa WAKE_UP

Di Sensors HAL 1.0, HAL dapat mengelola penguncian layar saat aktif untuk penerapannya. Di Sensors Multi-HAL 2.0, sub-HAL memungkinkan penerapan Multi-HAL mengelola penguncian layar saat aktif dan dapat meminta penguncian layar saat aktif diperoleh dengan memanggil createScopedWakelock. Wake lock cakupan yang terkunci harus diperoleh dan diteruskan ke postEvents saat memposting peristiwa bangun ke penerapan Multi-HAL.

Sensor dinamis

Di Sensors HAL 1.0, sensor dinamis ditampilkan melalui fungsi poll(). Sensors Multi-HAL 2.0 mengharuskan onDynamicSensorsConnected dan onDynamicSensorsDisconnected di IHalProxyCallback dipanggil setiap kali koneksi sensor dinamis berubah. Callback ini tersedia sebagai bagian dari pointer IHalProxyCallback yang disediakan melalui fungsi initialize().

Melakukan porting dari Sensors Multi-HAL 1.0

Untuk melakukan porting penerapan yang ada dari Sensors Multi-HAL 1.0, ikuti langkah-langkah berikut.

  1. Pastikan konfigurasi HAL sensor terletak di /vendor/etc/sensors/hals.conf. Hal ini mungkin melibatkan pemindahan file yang terletak di /system/etc/sensors/hals.conf.
  2. Hapus referensi ke hardware/hardware.h dan hardware/sensors.h karena tidak didukung untuk HAL 2.0.
  3. Lakukan porting sub-HAL seperti yang dijelaskan dalam Melakukan porting dari Sensors Hal 1.0.
  4. Tetapkan Sensors Multi-HAL 2.0 sebagai HAL yang ditetapkan dengan mengikuti langkah 3 dan 4 di bagian Menerapkan Sensors Multi-HAL 2.0.

Validasi

Menjalankan VTS

Setelah mengintegrasikan satu atau beberapa sub-HAL dengan Sensors Multi-Hal 2.1, gunakan Vendor Test Suite (VTS) untuk memastikan penerapan sub-HAL Anda memenuhi semua persyaratan yang ditetapkan oleh antarmuka Sensors HAL.

Untuk menjalankan pengujian VTS sensor saja saat VTS disiapkan di mesin host, jalankan perintah berikut:

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

Jika Anda menjalankan lapisan shim Multi-HAL AIDL, jalankan VtsAidlHalSensorsTargetTest.

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

Menjalankan pengujian unit

Pengujian unit di HalProxy_test.cpp menguji HalProxy menggunakan sub-HAL palsu yang dibuat instance-nya dalam pengujian unit dan tidak dimuat secara dinamis. Saat membuat sub-HAL baru, pengujian ini harus berfungsi sebagai panduan tentang cara menambahkan pengujian unit yang memverifikasi bahwa sub-HAL baru diterapkan dengan benar.

Untuk menjalankan pengujian, jalankan perintah berikut:

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

Menguji dengan sub-HAL palsu

Sub-HAL palsu adalah penerapan dummy dari antarmuka ISensorsSubHal. Sub-HAL mengekspos daftar sensor yang berbeda. Saat sensor diaktifkan, sensor akan memposting peristiwa sensor yang dibuat secara otomatis ke HalProxy secara berkala berdasarkan interval yang ditentukan dalam permintaan sensor tertentu.

Sub-HAL palsu dapat digunakan untuk menguji cara kerja kode Multi-HAL lengkap dengan sub-HAL lain yang dimuat ke dalam sistem dan untuk menekankan berbagai aspek kode Sensors Multi-HAL.

Dua sub-HAL palsu tersedia di hardware/interfaces/sensors/common/default/2.X/multihal/tests/fake_subhal/.

Untuk membuat dan mendorong sub-HAL palsu ke perangkat, lakukan langkah-langkah berikut:

  1. Jalankan perintah berikut untuk membuat dan mendorong tiga sub-HAL palsu yang berbeda ke perangkat:

    $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. Perbarui konfigurasi HAL sensor di /vendor/etc/sensors/hals.conf dengan jalur untuk sub-HAL palsu.

    /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. Mulai ulang HalProxy dan muat sub-HAL baru yang tercantum dalam konfigurasi.

    adb shell stop
adb shell start

Proses Debug

Developer dapat melakukan proses debug framework menggunakan perintah lshal. Untuk meminta output proses debug Sensors HAL, jalankan perintah berikut:

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

Informasi tentang status HalProxy saat ini dan sub-HAL-nya kemudian akan ditampilkan ke terminal. Di bawah ini adalah contoh output perintah untuk objek HalProxy dan sub-HAL palsu.

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

Jika angka yang ditentukan untuk # of events on pending write queue adalah angka yang besar (1000 atau lebih), hal ini menunjukkan bahwa ada banyak peristiwa yang tertunda untuk ditulis ke framework sensor. Hal ini menunjukkan bahwa layanan sensor mengalami kebuntuan atau error dan tidak memproses peristiwa sensor, atau bahwa batch besar peristiwa sensor baru-baru ini diposting dari sub-HAL.

Jika jumlah referensi penguncian layar saat aktif lebih besar dari 0, berarti HalProxy telah memperoleh penguncian layar saat aktif. Nilai ini hanya boleh lebih besar dari 0 jika ScopedWakelock sengaja ditahan atau jika peristiwa bangun dikirim ke HalProxy dan belum diproses oleh framework sensor.

Deskriptor file yang diteruskan ke metode proses debug HalProxy diteruskan ke setiap sub-HAL sehingga developer harus menerapkan metode proses debug sebagai bagian dari antarmuka ISensorsSubHal.