Hashing antarmuka

Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

Dokumen ini menjelaskan hashing antarmuka HIDL, mekanisme untuk mencegah perubahan antarmuka yang tidak disengaja dan memastikan perubahan antarmuka diperiksa secara menyeluruh. Mekanisme ini diperlukan karena antarmuka HIDL diberi versi, yang berarti setelah antarmuka dirilis, antarmuka tersebut 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 hash yang berasal dari mana, Google memisahkan file current.txt HIDL ke dalam bagian yang berbeda: Bagian pertama adalah Dirilis di Android 8; bagian berikutnya akan Dirilis di Android 8 MR1. Sebaiknya gunakan tata letak yang serupa dalam file current.txt Anda.

Hash 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 tersebut, tambahkan hash baru ke akhir file current.txt. Untuk mengetahui detailnya, lihat Stabilitas ABI.

Setiap library definisi antarmuka yang dihasilkan oleh hidl-gen menyertakan hash, yang dapat diambil dengan memanggil IBase::getHashChain. Saat mengompilasi antarmuka, hidl-gen akan 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 akan dilanjutkan.
• Jika ditemukan, hash akan diperiksa terhadap antarmuka saat ini:
  • Jika antarmuka cocok dengan hash, kompilasi akan dilanjutkan.
  • Jika antarmuka tidak cocok dengan hash, kompilasi akan 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 upgrade versi minor atau utama antarmuka.

Stabilitas ABI

ABI mencakup penautan biner/konvensi panggilan/dll. Jika ABI atau API berubah, antarmuka tidak lagi berfungsi dengan system.img generik yang dikompilasi dengan antarmuka resmi.

Memastikan antarmuka memiliki versi dan ABI stabil sangat penting karena beberapa alasan:

• Hal ini memastikan implementasi Anda dapat lulus Vendor Test Suite (VTS), yang memungkinkan Anda melakukan OTA khusus framework.
• Sebagai OEM, Anda dapat menyediakan Board Support Package (BSP) yang mudah digunakan dan mematuhi standar.
• Hal ini membantu Anda melacak antarmuka yang dapat dirilis. Pertimbangkan current.txt sebagai peta direktori antarmuka yang memungkinkan Anda melihat histori dan status semua antarmuka yang disediakan di root paket.

Saat menambahkan hash baru untuk antarmuka yang sudah memiliki entri di current.txt, pastikan untuk hanya menambahkan hash yang mewakili antarmuka yang mempertahankan stabilitas ABI. Tinjau jenis perubahan berikut: