介面雜湊

本文件說明 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 8 中發布」；下一個部分是「已在 Android 8 MR1 中發布」。強烈建議您在 current.txt 檔案中使用類似的版面配置。

使用 hidl-gen 產生雜湊

您可以手動將雜湊值新增至 current.txt 檔案，也可以使用 hidl-gen 新增。以下程式碼片段提供可搭配 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 的內容。
  • 等