本文檔介紹了 HIDL 接口哈希,這是一種防止意外接口更改並確保接口更改得到徹底審查的機制。此機制是必需的,因為 HIDL 接口是版本化的,這意味著在接口發布後不得更改,除非以應用程序二進制接口 (ABI) 保留方式(例如註釋更正)。
佈局
每個包根目錄(即android.hardware
映射到hardware/interfaces
或vendor.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::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
警告:不要替換先前發布的接口的哈希值。更改此類接口時,請在current.txt
文件的末尾添加一個新的哈希。有關詳細信息,請參閱ABI 穩定性。
hidl-gen
生成的每個接口定義庫都包含哈希,可以通過調用IBase::getHashChain
來檢索。 hidl-gen
在編譯接口時,會檢查 HAL 包根目錄下的current.txt
文件,看 HAL 是否發生了變化:
- 如果未找到 HAL 的哈希,則認為接口未發布(開發中)並繼續編譯。
- 如果找到哈希,則根據當前接口檢查它們:
- 如果接口與哈希匹配,則繼續編譯。
- 如果接口與哈希不匹配,則編譯將停止,因為這意味著先前發布的接口正在被更改。
- 對於保留 ABI 的更改(請參閱ABI 穩定性),必須先修改
current.txt
文件,然後才能繼續編譯。 - 所有其他更改都應在界面的次要或主要版本升級中進行。
- 對於保留 ABI 的更改(請參閱ABI 穩定性),必須先修改
ABI 穩定性
應用程序二進制接口 (ABI) 包括二進制鏈接/調用約定/等。如果 ABI/API 發生更改,則該接口不再適用於使用官方接口編譯的通用system.img
。
確保接口已版本化且 ABI 穩定至關重要,原因如下:
- 它確保您的實施可以通過供應商測試套件 (VTS),從而使您能夠進行僅框架的 OTA。
- 作為 OEM,它使您能夠提供簡單易用且合規的板級支持包 (BSP)。
- 它可以幫助您跟踪可以發布的接口。考慮
current.txt
一個接口目錄的映射,它允許您查看包根目錄中提供的所有接口的歷史記錄和狀態。
為在current.txt
中已有條目的接口添加新哈希時,請確保僅添加表示保持 ABI 穩定性的接口的哈希。查看以下類型的更改:
允許更改 |
|
---|---|
不允許更改 |
|