介面雜湊

本文件說明 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

警告：請勿取代 我們推出了舊版 UI變更這類介面時，請加入新的雜湊 至 current.txt 檔案結尾處。詳情請參閱 ABI 穩定性。

由 hidl-gen 產生的每個介面定義程式庫 包含雜湊，可藉由呼叫 IBase::getHashChain。當 hidl-gen 編譯為 介面，就會檢查 current.txt 根目錄中的 檔案 HAL 套件，用於檢查 HAL 是否已變更：

  • 如果找不到 HAL 的雜湊，系統就會將介面視為未發布 ( 編譯) 和編譯作業
  • 找到雜湊後，系統會按照目前介面檢查雜湊：
    • 如果介面與雜湊相符，系統就會繼續編譯。
    • 如果介面與雜湊不相符，系統會停止編譯，因為舊版介面即將變更。
      • 如需 ABI 保留變更 (請參閱 ABI 穩定性)，current.txt 檔案 必須先修改才能繼續進行編譯。
      • 所有其他變更均應進行次要或主要版本升級 存取 API

ABI 穩定性

ABI 包含二進位檔案 連結/通話慣例等如果 ABI 或 API 變更，介面就不會顯示 較完整的程式碼搭配一般 system.img 使用 官方介面。

確認介面已建立版本，且 ABI 穩定版本為 重要：

  • 確保導入作業能夠通過供應商測試套件 (VTS)， 能讓您進行架構專用的網路旅行社。
  • 原始設備製造商 (OEM) 可讓您提供板型支援套件 (BSP)，也就是 易於使用且符合規定
  • 可協助您追蹤可發布的介面。您可以考慮使用 current.txt 是可讓您查看介面目錄的地圖 套件根目錄中提供的所有介面的記錄和狀態。

為 中已有項目的介面新增雜湊時 current.txt，請務必只加入代表 確保 ABI 穩定性的介面。請查看下列類型的變更：

允許變更
  • 變更註解 (除非此變更方法的意義)。
  • 變更參數的名稱。
  • 變更傳回參數的名稱。
  • 變更註解。
不允許變更
  • 重新排列引數、方法等
  • 將介面重新命名或移至新套件。
  • 重新命名套件。
  • 新增方法/結構欄位/等等介面中的任何位置
  • 任何會破壞 C++ vtable 的任何項目。
  • 等