Android 11 memperkenalkan kemampuan menggunakan AIDL untuk HAL di Android. Hal ini memungkinkan untuk mengimplementasikan bagian-bagian Android tanpa HIDL. Transisi HAL untuk menggunakan AIDL secara eksklusif jika memungkinkan (jika HAL upstream menggunakan HIDL, HIDL harus digunakan).
HAL yang menggunakan AIDL untuk berkomunikasi antar komponen framework, seperti yang ada dalam
system.img
, dan komponen hardware, seperti yang ada dalam vendor.img
, harus menggunakan
AIDL Stabil. Namun, untuk berkomunikasi dalam partisi, misalnya, dari satu
HAL ke HAL lainnya, tidak ada batasan dalam mekanisme IPC yang dapat digunakan.
Motivasi
AIDL telah ada lebih lama dari HIDL, dan digunakan di banyak tempat lain, seperti di antara komponen framework Android atau dalam aplikasi. Setelah AIDL memiliki dukungan stabilitas, seluruh stack dapat diterapkan dengan satu runtime IPC. AIDL juga memiliki sistem pembuatan versi yang lebih baik daripada HIDL.
- Menggunakan satu bahasa IPC berarti hanya memiliki satu hal untuk dipelajari, di-debug, dioptimalkan, dan diamankan.
- AIDL mendukung pembuatan versi langsung untuk pemilik antarmuka:
- Pemilik dapat menambahkan metode ke akhir antarmuka, atau kolom ke parcelable. Artinya, pembuatan versi kode dari tahun ke tahun menjadi lebih mudah, dan biaya dari tahun ke tahun juga lebih kecil (jenis dapat diubah secara langsung dan tidak perlu library tambahan untuk setiap versi antarmuka).
- Antarmuka ekstensi dapat dipasang saat runtime, bukan pada sistem jenis, sehingga Anda tidak perlu rebase ekstensi downstream ke versi antarmuka yang lebih baru.
- Antarmuka AIDL yang sudah ada dapat digunakan langsung ketika pemiliknya memilih untuk menstabilkannya. Sebelumnya, seluruh salinan antarmuka harus dibuat di HIDL.
Membangun aplikasi dengan runtime AIDL
AIDL memiliki tiga backend yang berbeda: Java, NDK, CPP. Untuk menggunakan AIDL Stabil, Anda harus
selalu menggunakan salinan sistem libbinder di system/lib*/libbinder.so
dan berkomunikasi
di /dev/binder
. Untuk kode pada image vendor, ini berarti libbinder
(dari VNDK) tidak dapat digunakan: library ini memiliki C++ API yang tidak stabil dan
internal yang tidak stabil. Sebagai gantinya, kode vendor native harus menggunakan backend NDK
AIDL, menautkan ke libbinder_ndk
(yang didukung oleh libbinder.so
sistem),
dan menautkan ke library NDK yang dibuat oleh entri aidl_interface
. Untuk
nama modul persisnya, lihat
aturan penamaan modul.
Menulis antarmuka AIDL HAL
Agar antarmuka AIDL dapat digunakan antara sistem dan vendor, antarmuka memerlukan dua perubahan:
- Setiap definisi jenis harus dianotasi dengan
@VintfStability
. - Deklarasi
aidl_interface
harus menyertakanstability: "vintf",
.
Hanya pemilik antarmuka yang dapat melakukan perubahan ini.
Jika Anda melakukan perubahan ini, antarmuka harus berada dalam
manifes VINTF agar dapat berfungsi. Uji ini (dan persyaratan
terkait, seperti memverifikasi bahwa antarmuka yang dirilis telah dibekukan) menggunakan
pengujian VTS vts_treble_vintf_vendor_test
. Anda dapat menggunakan antarmuka @VintfStability
tanpa persyaratan ini dengan memanggil
AIBinder_forceDowngradeToLocalStability
di backend NDK,
android::Stability::forceDowngradeToLocalStability
di backend C++,
atau android.os.Binder#forceDowngradeToSystemStability
di backend Java
pada objek binder sebelum dikirim ke proses lain. Mendowngrade layanan ke stabilitas vendor tidak didukung di Java karena semua aplikasi berjalan dalam konteks sistem.
Selain itu, untuk portabilitas kode yang maksimum dan untuk menghindari potensi masalah seperti library tambahan yang tidak perlu, nonaktifkan backend CPP.
Perlu diperhatikan bahwa penggunaan backends
dalam contoh kode di bawah sudah benar, karena ada
tiga backend (Java, NDK, dan CPP). Kode di bawah ini memberi tahu cara memilih
backend CPP secara khusus, untuk menonaktifkannya.
aidl_interface: {
...
backends: {
cpp: {
enabled: false,
},
},
}
Menemukan antarmuka AIDL HAL
Antarmuka AIDL Stabil AOSP untuk HAL berada dalam direktori dasar yang sama dengan
antarmuka HIDL, di folder aidl
.
- hardware/antarmuka
- framework/hardware/antarmuka
- sistem/hardware/antarmuka
Anda harus memasukkan antarmuka ekstensi ke subdirektori hardware/interfaces
lain di vendor
atau hardware
.
Antarmuka ekstensi
Android memiliki serangkaian antarmuka AOSP resmi untuk setiap rilis. Saat partner Android ingin menambahkan fungsi ke antarmuka ini, mereka tidak boleh mengubahnya secara langsung karena ini berarti runtime Android mereka tidak kompatibel dengan runtime Android AOSP. Untuk perangkat GMS, menghindari perubahan antarmuka ini juga merupakan hal yang memastikan image GSI dapat terus berfungsi.
Ekstensi dapat didaftarkan dengan dua cara:
- saat runtime, lihat ekstensi yang dilampirkan.
- mandiri, terdaftar secara global, dan di VINTF.
Namun, ekstensi didaftarkan, ketika komponen khusus vendor (artinya bukan bagian dari AOSP upstream) menggunakan antarmuka, tidak ada kemungkinan konflik penggabungan. Namun, saat modifikasi downstream ke komponen AOSP upstream dibuat, konflik penggabungan dapat terjadi, dan strategi berikut direkomendasikan:
- penambahan antarmuka dapat di-upstream ke AOSP dalam rilis berikutnya
- penambahan antarmuka yang memungkinkan fleksibilitas lebih lanjut, tanpa konflik penggabungan, dapat di-upstream dalam rilis berikutnya
parcelable ekstensi: ParcelableHolder
ParcelableHolder
adalah Parcelable
yang dapat berisi Parcelable
lainnya.
Kasus penggunaan utama ParcelableHolder
adalah membuat Parcelable
dapat diperluas.
Misalnya, image yang diharapkan oleh pengimplementasi perangkat dapat memperluas
Parcelable
, AospDefinedParcelable
yang ditentukan AOSP untuk menyertakan fitur
nilai tambah mereka.
Sebelumnya tanpa ParcelableHolder
, pengimplementasi perangkat tidak dapat memodifikasi
antarmuka AIDL stabil yang ditentukan AOSP karena akan terjadi error jika menambahkan lebih banyak
kolom:
parcelable AospDefinedParcelable {
int a;
String b;
String x; // ERROR: added by a device implementer
int[] y; // added by a device implementer
}
Seperti yang terlihat dalam kode sebelumnya, praktik ini rusak karena kolom yang ditambahkan oleh pengimplementasi perangkat mungkin mengalami konflik saat Parcelable direvisi dalam rilis Android berikutnya.
Dengan ParcelableHolder
, pemilik parcelable dapat menentukan titik ekstensi di Parcelable
.
parcelable AospDefinedParcelable {
int a;
String b;
ParcelableHolder extension;
}
Kemudian, pengimplementasi perangkat dapat menentukan Parcelable
mereka sendiri untuk
ekstensinya.
parcelable OemDefinedParcelable {
String x;
int[] y;
}
Terakhir, Parcelable
baru dapat dilampirkan ke Parcelable
asli dengan
kolom ParcelableHolder
.
// Java
AospDefinedParcelable ap = ...;
OemDefinedParcelable op = new OemDefinedParcelable();
op.x = ...;
op.y = ...;
ap.extension.setParcelable(op);
...
OemDefinedParcelable op = ap.extension.getParcelable(OemDefinedParcelable.class);
// C++
AospDefinedParcelable ap;
OemDefinedParcelable op;
std::shared_ptr<OemDefinedParcelable> op_ptr = make_shared<OemDefinedParcelable>();
ap.extension.setParcelable(op);
ap.extension.setParcelable(op_ptr);
...
std::shared_ptr<OemDefinedParcelable> op_ptr;
ap.extension.getParcelable(&op_ptr);
// NDK
AospDefinedParcelable ap;
OemDefinedParcelable op;
ap.extension.setParcelable(op);
...
std::optional<OemDefinedParcelable> op;
ap.extension.getParcelable(&op);
// Rust
let mut ap = AospDefinedParcelable { .. };
let op = Rc::new(OemDefinedParcelable { .. });
ap.extension.set_parcelable(Rc::clone(&op));
...
let op = ap.extension.get_parcelable::<OemDefinedParcelable>();
Nama instance server AIDL HAL
Berdasarkan konvensi, layanan AIDL HAL memiliki nama instance dengan format
$package.$type/$instance
. Misalnya, instance vibrator HAL
terdaftar sebagai android.hardware.vibrator.IVibrator/default
.
Menulis server AIDL HAL
Server AIDL @VintfStability
harus dideklarasikan dalam manifes VINTF, misalnya seperti ini:
<hal format="aidl">
<name>android.hardware.vibrator</name>
<version>1</version>
<fqname>IVibrator/default</fqname>
</hal>
Jika tidak, mereka harus mendaftarkan layanan AIDL seperti biasa. Saat menjalankan pengujian VTS, semua HAL AIDL yang dideklarasikan harus tersedia.
Menulis klien AIDL
Klien AIDL harus mendeklarasikan diri mereka sendiri dalam matriks kompatibilitas, misalnya, seperti ini:
<hal format="aidl" optional="true">
<name>android.hardware.vibrator</name>
<version>1-2</version>
<interface>
<name>IVibrator</name>
<instance>default</instance>
</interface>
</hal>
Mengonversi HAL yang ada dari HIDL ke AIDL
Gunakan alat hidl2aidl
untuk mengonversi antarmuka HIDL menjadi AIDL.
Fitur hidl2aidl
:
- Membuat file
.aidl
berdasarkan file.hal
untuk paket yang ditentukan - Buat aturan build untuk paket AIDL yang baru dibuat dengan semua backend diaktifkan
- Buat metode penerjemahan di backend Java, CPP, dan NDK untuk menerjemahkan dari jenis HIDL ke jenis AIDL
- Membuat aturan build untuk menerjemahkan library dengan dependensi yang diperlukan
- Buat pernyataan statis untuk memastikan bahwa enumerator HIDL dan AIDL memiliki nilai yang sama di backend CPP dan NDK
Ikuti langkah-langkah berikut untuk mengonversi paket file .hal menjadi file .aidl:
Bangun alat yang terletak di
system/tools/hidl/hidl2aidl
.Membuat alat ini dari sumber terbaru akan memberikan pengalaman paling lengkap. Anda dapat menggunakan versi terbaru untuk mengonversi antarmuka pada cabang lama dari rilis sebelumnya.
m hidl2aidl
Jalankan alat dengan direktori output yang diikuti dengan paket yang akan dikonversi.
Secara opsional, gunakan argumen
-l
untuk menambahkan konten file lisensi baru ke bagian atas semua file yang dihasilkan. Pastikan Anda menggunakan lisensi dan tanggal yang benar.hidl2aidl -o <output directory> -l <file with license> <package>
Contoh:
hidl2aidl -o . -l my_license.txt android.hardware.nfc@1.2
Baca file yang dihasilkan dan perbaiki masalah apa pun pada konversi.
conversion.log
berisi masalah yang tidak tertangani untuk diperbaiki terlebih dahulu.- File
.aidl
yang dihasilkan mungkin memiliki peringatan dan saran yang mungkin memerlukan tindakan. Komentar ini diawali dengan//
. - Manfaatkan kesempatan ini untuk membersihkan dan melakukan perbaikan pada paket.
- Periksa anotasi
@JavaDerive
untuk mengetahui fitur yang mungkin diperlukan, sepertitoString
atauequals
.
Bangun target yang diperlukan saja.
- Nonaktifkan backend yang tidak akan digunakan. Pilih backend NDK daripada backend CPP, lihat memilih runtime.
- Menghapus library terjemahan atau kode yang dihasilkan yang tidak akan digunakan.
Lihat Perbedaan utama AIDL/HIDL.
- Penggunaan
Status
bawaan dan pengecualian AIDL biasanya akan meningkatkan antarmuka dan menghilangkan kebutuhan akan jenis status khusus antarmuka lainnya. - Argumen antarmuka AIDL dalam metode secara default bukan
@nullable
seperti ada di HIDL.
- Penggunaan
SEPolicy untuk AIDL HAL
Jenis layanan AIDL yang terlihat oleh kode vendor harus memiliki
atribut hal_service_type
. Jika tidak, konfigurasi sepolicy sama dengan
layanan AIDL lainnya (meskipun ada atribut khusus untuk HAL). Berikut
adalah contoh definisi konteks layanan HAL:
type hal_foo_service, service_manager_type, hal_service_type;
Untuk sebagian besar layanan yang ditentukan oleh platform, konteks layanan dengan jenis
yang benar sudah ditambahkan (misalnya, android.hardware.foo.IFoo/default
sudah
akan ditandai sebagai hal_foo_service
). Namun, jika klien framework mendukung
beberapa nama instance, nama instance tambahan harus ditambahkan di
file service_contexts
khusus perangkat.
android.hardware.foo.IFoo/custom_instance u:object_r:hal_foo_service:s0
Atribut HAL harus ditambahkan saat membuat jenis HAL baru. Atribut HAL tertentu
dapat dikaitkan dengan beberapa jenis layanan (yang masing-masing
dapat memiliki beberapa instance seperti yang baru saja kita bahas). Untuk HAL, foo
, kita memiliki
hal_attribute(foo)
. Makro ini menentukan atribut hal_foo_client
dan
hal_foo_server
. Untuk domain tertentu, makro hal_client_domain
dan
hal_server_domain
mengaitkan domain dengan atribut HAL tertentu. Misalnya, server sistem yang menjadi klien HAL ini sesuai dengan kebijakan
hal_client_domain(system_server, hal_foo)
. Server HAL juga menyertakan
hal_server_domain(my_hal_domain, hal_foo)
. Biasanya, untuk atribut HAL
tertentu, kami juga membuat domain seperti hal_foo_default
untuk referensi atau
contoh HAL. Namun, beberapa perangkat menggunakan domain ini untuk servernya sendiri.
Membedakan antara domain untuk beberapa server hanya penting jika kita memiliki beberapa server yang menyediakan antarmuka yang sama dan memerlukan izin yang ditetapkan berbeda dalam implementasinya. Di semua makro ini, hal_foo
sebenarnya bukan
objek sepolicy. Sebaliknya, token ini digunakan oleh makro tersebut untuk merujuk pada
grup atribut yang terkait dengan pasangan server klien.
Namun, sejauh ini, kita belum mengaitkan hal_foo_service
dan hal_foo
(pasangan atribut dari hal_attribute(foo)
). Atribut HAL dikaitkan
dengan layanan AIDL HAL menggunakan makro hal_attribute_service
(HIDL HAL menggunakan
makro hal_attribute_hwservice
). Misalnya,
hal_attribute_service(hal_foo, hal_foo_service)
. Ini berarti bahwa
proses hal_foo_client
dapat memperoleh HAL, dan proses hal_foo_server
dapat mendaftarkan HAL. Penerapan aturan pendaftaran ini dilakukan oleh pengelola konteks (servicemanager
). Perhatikan bahwa nama layanan mungkin tidak selalu sesuai dengan atribut HAL. Misalnya, kita mungkin melihat
hal_attribute_service(hal_foo, hal_foo2_service)
. Namun secara umum, karena hal ini menyiratkan bahwa layanan selalu digunakan bersama, kita dapat mempertimbangkan untuk menghapus hal_foo2_service
dan menggunakan hal_foo_service
untuk semua konteks layanan. Sebagian besar HAL yang menetapkan beberapa hal_attribute_service
adalah karena
nama atribut HAL asli tidak cukup umum dan tidak dapat diubah.
Dengan menyatukan semuanya, contoh HAL terlihat seperti ini:
public/attributes:
// define hal_foo, hal_foo_client, hal_foo_server
hal_attribute(foo)
public/service.te
// define hal_foo_service
type hal_foo_service, hal_service_type, protected_service, service_manager_type
public/hal_foo.te:
// allow binder connection from client to server
binder_call(hal_foo_client, hal_foo_server)
// allow client to find the service, allow server to register the service
hal_attribute_service(hal_foo, hal_foo_service)
// allow binder communication from server to service_manager
binder_use(hal_foo_server)
private/service_contexts:
// bind an AIDL service name to the selinux type
android.hardware.foo.IFooXxxx/default u:object_r:hal_foo_service:s0
private/<some_domain>.te:
// let this domain use the hal service
binder_use(some_domain)
hal_client_domain(some_domain, hal_foo)
vendor/<some_hal_server_domain>.te
// let this domain serve the hal service
hal_server_domain(some_hal_server_domain, hal_foo)
Antarmuka ekstensi yang disertakan
Ekstensi dapat disertakan ke antarmuka binder apa pun, baik antarmuka tingkat atas yang terdaftar langsung dengan pengelola layanan maupun sub-antarmuka. Saat mendapatkan ekstensi, Anda harus mengonfirmasi jenis ekstensi seperti yang diharapkan. Ekstensi hanya dapat disetel dari proses yang menyajikan binder.
Ekstensi yang disertakan harus digunakan setiap kali ekstensi mengubah fungsi HAL yang sudah ada. Jika fungsi yang benar-benar baru diperlukan, mekanisme ini tidak perlu digunakan, dan antarmuka ekstensi dapat didaftarkan dengan pengelola layanan secara langsung. Antarmuka ekstensi yang disertakan akan sangat cocok jika dikaitkan ke sub-antarmuka, karena hierarki ini mungkin dalam atau multi-instance. Menggunakan ekstensi global untuk menduplikasi hierarki antarmuka binder layanan lain akan memerlukan pembukuan yang ekstensif untuk menyediakan fungsi yang setara ke ekstensi yang terpasang langsung.
Untuk menyetel ekstensi pada binder, gunakan API berikut:
- Di backend NDK:
AIBinder_setExtension
- Di backend Java:
android.os.Binder.setExtension
- Di backend CPP:
android::Binder::setExtension
- Di backend Rust:
binder::Binder::set_extension
Untuk mendapatkan ekstensi pada binder, gunakan API berikut:
- Di backend NDK:
AIBinder_getExtension
- Di backend Java:
android.os.IBinder.getExtension
- Di backend CPP:
android::IBinder::getExtension
- Di backend Rust:
binder::Binder::get_extension
Anda dapat menemukan informasi selengkapnya untuk API ini dalam dokumentasi fungsi getExtension
di backend terkait. Contoh cara menggunakan ekstensi dapat ditemukan di hardware/interfaces/tests/extension/vibrator.
Perbedaan utama AIDL dan HIDL
Saat menggunakan AIDL HAL atau antarmuka AIDL HAL, perhatikan perbedaan dibandingkan dengan menulis HAL HIDL.
- Sintaks bahasa AIDL lebih dekat dengan Java. Sintaksis HIDL mirip dengan C++.
- Semua antarmuka AIDL memiliki status error bawaan. Daripada membuat jenis
status kustom, buat int status konstan di file antarmuka dan gunakan
EX_SERVICE_SPECIFIC
di backend CPP/NDK danServiceSpecificException
di backend Java. Lihat Penanganan Error. - AIDL tidak otomatis memulai thread pool saat objek binder dikirim. Pengujian ini harus dimulai secara manual (lihat pengelolaan thread).
- AIDL tidak dibatalkan jika ada error transpor yang tidak dicentang (HIDL
Return
akan dibatalkan jika terjadi error yang tidak dicentang). - AIDL hanya dapat mendeklarasikan satu jenis per file.
- Argumen AIDL dapat ditetapkan sebagai in/out/inout selain parameter output (tidak ada "callback sinkron").
- AIDL menggunakan fd sebagai jenis primitif, bukan handle.
- HIDL menggunakan versi utama untuk perubahan yang tidak kompatibel dan versi minor untuk
perubahan yang kompatibel. Dalam AIDL, perubahan yang kompatibel dengan versi lama dilakukan di tempatnya.
AIDL tidak memiliki konsep eksplisit tentang versi utama; sebagai gantinya, ini
dimasukkan ke dalam nama paket. Misalnya, AIDL mungkin menggunakan nama paket
bluetooth2
. - AIDL tidak mewarisi prioritas realtime secara default. Fungsi
setInheritRt
harus digunakan per-binder untuk mengaktifkan pewarisan prioritas realtime.