Android HIDL 官方文檔（三）—— 接口哈希（Interfaces Hashing）

---

• 對應的官方文檔地址：HIDL(General) - Interfaces & Packages

---

This document describes HIDL interface hashing, a mechanism to prevent accidental interface changes and ensure interface changes are thoroughly vetted. This mechanism is required because HIDL interfaces are versioned, which means that after an interface is released it must not be changed except in an Application Binary Interface (ABI) preserving manner (such as a comment correction).

       接口哈希這一機制的目的，是爲了防止接口意外被修改，它確保接口的任何更改都會被徹底審查。由於 HIDL 接口是版本化的，這就意味着除了在應用程序二進制接口（Application Binary Interface，ABI）保存方式（如註釋更正）中使用的方法以外，任何已發佈的接口是不應該改變的，而接口哈希機制則保證了這一點。

1. 佈局

（Layout）

Every package root directory (i.e. android.hardware mapping to hardware/interfaces or vendor.foo mapping to vendor/foo/hardware/interfaces) must contain a current.txt file that lists all released HIDL interface files.

       每一個包的根目錄（比如 android.hardware 對應 hardware/interfaces，或者 vendor.foo 對應 vendor/foo/hardware/interfaces）下都必須有一個 current.txt 文件，這個文件列出了所有已發佈的接口。

# 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 types.hal 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

Note: To help keep track of which hashes come from where, Google separates HIDL current.txt files into different sections: The first section is Released in Android O; the next section will be Released in Android O MR1. We strongly recommend using a similar layout in your current.txt file.

• NOTE：
  
  • 爲了幫助跟蹤每個哈希來自哪裏，Google 將 current.txt 分成了兩個不同的部分：
    
    • 第一部分是發佈在 Android O 的。
    • 第二部分將被髮布在 Android O MR1。
  • 我們強烈建議在您的 current.txt 中採用上述類似的佈局。

2. 通過 hidl-gen 生成哈希值

（Hashing with hidl-gen）

You can add a hash to a current.txt file manually or by using hidl-gen. The following code snippet provides examples of commands you can use with hidl-gen to manage a current.txt file (hashes have been shortened):

       您可以手動地在 current.txt 中添加一個哈希值，也可以通過 hidl-gen 來自動生成。以下代碼提供了一些使用 hidl-gen 生成哈希的例子（所顯示的哈希值是縮短後的）：

$ hidl-gen -L hash -r vendor.awesome:vendor/awesome/hardware/interfaces -r android.hardware:hardware/interfaces -r android.hidl:system/libhidl/transport [email protected]::types
9626fd18...f9d298a6 [email protected]::types

$ hidl-gen -L hash -r vendor.awesome:vendor/awesome/hardware/interfaces -r android.hardware:hardware/interfaces -r android.hidl:system/libhidl/transport [email protected]::INfc
07ac2dc9...11e3cf57 [email protected]::INfc

$ hidl-gen -L hash -r vendor.awesome:vendor/awesome/hardware/interfaces -r android.hardware:hardware/interfaces -r android.hidl:system/libhidl/transport [email protected]
9626fd18...f9d298a6 [email protected]::types
07ac2dc9...11e3cf57 [email protected]::INfc
f2fe5442...72655de6 [email protected]::INfcClientCallback

$ hidl-gen -L hash -r vendor.awesome:vendor/awesome/hardware/interfaces -r android.hardware:hardware/interfaces -r android.hidl:system/libhidl/transport [email protected] >> vendor/awesome/hardware/interfaces/current.txt

Warning: Do not replace a hash for a previously-released interface. When changing such an interface, add a new hash to the end of the current.txt file. For details, refer to ABI stability.

• WARNING：
  
  • 不可爲預先發布的接口替換哈希值。
  • 當更改這樣一個接口時，需要在 current.txt 文件的末尾加上新的哈希值。
  • 更多詳情參見 ABI 穩定性的部分。

Every interface definition library generated by hidl-gen includes hashes, which can be retrieved by calling IBase::getHashChain. When hidl-gen is compiling an interface, it checks the current.txt file in the root directory of the HAL package to see if the HAL has been changed:

• If no hash for the HAL is found, the interface is considered unreleased (in development) and compilation proceeds.
• If hashes are found, they are checked against the current interface:
  
  • If the interface does match the hash, compilation proceeds.
  • If the interface does not match a hash, compilation is halted as this means a previously-released interface is being changed.
    
    • For an ABI-preserving change (see ABI stability), the current.txt file must be modified before compilation can proceed.
    • All other changes should be made in a minor or major version upgrade of the interface.

       通過 hidl-gen 生成的每個接口定義庫包含了哈希值，通過調用 IBase:getHashChain 來檢索哈希。當 hidl-gen 編譯接口時，它會檢查 HAL 包根目錄下的 current.txt 文件，看看 HAL 是否發生了改變：

• 如果沒有找到 HAL 的哈希，則接口會被認爲是未發佈的（在開發中），編譯依舊正常進行下去。
• 如果找到了對應的哈希，則再次檢查當前接口：
  
  • 如果接口與哈希是對應的，則編譯正常進行。
  • 如果不對應，則停止編譯，因爲這表明了一個預先發布的接口正被改變。
    
    • 對於一個 ABI-preserving 的改變，只要修改對應的 current.txt 就可以繼續正常編譯。
    • 所有其它類型的更改都應在接口的一個主版本或從版本升級中進行。

3. ABI 穩定性

（ABI stability）
Key Point: Please read and understand this section carefully.

• 注意，這部分內容需要仔細閱讀並且弄明白。

An Application Binary Interface (ABI) includes the binary linkages/calling conventions/etc. If the ABI/API changes, the interface no longer works with a generic system.img that was compiled with official interfaces.

       一個應用程序二進制接口包括了二進制連接，調用或約定等等。如果 ABI（或 API）改變，則由官方接口編譯生成的 system.img 將無法正常工作。

Making sure that interfaces are versioned and ABI stable is crucial for several reasons:

• It ensures your implementation can pass the Vendor Test Suite (VTS), which puts you on track to being able to do framework-only OTAs.
• As an OEM, it enables you to provide a Board Support Package (BSP) that is straightforward to use and compliant.
• 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.

       確保接口是版本化的以及 ABI 穩定，有以下幾個重要的原因：

• 它確保了您的實現可以通過供應商測試套件（Vendor Test Suite，VTS）的測試，這讓您可以通過 OTA 方式實現僅針對框架層的升級。
• 對於原始設備製造商（Original Equipment Manufacturer，OEM），它使其可以提供一個可直接使用與兼容的板級支持包（Board Support Package，BSP）。
• 它使您可以追蹤哪個接口可以被髮布。考慮到 current.txt 是一個接口目錄的映射，它允許您查看包的根目錄中提供的所有接口的歷史與狀態。

When adding a new hash for an interface that already has an entry in current.txt, make sure to add only the hashes that represent interfaces which maintain ABI stability. Review the following types of changes:

• 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.
• Changes not allowed
  
  • Reordering arguments, methods, etc…
  • Adding a method/struct field/etc… anywhere in the interface.
  • Anything that would break a C++ vtable.
  • etc..

       當爲一個已經在 current.txt 中有條目的接口添加新的哈希值時，需要確保只添加表示維護 ABI 穩定性的接口的哈希。回顧以下的更改類型：

• 允許的改變：
  
  • 改變註釋（comment）中的內容（除了這個改變導致了方法的改變）。
  • 改變參數名稱。
  • 改變返回的參數的名稱。
  • 改變註釋（annotations）。
• 不允許的改變：
  
  • 重新排序參數，方法等。
  • 在接口的任何位置添加一個方法，結構或字段等等。
  • 任何會破壞 C++ 虛函數表的東西。
  • 諸如此類……