Google berkomitmen untuk mendorong terwujudnya keadilan ras bagi komunitas Kulit Hitam. Lihat caranya.

Halaman ini diterjemahkan oleh Cloud Translation API.

AIDL HAL sensor

Sensors Hardware Abstraction Layer (HAL) adalah antarmuka antara framework sensor Android dan sensor perangkat, seperti akselerometer atau giroskop. Sensors HAL menentukan fungsi yang harus diterapkan untuk memungkinkan framework mengontrol sensor.

Sensors AIDL HAL tersedia di Android 13 dan yang lebih tinggi untuk perangkat baru dan yang diupgrade. Sensors AIDL HAL, yang didasarkan pada Sensors HAL 2.1, menggunakan antarmuka AIDL HAL dan mengekspos jenis sensor IMU sumbu terbatas dan pelacak kepala.

Antarmuka HAL AIDL

Sumber utama dokumentasi untuk Sensors AIDL HAL berada dalam definisi HAL di hardware/interfaces/sensors/aidl/android/hardware/sensors/ISensors.aidl.

Mengimplementasikan Sensors AIDL HAL

Untuk mengimplementasikan HAL AIDL Sensor, objek harus memperluas antarmuka ISensors dan mengimplementasikan semua fungsi yang ditentukan di hardware/interfaces/sensors/aidl/android/hardware/sensors/ISensors.aidl.

Melakukan inisialisasi HAL

HAL Sensor harus diinisialisasi oleh framework sensor Android sebelum dapat digunakan. Framework memanggil fungsi initialize() untuk menyediakan tiga parameter ke Sensors HAL: dua deskripsi FMQ dan satu pointer ke objek ISensorsCallback.

HAL menggunakan deskriptor pertama untuk membuat Peristiwa FMQ yang digunakan untuk menulis peristiwa sensor ke framework. HAL menggunakan deskripsi kedua untuk membuat FMQ Wake Lock yang digunakan untuk menyinkronkan saat HAL melepaskan wake lock untuk peristiwa sensor WAKE_UP. HAL harus menyimpan pointer ke objek ISensorsCallback sehingga fungsi callback yang diperlukan dapat dipanggil.

Fungsi initialize() harus menjadi fungsi pertama yang dipanggil saat menginisialisasi Sensors HAL.

Mengekspos sensor yang tersedia

Untuk mendapatkan daftar semua sensor statis yang tersedia di perangkat, gunakan fungsi getSensorsList(). Fungsi ini menampilkan daftar sensor, yang masing-masing diidentifikasi secara unik oleh handle-nya. ID untuk sensor tertentu tidak boleh berubah saat proses yang menghosting Sensors HAL dimulai ulang. Nama sebutan channel dapat berubah di seluruh proses mulai ulang perangkat, dan di seluruh server sistem yang dimulai ulang.

Jika beberapa sensor memiliki jenis sensor dan properti pengaktifan yang sama, sensor pertama dalam daftar akan disebut sensor default dan ditampilkan ke aplikasi yang menggunakan fungsi getDefaultSensor(int sensorType, bool wakeUp).

Stabilitas daftar sensor

Setelah Sensors HAL dimulai ulang, jika data yang ditampilkan oleh getSensorsList() menunjukkan perubahan yang signifikan dibandingkan dengan daftar sensor yang diambil sebelum memulai ulang, framework akan memicu dimulai ulangnya runtime Android. Perubahan signifikan pada daftar sensor mencakup kasus saat sensor dengan tuas tertentu tidak ada atau memiliki atribut yang berubah, 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 secara deterministik ke handle-nya. Meskipun tidak ada implementasi 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 bergantung pada fakta bahwa kumpulan sensor statis perangkat diperbaiki dalam hardware, sehingga HAL perlu mengetahui kapan semua sensor yang diharapkan telah menyelesaikan inisialisasi sebelum kembali dari getSensorsList(). 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 penanganan sensor tidak berubah saat HAL dimulai ulang.

Mengonfigurasi sensor

Sebelum diaktifkan, sensor harus dikonfigurasi dengan periode sampling dan latensi pelaporan maksimum menggunakan fungsi batch().

Sensor harus dapat dikonfigurasi ulang kapan saja menggunakan batch() tanpa kehilangan data sensor.

Periode pengambilan sampel

Periode sampling memiliki arti yang berbeda berdasarkan jenis sensor yang dikonfigurasi:

Berkelanjutan: Peristiwa sensor dihasilkan pada kecepatan berkelanjutan.
Saat berubah: Peristiwa dibuat tidak lebih cepat dari periode sampling dan dapat dibuat dengan kecepatan yang lebih lambat dari periode sampling 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 sehingga peristiwa dapat ditunda dan disimpan dalam FIFO hardware sebelum ditulis ke Event FMQ melalui HAL saat SoC aktif.

Nilai nol menunjukkan 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 gangguan 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 beberapa batch, selama tidak ada peristiwa yang tertunda melebihi latensi pelaporan maksimum. Semua peristiwa sejak batch sebelumnya dicatat dan ditampilkan sekaligus. Hal ini mengurangi jumlah gangguan yang dikirim ke SoC dan memungkinkan SoC beralih ke mode daya yang lebih rendah saat sensor merekam dan mengelompokkan data.

Setiap peristiwa memiliki stempel waktu yang terkait dengannya. Menunda waktu saat 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 yang bukan nol, lihat Penggabungan.

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 flush

Jika sensor dikonfigurasi untuk mengelompokkan data sensor, framework dapat memaksa pembuangan langsung peristiwa sensor yang dikelompokkan dengan memanggil flush(). Hal ini menyebabkan peristiwa sensor batch untuk handle sensor yang ditentukan segera ditulis ke FMQ Peristiwa. HAL Sensor harus menambahkan peristiwa flush complete ke akhir peristiwa sensor yang ditulis sebagai hasil dari panggilan ke flush().

Flush terjadi secara asinkron (yaitu, fungsi ini harus segera ditampilkan). Jika implementasi menggunakan satu FIFO untuk beberapa sensor, FIFO tersebut akan dihapus dan peristiwa flush complete 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() harus tetap berhasil dan mengirim peristiwa penyemprotan lengkap untuk sensor tersebut. 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 flush lengkap.

Menulis peristiwa sensor ke FMQ

FMQ Peristiwa digunakan oleh Sensors HAL untuk mendorong peristiwa sensor ke 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 menyebabkan operasi tulis gagal. Dalam hal ini, HAL harus menentukan apakah akan menulis kumpulan peristiwa saat ini sebagai dua grup peristiwa yang lebih kecil atau menulis semua peristiwa bersama-sama jika ruang yang tersedia cukup.

Saat Sensors HAL telah 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.

Sensors AIDL HAL 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 disetel 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 pemroses aplikasi (AP) aktif dan langsung menangani peristiwa. Setiap kali peristiwa WAKE_UP ditulis ke FMQ Peristiwa, HAL Sensor harus mengamankan kunci layar aktif untuk memastikan bahwa sistem tetap aktif hingga framework dapat menangani peristiwa. 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 Sensors HAL melepaskan wake lock-nya, gunakan Wake Lock FMQ.

HAL Sensor harus membaca FMQ Penguncian Layar untuk menentukan jumlah peristiwa WAKE_UP yang telah ditangani oleh framework. 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 peristiwa sensor, framework 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 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 untuk perangkat, seperti gamepad dengan akselerometer.

Saat sensor dinamis terhubung, fungsi onDynamicSensorConnected di ISensorsCallback harus dipanggil dari Sensors HAL. Tindakan ini akan memberi tahu framework tentang sensor dinamis baru dan memungkinkan sensor dikontrol melalui framework serta membuat 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

Direct channel adalah metode operasi saat peristiwa sensor ditulis ke memori tertentu, bukan ke FMQ Peristiwa yang mengabaikan 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 memasukkan data sensor ke dalam sensor. Hal ini berguna untuk pengujian, terutama untuk algoritma yang ada di bawah framework.

Fungsi injectSensorData() biasanya digunakan untuk mengirim parameter operasional ke Sensor HAL. Fungsi ini juga dapat digunakan untuk memasukkan peristiwa sensor ke dalam sensor tertentu.

Validasi

Untuk memvalidasi penerapan Sensor HAL, jalankan pengujian CTS dan VTS sensor.

Pengujian CTS

Uji CTS sensor tersedia baik pada uji CTS otomatis maupun 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 sensor melaporkan nilai yang akurat.

Lulus pengujian CTS sangat penting untuk memastikan bahwa perangkat yang sedang diuji memenuhi semua persyaratan CDD.

Pengujian VTS

Pengujian VTS untuk Sensors AIDL HAL terletak di hardware/interfaces/sensors/aidl/vts/. Pengujian ini memastikan bahwa Sensors HAL diimplementasikan dengan benar dan semua persyaratan dalam ISensors.aidl dan ISensorsCallback.aidl terpenuhi dengan benar.

Melakukan inisialisasi HAL

Fungsi initialize() harus didukung untuk membuat FMQ antara framework dan HAL.

Ekspos sensor yang tersedia

Di Sensors AIDL HAL, fungsi getSensorsList() harus menampilkan nilai yang sama selama booting perangkat tunggal, bahkan di seluruh Sensors HAL yang dimulai ulang. Persyaratan baru dari fungsi getSensorsList() adalah fungsi tersebut harus menampilkan nilai yang sama selama booting satu perangkat, bahkan di seluruh Sensors HAL yang dimulai ulang. Hal ini memungkinkan framework mencoba membangun kembali 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 AIDL HAL, Sensors 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 yang menyebabkan pembacaan FMQ dalam framework.

Peristiwa WAKE_UP

Di Sensors HAL 1.0, HAL dapat melepaskan kunci layar aktifnya untuk peristiwa WAKE_UP 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 kunci layar aktif, jika diperlukan. Karena, di HAL AIDL Sensor, HAL tidak lagi diberi tahu saat framework telah memproses peristiwa yang ditulis ke FMQ, Wake Lock FMQ memungkinkan framework berkomunikasi dengan HAL saat telah menangani peristiwa WAKE_UP.

Di Sensors AIDL HAL, wake lock yang diamankan oleh Sensors HAL untuk peristiwa WAKE_UP harus dimulai dengan SensorsHAL_WAKEUP.

Sensor dinamis

Sensor dinamis ditampilkan menggunakan fungsi poll() di Sensors HAL 1.0. Sensors AIDL HAL 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.

Dukungan multi-HAL

AIDL HAL Sensor mendukung multi-HAL menggunakan framework Multi-HAL Sensor. Untuk detail implementasi, lihat Porting dari Sensor HAL 2.1.