Google berkomitmen untuk mendorong terwujudnya keadilan ras bagi komunitas Kulit Hitam. Lihat caranya.

Halaman ini diterjemahkan oleh Cloud Translation API.

Hashing antarmuka

Dokumen ini menjelaskan {i>hashing<i} 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 beberapa versi, yang berarti bahwa setelah antarmuka dirilis, antarmuka itu tidak boleh diubah kecuali dalam cara mempertahankan antarmuka biner aplikasi (ABI) (seperti komentar koreksi).

Tata Letak

Setiap direktori utama paket (yaitu android.hardware yang memetakan ke hardware/interfaces atau vendor.foo memetakan ke vendor/foo/hardware/interfaces) harus berisi 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 mana yang masuk dari mana, Google memisahkan file HIDL current.txt ke dalam bagian: Bagian pertama adalah Dirilis di Android 8; bagian berikutnya akan Dirilis di Android 8 MR1. Kami sangat menyarankan penggunaan dan tata letak 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 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 yang sama dengan yang dirilis sebelumnya. Saat mengubah antarmuka seperti itu, tambahkan {i>hash<i} baru ke akhir file current.txt. Untuk mengetahui detailnya, lihat Stabilitas ABI.

Setiap library definisi antarmuka yang dihasilkan oleh hidl-gen yang berisi {i>hash<i}, yang dapat diambil dengan memanggil IBase::getHashChain. Saat hidl-gen mengompilasi sebuah antarmuka, ia memeriksa file current.txt di direktori {i>root<i} dari paket HAL untuk melihat apakah HAL telah diubah:

Jika tidak ditemukan {i>hash<i} untuk HAL, antarmuka dianggap belum dirilis (di pengembangan) dan kompilasi berlangsung.
Jika ditemukan, hash akan dibandingkan dengan 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 dimodifikasi sebelum kompilasi dapat dilanjutkan.
  - Semua perubahan lainnya harus dilakukan pada upgrade versi minor atau utama dari dalam antarmuka berbasis web yang sederhana.

Stabilitas ABI

ABI mencakup biner penautan/konvensi panggilan/dll. Jika ABI atau 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 meneruskan Vendor Test Suite (VTS), yang membuat Anda berada di jalur yang dapat melakukan OTA khusus kerangka kerja.
Sebagai OEM, produk ini memungkinkan Anda menyediakan Board Support Package (BSP) yang mudah digunakan dan sesuai standar.
Hal ini membantu Anda melacak antarmuka apa yang dapat dirilis. Pertimbangkan current.txt peta direktori antarmuka yang memungkinkan Anda melihat riwayat dan status semua antarmuka yang disediakan dalam sebuah {i>root<i} paket.

Saat menambahkan {i>hash<i} baru untuk antarmuka yang sudah memiliki entri di current.txt, pastikan untuk hanya menambahkan hash yang mewakili yang menjaga stabilitas ABI. Tinjau jenis perubahan berikut:

Perubahan diizinkan	Mengubah komentar (kecuali jika tindakan ini mengubah arti metode). Mengubah nama parameter. Mengubah nama parameter yang ditampilkan. Mengubah anotasi.
Perubahan tidak diizinkan	Mengurutkan ulang argumen, metode, dll. Mengganti nama antarmuka atau memindahkannya ke paket baru. Mengganti nama paket. Menambahkan kolom metode/struct/dll. di mana pun dalam antarmuka. Apa pun yang akan merusak vtable C++. dll.