本文檔介紹了 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 穩定性),必須先修改 c
current.txt
文件,然後才能繼續編譯。 - 所有其他變更應在介面的次要或主要版本升級中進行。
- 對於保留 ABI 的變更(請參閱ABI 穩定性),必須先修改 c
ABI穩定性
應用程式二進位介面(ABI)包括二進位連結/呼叫約定/等。如果 ABI/API 發生更改,則該介面將不再適用於使用官方介面編譯的通用system.img
。
確保介面版本化和 ABI 穩定至關重要,原因如下:
- 它確保您的實施可以通過供應商測試套件 (VTS),這使您能夠進行純框架 OTA。
- 作為 OEM,它使您能夠提供易於使用且合規的主機板支援套件 (BSP)。
- 它可以幫助您追蹤可以發布哪些介面。考慮
current.txt
介面目錄的映射,它允許您查看包根中提供的所有介面的歷史記錄和狀態。
為current.txt
中已有條目的介面新增雜湊時,請確保僅新增代表保持 ABI 穩定性的介面的雜湊。查看以下類型的變更:
允許更改 |
|
---|---|
不允許更改 |
|