Tài liệu này mô tả băm giao diện HIDL, một cơ chế ngăn chặn các thay đổi giao diện vô tình và đảm bảo các thay đổi giao diện được xem xét kỹ lưỡng. Cơ chế này là bắt buộc vì các giao diện HIDL đã được phiên bản, có nghĩa là sau khi một giao diện được phát hành, nó không được thay đổi ngoại trừ theo cách duy trì Giao diện nhị phân ứng dụng (ABI) (chẳng hạn như sửa nhận xét).
Cách trình bày
Mọi thư mục gốc của gói (tức là ánh xạ android.hardware
tới hardware/interfaces
hoặc ánh xạ vendor.foo
tới vendor/foo/hardware/interfaces
) phải chứa tệp current.txt
liệt kê tất cả các tệp giao diện HIDL được phát hành.
# 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
Lưu ý: Để giúp theo dõi hàm băm nào đến từ đâu, Google tách các tệp HIDL current.txt
thành các phần khác nhau: Phần đầu tiên được phát hành trong Android O ; phần tiếp theo sẽ được phát hành trong Android O MR1 . Chúng tôi thực sự khuyên bạn nên sử dụng bố cục tương tự trong tệp current.txt
của mình.
Băm với hidl-gen
Bạn có thể thêm hàm băm vào tệp current.txt
theo cách thủ công hoặc bằng cách sử dụng hidl-gen
. Đoạn mã sau đây cung cấp ví dụ về các lệnh bạn có thể sử dụng với hidl-gen
để quản lý tệp current.txt
(các giá trị băm đã được rút ngắn):
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
Cảnh báo: Không thay thế hàm băm cho giao diện đã phát hành trước đó. Khi thay đổi giao diện như vậy, hãy thêm hàm băm mới vào cuối tệp current.txt
. Để biết chi tiết, hãy tham khảo độ ổn định của ABI .
Mọi thư viện định nghĩa giao diện được tạo bởi hidl-gen
đều bao gồm các giá trị băm, có thể được truy xuất bằng cách gọi IBase::getHashChain
. Khi hidl-gen
biên dịch một giao diện, nó sẽ kiểm tra tệp current.txt
trong thư mục gốc của gói HAL để xem HAL có bị thay đổi hay không:
- Nếu không tìm thấy hàm băm cho HAL, giao diện được coi là chưa được phát hành (đang trong quá trình phát triển) và quá trình biên dịch sẽ được tiến hành.
- Nếu tìm thấy giá trị băm, chúng sẽ được kiểm tra dựa trên giao diện hiện tại:
- Nếu giao diện khớp với hàm băm thì quá trình biên dịch sẽ được tiến hành.
- Nếu giao diện không khớp với hàm băm thì quá trình biên dịch sẽ bị tạm dừng vì điều này có nghĩa là giao diện được phát hành trước đó đang bị thay đổi.
- Đối với thay đổi duy trì ABI (xem độ ổn định của ABI ), tệp
current.txt
phải được sửa đổi trước khi có thể tiến hành biên dịch. - Tất cả các thay đổi khác phải được thực hiện trong bản nâng cấp giao diện nhỏ hoặc phiên bản chính.
- Đối với thay đổi duy trì ABI (xem độ ổn định của ABI ), tệp
Độ ổn định ABI
Giao diện nhị phân ứng dụng (ABI) bao gồm các liên kết nhị phân/quy ước gọi điện/v.v. Nếu ABI/API thay đổi, giao diện không còn hoạt động với system.img
chung được biên dịch bằng giao diện chính thức.
Việc đảm bảo rằng các giao diện được phiên bản và ABI ổn định là rất quan trọng vì một số lý do:
- Nó đảm bảo việc triển khai của bạn có thể vượt qua Bộ kiểm tra nhà cung cấp (VTS), giúp bạn đi đúng hướng để có thể thực hiện các OTA chỉ có khung.
- Với tư cách là OEM, nó cho phép bạn cung cấp Gói hỗ trợ bo mạch (BSP) dễ sử dụng và tuân thủ.
- Nó giúp bạn theo dõi những giao diện nào có thể được phát hành. Hãy xem
current.txt
một bản đồ của thư mục giao diện cho phép bạn xem lịch sử và trạng thái của tất cả các giao diện được cung cấp trong thư mục gốc của gói.
Khi thêm hàm băm mới cho giao diện đã có mục nhập trong current.txt
, hãy đảm bảo chỉ thêm các hàm băm đại diện cho các giao diện duy trì tính ổn định của ABI. Xem xét các loại thay đổi sau:
Cho phép thay đổi |
|
---|---|
Không được phép thay đổi |
|