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 berversi, yang berarti bahwa setelah antarmuka dirilis tidak boleh diubah kecuali dengan cara melestarikan 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 dari mana hash berasal, Google memisahkan file HIDL current.txt menjadi beberapa bagian: Bagian pertama Dirilis di Android O ; bagian selanjutnya akan Dirilis di Android O MR1 . Kami sangat menyarankan untuk menggunakan tata letak yang serupa di file current.txt Anda.

Hashing dengan hidl-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 ke 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 antarmuka, ia memeriksa file current.txt di direktori root paket HAL untuk melihat apakah HAL telah diubah:

• Jika hash untuk HAL tidak ditemukan, antarmuka dianggap belum dirilis (dalam pengembangan) dan kompilasi dilanjutkan.
• Jika hash ditemukan, mereka akan diperiksa dengan antarmuka saat ini:
  • Jika antarmuka tidak cocok dengan hash, kompilasi 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 dimodifikasi sebelum kompilasi dapat dilanjutkan.
    • Semua perubahan lain harus dilakukan dalam peningkatan versi minor atau mayor dari antarmuka.

stabilitas ABI

Application Binary Interface (ABI) mencakup hubungan biner/konvensi pemanggilan/dll. Jika ABI/API berubah, antarmuka tidak lagi berfungsi dengan system.img generik yang dikompilasi dengan antarmuka resmi.

Memastikan bahwa antarmuka berversi dan ABI stabil sangat penting karena beberapa alasan:

• Ini memastikan implementasi Anda dapat lulus Vendor Test Suite (VTS), yang menempatkan Anda di jalur untuk dapat melakukan OTA kerangka saja.
• Sebagai OEM, ini memungkinkan Anda untuk menyediakan Paket Dukungan Dewan (BSP) yang mudah digunakan dan sesuai.
• 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 di 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: