Lapisan Abstraksi Perangkat Keras Sensor (HAL) adalah antarmuka antara kerangka sensor Android dan sensor perangkat, seperti akselerometer atau giroskop. Sensor HAL mendefinisikan fungsi yang harus diterapkan agar kerangka kerja dapat mengontrol sensor.
Sensor HAL 2.0 tersedia di Android 10 dan lebih tinggi untuk perangkat baru dan yang ditingkatkan. Sensor HAL 2.0 didasarkan pada Sensor HAL 1.0 namun memiliki beberapa perbedaan utama, sehingga tidak kompatibel dengan versi sebelumnya. Sensor HAL 2.0 menggunakan Fast Message Queues (FMQs) untuk mengirim peristiwa sensor dari HAL ke dalam kerangka sensor Android.
Sensor HAL 2.1 tersedia di Android 11 dan lebih tinggi untuk perangkat baru dan yang diupgrade. Sensor HAL 2.1 adalah iterasi 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 laman ini dan ISensors.hal , gunakan persyaratan di ISensors.hal .
Antarmuka HAL 2.0
Sumber utama dokumentasi untuk Sensor HAL 2.0 ada dalam definisi HAL di hardware/interfaces/sensors/2.0/ISensors.hal . Jika ada konflik persyaratan antara laman ini dan ISensors.hal , gunakan persyaratan di ISensors.hal .
Implementasi Sensor HAL 2.0 dan HAL 2.1
Untuk mengimplementasikan Sensors HAL 2.0 atau 2.1, suatu objek harus memperluas antarmuka ISensors dan mengimplementasikan semua fungsi yang ditentukan dalam 2.0/ISensors.hal atau 2.1/ISensors.hal .
Inisialisasi HAL
Sensor HAL harus diinisialisasi oleh kerangka sensor Android sebelum dapat digunakan. Kerangka kerja ini memanggil fungsi initialize() untuk HAL 2.0 dan fungsi initialize_2_1() untuk HAL 2.1 guna menyediakan tiga parameter ke Sensor HAL: dua deskriptor FMQ dan satu penunjuk ke objek ISensorsCallback .
HAL menggunakan deskriptor pertama untuk membuat Peristiwa FMQ yang digunakan untuk menulis peristiwa sensor ke kerangka kerja. HAL menggunakan deskriptor kedua untuk membuat Wake Lock FMQ yang digunakan untuk menyinkronkan ketika HAL melepaskan penguncian layar saat aktif 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.
Paparkan 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 mengembalikan daftar sensor, masing-masing diidentifikasi secara unik berdasarkan pegangannya. Pegangan untuk sensor tertentu tidak boleh berubah ketika proses hosting Sensor HAL dimulai ulang. Pegangan dapat berubah saat perangkat dinyalakan ulang, dan saat server sistem dihidupkan 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 Sensors HAL dimulai ulang, jika data yang dikembalikan oleh getSensorsList() atau getSensorsList_2_1() menunjukkan perubahan signifikan dibandingkan dengan daftar sensor yang diambil sebelum dimulai ulang, framework akan memicu dimulai ulang runtime Android. Perubahan signifikan pada daftar sensor mencakup kasus ketika sensor dengan pegangan tertentu hilang atau atributnya berubah, atau ketika sensor baru diperkenalkan. Meskipun memulai ulang runtime Android mengganggu pengguna, hal ini diperlukan karena framework Android tidak dapat lagi memenuhi kontrak API Android sehingga sensor statis (nondinamis) tidak berubah selama masa pakai aplikasi. Hal ini juga dapat mencegah framework untuk membuat 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 stabil, HAL harus memetakan sensor fisik tertentu di perangkat ke pegangannya secara deterministik. Meskipun tidak ada implementasi khusus yang diamanatkan oleh antarmuka Sensor 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 lainnya bergantung pada fakta bahwa rangkaian sensor statis perangkat sudah 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.
Konfigurasikan 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 berbeda berdasarkan jenis sensor yang dikonfigurasi:
- Berkelanjutan: Peristiwa sensor dihasilkan pada tingkat yang berkelanjutan.
- Saat Perubahan: Peristiwa dihasilkan tidak lebih cepat dari periode pengambilan sampel dan dapat dihasilkan dengan kecepatan lebih lambat dari periode pengambilan sampel jika nilai terukur tidak berubah.
- One-shot: Periode pengambilan sampel diabaikan.
- Spesial: Untuk lebih jelasnya, 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 agar peristiwa dapat ditunda dan disimpan di FIFO perangkat keras sebelum ditulis ke Peristiwa FMQ melalui HAL saat SoC aktif.
Nilai nol menandakan bahwa peristiwa harus dilaporkan segera setelah diukur, baik melewatkan 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 akan memicu interupsi 50 kali per detik saat SoC aktif.
Jika latensi pelaporan maksimum lebih besar dari nol, kejadian sensor tidak perlu dilaporkan segera setelah terdeteksi. Peristiwa dapat disimpan sementara di FIFO perangkat keras dan dilaporkan dalam batch, selama tidak ada peristiwa yang tertunda lebih dari latensi pelaporan maksimum. Semua kejadian sejak batch sebelumnya dicatat dan dikembalikan sekaligus. Hal ini mengurangi jumlah interupsi yang dikirim ke SoC dan memungkinkan SoC beralih ke mode daya yang lebih rendah saat sensor menangkap dan mengumpulkan data.
Setiap peristiwa memiliki stempel waktu yang terkait dengannya. Menunda waktu pelaporan suatu peristiwa tidak boleh berdampak pada 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 .
Aktifkan sensor
Kerangka kerja ini mengaktifkan dan menonaktifkan sensor menggunakan fungsi activate() . Sebelum mengaktifkan sensor, framework harus mengkonfigurasi sensor terlebih dahulu menggunakan batch() .
Setelah sensor dinonaktifkan, kejadian sensor tambahan dari sensor tersebut tidak boleh ditulis ke Event FMQ.
Sensor siram
Jika sensor dikonfigurasikan untuk mengumpulkan data sensor, kerangka kerja dapat memaksa penghapusan langsung peristiwa sensor yang dikumpulkan dengan memanggil flush() . Hal ini menyebabkan kejadian sensor batch untuk pegangan sensor tertentu segera ditulis ke Event FMQ. Sensor HAL harus menambahkan peristiwa flush complete ke akhir peristiwa sensor yang ditulis sebagai hasil panggilan ke flush() .
Flush terjadi secara asinkron (artinya, fungsi ini harus segera kembali). Jika implementasi menggunakan FIFO tunggal untuk beberapa sensor, FIFO tersebut akan di-flush dan kejadian flush complete ditambahkan hanya untuk sensor yang ditentukan.
Jika sensor yang ditentukan tidak memiliki FIFO (tidak ada buffering yang memungkinkan), atau jika FIFO kosong pada saat panggilan, flush() harus tetap berhasil dan mengirimkan peristiwa flush yang lengkap untuk sensor tersebut. Hal ini berlaku untuk semua sensor selain sensor sekali tembak.
Jika flush() dipanggil untuk sensor satu kali, maka flush() harus mengembalikan BAD_VALUE dan tidak menghasilkan peristiwa flush yang lengkap.
Tulis peristiwa sensor ke FMQ
Peristiwa FMQ digunakan oleh Sensor HAL untuk mendorong peristiwa sensor ke dalam kerangka sensor Android.
Event FMQ adalah FMQ tersinkronisasi, yang berarti bahwa setiap upaya untuk menulis lebih banyak peristiwa ke FMQ daripada ruang yang tersedia akan mengakibatkan kegagalan penulisan. Dalam kasus seperti ini, HAL harus menentukan apakah akan menuliskan rangkaian kejadian saat ini sebagai dua kelompok kejadian yang lebih kecil atau menuliskan semua kejadian secara bersamaan ketika tersedia ruang yang cukup.
Ketika Sensor HAL telah menulis jumlah kejadian sensor yang diinginkan ke Event FMQ, Sensor HAL harus memberi tahu kerangka kerja bahwa kejadian telah 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 pada Event FMQ. Implementasi default memberikan referensi untuk menggunakan write . Jika fungsi writeBlocking digunakan, flag readNotification harus disetel ke EventQueueFlagBits::EVENTS_READ , yang disetel oleh kerangka kerja saat membaca peristiwa dari Event FMQ. Bendera pemberitahuan tulis harus disetel ke EventQueueFlagBits::READ_AND_PROCESS , yang memberi tahu kerangka kerja bahwa peristiwa telah ditulis ke Event FMQ.
acara WAKE_UP
Peristiwa WAKE_UP adalah peristiwa sensor yang menyebabkan prosesor aplikasi (AP) bangun dan segera menangani peristiwa tersebut. Setiap kali peristiwa WAKE_UP ditulis ke FMQ Peristiwa, Sensor HAL harus mengamankan penguncian layar saat aktif 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 kunci layar saat aktifnya. Untuk menyinkronkan saat Sensor HAL melepaskan penguncian layar saat aktif, gunakan Wake Lock FMQ.
Sensor HAL harus membaca Wake Lock FMQ untuk menentukan jumlah kejadian WAKE_UP yang telah ditangani oleh kerangka kerja. HAL hanya boleh melepaskan penguncian layar saat aktif untuk peristiwa WAKE_UP jika jumlah total peristiwa WAKE_UP yang tidak tertangani adalah nol. Setelah menangani kejadian sensor, kerangka kerja menghitung jumlah kejadian yang ditandai sebagai kejadian WAKE_UP dan menulis nomor ini kembali ke Wake Lock FMQ.
Kerangka kerja ini menyetel pemberitahuan tulis 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 namun dapat digunakan sebagai input ke perangkat, seperti gamepad dengan akselerometer.
Saat sensor dinamis terhubung, fungsi onDynamicSensorConnected di ISensorsCallback harus dipanggil dari Sensors HAL. Hal ini memberi tahu kerangka sensor dinamis baru dan memungkinkan sensor dikontrol melalui kerangka kerja dan peristiwa sensor dikonsumsi oleh klien.
Demikian pula, ketika sensor dinamis terputus, fungsi onDynamicSensorDisconnected di ISensorsCallback harus dipanggil agar framework dapat menghapus sensor apa pun yang tidak lagi tersedia.
Saluran langsung
Saluran langsung adalah metode operasi di mana kejadian sensor ditulis ke memori tertentu dan bukan ke Event FMQ yang melewati Android Sensors Framework. Klien yang mendaftarkan saluran langsung harus membaca kejadian sensor langsung dari memori yang digunakan untuk membuat saluran langsung dan tidak akan menerima kejadian 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 kerangka kerja untuk mengonfigurasi sensor sehingga kerangka kerja 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 memasukkan parameter operasional ke Sensor HAL. Fungsi ini juga dapat digunakan untuk memasukkan peristiwa sensor ke dalam sensor tertentu.
Validasi
Untuk memvalidasi implementasi Sensor HAL Anda, jalankan pengujian sensor CTS dan VTS.
tes CTS
Tes Sensor CTS ada di 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 pengaktifan sensor, batching, dan laju kejadian sensor.
Tes CTS Verifier terletak di cts/apps/CtsVerifier/src/com/android/cts/verifier/sensors . Pengujian ini memerlukan masukan 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.
tes VTS
Tes VTS untuk Sensor HAL 2.0 terletak di hardware/interfaces/sensors/2.0/vts . Tes VTS untuk Sensor HAL 2.1 terletak di hardware/interfaces/sensors/2.1/vts . Pengujian ini memastikan bahwa Sensor HAL diterapkan dengan benar dan semua persyaratan dalam ISensors.hal dan ISensorsCallback.hal dipenuhi dengan benar.
Tingkatkan ke Sensor HAL 2.1 dari 2.0
Saat meningkatkan 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 tipe HAL 2.1. Metode ini harus memenuhi persyaratan yang sama seperti yang diuraikan pada 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 kerumitan dalam mendukung kedua versi HAL, sangat disarankan untuk menggunakan Multi-HAL 2.1.
Untuk contoh cara mengimplementasikan Sensors 2.1 HAL Anda sendiri, lihat Sensors.h .
Tingkatkan ke Sensor HAL 2.0 dari 1.0
Saat meningkatkan ke Sensor HAL 2.0 dari 1.0, pastikan implementasi HAL Anda memenuhi persyaratan berikut.
Inisialisasi HAL
Fungsi initialize() harus didukung untuk membangun FMQ antara kerangka kerja dan HAL.
Paparkan sensor yang tersedia
Di Sensors HAL 2.0, fungsi getSensorsList() harus mengembalikan nilai yang sama selama booting satu perangkat, bahkan saat Sensor HAL dimulai ulang. Persyaratan baru dari fungsi getSensorsList() adalah fungsi tersebut harus mengembalikan nilai yang sama selama booting satu perangkat, bahkan saat Sensor HAL dimulai ulang. Hal 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.
Tulis peristiwa sensor ke FMQ
Daripada menunggu poll() dipanggil, di Sensor HAL 2.0, Sensor HAL harus secara proaktif menulis kejadian sensor ke Event FMQ setiap kali kejadian sensor tersedia. HAL juga bertanggung jawab untuk menulis bit yang benar ke EventFlag untuk menyebabkan pembacaan FMQ dalam kerangka kerja.
acara WAKE_UP
Di Sensor HAL 1.0, HAL dapat melepaskan 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 memperoleh penguncian layar saat aktif, jika perlu. Karena, di Sensor HAL 2.0, HAL tidak lagi mengetahui kapan kerangka kerja telah memproses kejadian yang ditulis ke FMQ, Wake Lock FMQ memungkinkan kerangka kerja untuk berkomunikasi ke HAL ketika sudah menangani kejadian WAKE_UP .
Di Sensors HAL 2.0, penguncian layar saat aktif yang diamankan oleh Sensors HAL untuk peristiwa WAKE_UP harus dimulai dengan SensorsHAL_WAKEUP .
Sensor dinamis
Sensor dinamis dikembalikan 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 kerangka Sensor Multi-HAL . Untuk detail implementasi, lihat Porting dari Sensor HAL 1.0 .