Dokumen ini menjelaskan hashing antarmuka HIDL, sebuah mekanisme untuk mencegah perubahan antarmuka yang tidak disengaja dan memastikan perubahan antarmuka diperiksa secara menyeluruh. Mekanisme ini diperlukan karena antarmuka HIDL memiliki versi, yang berarti bahwa setelah dirilis, antarmuka tidak boleh diubah kecuali dengan cara mempertahankan Antarmuka Biner Aplikasi (ABI) (seperti koreksi komentar).
Tata Letak
Setiap direktori root paket (yaitu pemetaan android.hardware
ke hardware/interfaces
atau pemetaan vendor.foo
ke vendor/foo/hardware/interfaces
) harus berisi file current.txt
yang mencantumkan semua file antarmuka HIDL yang dirilis.
# current.txt files support comments starting with a ‘#' character # this file, for instance, would be vendor/foo/hardware/interfaces/current.txt # Each line has a SHA-256 hash followed by the name of an interface. # They have been shortened in this doc for brevity but they are # 64 characters in length in an actual current.txt file. d4ed2f0e...995f9ec4 vendor.awesome.foo@1.0::IFoo # comments can also go here # types.hal files are also noted in current.txt files c84da9f5...f8ea2648 vendor.awesome.foo@1.0::types # Multiple hashes can be in the file for the same interface. This can be used # to note how ABI sustaining changes were made to the interface. # For instance, here is another hash for IFoo: # Fixes type where "FooCallback" was misspelled in comment on "FooStruct" 822998d7...74d63b8c vendor.awesome.foo@1.0::IFoo
Catatan: Untuk membantu melacak asal hash mana, Google memisahkan file HIDL current.txt
menjadi beberapa bagian berbeda: Bagian pertama Dirilis di Android O ; bagian selanjutnya akan Dirilis di Android O MR1 . Kami sangat menyarankan penggunaan tata letak serupa di file current.txt
Anda saat ini.
Hashing dengan hidel-gen
Anda dapat menambahkan hash ke file current.txt
secara manual atau dengan menggunakan hidl-gen
. Cuplikan kode berikut memberikan contoh perintah yang dapat Anda gunakan dengan hidl-gen
untuk mengelola file current.txt
(hash telah dipersingkat):
hidl-gen -L hash -r vendor.awesome:vendor/awesome/hardware/interfaces -r android.hardware:hardware/interfaces -r android.hidl:system/libhidl/transport vendor.awesome.nfc@1.0::types
9626fd18...f9d298a6 vendor.awesome.nfc@1.0::typeshidl-gen -L hash -r vendor.awesome:vendor/awesome/hardware/interfaces -r android.hardware:hardware/interfaces -r android.hidl:system/libhidl/transport vendor.awesome.nfc@1.0::INfc
07ac2dc9...11e3cf57 vendor.awesome.nfc@1.0::INfchidl-gen -L hash -r vendor.awesome:vendor/awesome/hardware/interfaces -r android.hardware:hardware/interfaces -r android.hidl:system/libhidl/transport vendor.awesome.nfc@1.0
9626fd18...f9d298a6 vendor.awesome.nfc@1.0::types 07ac2dc9...11e3cf57 vendor.awesome.nfc@1.0::INfc f2fe5442...72655de6 vendor.awesome.nfc@1.0::INfcClientCallbackhidl-gen -L hash -r vendor.awesome:vendor/awesome/hardware/interfaces -r android.hardware:hardware/interfaces -r android.hidl:system/libhidl/transport vendor.awesome.nfc@1.0 >> vendor/awesome/hardware/interfaces/current.txt
Peringatan: Jangan ganti hash untuk antarmuka yang dirilis sebelumnya. Saat mengubah antarmuka seperti itu, tambahkan hash baru di akhir file current.txt
. Untuk detailnya, lihat stabilitas ABI .
Setiap pustaka definisi antarmuka yang dihasilkan oleh hidl-gen
menyertakan hash, yang dapat diambil dengan memanggil IBase::getHashChain
. Ketika hidl-gen
mengkompilasi sebuah antarmuka, ia memeriksa file current.txt
di direktori root paket HAL untuk melihat apakah HAL telah diubah:
- Jika tidak ada hash untuk HAL yang ditemukan, antarmuka dianggap belum dirilis (dalam pengembangan) dan kompilasi dilanjutkan.
- Jika hash ditemukan, hash tersebut akan diperiksa berdasarkan antarmuka saat ini:
- Jika antarmuka cocok dengan hash, kompilasi akan dilanjutkan.
- Jika antarmuka tidak cocok dengan hash, kompilasi dihentikan karena ini berarti antarmuka yang dirilis sebelumnya sedang diubah.
- Untuk perubahan yang mempertahankan ABI (lihat stabilitas ABI ), file
current.txt
harus diubah sebelum kompilasi dapat dilanjutkan. - Semua perubahan lainnya harus dilakukan dalam peningkatan versi antarmuka minor atau mayor.
- Untuk perubahan yang mempertahankan ABI (lihat stabilitas ABI ), file
Stabilitas ABI
Antarmuka Biner Aplikasi (ABI) mencakup tautan biner/konvensi panggilan/dll. Jika ABI/API berubah, antarmuka tidak lagi berfungsi dengan system.img
generik yang dikompilasi dengan antarmuka resmi.
Memastikan bahwa antarmuka memiliki versi dan ABI stabil sangat penting karena beberapa alasan:
- Hal ini memastikan implementasi Anda dapat lulus Vendor Test Suite (VTS), yang menempatkan Anda pada jalur yang tepat untuk dapat melakukan OTA khusus kerangka kerja.
- Sebagai OEM, ini memungkinkan Anda menyediakan Board Support Package (BSP) yang mudah digunakan dan patuh.
- Ini membantu Anda melacak antarmuka apa yang dapat dirilis. Pertimbangkan
current.txt
sebagai peta direktori antarmuka yang memungkinkan Anda melihat riwayat dan status semua antarmuka yang disediakan dalam root paket.
Saat menambahkan hash baru untuk antarmuka yang sudah memiliki entri di current.txt
, pastikan untuk menambahkan hanya hash yang mewakili antarmuka yang menjaga stabilitas ABI. Tinjau jenis perubahan berikut:
Perubahan diperbolehkan |
|
---|---|
Perubahan tidak diperbolehkan |
|