Google berkomitmen untuk mendorong terwujudnya keadilan ras bagi komunitas Kulit Hitam. Lihat caranya.

Sensor Multi-HAL

Sensor Multi-HAL adalah kerangka kerja yang memungkinkan sensor HAL berjalan bersama sensor HAL lainnya. Sensor Multi-HAL secara dinamis memuat sub-HAL sensor yang disimpan sebagai pustaka dinamis pada partisi vendor dan memberi mereka objek panggilan balik yang dapat menangani peristiwa posting dan memperoleh serta melepaskan kunci pengaktifan. Sensor sub-HAL adalah sensor HAL yang dibangun ke dalam objek bersama di partisi vendor dan digunakan oleh kerangka kerja multi-HAL. Sub-HAL ini tidak bergantung satu sama lain atau pada kode multi-HAL yang berisi fungsi utama untuk proses tersebut.

Sensor Multi-HAL 2.1, tersedia pada perangkat yang menjalankan Android 11 atau lebih tinggi, merupakan iterasi dari Sensor 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 dalam header 2.1 SubHal .

Perbedaan antara Sensor Multi-HAL 2 dan Sensor HAL 2

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

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

  • Metode inisialisasi meneruskan kelas IHalProxyCallback bukan dua FMQ dan ISensorsCallback .
  • Sub-HAL harus mengimplementasikan fungsi debug untuk menyediakan informasi debug dalam laporan bug.
  • Sub-HAL harus mengimplementasikan fungsi nama sehingga sub-HAL yang dimuat dapat dibedakan dari sub-HAL lainnya.

Perbedaan utama antara Sensor Multi-HAL 2 dan Sensor HAL 2 terletak pada fungsi inisialisasi. Alih-alih menyediakan FMQ, antarmuka IHalProxyCallback menyediakan dua metode, satu metode untuk memposting kejadian sensor ke kerangka kerja sensor dan satu metode untuk membuat penguncian layar saat bangun. Di bawah tenda, Sensor Multi-HAL mengelola semua interaksi dengan FMQ untuk memastikan pengiriman peristiwa sensor yang tepat waktu untuk semua sub-HAL. Sangat disarankan agar sub-HAL menggunakan metode createScopedWakelock untuk mendelegasikan beban waktu keluar kunci saat bangun ke Sensor Multi-HAL dan untuk memusatkan penggunaan kunci saat bangun ke satu kunci bangun umum untuk seluruh Sensor Multi-HAL, yang meminimalkan penguncian dan pembukaan kunci panggilan.

Sensor Multi-HAL 2 juga memiliki beberapa fitur keselamatan built-in. Ini menangani situasi ketika FMQ sensor penuh atau ketika kerangka kerja sensor Android dimulai ulang dan status sensor perlu disetel ulang. Selain itu, ketika peristiwa diposting ke kelas HalProxy tetapi kerangka kerja sensor tidak dapat menerima peristiwa dengan segera, Sensor Multi-HAL dapat memindahkan peristiwa ke thread latar belakang untuk memungkinkan pekerjaan dilanjutkan di semua sub-HAL sambil menunggu peristiwa. untuk diposting.

Kode sumber dan implementasi referensi

Semua kode Sensor Multi-HAL tersedia di hardware/interfaces/sensors/common/default/2.X/multihal/ . Berikut adalah petunjuk ke beberapa sumber.

  • HalProxy.h : Objek HalProxy dibuat oleh Sensor multi-HAL dan menangani penerusan data dari sub-HAL ke kerangka kerja sensor.
  • HalProxy.cpp : Implementasi HalProxy berisi semua logika yang dibutuhkan untuk komunikasi multipleks antara sub-HAL dan kerangka kerja sensor.
  • SubHal.h : Antarmuka ISensorsSubHal mendefinisikan antarmuka yang harus diikuti sub-HAL agar kompatibel dengan HalProxy . Sub-HAL mengimplementasikan metode inisialisasi sehingga objek HalProxyCallback dapat digunakan untuk postEvents dan createScopedWakelock .

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

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

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

Penerapan

Bagian ini menjelaskan cara mengimplementasikan Sensor Multi-HAL dalam situasi berikut:

Menerapkan Sensor Multi-HAL 2.1

Untuk mengimplementasikan Sensor Multi-HAL 2.1 pada perangkat baru, ikuti langkah-langkah berikut:

  1. Implementasikan antarmuka ISensorsSubHal seperti yang dijelaskan di SubHal.h .
  2. Melaksanakan sensorsHalGetSubHal_2_1 metode dalam SubHal.h .
  3. Tambahkan target cc_library_shared untuk membangun 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 perpustakaan di baris baru. Jika perlu, buat file hals.conf .

    Untuk contoh entri Android.bp 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 pada perangkat.

  5. Hapus semua layanan android.hardware.sensors dan file 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 boot, HalProxy dimulai, mencari sub-HAL yang baru diterapkan, dan menginisialisasinya dengan memanggil sensorsHalGetSubHal_2_1 .

Porting dari Sensor Multi-HAL 2.0 ke Multi-HAL 2.1

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

Ini adalah perbedaan antara antarmuka SubHal 2.0 dan 2.1:

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

Porting dari Sensor HAL 2.0

Saat meningkatkan ke Sensor Multi-HAL 2.0 dari Sensor HAL 2.0 , pastikan implementasi HAL memenuhi persyaratan berikut.

Menginisialisasi HAL

Sensor HAL 2.0 memiliki fungsi inisialisasi yang memungkinkan layanan sensor melewati FMQ dan panggilan balik sensor dinamis. Di Sensor Multi-HAL 2.0, fungsi initialize() meneruskan satu callback yang harus digunakan untuk memposting kejadian sensor, mendapatkan penguncian layar, dan memberi tahu koneksi dan pemutusan sensor dinamis.

Memposting peristiwa sensor ke implementasi Multi-HAL

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

Acara WAKE_UP

Di Sensor HAL 2.0, HAL dapat mengelola penguncian layar untuk implementasinya. Di Sensor Multi-HAL 2.0, sub-HAL memungkinkan implementasi Multi-HAL untuk mengelola penguncian layar saat aktif dan dapat meminta penguncian createScopedWakelock dengan menjalankan createScopedWakelock . Penguncian postEvents dengan postEvents dikunci harus diperoleh dan diteruskan ke postEvents saat memposting acara pengaktifan ke implementasi Multi-HAL.

Sensor dinamis

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

Porting dari Sensor HAL 1.0

Saat meningkatkan ke Sensor Multi-HAL 2.0 dari Sensor HAL 1.0 , pastikan implementasi HAL memenuhi persyaratan berikut.

Menginisialisasi HAL

Fungsi initialize() harus didukung untuk menetapkan panggilan balik antara sub-HAL dan implementasi Multi-HAL.

Mengekspos sensor yang tersedia

Di Sensor Multi-HAL 2.0, fungsi getSensorsList() harus mengembalikan nilai yang sama selama boot perangkat tunggal, bahkan di seluruh sensor HAL dimulai ulang. Hal ini memungkinkan framework untuk mencoba membangun kembali koneksi sensor jika server sistem dimulai ulang. Nilai yang dikembalikan oleh getSensorsList() bisa berubah setelah perangkat melakukan boot ulang.

Memposting peristiwa sensor ke implementasi Multi-HAL

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

Acara WAKE_UP

Di Sensor HAL 1.0, HAL dapat mengelola penguncian layar untuk implementasinya. Di Sensor Multi-HAL 2.0, sub-HAL memungkinkan implementasi Multi-HAL untuk mengelola penguncian layar saat aktif dan dapat meminta penguncian createScopedWakelock dengan menjalankan createScopedWakelock . Penguncian postEvents dengan postEvents dikunci harus diperoleh dan diteruskan ke postEvents saat memposting acara pengaktifan ke implementasi Multi-HAL.

Sensor dinamis

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

Porting dari Sensor Multi-HAL 1.0

Untuk mem-port implementasi yang ada dari Sensor Multi-HAL 1.0 , ikuti langkah-langkah berikut.

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

Validasi

Menjalankan VTS

Saat Anda telah mengintegrasikan satu atau lebih sub-HAL dengan Sensor Multi-Hal 2.1, gunakan Vendor Test Suite (VTS) untuk memastikan implementasi sub-HAL Anda memenuhi semua persyaratan yang ditetapkan oleh antarmuka Sensor HAL.

Untuk menjalankan hanya tes sensor VTS saat VTS diatur pada 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

Menjalankan tes 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 tes, 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 implementasi tiruan dari antarmuka ISensorsSubHal . Sub-HAL menampilkan daftar sensor yang berbeda. Saat sensor diaktifkan, mereka secara berkala memposting kejadian sensor yang dibuat secara otomatis ke HalProxy berdasarkan interval yang ditentukan dalam permintaan sensor tertentu.

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

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

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

  1. Jalankan perintah berikut untuk membangun 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 terdaftar di konfigurasi.

    adb shell stop
    adb shell start
    

Debugging

Pengembang dapat men-debug kerangka kerja dengan menggunakan perintah lshal . Untuk meminta keluaran debug dari Sensor HAL, jalankan perintah berikut:

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

Informasi tentang status HalProxy dan sub-HAL-nya kemudian dikeluarkan 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 jumlah yang ditentukan untuk # of events on pending write queue berjumlah besar (1000 atau lebih), ini menunjukkan bahwa ada banyak peristiwa yang menunggu untuk ditulis ke framework sensor. Hal ini menunjukkan bahwa layanan sensor mengalami kebuntuan atau crash dan tidak memproses peristiwa sensor, atau bahwa sejumlah besar peristiwa sensor baru-baru ini diposting dari sub-HAL.

Jika jumlah HalProxy lebih besar dari 0 , ini berarti HalProxy telah memperoleh penguncian layar. Ini seharusnya hanya lebih besar dari 0 jika ScopedWakelock sengaja diadakan atau jika peristiwa HalProxy dikirim ke HalProxy dan belum diproses oleh framework sensor.

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