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 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

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++ 虚函数表的东西。
  • 诸如此类……