接口散列

本文檔介紹了 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::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 穩定性），必須先修改 c current.txt文件，然後才能繼續編譯。
      • 所有其他變更應在介面的次要或主要版本升級中進行。

ABI穩定性

應用程式二進位介面（ABI）包括二進位連結/呼叫約定/等。如果 ABI/API 發生更改，則該介面將不再適用於使用官方介面編譯的通用system.img 。

確保介面版本化和 ABI 穩定至關重要，原因如下：

  • 它確保您的實施可以通過供應商測試套件 (VTS)，這使您能夠進行純框架 OTA。
  • 作為 OEM，它使您能夠提供易於使用且合規的主機板支援套件 (BSP)。
  • 它可以幫助您追蹤可以發布哪些介面。考慮current.txt介面目錄的映射，它允許您查看包根中提供的所有介面的歷史記錄和狀態。

為current.txt中已有條目的介面新增雜湊時，請確保僅新增代表保持 ABI 穩定性的介面的雜湊。查看以下類型的變更：

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