Android_Architecture_HIDL(General)--Interface Hashing（接口哈希）

说明：转载自官方英文+中文版https://source.android.com/devices/architecture/hidl/hashing

---

 

Interface Hashing 接口哈希

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 接口哈希，该哈希是一种旨在防止意外更改接口并确保接口更改经过全面审查的机制。这种机制是必需的，因为 HIDL 接口带有版本编号，也就是说，接口一经发布便不得再更改，但不会影响应用二进制接口 (ABI) 的情况（例如更正备注）除外。
 

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.

每个软件包根目录（即映射到 hardware/interfaces 的 android.hardware 或映射到 vendor/foo/hardware/interfaces 的 vendor.foo）都必须包含一个列出所有已发布 HIDL 接口文件的 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 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

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.

注意：为了便于跟踪各个哈希的来源，Google 会将 HIDL current.txt 文件分为不同的部分：第一部分列出在 Android O 中发布的接口文件，第二部分列出在 Android O MR1 中发布的接口文件。我们强烈建议在您的 current.txt 文件中使用类似布局。

 

Hashing with hidl-gen 使用 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 搭配使用来管理 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

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.

警告：请勿更换之前发布的接口的哈希。如要更改此类接口，请向 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（请参阅 ABI 稳定性），请务必先修改 current.txt 文件，然后编译才能继续进行。
    • 所有其他更改都应在接口的 minor 或 major 版本升级中进行。

 

ABI stability ABI稳定性

---

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.

 
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.

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

要点：请仔细阅读并理解本部分。

应用二进制接口 (ABI) 包括二进制关联/调用规范/等等。如果 ABI/API 发生更改，则相应接口就不再适用于使用官方接口编译的常规 system.img。

确保接口带有版本编号且 ABI 稳定至关重要，具体原因有如下几个：

• 可确保您的实现能够通过供应商测试套件 (VTS) 测试，通过该测试后您将能够正常进行仅限框架的 OTA。
• 作为原始设备制造商 (OEM)，您将能够提供简单易用且符合规定的板级支持包 (BSP)。
• 有助于您跟踪哪些接口可以发布。您可以将 current.txt 视为接口目录的“地图”，从中了解软件包根目录中提供的所有接口的历史记录和状态。

对于在 current.txt 中已有条目的接口，为其添加新的哈希时，请务必仅为可保持 ABI 稳定性的接口添加哈希。请查看以下更改类型：

允许的更改	- 更改备注（除非这会更改方法的含义）。 - 更改参数的名称。 - 更改返回参数的名称。 - 更改注释。
不允许的更改	- 重新排列参数、方法等… - 重命名接口或将其移至新的软件包。 - 重命名软件包。 - 在接口的任意位置添加方法/结构体字段等等… - 会破坏 C++ vtable 的任何更改。 - 等等…