Băm giao diện

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::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 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.

Độ ổ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
  • Thay đổi nhận xét (trừ khi điều này thay đổi ý nghĩa của phương thức).
  • Thay đổi tên của một tham số.
  • Thay đổi tên của tham số trả về.
  • Thay đổi chú thích.
Không được phép thay đổi
  • Sắp xếp lại các đối số, phương thức, v.v...
  • Đổi tên giao diện hoặc chuyển nó sang gói mới.
  • Đổi tên một gói.
  • Thêm phương thức/trường cấu trúc/v.v… vào bất kỳ đâu trong giao diện.
  • Bất cứ điều gì có thể phá vỡ vtable C++.
  • vân vân..