自 2025 年 3 月 27 日起，我們建議您使用 android-latest-release 而非 aosp-main 建構及貢獻 AOSP。詳情請參閱「Android 開放原始碼計畫變更」。
介面雜湊
透過集合功能整理內容
你可以依據偏好儲存及分類內容。
本文件說明 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 的內容。
- 等
|
這個頁面中的內容和程式碼範例均受《內容授權》中的授權所規範。Java 與 OpenJDK 是 Oracle 和/或其關係企業的商標或註冊商標。
上次更新時間：2025-07-27 (世界標準時間)。
[[["容易理解","easyToUnderstand","thumb-up"],["確實解決了我的問題","solvedMyProblem","thumb-up"],["其他","otherUp","thumb-up"]],[["缺少我需要的資訊","missingTheInformationINeed","thumb-down"],["過於複雜/步驟過多","tooComplicatedTooManySteps","thumb-down"],["過時","outOfDate","thumb-down"],["翻譯問題","translationIssue","thumb-down"],["示例/程式碼問題","samplesCodeIssue","thumb-down"],["其他","otherDown","thumb-down"]],["上次更新時間：2025-07-27 (世界標準時間)。"],[],[],null,["# Interface hashing\n\nThis document describes HIDL interface hashing, a mechanism to prevent\naccidental interface changes and ensure interface changes are thoroughly vetted.\nThis mechanism is required because HIDL interfaces are versioned, which means\nthat after an interface is released it must not be changed except in an\napplication binary interface (ABI) preserving manner (such as a comment\ncorrection).\n\nLayout\n------\n\nEvery package root directory (i.e. `android.hardware` mapping to\n`hardware/interfaces` or `vendor.foo` mapping to\n`vendor/foo/hardware/interfaces`) must contain a\n`current.txt` file that lists all released HIDL interface files. \n\n```objective-c\n# current.txt files support comments starting with a '#' character\n# this file, for instance, would be vendor/foo/hardware/interfaces/current.txt\n\n# Each line has a SHA-256 hash followed by the name of an interface.\n# They have been shortened in this doc for brevity but they are\n# 64 characters in length in an actual current.txt file.\nd4ed2f0e...995f9ec4 vendor.awesome.foo@1.0::IFoo # comments can also go here\n\n# types.hal files are also noted in current.txt files\nc84da9f5...f8ea2648 vendor.awesome.foo@1.0::types\n\n# Multiple hashes can be in the file for the same interface. This can be used\n# to note how ABI sustaining changes were made to the interface.\n# For instance, here is another hash for IFoo:\n\n# Fixes type where \"FooCallback\" was misspelled in comment on \"FooStruct\"\n822998d7...74d63b8c vendor.awesome.foo@1.0::IFoo\n```\n\n**Note:** To help keep track of which hashes come\nfrom where, Google separates HIDL `current.txt` files into different\nsections: The first section is *Released in Android 8* ; the next section\nwill be *Released in Android 8 MR1* . We strongly recommend using a\nsimilar layout in your `current.txt` file.\n\nHash with hidl-gen\n------------------\n\nYou can add a hash to a `current.txt` file manually or by\nusing `hidl-gen`. The following code snippet provides examples of\ncommands you can use with `hidl-gen` to manage a\n`current.txt` file (hashes have been shortened): \n\n 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\n 9626fd18...f9d298a6 vendor.awesome.nfc@1.0::types\n 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\n 07ac2dc9...11e3cf57 vendor.awesome.nfc@1.0::INfc\n 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\n 9626fd18...f9d298a6 vendor.awesome.nfc@1.0::types\n 07ac2dc9...11e3cf57 vendor.awesome.nfc@1.0::INfc\n f2fe5442...72655de6 vendor.awesome.nfc@1.0::INfcClientCallback\n 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 \u003e\u003e vendor/awesome/hardware/interfaces/current.txt\n\n**Warning:** Do not replace a hash for a\npreviously-released interface. When changing such an interface, add a new hash\nto the end of the `current.txt` file. For details, refer to\n[ABI stability](#abi-stability).\n\nEvery interface definition library generated by `hidl-gen`\nincludes hashes, which can be retrieved by calling\n`IBase::getHashChain`. When `hidl-gen` is compiling an\ninterface, it checks the `current.txt` file in the root directory of\nthe HAL package to see if the HAL has been changed:\n\n- If no hash for the HAL is found, the interface is considered unreleased (in development) and compilation proceeds.\n- If hashes are found, they are checked against the current interface:\n - If the interface does match the hash, compilation proceeds.\n - If the interface does not match a hash, compilation is halted as this means a previously-released interface is being changed.\n - For an ABI-preserving change (see [ABI stability](#abi-stability)), the `current.txt` file must be modified before compilation can proceed.\n - All other changes should be made in a minor or major version upgrade of the interface.\n\nABI stability\n-------------\n\n| **Key Point:** Please read and understand this section carefully.\n\nAn ABI includes the binary\nlinkages/calling conventions/etc. If the ABI or API changes, the interface no\nlonger works with a generic `system.img` that was compiled with\nofficial interfaces.\n\nMaking sure that interfaces are versioned and ABI stable is\n**crucial** for several reasons:\n\n- It ensures your implementation can pass the Vendor Test Suite (VTS), which puts you on track to being able to do framework-only OTAs.\n- As an OEM, it enables you to provide a Board Support Package (BSP) that is straightforward to use and compliant.\n- It helps you keep track of what interfaces can be released. Consider `current.txt` a map of an interfaces directory that allows you to see the history and state of all interfaces being provided in a package root.\n\nWhen adding a new hash for an interface that already has an entry in\n`current.txt`, make sure to add only the hashes that represent\ninterfaces which maintain ABI stability. Review the following types of changes:\n\n| Changes allowed | - Changing a comment (unless this changes the meaning of a method). - Changing the name of a parameter. - Changing the name of a return parameter. - Changing annotations. |\n| Changes not allowed | - Reordering arguments, methods, etc. - Renaming an interface or moving it to a new package. - Renaming a package. - Adding a method/struct field/etc. anywhere in the interface. - Anything that would break a C++ vtable. - etc. |\n|---------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|"]]
