Hardware Abstraction Layer (HAL) Sensor adalah antarmuka antara framework sensor Android dan sensor perangkat, seperti akselerometer atau giroskop. HAL Sensor menentukan fungsi yang harus diimplementasikan untuk memungkinkan framework 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 membuatnya tidak kompatibel mundur. HAL Sensor 2.0 menggunakan Fast Message Queues (FMQ) untuk mengirim peristiwa sensor dari HAL ke framework sensor Android.
HAL Sensor 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 memperbarui berbagai metode untuk menerima jenis HINGE_ANGLE.
Antarmuka HAL 2.1
Sumber utama dokumentasi untuk Sensors HAL 2.1 ada 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 Sensors HAL 2.0 ada 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.
Menerapkan HAL Sensor 2.0 dan HAL 2.1
Untuk mengimplementasikan Sensors HAL 2.0 atau 2.1, objek harus memperluas antarmuka ISensors dan mengimplementasikan semua fungsi yang ditentukan dalam 2.0/ISensors.hal atau 2.1/ISensors.hal.
Menginisialisasi HAL
HAL Sensor 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 Sensors HAL: dua deskriptor FMQ dan satu pointer ke objek ISensorsCallback.
HAL menggunakan deskriptor pertama untuk membuat Event FMQ yang digunakan untuk menulis peristiwa sensor ke framework. HAL menggunakan deskriptor kedua untuk membuat FMQ Wake Lock yang digunakan untuk menyinkronkan saat HAL melepaskan kunci wake-nya 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 HAL Sensor.
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 HAL Sensor dimulai ulang. Nama sebutan channel dapat berubah saat perangkat dimulai ulang dan saat server sistem dimulai ulang.
Jika beberapa sensor memiliki jenis sensor dan properti aktif yang sama, maka sensor pertama dalam daftar disebut sensor default dan ditampilkan ke aplikasi yang menggunakan fungsi getDefaultSensor(int sensorType, bool wakeUp).
Stabilitas daftar sensor
Setelah HAL Sensor 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 lagi dapat 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 penanganan sensor yang stabil, HAL harus memetakan sensor fisik tertentu dalam perangkat ke penanganannya secara deterministik. Meskipun tidak ada penerapan khusus yang diwajibkan oleh antarmuka HAL Sensor, 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 mengandalkan
fakta bahwa kumpulan sensor statis perangkat ditetapkan dalam hardware, sehingga
HAL perlu mengetahui kapan semua sensor yang diharapkan telah menyelesaikan inisialisasi sebelum
kembali 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 kemunculannya dapat digunakan untuk mendapatkan handle yang stabil. Meskipun solusi terbaik bergantung pada detail implementasi spesifik HAL Anda, persyaratan utamanya adalah bahwa handle sensor tidak berubah di seluruh proses mulai ulang HAL.
Mengonfigurasi sensor
Sebelum 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 dikonfigurasi:
- Berkelanjutan: Peristiwa sensor dibuat dengan kecepatan berkelanjutan.
- Saat berubah: Peristiwa dibuat tidak lebih cepat dari periode pengambilan sampel dan dapat dibuat dengan kecepatan yang lebih lambat dari periode pengambilan sampel jika nilai yang diukur tidak berubah.
- Sekali pengambilan: 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 yang dapat ditunda dan disimpan dalam FIFO hardware sebelum ditulis ke Event FMQ melalui HAL saat SoC aktif.
Nilai nol menandakan bahwa peristiwa harus dilaporkan segera setelah diukur, baik dengan melewati FIFO sama sekali, atau mengosongkan FIFO segera setelah satu peristiwa dari sensor ada di FIFO.
Misalnya, akselerometer yang diaktifkan pada 50 Hz dengan latensi pelaporan maksimum nol 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 membatasi data.
Setiap peristiwa memiliki stempel waktu yang terkait dengannya. Menunda waktu pelaporan peristiwa tidak boleh memengaruhi stempel waktu peristiwa. Stempel waktu harus akurat dan sesuai dengan waktu saat peristiwa terjadi secara fisik, bukan waktu saat dilaporkan.
Untuk informasi dan persyaratan tambahan tentang pelaporan peristiwa sensor dengan latensi pelaporan maksimum bukan nol, lihat Batching.
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.
Sensor toilet
Jika sensor dikonfigurasi untuk mengelompokkan data sensor, framework dapat memaksa flush langsung peristiwa sensor yang dikelompokkan dengan memanggil flush(). Hal ini menyebabkan peristiwa sensor yang dikelompokkan untuk handle sensor yang ditentukan segera ditulis ke Event FMQ. HAL Sensor harus menambahkan peristiwa selesai penghapusan ke akhir peristiwa sensor yang ditulis sebagai hasil panggilan ke flush().
Pengosongan terjadi secara asinkron (yaitu, fungsi ini harus langsung ditampilkan). Jika penerapan menggunakan satu FIFO untuk beberapa sensor, FIFO tersebut akan dikosongkan dan peristiwa selesai pengosongan hanya ditambahkan untuk sensor yang ditentukan.
Jika sensor yang ditentukan tidak memiliki FIFO (tidak dapat melakukan buffering), atau jika FIFO kosong pada saat panggilan, flush() tetap harus berhasil dan mengirim peristiwa selesai penghapusan untuk sensor tersebut. Hal ini berlaku untuk semua sensor selain sensor
sekali baca.
Jika flush() dipanggil untuk sensor sekali pengambilan, flush() harus menampilkan
BAD_VALUE dan tidak menghasilkan peristiwa selesai penghapusan.
Menulis peristiwa sensor ke FMQ
FMQ Peristiwa digunakan oleh HAL Sensor untuk mengirimkan peristiwa sensor ke framework sensor Android.
FMQ Acara adalah FMQ yang disinkronkan, yang berarti bahwa setiap upaya untuk menulis lebih banyak peristiwa ke FMQ daripada ruang yang tersedia akan mengakibatkan kegagalan penulisan. Dalam kasus tersebut, HAL harus menentukan apakah akan menulis kumpulan peristiwa saat ini sebagai dua grup peristiwa yang lebih kecil atau menulis semua peristiwa secara bersamaan jika ruang yang tersedia cukup.
Setelah Sensors HAL menulis jumlah peristiwa sensor yang diinginkan ke Event FMQ, Sensors HAL harus memberi tahu framework bahwa peristiwa sudah siap dengan menulis bit EventQueueFlagBits::READ_AND_PROCESS ke fungsi EventFlag::wake Event FMQ. EventFlag dapat dibuat dari Event FMQ
menggunakan EventFlag::createEventFlag dan fungsi getEventFlagWord()
Event FMQ.
Sensor HAL 2.0/2.1 mendukung write dan writeBlocking di Event FMQ.
Implementasi default menyediakan referensi untuk menggunakan write. Jika fungsi
writeBlocking digunakan, flag readNotification harus ditetapkan ke
EventQueueFlagBits::EVENTS_READ, yang ditetapkan oleh framework saat membaca
peristiwa dari Event FMQ. Flag notifikasi tulis harus disetel ke
EventQueueFlagBits::READ_AND_PROCESS, yang memberi tahu framework bahwa peristiwa
telah ditulis ke Event FMQ.
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 Event FMQ, Sensors HAL harus mengamankan kunci wake untuk memastikan bahwa
sistem tetap aktif hingga framework dapat menangani peristiwa tersebut. Setelah menerima peristiwa
WAKE_UP, framework mengamankan penguncian layar saat aktifnya sendiri, sehingga
HAL Sensor dapat melepaskan penguncian layar saat aktifnya. Untuk menyinkronkan saat HAL Sensor
melepas kunci wake lock-nya, gunakan FMQ Wake Lock.
HAL Sensor harus membaca FMQ Wake Lock untuk menentukan jumlah peristiwa WAKE_UP yang telah ditangani framework. HAL hanya boleh melepaskan kunci aktifnya
untuk peristiwa WAKE_UP jika jumlah total peristiwa WAKE_UP yang tidak ditangani adalah nol.
Setelah menangani peristiwa sensor, framework menghitung jumlah peristiwa yang ditandai sebagai peristiwa WAKE_UP dan menulis kembali jumlah ini ke Wake Lock FMQ.
Framework menetapkan notifikasi penulisan 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 HAL Sensor. Hal ini memberi tahu framework tentang sensor dinamis baru dan memungkinkan sensor dikontrol melalui framework dan peristiwa sensor digunakan 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 saat peristiwa sensor ditulis ke memori tertentu, bukan ke FMQ Peristiwa dengan 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
pelaporan langsung.
Fungsi registerDirectChannel() dan unregisterDirectChannel() membuat
atau menghancurkan saluran langsung baru.
Mode operasi
Fungsi setOperationMode() memungkinkan framework mengonfigurasi sensor
sehingga framework dapat memasukkan data sensor ke dalam 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 mengirimkan parameter operasional ke Sensors HAL. Fungsi ini juga dapat digunakan untuk menyuntikkan peristiwa sensor ke sensor tertentu.
Validasi
Untuk memvalidasi penerapan HAL Sensor, jalankan pengujian CTS dan VTS sensor.
Pengujian CTS
Pengujian CTS sensor ada dalam pengujian CTS otomatis dan aplikasi CTS Verifier manual.
Pengujian otomatis berada 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 berada 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 uji CTS sangat penting untuk memastikan bahwa perangkat yang diuji memenuhi semua persyaratan CDD.
Pengujian VTS
Pengujian VTS untuk Sensors HAL 2.0 berada di
hardware/interfaces/sensors/2.0/vts.
Pengujian VTS untuk Sensors HAL 2.1 berada di
hardware/interfaces/sensors/2.1/vts.
Pengujian ini memastikan bahwa HAL Sensor diimplementasikan dengan benar dan semua persyaratan dalam ISensors.hal dan ISensorsCallback.hal terpenuhi dengan benar.
Mengupgrade ke HAL Sensor 2.1 dari 2.0
Saat mengupgrade ke Sensors 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 dalam mendukung kedua versi HAL, sebaiknya gunakan Multi-HAL 2.1.
Untuk contoh cara mengimplementasikan HAL Sensor 2.1 Anda sendiri, lihat Sensors.h.
Mengupgrade ke HAL Sensor 2.0 dari 1.0
Saat mengupgrade ke HAL Sensor 2.0 dari 1.0, pastikan penerapan HAL Anda memenuhi persyaratan berikut.
Menginisialisasi HAL
Fungsi initialize() harus didukung untuk membuat FMQ antara framework dan HAL.
Mengekspos sensor yang tersedia
Di Sensors HAL 2.0, fungsi getSensorsList() harus menampilkan nilai yang sama
selama satu kali booting perangkat, bahkan di seluruh proses mulai ulang Sensors HAL. Persyaratan baru
fungsi getSensorsList() adalah fungsi tersebut harus menampilkan nilai yang sama selama
satu kali booting perangkat, bahkan di seluruh proses mulai ulang HAL Sensor. Hal ini memungkinkan framework mencoba memulihkan koneksi sensor jika server sistem dimulai ulang. Nilai yang ditampilkan oleh getSensorsList() dapat berubah setelah perangkat melakukan mulai ulang.
Menulis peristiwa sensor ke FMQ
Daripada menunggu poll() dipanggil, di Sensors HAL 2.0, Sensors
HAL harus secara proaktif menulis peristiwa sensor ke Event FMQ 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 Sensors HAL 1.0, HAL dapat melepaskan kunci wake-nya untuk peristiwa WAKE_UP apa pun pada panggilan poll() berikutnya setelah WAKE_UP diposting ke poll() karena ini menunjukkan bahwa framework telah memproses semua peristiwa sensor dan telah mendapatkan kunci wake, jika perlu. Karena, di Sensors HAL 2.0,
HAL tidak lagi mengetahui kapan framework telah memproses peristiwa yang ditulis ke
FMQ, Wake Lock FMQ memungkinkan framework berkomunikasi dengan HAL saat framework
telah menangani peristiwa WAKE_UP.
Di Sensors HAL 2.0, kunci wake yang diamankan oleh Sensors HAL untuk WAKE_UP
peristiwa harus dimulai dengan SensorsHAL_WAKEUP.
Sensor dinamis
Sensor dinamis ditampilkan menggunakan fungsi poll() di Sensors 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
penunjuk ISensorsCallback yang disediakan melalui fungsi initialize().
Mode operasi
Mode DATA_INJECTION untuk sensor WAKE_UP harus didukung di Sensors HAL 2.0.
Dukungan Multi-HAL
HAL Sensor 2.0 dan 2.1 mendukung multi-HAL menggunakan framework Multi-HAL Sensor. Untuk mengetahui detail penerapan, lihat Melakukan porting dari Sensors HAL 1.0.