Hashing Antarmuka

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::types
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::INfc
07ac2dc9...11e3cf57 vendor.awesome.nfc@1.0::INfc
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
9626fd18...f9d298a6 vendor.awesome.nfc@1.0::types
07ac2dc9...11e3cf57 vendor.awesome.nfc@1.0::INfc
f2fe5442...72655de6 vendor.awesome.nfc@1.0::INfcClientCallback
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 >> 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.

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: