Hàm băm giao diện

Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.

Tài liệu này mô tả tính năng băm giao diện HIDL, một cơ chế để ngăn chặn các thay đổi giao diện do nhầm lẫn và đảm bảo các thay đổi giao diện được kiểm tra kỹ lưỡng. Cơ chế này là bắt buộc vì các giao diện HIDL được tạo phiên bản, nghĩa là sau khi phát hành giao diện, bạn không được thay đổi giao diện đó, ngoại trừ việc bảo tồn giao diện nhị phân ứng dụng (ABI) (chẳng hạn như sửa lỗi nhận xét).

Bố cục

Mọi thư mục gốc của gói (tức là android.hardware ánh xạ đến hardware/interfaces hoặc vendor.foo ánh xạ đến vendor/foo/hardware/interfaces) đều phải chứa tệp current.txt liệt kê tất cả các tệp giao diện HIDL đã 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 từ đâu, Google tách các tệp current.txt HIDL thành nhiều phần: Phần đầu tiên là Đã phát hành trong Android 8; phần tiếp theo sẽ là Đã phát hành trong Android 8 MR1. Bạn nên sử dụng bố cục tương tự trong tệp current.txt.

Hàm băm bằng 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 (đã rút gọn hàm băm):

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

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 một hàm băm mới vào cuối tệp current.txt. Để biết thông tin chi tiết, hãy tham khảo phần Độ ổn định của ABI.

Mọi thư viện định nghĩa giao diện do hidl-gen tạo đều bao gồm các hàm băm. Bạn có thể truy xuất các hàm băm này bằng cách gọi IBase::getHashChain. Khi biên dịch giao diện, hidl-gen sẽ kiểm tra tệp current.txt trong thư mục gốc của gói HAL để xem HAL có thay đổi hay không:

• Nếu không tìm thấy hàm băm cho HAL, giao diện sẽ được coi là chưa phát hành (đang phát triển) và quá trình biên dịch sẽ tiếp tục.
• Nếu tìm thấy hàm băm, các hàm này 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, quá trình biên dịch sẽ tiếp tục.
  • Nếu giao diện không khớp với hàm băm, 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 đã phát hành trước đó đang được thay đổi.
    • Đối với thay đổi giữ nguyên ABI (xem phần Tính ổn định của ABI), bạn phải sửa đổi tệp current.txt trước khi có thể biên dịch.
    • Tất cả các thay đổi khác phải được thực hiện trong quá trình nâng cấp phiên bản nhỏ hoặc lớn của giao diện.

Độ ổn định của ABI

ABI bao gồm các đường liên kết nhị phân/quy ước gọi/v.v. Nếu ABI hoặc API thay đổi, giao diện sẽ 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 tạo phiên bản và ABI ổn định là quan trọng vì một số lý do:

• Điều này đảm bảo việc triển khai của bạn có thể vượt qua Bộ kiểm thử của nhà cung cấp (VTS), giúp bạn có thể thực hiện các bản cập nhật OTA chỉ dành cho khung.
• Là nhà sản xuất thiết bị gốc (OEM), bạn có thể cung cấp Gói hỗ trợ bo mạch (BSP) dễ sử dụng và tuân thủ.
• Tính năng này giúp bạn theo dõi những giao diện có thể phát hành. Hãy xem current.txt là một bản đồ của thư mục giao diện cho phép bạn xem nhật ký và trạng thái của tất cả giao diện được cung cấp trong thư mục gốc của gói.

Khi thêm một hàm băm mới cho một giao diện đã có mục nhập trong current.txt, hãy nhớ 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: