接口哈希

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

布局

每个软件包根目录（即映射到 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

注意：为了方便跟踪各个哈希的来源，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 的任何更改。
  • 等等