接口散列

本文檔介紹了 HIDL 接口哈希,這是一種防止意外接口更改並確保接口更改得到徹底審查的機制。此機制是必需的,因為 HIDL 接口是版本化的,這意味著在接口發布後不得更改,除非以應用程序二進制接口 (ABI) 保留方式(例如註釋更正)。

佈局

每個包根目錄(即android.hardware映射到hardware/interfacesvendor.foo映射到vendor/foo/hardware/interfaces )必須包含一個current.txt文件,該文件列出所有已發布的 HIDL 接口文件。

# 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

注意:為了幫助跟踪哪些哈希來自何處,Google 將 HIDL current.txt文件分成不同的部分:第一部分在 Android O 中發布;下一節將在 Android O MR1 中發布。我們強烈建議您在current.txt文件中使用類似的佈局。

使用 hidl-gen 散列

您可以手動或使用hidl-gen將哈希添加到current.txt文件。以下代碼片段提供了可與hidl-gen一起使用來管理current.txt文件的命令示例(哈希已被縮短):

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

警告:不要替換先前發布的接口的哈希值。更改此類接口時,請在current.txt文件的末尾添加一個新的哈希。有關詳細信息,請參閱ABI 穩定性

hidl-gen生成的每個接口定義庫都包含哈希,可以通過調用IBase::getHashChain來檢索。 hidl-gen在編譯接口時,會檢查 HAL 包根目錄下的current.txt文件,看 HAL 是否發生了變化:

  • 如果未找到 HAL 的哈希,則認為接口未發布(開發中)並繼續編譯。
  • 如果找到哈希,則根據當前接口檢查它們:
    • 如果接口與哈希匹配,則繼續編譯。
    • 如果接口與哈希不匹配,則編譯將停止,因為這意味著先前發布的接口正在被更改。
      • 對於保留 ABI 的更改(請參閱ABI 穩定性),必須先修改current.txt文件,然後才能繼續編譯。
      • 所有其他更改都應在界面的次要或主要版本升級中進行。

ABI 穩定性

應用程序二進制接口 (ABI) 包括二進制鏈接/調用約定/等。如果 ABI/API 發生更改,則該接口不再適用於使用官方接口編譯的通用system.img

確保接口已版本化且 ABI 穩定至關重要,原因如下:

  • 它確保您的實施可以通過供應商測試套件 (VTS),從而使您能夠進行僅框架的 OTA。
  • 作為 OEM,它使您能夠提供簡單易用且合規的板級支持包 (BSP)。
  • 它可以幫助您跟踪可以發布的接口。考慮current.txt一個接口目錄的映射,它允許您查看包根目錄中提供的所有接口的歷史記錄和狀態。

為在current.txt中已有條目的接口添加新哈希時,請確保僅添加表示保持 ABI 穩定性的接口的哈希。查看以下類型的更改:

允許更改
  • 更改註釋(除非這會更改方法的含義)。
  • 更改參數的名稱。
  • 更改返回參數的名稱。
  • 更改註釋。
不允許更改
  • 重新排序參數、方法等……
  • 重命名界面或將其移動到新包中。
  • 重命名包。
  • 在界面的任何位置添加方法/結構字段/等。
  • 任何會破壞 C++ vtable 的東西。
  • ETC..