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

Sensor HAL 2

Lapisan Abstraksi Perangkat Keras Sensor (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 mencegah dari yang kompatibel. Sensor HAL 2.0 kegunaan Cepat Pesan Antrian (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 ditingkatkan versinya. Sensor HAL 2.1 adalah iterasi dari sensor HAL 2.0 yang mengekspos HINGE_ANGLE jenis sensor dan update berbagai metode untuk menerima HINGE_ANGLE jenis.

Antarmuka HAL 2.1

Sumber utama dokumentasi untuk Sensor HAL 2.1 adalah dalam definisi HAL di hardware / interface / sensor / 2.1 / ISensors.hal . Jika ada konflik persyaratan antara halaman ini dan ISensors.hal , menggunakan persyaratan dalam ISensors.hal .

Antarmuka HAL 2.0

Sumber utama dokumentasi untuk Sensor HAL 2.0 adalah dalam definisi HAL di hardware / interface / sensor / 2.0 / ISensors.hal . Jika ada konflik persyaratan antara halaman ini dan ISensors.hal , menggunakan persyaratan dalam ISensors.hal .

Menerapkan Sensor HAL 2.0 dan HAL 2.1

Untuk melaksanakan Sensor HAL 2.0 atau 2.1, sebuah objek harus memperpanjang ISensors antarmuka dan melaksanakan 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. Kerangka kerja ini menyebut initialize() fungsi untuk HAL 2.0 dan initialize_2_1() fungsi untuk HAL 2.1 untuk menyediakan tiga parameter ke Sensor HAL: dua FMQ deskriptor dan satu pointer ke ISensorsCallback objek.

HAL menggunakan deskriptor pertama untuk membuat Event FMQ yang digunakan untuk menulis event sensor ke framework. HAL menggunakan deskriptor kedua untuk menciptakan Wake Lock FMQ digunakan untuk menyinkronkan ketika HAL melepaskan kunci bangun untuk WAKE_UP peristiwa sensor. HAL harus menyimpan pointer ke ISensorsCallback objek sehingga setiap fungsi callback yang diperlukan mungkin akan dipanggil.

The initialize() atau initialize_2_1() fungsi harus fungsi pertama dipanggil saat inisialisasi Sensor HAL.

Mengekspos sensor yang tersedia

Untuk mendapatkan daftar semua sensor statis yang tersedia dalam perangkat, gunakan getSensorsList() fungsi pada HAL 2.0 dan getSensorsList_2_1() fungsi 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 yang sama dan properti bangun, maka sensor pertama dalam daftar disebut sensor default dan dikembalikan ke aplikasi yang memanfaatkan getDefaultSensor(int sensorType, bool wakeUp) fungsi.

Stabilitas daftar sensor

Setelah restart Sensor HAL, jika data yang dikembalikan oleh getSensorsList() atau getSensorsList_2_1() menunjukkan perubahan yang signifikan dibandingkan dengan daftar sensor diambil sebelum restart, kerangka memicu restart dari runtime 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 yang diberikan 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. Pilihan lain bergantung pada fakta bahwa set perangkat sensor statis adalah tetap dalam perangkat keras, sehingga HAL perlu tahu kapan semua sensor 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 sampling dan maksimum melaporkan latency menggunakan batch() fungsi.

Sebuah sensor harus dapat dikonfigurasi ulang setiap saat 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 lebih jelasnya, lihat jenis Sensor .

Untuk mempelajari tentang interaksi antara periode sampling dan pelaporan mode sensor, lihat Pelaporan Mode .

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 tambahan dan persyaratan pada pelaporan peristiwa sensor dengan nol maksimum pelaporan latency, lihat Batching .

Mengaktifkan sensor

Kerangka kerja ini memungkinkan dan menonaktifkan sensor menggunakan activate() fungsi. Sebelum mengaktifkan sensor, kerangka pertama harus mengkonfigurasi sensor menggunakan batch() .

Setelah sensor dinonaktifkan, peristiwa sensor tambahan dari sensor tersebut tidak boleh ditulis ke FMQ Peristiwa.

Sensor pembilasan

Jika sensor dikonfigurasi untuk data sensor batch, kerangka bisa memaksa siram langsung peristiwa sensor batched dengan memanggil flush() . Ini menyebabkan peristiwa sensor batch untuk pegangan sensor yang ditentukan segera ditulis ke FMQ Peristiwa. Sensor HAL harus menambahkan sebuah acara lengkap flush untuk akhir peristiwa sensor yang ditulis sebagai hasil dari panggilan untuk 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 ditentukan tidak memiliki FIFO (tidak ada penyangga mungkin), atau jika FIFO kosong pada saat panggilan, flush() masih harus berhasil dan mengirim acara lengkap siram untuk sensor itu. Ini berlaku untuk semua sensor selain sensor sekali tembak.

Jika flush() disebut untuk sensor satu-shot, maka flush() harus kembali BAD_VALUE dan tidak menghasilkan acara lengkap flush.

Menulis peristiwa sensor ke FMQ

FMQ Peristiwa digunakan oleh Sensor HAL untuk mendorong peristiwa sensor ke dalam kerangka kerja sensor Android.

Acara FMQ 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 untuk menulis semua kejadian bersama-sama bila tersedia cukup ruang.

Ketika Sensor HAL telah menulis nomor yang dikehendaki dari peristiwa sensor ke Event FMQ, Sensor HAL harus memberitahu kerangka bahwa peristiwa siap dengan menulis EventQueueFlagBits::READ_AND_PROCESS bit ke Event FMQ ini EventFlag::wake fungsi. EventFlag yang dapat dibuat dari acara FMQ menggunakan EventFlag::createEventFlag dan acara FMQ ini getEventFlagWord() fungsi.

Sensor HAL 2.0 / 2.1 mendukung kedua write dan writeBlocking pada acara FMQ. Implementasi standar menyediakan referensi untuk menggunakan write . Jika writeBlocking fungsi digunakan, readNotification bendera harus diatur ke EventQueueFlagBits::EVENTS_READ , yang diatur oleh kerangka kerja saat membaca peristiwa dari acara FMQ. Menulis bendera pemberitahuan harus diatur ke EventQueueFlagBits::READ_AND_PROCESS , yang memberitahukan kerangka bahwa peristiwa telah ditulis untuk Event FMQ.

Acara WAKE_UP

WAKE_UP peristiwa adalah peristiwa sensor yang menyebabkan aplikasi prosesor (AP) untuk bangun dan menangani acara segera. Setiap kali WAKE_UP acara ditulis untuk Event FMQ, Sensor HAL harus mengamankan kunci bangun untuk memastikan bahwa sistem tetap terjaga sampai kerangka dapat menangani acara tersebut. Setelah menerima WAKE_UP acara, kerangka mengamankan kunci bangun sendiri, memungkinkan untuk Sensor HAL untuk melepaskan kunci belakangnya. Untuk menyinkronkan saat Sensor HAL melepaskan penguncian layarnya, gunakan Wake Lock FMQ.

Sensor HAL harus membaca Wake Lock FMQ untuk menentukan jumlah WAKE_UP peristiwa yang kerangka telah ditangani. HAL hanya harus melepaskan kunci bangun untuk WAKE_UP peristiwa jika jumlah total tertangani WAKE_UP peristiwa adalah nol. Setelah menangani peristiwa sensor, kerangka menghitung jumlah peristiwa yang ditandai sebagai WAKE_UP peristiwa dan menulis nomor ini kembali ke Wake Lock FMQ.

Kerangka kerja ini menetapkan WakeLockQueueFlagBits::DATA_WRITTEN menulis pemberitahuan di Wake Lock FMQ setiap kali 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.

Ketika sensor dinamis terhubung, onDynamicSensorConnected fungsi dalam 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 sebuah sensor yang dinamis terputus, onDynamicSensorDisconnected fungsi dalam ISensorsCallback harus disebut bahwa kerangka dapat menghapus sensor 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. The configDirectReport() fungsinya hampir sama dengan batch() untuk operasi normal dan mengkonfigurasi channel laporan langsung.

The registerDirectChannel() dan unregisterDirectChannel() fungsi membuat atau menghancurkan saluran langsung baru.

Mode operasi

The setOperationMode() fungsi memungkinkan untuk kerangka untuk mengkonfigurasi sensor sehingga kerangka dapat menyuntikkan data sensor ke sensor. Ini berguna untuk pengujian, terutama untuk algoritma yang ada di bawah framework.

The injectSensorData() fungsi dalam HAL 2.0 dan injectSensorsData_2_1() fungsi dalam HAL 2.0 biasanya digunakan untuk mendorong parameter operasional ke dalam 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 / tes / 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 / sensor . 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 hardware / interface / sensor / 2.0 / VTS . Tes VTS untuk Sensor HAL 2.1 terletak di hardware / interface / sensor / 2.1 / VTS . Tes ini memastikan bahwa Sensor HAL diimplementasikan dengan benar dan bahwa semua persyaratan dalam ISensors.hal dan ISensorsCallback.hal terpenuhi dengan baik.

Upgrade ke Sensor HAL 2.1 dari 2.0

Ketika upgrade ke Sensor HAL 2.1 dari 2.0, implementasi HAL Anda harus menyertakan initialize_2_1() , getSensorsList_2_1() , dan injectSensorsData_2_1() metode, bersama-sama 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 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 Anda sendiri 2.1 HAL, lihat Sensors.h .

Upgrade 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

The initialize() fungsi harus didukung untuk mendirikan FMQs antara kerangka dan HAL.

Mengekspos sensor yang tersedia

Dalam Sensor HAL 2.0, getSensorsList() fungsi harus mengembalikan nilai yang sama selama boot perangkat tunggal, bahkan di seluruh Sensor HAL restart. Persyaratan baru dari getSensorsList() fungsi adalah bahwa ia harus mengembalikan nilai yang sama selama boot perangkat tunggal, bahkan di seluruh Sensor 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 ini melakukan perangkat reboot.

Menulis peristiwa sensor ke FMQ

Daripada menunggu poll() akan dipanggil, di Sensor HAL 2.0, Sensor HAL harus peristiwa sensor proaktif menulis ke Event FMQ setiap kali peristiwa sensor yang tersedia. HAL juga bertanggung jawab untuk menulis bit yang benar untuk EventFlag untuk menyebabkan FMQ membaca dalam kerangka.

Acara WAKE_UP

Dalam Sensor HAL 1.0, HAL mampu melepaskan kunci bangun untuk setiap WAKE_UP acara pada setiap panggilan berikutnya untuk poll() setelah WAKE_UP telah diposting ke poll() karena ini menunjukkan bahwa kerangka itu diproses semua peristiwa sensor dan telah memperoleh kunci bangun, jika perlu. Karena, di Sensor HAL 2.0, HAL tidak lagi tahu kapan kerangka telah diproses peristiwa tertulis kepada FMQ, Wake Lock FMQ memungkinkan kerangka kerja untuk berkomunikasi dengan HAL ketika telah ditangani WAKE_UP peristiwa.

Dalam Sensor HAL 2.0, kunci bangun dijamin dengan Sensor HAL untuk WAKE_UP acara harus dimulai dengan SensorsHAL_WAKEUP .

Sensor dinamis

Sensor dinamis dikembalikan menggunakan poll() fungsi dalam Sensor HAL 1.0. Sensor HAL 2.0 mengharuskan onDynamicSensorsConnected dan onDynamicSensorsDisconnected di ISensorsCallback disebut setiap kali dinamis koneksi sensor perubahan. Callback ini tersedia sebagai bagian dari ISensorsCallback pointer yang disediakan melalui initialize() fungsi.

Mode operasi

The DATA_INJECTION modus untuk WAKE_UP sensor harus didukung dalam Sensor HAL 2.0.

Dukungan multi-HAL

Sensor HAL 2.0 dan 2.1 mendukung multi-HAL menggunakan kerangka kerja sensor Multi-HAL . Untuk rincian pelaksanaan, lihat Porting dari Sensor HAL 1.0 .