Sensors Hardware Abstraction Layer (HAL) adalah antarmuka antara kerangka kerja sensor Android dan sensor perangkat, seperti akselerometer atau giroskop. Sensor HAL mendefinisikan fungsi yang harus diimplementasikan untuk memungkinkan kerangka kerja mengontrol sensor.
Sensor HAL 2.0 tersedia di Android 10 dan lebih tinggi untuk perangkat baru dan yang ditingkatkan versinya. Sensor HAL 2.0 didasarkan pada Sensor HAL 1.0 tetapi memiliki beberapa perbedaan utama, yang mencegahnya agar tidak kompatibel. Sensor HAL 2.0 menggunakan Fast Message Queues (FMQs) untuk mengirim peristiwa sensor dari HAL ke dalam kerangka kerja sensor Android.
Sensor HAL 2.1 tersedia di Android 11 dan lebih tinggi untuk perangkat baru dan yang ditingkatkan versinya. Sensor HAL 2.1 adalah iterasi dari Sensor HAL 2.0 yang mengekspos tipe sensor HINGE_ANGLE dan memperbarui berbagai metode untuk menerima tipe HINGE_ANGLE .
Antarmuka HAL 2.1
Sumber utama dokumentasi untuk Sensor HAL 2.1 ada dalam definisi HAL di hardware/interfaces/sensors/2.1/ISensors.hal . Jika ada konflik persyaratan 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 konflik persyaratan antara halaman ini dan ISensors.hal , gunakan persyaratan di ISensors.hal .
Menerapkan Sensor HAL 2.0 dan HAL 2.1
Untuk mengimplementasikan Sensors HAL 2.0 atau 2.1, sebuah objek harus memperluas antarmuka ISensors dan mengimplementasikan semua fungsi yang didefinisikan dalam 2.0/ISensors.hal atau 2.1/ISensors.hal .
Inisialisasi 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 untuk menyediakan tiga parameter ke Sensor HAL: dua deskriptor FMQ dan satu pointer ke objek ISensorsCallback .
HAL menggunakan deskriptor pertama untuk membuat Event FMQ yang digunakan untuk menulis event sensor ke framework. HAL menggunakan deskriptor kedua untuk membuat Wake Lock FMQ yang digunakan untuk menyinkronkan saat HAL melepaskan kunci bangunnya untuk peristiwa sensor WAKE_UP . HAL harus menyimpan pointer ke objek ISensorsCallback sehingga fungsi panggilan balik 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() pada HAL 2.0 dan fungsi getSensorsList_2_1() pada HAL 2.1. Fungsi ini mengembalikan daftar sensor, masing-masing diidentifikasi secara unik oleh pegangannya. Pegangan untuk sensor yang diberikan tidak boleh berubah saat proses yang menghosting Sensor HAL dimulai ulang. Pegangan dapat berubah di seluruh reboot perangkat, dan di seluruh server sistem dimulai ulang.
Jika beberapa sensor berbagi jenis sensor dan properti bangun yang sama, maka sensor pertama dalam daftar disebut sensor default dan dikembalikan ke aplikasi yang menggunakan fungsi getDefaultSensor(int sensorType, bool wakeUp) .
Stabilitas daftar sensor
Setelah Sensor HAL dimulai ulang, jika data yang dikembalikan oleh getSensorsList() atau getSensorsList_2_1() menunjukkan perubahan yang signifikan dibandingkan dengan daftar sensor yang diambil sebelum dimulai ulang, framework akan memicu mulai ulang waktu proses Android. Perubahan signifikan pada daftar sensor termasuk kasus di mana sensor dengan pegangan tertentu hilang atau telah mengubah atribut, atau di mana sensor baru diperkenalkan. Meskipun memulai ulang waktu proses Android mengganggu pengguna, hal itu diperlukan karena kerangka kerja Android tidak dapat lagi memenuhi kontrak Android API sehingga sensor statis (nondinamis) tidak berubah selama masa pakai aplikasi. Ini juga dapat mencegah kerangka kerja membangun kembali permintaan sensor aktif yang dibuat oleh aplikasi. Oleh karena itu, vendor HAL disarankan untuk mencegah perubahan daftar sensor yang dapat dihindari.
Untuk memastikan pegangan sensor yang stabil, HAL harus secara deterministik memetakan sensor fisik tertentu di perangkat ke pegangannya. Meskipun tidak ada implementasi khusus yang diamanatkan oleh antarmuka Sensors HAL, pengembang memiliki sejumlah opsi yang tersedia untuk memenuhi persyaratan ini.
Misalnya, daftar sensor dapat diurutkan menggunakan kombinasi atribut tetap masing-masing sensor, seperti vendor, model, dan jenis sensor. Opsi lain bergantung pada fakta bahwa rangkaian sensor statis perangkat diperbaiki di perangkat keras, 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 tampilan dapat digunakan untuk mendapatkan pegangan yang stabil. Meskipun solusi terbaik bergantung pada detail implementasi spesifik HAL Anda, persyaratan utamanya adalah pegangan sensor tidak berubah saat 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 dikonfigurasi:
- Berkelanjutan: Peristiwa sensor dihasilkan pada tingkat yang berkelanjutan.
- Pada perubahan: Peristiwa dihasilkan tidak lebih cepat dari periode pengambilan sampel dan dapat dihasilkan pada tingkat yang lebih lambat dari periode pengambilan sampel jika nilai yang diukur tidak berubah.
- One-shot: Periode pengambilan sampel diabaikan.
- Khusus: Untuk detail selengkapnya, lihat Jenis sensor .
Untuk mempelajari tentang interaksi antara periode pengambilan sampel dan mode pelaporan sensor, lihat Mode Pelaporan .
Latensi pelaporan maksimum
Latensi pelaporan maksimum menetapkan waktu maksimum dalam nanodetik bahwa peristiwa dapat ditunda dan disimpan di FIFO perangkat keras sebelum ditulis ke FMQ Peristiwa melalui HAL saat SoC terjaga.
Nilai nol menandakan bahwa peristiwa harus dilaporkan segera setelah diukur, baik melewatkan FIFO sama sekali, atau mengosongkan FIFO segera setelah satu peristiwa dari sensor hadir di FIFO.
Misalnya, akselerometer yang diaktifkan pada 50 Hz dengan latensi pelaporan maksimum nol memicu interupsi 50 kali per detik saat SoC terjaga.
Jika latensi pelaporan maksimum lebih besar dari nol, peristiwa sensor tidak perlu dilaporkan segera setelah terdeteksi. Peristiwa dapat disimpan sementara di FIFO perangkat keras dan dilaporkan dalam kumpulan, selama tidak ada peristiwa yang tertunda lebih dari latensi pelaporan maksimum. Semua peristiwa sejak batch sebelumnya dicatat dan dikembalikan sekaligus. Ini mengurangi jumlah interupsi yang dikirim ke SoC dan memungkinkan SoC untuk beralih ke mode daya yang lebih rendah saat sensor menangkap dan mengelompokkan data.
Setiap acara memiliki stempel waktu yang terkait dengannya. Menunda waktu pelaporan peristiwa tidak boleh memengaruhi stempel waktu peristiwa. Stempel waktu harus akurat dan sesuai dengan waktu terjadinya peristiwa secara fisik, bukan waktu dilaporkan.
Untuk informasi dan persyaratan tambahan tentang pelaporan peristiwa sensor dengan latensi pelaporan maksimum bukan nol, lihat Pengelompokan .
Mengaktifkan sensor
Kerangka kerja mengaktifkan dan menonaktifkan sensor menggunakan fungsi activate() . Sebelum mengaktifkan sensor, framework harus terlebih dahulu mengonfigurasi sensor menggunakan batch() .
Setelah sensor dinonaktifkan, peristiwa sensor tambahan dari sensor itu tidak boleh ditulis ke FMQ Peristiwa.
Sensor pembilasan
Jika sebuah sensor dikonfigurasikan untuk mengelompokkan data sensor, kerangka kerja dapat memaksa flush langsung dari peristiwa sensor batch dengan memanggil flush() . Hal ini menyebabkan peristiwa sensor batch untuk pegangan sensor yang ditentukan segera ditulis ke FMQ Peristiwa. Sensors HAL harus menambahkan event flush complete ke akhir event sensor yang ditulis sebagai hasil dari panggilan ke flush() .
Flush terjadi secara tidak sinkron (yaitu, fungsi ini harus segera kembali). Jika implementasi menggunakan FIFO tunggal untuk beberapa sensor, FIFO tersebut akan di-flush dan event flush complete ditambahkan hanya untuk sensor yang ditentukan.
Jika sensor yang ditentukan tidak memiliki FIFO (tidak ada buffering), atau jika FIFO kosong pada saat panggilan, flush() masih harus berhasil dan mengirim acara flush complete untuk sensor itu. Ini berlaku untuk semua sensor selain sensor sekali tembak.
Jika flush() dipanggil untuk sensor one-shot, maka flush() harus mengembalikan BAD_VALUE dan tidak menghasilkan acara flush complete.
Menulis peristiwa sensor ke FMQ
FMQ Peristiwa digunakan oleh Sensor HAL untuk mendorong peristiwa sensor ke dalam kerangka kerja sensor Android.
FMQ Acara adalah FMQ yang disinkronkan, yang berarti bahwa setiap upaya untuk menulis lebih banyak acara ke FMQ daripada ruang yang tersedia akan menghasilkan penulisan yang gagal. Dalam kasus seperti itu, HAL harus menentukan apakah akan menulis rangkaian kejadian saat ini sebagai dua kelompok kejadian yang lebih kecil atau menulis semua kejadian bersama-sama bila tersedia cukup ruang.
Ketika Sensor HAL telah menulis jumlah peristiwa sensor yang diinginkan ke FMQ Peristiwa, HAL Sensor harus memberi tahu kerangka kerja 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() dari Event FMQ.
Sensor HAL 2.0/2.1 mendukung write dan writeBlocking pada Event FMQ. Implementasi default menyediakan referensi untuk menggunakan write . Jika fungsi writeBlocking digunakan, flag readNotification harus disetel ke EventQueueFlagBits::EVENTS_READ , yang disetel oleh framework saat membaca event dari Event FMQ. Tanda pemberitahuan tulis harus disetel ke EventQueueFlagBits::READ_AND_PROCESS , yang memberi tahu kerangka kerja bahwa peristiwa telah ditulis ke FMQ Acara.
Acara WAKE_UP
Peristiwa WAKE_UP adalah peristiwa sensor yang menyebabkan pemroses aplikasi (AP) bangun dan segera menangani peristiwa tersebut. Setiap kali peristiwa WAKE_UP ditulis ke FMQ Peristiwa, Sensor HAL harus mengamankan penguncian saat aktif untuk memastikan bahwa sistem tetap terjaga hingga kerangka kerja dapat menangani peristiwa tersebut. Setelah menerima peristiwa WAKE_UP , kerangka kerja mengamankan penguncian layarnya sendiri, memungkinkan Sensor HAL untuk melepaskan penguncian layarnya. Untuk menyinkronkan saat Sensor HAL melepaskan penguncian layarnya, gunakan Wake Lock FMQ.
Sensor HAL harus membaca Wake Lock FMQ untuk menentukan jumlah kejadian WAKE_UP yang telah ditangani oleh framework. HAL hanya boleh melepaskan kunci bangunnya untuk peristiwa WAKE_UP jika jumlah total peristiwa WAKE_UP yang tidak tertangani adalah nol. Setelah menangani peristiwa sensor, kerangka kerja menghitung jumlah peristiwa yang ditandai sebagai peristiwa WAKE_UP dan menulis nomor ini kembali ke Wake Lock FMQ.
Kerangka kerja menyetel pemberitahuan penulisan WakeLockQueueFlagBits::DATA_WRITTEN di Wake Lock FMQ setiap kali ia menulis data ke Wake Lock FMQ.
Sensor dinamis
Sensor dinamis adalah sensor yang secara fisik bukan merupakan 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. Ini memberi tahu kerangka kerja sensor dinamis baru dan memungkinkan sensor dikendalikan melalui kerangka kerja dan agar peristiwa sensor dikonsumsi oleh klien.
Demikian pula, ketika sensor dinamis terputus, fungsi onDynamicSensorDisconnected di ISensorsCallback harus dipanggil sehingga kerangka kerja dapat menghapus sensor apa pun yang tidak lagi tersedia.
saluran langsung
Saluran langsung adalah metode operasi di mana peristiwa sensor ditulis ke memori tertentu alih-alih ke FMQ Peristiwa yang melewati Kerangka 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 kerangka kerja. 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 untuk mengonfigurasi sensor sehingga framework dapat menginjeksi data sensor ke dalam sensor. Ini berguna untuk pengujian, terutama untuk algoritma yang ada di bawah kerangka kerja.
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 penerapan Sensor HAL Anda, jalankan pengujian sensor CTS dan VTS.
tes CTS
Tes CTS sensor ada di kedua tes CTS otomatis dan aplikasi CTS Verifier manual.
Tes otomatis terletak di cts/tests/sensor/src/android/hardware/cts . Pengujian ini memverifikasi fungsionalitas standar sensor, seperti mengaktifkan sensor, batching, dan tingkat kejadian sensor.
Tes 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 tes CTS sangat penting untuk memastikan bahwa perangkat yang diuji memenuhi semua persyaratan CDD.
tes VTS
Tes VTS untuk Sensor HAL 2.0 terletak di perangkat keras/antarmuka/sensor/2.0/vts . Tes VTS untuk Sensor HAL 2.1 terletak di perangkat keras/antarmuka/sensor/2.1/vts . Tes ini memastikan bahwa Sensor HAL diimplementasikan dengan benar dan semua persyaratan dalam ISensors.hal dan ISensorsCallback.hal terpenuhi dengan benar.
Upgrade ke Sensor HAL 2.1 dari 2.0
Saat memutakhirkan 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, 2.1 HAL harus mendukung untuk diinisialisasi sebagai 2.0 HAL. Untuk menghindari kerumitan dalam mendukung kedua versi HAL, sangat disarankan untuk menggunakan Multi-HAL 2.1.
Untuk contoh bagaimana menerapkan Sensor 2.1 HAL Anda sendiri, lihat Sensors.h .
Meningkatkan ke Sensor HAL 2.0 dari 1.0
Saat meningkatkan ke Sensor HAL 2.0 dari 1.0, pastikan penerapan HAL Anda memenuhi persyaratan berikut.
Inisialisasi HAL
Fungsi initialize() harus didukung untuk membuat FMQ antara framework dan HAL.
Mengekspos sensor yang tersedia
Di Sensors HAL 2.0, fungsi getSensorsList() harus mengembalikan nilai yang sama selama satu perangkat boot, bahkan di seluruh Sensors HAL restart. Persyaratan baru dari fungsi getSensorsList() adalah ia harus mengembalikan nilai yang sama selama booting perangkat tunggal, bahkan di seluruh Sensors HAL restart. Ini memungkinkan kerangka kerja untuk mencoba membangun kembali koneksi sensor jika server sistem dimulai ulang. Nilai yang dikembalikan oleh getSensorsList() dapat berubah setelah perangkat melakukan reboot.
Menulis peristiwa sensor ke FMQ
Alih-alih menunggu poll() dipanggil, di Sensor HAL 2.0, Sensor HAL harus secara proaktif menulis peristiwa sensor ke FMQ Peristiwa kapan pun peristiwa sensor tersedia. HAL juga bertanggung jawab untuk menulis bit yang benar ke EventFlag untuk menyebabkan pembacaan FMQ dalam kerangka kerja.
Acara WAKE_UP
Di Sensors HAL 1.0, HAL dapat melepaskan penguncian bangunnya untuk setiap peristiwa WAKE_UP pada panggilan berikutnya ke poll() setelah WAKE_UP diposting ke poll() karena ini menunjukkan bahwa kerangka kerja telah memproses semua peristiwa sensor dan telah memperoleh kunci bangun, jika perlu. Karena, di Sensor HAL 2.0, HAL tidak lagi mengetahui kapan kerangka kerja telah memproses peristiwa yang ditulis ke FMQ, Wake Lock FMQ memungkinkan kerangka kerja untuk berkomunikasi dengan HAL ketika telah menangani peristiwa WAKE_UP .
Di Sensors HAL 2.0, penguncian layar saat aktif yang diamankan oleh Sensor HAL untuk acara WAKE_UP harus dimulai dengan SensorsHAL_WAKEUP .
Sensor dinamis
Sensor dinamis dikembalikan menggunakan fungsi poll() di Sensors HAL 1.0. Sensors 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 Sensors HAL 2.0.
Dukungan multi-HAL
Sensor HAL 2.0 dan 2.1 mendukung multi-HAL menggunakan kerangka Sensor Multi-HAL . Untuk detail implementasi, lihat Porting dari Sensor HAL 1.0 .