Sensors Hardware Abstraksi Layer (HAL) adalah antarmuka antara Framework sensor Android dan sensor perangkat, seperti akselerometer atau giroskop. Sensor HAL mendefinisikan fungsi yang harus diimplementasikan ke memungkinkan framework untuk mengontrol sensor.
Sensors AIDL HAL tersedia di Android 13 dan untuk perangkat baru dan yang diupgrade. Sensor AIDL HAL, yang didasarkan pada Sensor HAL 2.1, menggunakan Antarmuka AIDL HAL dan menampilkan jenis sensor IMU sumbu terbatas dan pelacak kepala.
Antarmuka AIDL HAL
Sumber utama dokumentasi untuk Sensor AIDL HAL ada dalam HAL definisi di hardware/interfaces/sensors/aidl/android/hardware/sensors/ISensors.aidl.
Mengimplementasikan HAL AIDL Sensor
Untuk menerapkan Sensor AIDL HAL, objek harus memperluas ISensors
dan mengimplementasikan semua fungsi yang didefinisikan dalam
hardware/interfaces/sensors/aidl/android/hardware/sensors/ISensors.aidl.
Melakukan inisialisasi HAL
Sensor HAL harus diinisialisasi oleh framework sensor Android sebelum
dapat digunakan. Framework ini memanggil fungsi initialize()
untuk menyediakan tiga
parameter ke Sensor HAL: dua deskriptor FMQ dan satu pointer ke
Objek ISensorsCallback
.
HAL menggunakan deskriptor pertama untuk membuat Peristiwa FMQ yang digunakan untuk menulis sensor
peristiwa ke kerangka kerja. HAL menggunakan deskriptor kedua untuk membuat Wake
Mengunci FMQ yang digunakan untuk menyinkronkan saat HAL melepaskan penguncian layar saat aktif untuk WAKE_UP
kejadian sensor. HAL harus menyimpan pointer ke objek ISensorsCallback
sehingga
fungsi callback yang diperlukan dapat dipanggil.
Fungsi initialize()
harus menjadi fungsi pertama yang dipanggil saat melakukan inisialisasi
Sensor HAL.
Ekspos sensor yang tersedia
Untuk mendapatkan daftar semua sensor statis yang tersedia di perangkat, gunakan
Fungsi getSensorsList()
. Fungsi ini menampilkan daftar sensor, masing-masing
secara unik
diidentifikasi oleh {i>handle<i}-nya. Tuas untuk sensor tertentu tidak boleh berubah
saat proses yang menjadi {i>host<i}
Sensor HAL dimulai ulang. Nama sebutan channel dapat berubah di
perangkat dimulai ulang, dan
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 getDefaultSensor(int sensorType, bool wakeUp)
fungsi tersebut.
Stabilitas daftar sensor
Setelah HAL Sensor dimulai ulang, jika data yang ditampilkan oleh getSensorsList()
menunjukkan perubahan yang signifikan dibandingkan dengan daftar sensor yang diambil sebelum
{i>restart<i}, kerangka kerja akan memicu {i>restart<i}
Android Runtime. Perubahan signifikan pada daftar sensor mencakup kasus di mana
sensor dengan tuas tertentu tidak ada atau telah berubah atribut, atau di mana
sensor-sensor tersebut dimasukkan. Meskipun memulai ulang runtime Android akan mengganggu
kepada pengguna, itu diperlukan karena kerangka
kerja Android tidak bisa lagi memenuhi
Kontrak API Android bahwa sensor statis (nondinamis) tidak berubah selama
masa aktif aplikasi. Hal ini juga dapat mencegah kerangka kerja
untuk 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 tuas sensor yang stabil, HAL harus dengan pasti memetakan sensor fisik pada perangkat ke pegangannya. Meskipun tidak ada implementasi yang spesifik dimandatkan oleh antarmuka Sensors HAL, developer memiliki sejumlah opsi yang tersedia untuk memenuhi persyaratan ini.
Misalnya, daftar sensor dapat diurutkan menggunakan kombinasi dari
atribut tetap, seperti vendor, model, dan jenis sensor. Pilihan lain bergantung pada
fakta bahwa rangkaian sensor statis perangkat
telah diperbaiki di perangkat keras, sehingga
HAL perlu mengetahui kapan semua sensor yang diharapkan telah menyelesaikan inisialisasi sebelum
kembali dari getSensorsList()
. Daftar ini
sensor yang diharapkan dapat dikompilasi ke
dalam biner HAL atau disimpan dalam
file konfigurasi dalam sistem file, dan urutan penampilan dapat digunakan
untuk mendapatkan handle yang stabil. Meskipun solusi terbaik
bergantung pada kemampuan HAL Anda
detail implementasi yang spesifik, persyaratan utamanya adalah
jangan berubah setiap kali HAL dimulai ulang.
Konfigurasi sensor
Sebelum sensor diaktifkan, sensor harus dikonfigurasi dengan pengambilan sampel
periode dan latensi pelaporan maksimum menggunakan fungsi batch()
.
Sensor harus dapat dikonfigurasi ulang kapan saja menggunakan batch()
tanpa
hilangnya 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.
- Kapan saja: Peristiwa dibuat tidak lebih cepat daripada periode pengambilan sampel dan mungkin yang dihasilkan dengan kecepatan yang lebih lambat dari periode pengambilan sampel tidak berubah.
- Satu kali: Periode pengambilan sampel diabaikan.
- Khusus: Untuk detail selengkapnya, lihat Jenis sensor.
Untuk mempelajari interaksi antara periode pengambilan sampel dan deteksi mode pelaporan, lihat Mode pelaporan.
Latensi pelaporan maksimum
Latensi pelaporan maksimum menetapkan waktu maksimum dalam nanodetik yang peristiwa dapat tertunda dan disimpan dalam FIFO perangkat keras sebelum ditulis ke {i>Event FMQ<i} melalui HAL saat SoC aktif.
Nilai nol menandakan bahwa peristiwa harus dilaporkan segera setelah diukur, baik melewatkan FIFO sama sekali, atau mengosongkan FIFO segera satu kejadian dari sensor ada di FIFO.
Misalnya, akselerometer diaktifkan pada 50 Hz dengan pelaporan maksimum latensi dari pemicu nol mengganggu 50 kali per detik saat SoC aktif.
Saat latensi pelaporan maksimum lebih besar dari nol, peristiwa sensor tidak perlu dilaporkan segera setelah terdeteksi. Acara dapat sementara disimpan dalam FIFO perangkat keras dan dilaporkan dalam kelompok, selama tidak ada tertunda lebih dari latensi pelaporan maksimum. Semua peristiwa sejak batch sebelumnya dicatat dan dikembalikan sekaligus. Hal ini mengurangi jumlah menginterupsi yang dikirim ke SoC dan memungkinkan SoC untuk beralih ke mode daya yang lebih rendah saat sensor mengambil dan mengelompokkan data.
Setiap peristiwa memiliki stempel waktu yang terkait. Menunda waktu saat peristiwa yang dilaporkan tidak boleh memengaruhi stempel waktu peristiwa. Stempel waktu harus akurat dan sesuai dengan waktu ketika peristiwa terjadi secara fisik, bukan waktu pelaporannya.
Untuk informasi dan persyaratan tambahan tentang pelaporan kejadian sensor dengan latensi pelaporan maksimum yang bukan nol, lihat Pengelompokan.
Aktifkan sensor
Framework ini 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 Event FMQ.
Flush sensor
Jika sensor dikonfigurasi untuk mengelompokkan data sensor, framework dapat memaksa
pengosongan langsung peristiwa sensor batch dengan memanggil flush()
. Hal ini menyebabkan
peristiwa sensor yang dikelompokkan agar handle sensor yang ditentukan segera
yang ditulis ke Event FMQ. HAL Sensor harus menambahkan peristiwa lengkap flush
ke akhir kejadian sensor yang ditulis sebagai hasil panggilan ke
flush()
.
Proses pengosongan terjadi secara asinkron (artinya, fungsi ini harus menampilkan segera). Jika implementasinya menggunakan satu FIFO untuk beberapa sensor, FIFO tersebut di-flush dan kejadian flush complete ditambahkan hanya untuk sensor yang ditentukan.
Jika sensor yang ditentukan tidak memiliki FIFO (tidak ada kemungkinan buffering), atau jika FIFO
kosong saat panggilan berlangsung, flush()
harus tetap berhasil dan mengirimkan
peristiwa lengkap untuk sensor tersebut. Ini berlaku untuk semua sensor selain sensor satu kali
sensor.
Jika flush()
dipanggil untuk sensor satu kali, flush()
harus ditampilkan
BAD_VALUE
dan tidak menghasilkan peristiwa flush complete.
Menulis peristiwa sensor ke FMQ
FMQ Peristiwa digunakan oleh Sensor HAL untuk mendorong kejadian sensor ke Android framework sensor.
Event FMQ adalah FMQ yang disinkronkan, yang berarti bahwa setiap upaya untuk menulis ke FMQ daripada ruang yang tersedia memungkinkan terjadinya kegagalan tulis. Dalam kasus semacam itu, HAL harus menentukan apakah akan menulis rangkaian kode saat ini peristiwa sebagai dua kelompok peristiwa yang lebih kecil atau menulis semua peristiwa bersama-sama ketika ada cukup ruang yang tersedia.
Ketika Sensor HAL telah menulis jumlah kejadian sensor yang diinginkan ke
Event FMQ, Sensor HAL harus memberi tahu framework bahwa peristiwa sudah siap
menulis bit EventQueueFlagBits::READ_AND_PROCESS
ke Event FMQ
fungsi EventFlag::wake
. EventFlag dapat dibuat dari Event FMQ
menggunakan EventFlag::createEventFlag
dan getEventFlagWord()
Event FMQ
fungsi tersebut.
AIDL HAL Sensor 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.
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 Event FMQ, Sensor HAL harus mengamankan penguncian layar saat aktif untuk
sistem tetap aktif hingga framework dapat menangani peristiwa tersebut. Setelah menerima
WAKE_UP
, framework mengamankan penguncian layar saat aktifnya sendiri, sehingga memungkinkan
Sensor HAL untuk melepaskan penguncian layar saat aktif. Untuk menyinkronkan saat Sensor HAL
melepaskan penguncian layar saat aktifnya, gunakan Wake Lock FMQ.
HAL Sensor harus membaca FMQ Penguncian Layar untuk menentukan jumlah WAKE_UP
yang telah ditangani oleh kerangka kerja. HAL hanya boleh melepaskan penguncian layar saat aktifnya
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 peristiwa WAKE_UP
dan menulis nomor ini kembali ke Wake Lock FMQ.
Framework menetapkan penulisan WakeLockQueueFlagBits::DATA_WRITTEN
pada Wake Lock FMQ setiap kali menulis data ke Wake Lock FMQ.
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 sensor dinamis baru dan memungkinkan sensor dikontrol
melalui kerangka kerja dan membuat
kejadian sensor digunakan oleh klien.
Demikian pula, ketika 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 di mana kejadian sensor ditulis
memori tertentu, alih-alih ke Event FMQ
yang melewati Sensor Android
Google Workspace. Klien yang mendaftarkan saluran langsung harus membaca peristiwa sensor
langsung dari memori yang digunakan untuk
membuat saluran langsung dan tidak akan
menerima kejadian sensor
melalui kerangka kerja. configDirectReport()
mirip dengan batch()
untuk operasi normal dan mengonfigurasi
saluran laporan.
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 sensor. Hal ini berguna untuk
pengujian, terutama untuk algoritma yang ada di bawah kerangka kerja.
Fungsi injectSensorData()
biasanya digunakan untuk mendorong operasional
parameter ke HAL Sensor. Fungsi ini juga dapat digunakan
untuk memasukkan sensor
peristiwa ke sensor tertentu.
Validasi
Untuk memvalidasi penerapan Sensor HAL, jalankan CTS dan VTS sensor pengujian.
Uji CTS
Uji CTS sensor tersedia baik pada uji CTS otomatis maupun 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 tingkat peristiwa sensor.
Tes CTS Verifier terletak di cts/apps/CtsVerifier/src/com/android/cts/verifier/sensors. Pengujian ini memerlukan input manual dari operator uji 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
Tes VTS untuk Sensor AIDL HAL berada di
hardware/interfaces/sensors/aidl/vts/.
Pengujian ini memastikan bahwa Sensor HAL
diterapkan dengan benar dan semua
persyaratan dalam ISensors.aidl
dan ISensorsCallback.aidl
terpenuhi dengan benar.
Melakukan inisialisasi HAL
Fungsi initialize()
harus didukung untuk membuat FMQ di antara
dan HAL.
Ekspos sensor yang tersedia
Di Sensor AIDL HAL, fungsi getSensorsList()
harus menampilkan nilai yang sama
selama {i>booting<i} perangkat tunggal, bahkan
saat HAL Sensor dimulai ulang. Persyaratan baru
dari fungsi getSensorsList()
adalah bahwa fungsi tersebut harus
menampilkan nilai yang sama selama
booting perangkat tunggal, bahkan saat Sensor HAL dimulai ulang. Hal ini memungkinkan
untuk mencoba menyambung kembali
koneksi sensor jika server sistem
akan dimulai ulang. Nilai yang ditampilkan oleh getSensorsList()
dapat berubah setelah perangkat
akan melakukan {i>reboot<i}.
Menulis peristiwa sensor ke FMQ
Alih-alih menunggu poll()
dipanggil, di Sensor AIDL HAL, Sensor
HAL harus secara proaktif menulis peristiwa sensor ke Event FMQ setiap kali terjadi peristiwa sensor
yang tersedia. HAL juga bertanggung jawab untuk
menulis bit yang benar ke
EventFlag
menyebabkan pembacaan FMQ dalam framework.
Acara WAKE_UP
Di Sensor HAL 1.0, HAL dapat melepaskan penguncian layar saat aktifnya untuk semua WAKE_UP
pada panggilan berikutnya ke poll()
setelah WAKE_UP
diposting ke
poll()
karena hal ini menunjukkan bahwa framework telah memproses semua sensor
dan memperoleh penguncian layar saat aktif, jika perlu. Karena, pada Sensor AIDL
HAL, HAL tidak lagi diberi tahu saat framework telah memproses peristiwa
ditulis ke FMQ, Wake Lock FMQ memungkinkan kerangka kerja untuk berkomunikasi
HAL jika telah menangani peristiwa WAKE_UP
.
Di Sensor AIDL HAL, penguncian layar saat aktif diamankan oleh Sensor HAL untuk WAKE_UP
peristiwa harus diawali dengan SensorsHAL_WAKEUP
.
Sensor dinamis
Sensor dinamis ditampilkan menggunakan fungsi poll()
di Sensor HAL 1.0.
AIDL HAL Sensor memerlukan onDynamicSensorsConnected
dan
onDynamicSensorsDisconnected
dalam ISensorsCallback
dipanggil setiap kali dinamis
koneksi sensor 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.
Dukungan Multi-HAL
AIDL HAL Sensor mendukung multi-HAL menggunakan Framework Multi-HAL Sensor. Sebagai detail penerapan, lihat Porting dari Sensors HAL 2.1.