Sensor Hardware Abstraction Layer (HAL) adalah antarmuka antara framework sensor Android dan sensor perangkat, seperti akselerometer atau giroskop. Sensor HAL menentukan fungsi yang harus diterapkan agar framework dapat mengontrol sensor.
Sensor HAL 2.0 tersedia di Android 10 dan yang lebih tinggi untuk perangkat baru dan yang diupgrade. Sensor HAL 2.0 didasarkan pada Sensor HAL 1.0, tetapi memiliki beberapa perbedaan utama, yang mencegahnya kompatibel dengan versi sebelumnya. Sensor HAL 2.0 menggunakan Fast Message Queues (FMQ) untuk mengirim peristiwa sensor dari HAL ke framework sensor Android.
Sensor HAL 2.1 tersedia di Android 11 dan yang lebih tinggi untuk perangkat baru dan yang diupgrade. Sensor HAL 2.1 adalah iterasi Sensor HAL 2.0
yang mengekspos jenis sensor
HINGE_ANGLE
dan mengupdate berbagai metode untuk menerima jenis HINGE_ANGLE.
Antarmuka HAL 2.1
Sumber utama dokumentasi untuk Sensor HAL 2.1 berada dalam definisi HAL di hardware/interfaces/sensors/2.1/ISensors.hal.
Jika ada persyaratan yang bertentangan antara halaman ini dan ISensors.hal, gunakan persyaratan di ISensors.hal.
Antarmuka HAL 2.0
Sumber utama dokumentasi untuk Sensor HAL 2.0 berada dalam definisi HAL
di
hardware/interfaces/sensors/2.0/ISensors.hal.
Jika ada persyaratan yang bertentangan antara halaman ini dan ISensors.hal, gunakan persyaratan di ISensors.hal.
Mengimplementasikan Sensor HAL 2.0 dan HAL 2.1
Untuk mengimplementasikan Sensor HAL 2.0 atau 2.1, objek harus memperluas ISensors
antarmuka dan mengimplementasikan semua fungsi yang ditentukan dalam
2.0/ISensors.hal
atau
2.1/ISensors.hal.
Menginisialisasi HAL
Sensor HAL harus diinisialisasi oleh framework sensor Android sebelum dapat digunakan. Framework memanggil fungsi initialize() untuk HAL 2.0 dan fungsi initialize_2_1() untuk HAL 2.1 guna memberikan tiga parameter ke Sensor HAL: dua deskriptor FMQ dan satu pointer ke objek ISensorsCallback.
HAL menggunakan deskriptor pertama untuk membuat FMQ Peristiwa yang digunakan untuk menulis peristiwa sensor ke framework. HAL menggunakan deskriptor kedua untuk membuat FMQ Wake Lock yang digunakan untuk menyinkronkan saat HAL merilis wake lock untuk peristiwa sensor WAKE_UP. HAL harus menyimpan pointer ke objek ISensorsCallback sehingga fungsi callback yang diperlukan dapat dipanggil.
Fungsi initialize() atau initialize_2_1() harus menjadi fungsi pertama yang dipanggil saat menginisialisasi Sensor HAL.
Mengekspos sensor yang tersedia
Untuk mendapatkan daftar semua sensor statis yang tersedia di perangkat, gunakan fungsi getSensorsList() di HAL 2.0 dan fungsi getSensorsList_2_1() di HAL 2.1. Fungsi ini menampilkan daftar sensor, yang masing-masing diidentifikasi secara unik oleh handle-nya. Handle untuk sensor tertentu tidak boleh berubah saat proses yang menghosting Sensor HAL dimulai ulang. Handle dapat berubah di seluruh reboot perangkat, dan di seluruh server sistem dimulai ulang.
Jika beberapa sensor memiliki jenis sensor dan properti aktivasi yang sama, sensor pertama dalam daftar disebut sensor default dan ditampilkan ke aplikasi yang menggunakan fungsi getDefaultSensor(int sensorType, bool wakeUp).
Stabilitas daftar sensor
Setelah Sensor HAL dimulai ulang, jika data yang ditampilkan oleh getSensorsList() atau getSensorsList_2_1() menunjukkan perubahan signifikan dibandingkan dengan daftar sensor yang diambil sebelum dimulai ulang, framework akan memicu mulai ulang runtime Android. Perubahan signifikan pada daftar sensor mencakup kasus saat sensor dengan handle tertentu tidak ada atau telah mengubah atribut, atau saat sensor baru diperkenalkan. Meskipun memulai ulang runtime Android mengganggu pengguna, hal ini diperlukan karena framework Android tidak dapat lagi memenuhi kontrak Android API bahwa sensor statis (non-dinamis) tidak berubah selama masa aktif aplikasi. Hal ini juga dapat mencegah framework membuat ulang permintaan sensor aktif yang dibuat oleh aplikasi. Oleh karena itu, vendor HAL disarankan untuk mencegah perubahan daftar sensor yang dapat dihindari.
Untuk memastikan handle sensor yang stabil, HAL harus memetakan sensor fisik tertentu di perangkat ke handle-nya secara deterministik. Meskipun tidak ada implementasi khusus yang diwajibkan oleh antarmuka Sensor HAL, developer memiliki sejumlah opsi yang tersedia untuk memenuhi persyaratan ini.
Misalnya, daftar sensor dapat diurutkan menggunakan kombinasi atribut tetap setiap sensor, seperti vendor, model, dan jenis sensor. Opsi lain bergantung pada fakta bahwa kumpulan sensor statis perangkat ditetapkan dalam hardware, sehingga HAL perlu mengetahui kapan semua sensor yang diharapkan telah menyelesaikan inisialisasi sebelum ditampilkan dari getSensorsList() atau getSensorsList_2_1(). Daftar sensor yang diharapkan ini dapat dikompilasi ke dalam biner HAL atau disimpan dalam file konfigurasi di sistem file, dan urutan kemunculan dapat digunakan untuk mendapatkan handle yang stabil. Meskipun solusi terbaik bergantung pada detail implementasi spesifik HAL Anda, persyaratan utamanya adalah handle sensor tidak berubah di seluruh HAL dimulai ulang.
Mengonfigurasi sensor
Sebelum sensor diaktifkan, sensor harus dikonfigurasi dengan periode pengambilan sampel dan latensi pelaporan maksimum menggunakan fungsi batch().
Sensor harus dapat dikonfigurasi ulang kapan saja menggunakan batch() tanpa kehilangan data sensor.
Periode pengambilan sampel
Periode pengambilan sampel memiliki arti yang berbeda berdasarkan jenis sensor yang sedang dikonfigurasi:
- Berkelanjutan: Peristiwa sensor dihasilkan pada kecepatan berkelanjutan.
- Saat berubah: Peristiwa tidak dihasilkan lebih cepat dari periode pengambilan sampel dan dapat dihasilkan pada kecepatan yang lebih lambat dari periode pengambilan sampel jika nilai yang diukur tidak berubah.
- Satu kali: Periode pengambilan sampel diabaikan.
- Khusus: Untuk mengetahui detail selengkapnya, lihat Jenis sensor.
Untuk mempelajari interaksi antara periode pengambilan sampel dan mode pelaporan sensor, lihat Mode Pelaporan.
Latensi pelaporan maksimum
Latensi pelaporan maksimum menetapkan waktu maksimum dalam nanodetik peristiwa dapat ditunda dan disimpan dalam FIFO hardware sebelum ditulis ke FMQ Peristiwa melalui HAL saat SoC aktif.
Nilai nol menandakan bahwa peristiwa harus dilaporkan segera setelah diukur, baik dengan melewati FIFO sepenuhnya, atau mengosongkan FIFO segera setelah satu peristiwa dari sensor ada di FIFO.
Misalnya, akselerometer yang diaktifkan pada 50 Hz dengan latensi pelaporan maksimum nol akan memicu interupsi 50 kali per detik saat SoC aktif.
Jika latensi pelaporan maksimum lebih besar dari nol, peristiwa sensor tidak perlu dilaporkan segera setelah terdeteksi. Peristiwa dapat disimpan sementara di FIFO hardware dan dilaporkan dalam batch, selama tidak ada peristiwa yang tertunda lebih dari latensi pelaporan maksimum. Semua peristiwa sejak batch sebelumnya dicatat dan ditampilkan sekaligus. Hal ini mengurangi jumlah interupsi yang dikirim ke SoC dan memungkinkan SoC beralih ke mode daya yang lebih rendah saat sensor mengambil dan mengelompokkan data.
Setiap peristiwa memiliki stempel waktu yang terkait dengannya. Menunda waktu peristiwa dilaporkan tidak boleh memengaruhi stempel waktu peristiwa. Stempel waktu harus akurat dan sesuai dengan waktu terjadinya peristiwa secara fisik, bukan waktu peristiwa dilaporkan.
Untuk informasi dan persyaratan tambahan tentang pelaporan peristiwa sensor dengan latensi pelaporan maksimum bukan nol, lihat Pengelompokan.
Mengaktifkan sensor
Framework mengaktifkan dan menonaktifkan sensor menggunakan fungsi activate().
Sebelum mengaktifkan sensor, framework harus mengonfigurasi sensor terlebih dahulu menggunakan batch().
Setelah sensor dinonaktifkan, peristiwa sensor tambahan dari sensor tersebut tidak boleh ditulis ke FMQ Peristiwa.
Flush sensor
Jika sensor dikonfigurasi untuk mengelompokkan data sensor, framework dapat memaksa pengosongan peristiwa sensor yang dikelompokkan secara langsung dengan memanggil flush(). Hal ini menyebabkan peristiwa sensor yang dikelompokkan untuk handle sensor yang ditentukan segera ditulis ke FMQ Peristiwa. Sensor HAL harus menambahkan peristiwa pengosongan selesai ke akhir peristiwa sensor yang ditulis sebagai hasil panggilan ke flush().
Pengosongan terjadi secara asinkron (yaitu, fungsi ini harus segera ditampilkan). Jika implementasi menggunakan satu FIFO untuk beberapa sensor, FIFO tersebut akan dikosongkan dan peristiwa pengosongan selesai hanya ditambahkan untuk sensor yang ditentukan.
Jika sensor yang ditentukan tidak memiliki FIFO (tidak ada buffering yang mungkin), atau jika FIFO kosong pada saat panggilan, flush() harus tetap berhasil dan mengirim peristiwa pengosongan selesai untuk sensor tersebut. Hal ini berlaku untuk semua sensor selain sensor satu kali.
Jika flush() dipanggil untuk sensor satu kali, flush() harus menampilkan BAD_VALUE dan tidak menghasilkan peristiwa pengosongan selesai.
Menulis peristiwa sensor ke FMQ
FMQ Peristiwa digunakan oleh Sensor HAL untuk mendorong peristiwa sensor ke dalam framework sensor Android.
FMQ Peristiwa adalah FMQ yang disinkronkan, yang berarti bahwa setiap upaya untuk menulis lebih banyak peristiwa ke FMQ daripada ruang yang tersedia akan menghasilkan penulisan yang gagal. Dalam hal ini, HAL harus menentukan apakah akan menulis kumpulan peristiwa saat ini sebagai dua kelompok peristiwa yang lebih kecil atau menulis semua peristiwa bersama-sama saat ruang yang cukup tersedia.
Saat Sensor HAL telah menulis jumlah peristiwa sensor yang diinginkan ke FMQ Peristiwa, Sensor HAL harus memberi tahu framework bahwa peristiwa sudah siap dengan menulis bit EventQueueFlagBits::READ_AND_PROCESS ke fungsi EventFlag::wake FMQ Peristiwa. EventFlag dapat dibuat dari FMQ Peristiwa menggunakan EventFlag::createEventFlag dan fungsi getEventFlagWord() FMQ Peristiwa.
Sensor HAL 2.0/2.1 mendukung write dan writeBlocking di FMQ Peristiwa.
Implementasi default memberikan referensi untuk menggunakan write. Jika fungsi writeBlocking digunakan, flag readNotification harus ditetapkan ke EventQueueFlagBits::EVENTS_READ, yang ditetapkan oleh framework saat membaca peristiwa dari FMQ Peristiwa. Flag notifikasi tulis harus ditetapkan ke EventQueueFlagBits::READ_AND_PROCESS, yang memberi tahu framework bahwa peristiwa telah ditulis ke FMQ Peristiwa.
Peristiwa WAKE_UP
Peristiwa WAKE_UP adalah peristiwa sensor yang menyebabkan prosesor aplikasi (AP) aktif dan menangani peristiwa tersebut secara langsung. Setiap kali peristiwa WAKE_UP ditulis ke FMQ Peristiwa, Sensor HAL harus mengamankan penguncian layar saat aktif untuk memastikan sistem tetap aktif hingga framework dapat menangani peristiwa tersebut. Setelah menerima peristiwa WAKE_UP, framework akan mengamankan penguncian layar saat aktifnya sendiri, sehingga Sensor HAL dapat melepaskan penguncian layar saat aktifnya. Untuk menyinkronkan saat Sensor HAL merilis wake lock-nya, gunakan FMQ Wake Lock.
Sensor HAL harus membaca FMQ Wake Lock untuk menentukan jumlah peristiwa WAKE_UP yang telah ditangani framework. HAL hanya boleh merilis penguncian layar saat aktif untuk peristiwa WAKE_UP jika jumlah total peristiwa WAKE_UP yang belum ditangani adalah nol.
Setelah menangani peristiwa sensor, framework akan menghitung jumlah peristiwa yang ditandai sebagai peristiwa WAKE_UP dan menulis kembali angka ini ke FMQ Wake Lock.
Framework menetapkan notifikasi tulis WakeLockQueueFlagBits::DATA_WRITTEN di FMQ Wake Lock setiap kali menulis data ke FMQ Wake Lock.
Sensor dinamis
Sensor dinamis adalah sensor yang secara fisik bukan bagian dari perangkat, tetapi dapat digunakan sebagai input ke perangkat, seperti gamepad dengan akselerometer.
Saat sensor dinamis terhubung, fungsi onDynamicSensorConnected di ISensorsCallback harus dipanggil dari Sensor HAL. Hal ini memberi tahu framework tentang sensor dinamis baru dan memungkinkan sensor dikontrol melalui framework dan peristiwa sensor dikonsumsi oleh klien.
Demikian pula, saat sensor dinamis terputus, fungsi onDynamicSensorDisconnected di ISensorsCallback harus dipanggil agar framework dapat menghapus sensor yang tidak lagi tersedia.
Saluran langsung
Saluran langsung adalah metode operasi tempat peristiwa sensor ditulis ke memori tertentu, bukan ke FMQ Peristiwa yang melewati Framework Sensor Android. Klien yang mendaftarkan saluran langsung harus membaca peristiwa sensor langsung dari memori yang digunakan untuk membuat saluran langsung dan tidak akan menerima peristiwa sensor melalui framework. Fungsi configDirectReport() mirip dengan batch() untuk operasi normal dan mengonfigurasi saluran laporan langsung.
Fungsi registerDirectChannel() dan unregisterDirectChannel() membuat
atau menghancurkan saluran langsung baru.
Mode operasi
Fungsi setOperationMode() memungkinkan framework mengonfigurasi sensor sehingga framework dapat menyuntikkan data sensor ke sensor. Hal ini berguna untuk pengujian, terutama untuk algoritma yang ada di bawah framework.
Fungsi injectSensorData() di HAL 2.0 dan fungsi injectSensorsData_2_1() di HAL 2.0 biasanya digunakan untuk mendorong parameter operasional ke Sensor HAL. Fungsi ini juga dapat digunakan untuk menyuntikkan peristiwa sensor ke sensor tertentu.
Validasi
Untuk memvalidasi implementasi Sensor HAL, jalankan pengujian CTS dan VTS sensor.
Pengujian CTS
Pengujian CTS sensor ada dalam pengujian CTS otomatis dan aplikasi CTS Verifier manual.
Pengujian otomatis terletak di cts/tests/sensor/src/android/hardware/cts. Pengujian ini memverifikasi fungsi standar sensor, seperti mengaktifkan sensor, pengelompokan, dan kecepatan peristiwa sensor.
Pengujian CTS Verifier terletak di cts/apps/CtsVerifier/src/com/android/cts/verifier/sensors. Pengujian ini memerlukan input manual dari operator pengujian dan memastikan bahwa sensor melaporkan nilai yang akurat.
Lulus pengujian CTS sangat penting untuk memastikan bahwa perangkat yang diuji memenuhi semua persyaratan CDD.
Pengujian VTS
Pengujian VTS untuk Sensor HAL 2.0 terletak di
hardware/interfaces/sensors/2.0/vts.
Pengujian VTS untuk Sensor HAL 2.1 terletak di
hardware/interfaces/sensors/2.1/vts.
Pengujian ini memastikan bahwa Sensor HAL diimplementasikan dengan benar dan semua persyaratan dalam ISensors.hal dan ISensorsCallback.hal terpenuhi dengan benar.
Mengupgrade ke Sensor HAL 2.1 dari 2.0
Saat mengupgrade ke Sensor HAL 2.1 dari 2.0, implementasi HAL Anda harus menyertakan metode initialize_2_1(), getSensorsList_2_1(), dan injectSensorsData_2_1(), bersama dengan jenis HAL 2.1. Metode ini harus memenuhi persyaratan yang sama yang diuraikan untuk HAL 2.0 di atas.
Karena HAL versi minor harus mendukung semua fungsi dari HAL sebelumnya, HAL 2.1 harus mendukung inisialisasi sebagai HAL 2.0. Untuk menghindari kompleksitas dukungan kedua versi HAL, sebaiknya gunakan Multi-HAL 2.1.
Untuk contoh cara mengimplementasikan Sensor HAL 2.1 Anda sendiri, lihat Sensors.h.
Mengupgrade ke Sensor HAL 2.0 dari 1.0
Saat mengupgrade ke Sensor HAL 2.0 dari 1.0, pastikan implementasi HAL Anda memenuhi persyaratan berikut.
Menginisialisasi HAL
Fungsi initialize() harus didukung untuk membuat FMQ antara framework dan HAL.
Mengekspos sensor yang tersedia
Di Sensor HAL 2.0, fungsi getSensorsList() harus menampilkan nilai yang sama selama satu booting perangkat, bahkan di seluruh Sensor HAL dimulai ulang. Persyaratan baru fungsi getSensorsList() adalah fungsi tersebut harus menampilkan nilai yang sama selama satu booting perangkat, bahkan di seluruh Sensor HAL dimulai ulang. Hal ini memungkinkan framework mencoba membuat ulang koneksi sensor jika server sistem dimulai ulang. Nilai yang ditampilkan oleh getSensorsList() dapat berubah setelah perangkat melakukan reboot.
Menulis peristiwa sensor ke FMQ
Daripada menunggu poll() dipanggil, di Sensor HAL 2.0, Sensor HAL harus secara proaktif menulis peristiwa sensor ke FMQ Peristiwa setiap kali peristiwa sensor tersedia. HAL juga bertanggung jawab untuk menulis bit yang benar ke EventFlag untuk menyebabkan pembacaan FMQ dalam framework.
Peristiwa WAKE_UP
Di Sensor HAL 1.0, HAL dapat merilis penguncian layar saat aktif untuk peristiwa WAKE_UP apa pun pada panggilan berikutnya ke poll() setelah WAKE_UP diposting ke poll() karena hal ini menunjukkan bahwa framework telah memproses semua peristiwa sensor dan telah mendapatkan penguncian layar saat aktif, jika diperlukan. Karena, di Sensor HAL 2.0, HAL tidak lagi mengetahui kapan framework telah memproses peristiwa yang ditulis ke FMQ, FMQ Wake Lock memungkinkan framework berkomunikasi ke HAL saat menangani peristiwa WAKE_UP.
Di Sensor HAL 2.0, penguncian layar saat aktif yang diamankan oleh Sensor HAL untuk peristiwa WAKE_UP harus dimulai dengan SensorsHAL_WAKEUP.
Sensor dinamis
Sensor dinamis ditampilkan menggunakan fungsi poll() di Sensor HAL 1.0.
Sensor HAL 2.0 mengharuskan onDynamicSensorsConnected dan onDynamicSensorsDisconnected di ISensorsCallback dipanggil setiap kali koneksi sensor dinamis berubah. Callback ini tersedia sebagai bagian dari pointer ISensorsCallback yang disediakan melalui fungsi initialize().
Mode operasi
Mode DATA_INJECTION untuk sensor WAKE_UP harus didukung di Sensor HAL 2.0.
Dukungan Multi-HAL
Sensor HAL 2.0 dan 2.1 mendukung multi-HAL menggunakan framework Multi-HAL Sensor. Untuk mengetahui detail implementasi, lihat Melakukan Porting dari Sensor HAL 1.0.