接口哈希

本文档介绍了 HIDL 接口哈希，这是一种防止意外接口变更并确保彻底审查接口变更的机制。之所以需要此机制，是因为 HIDL 接口是版本化的，这意味着接口发布后，不得对其进行更改，除非是以应用二进制接口 (ABI) 保持兼容的方式（例如更正注释）。

布局

每个软件包根目录（即映射到 hardware/interfaces 的 android.hardware 或映射到 vendor/foo/hardware/interfaces 的 vendor.foo）都必须包含一个 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 进行哈希处理

您可以手动或使用 hidl-gen 将哈希添加到 current.txt 文件。以下代码段提供了您可以使用 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 的操作。
  • 等等。