Android HIDL官方文档（二）—— Interfaces & Packages

接口和软件包

       HIDL 是围绕接口进行编译的，接口是面向对象的语言使用的一种用来定义行为的抽象类型。每个接口都是软件包的一部分。

软件包

       软件包名称可以具有子级，例如 package.subpackage。已发布的 HIDL 软件包的根目录是 hardware/interfaces 或 vendor/vendorName（例如 Pixel 设备为 vendor/google）。软件包名称在根目录下形成一个或多个子目录；定义软件包的所有文件都位于同一目录下。例如，package [email protected] 可以在 hardware/interfaces/example/extension/light/2.0 下找到。

       下表列出了软件包前缀和位置：

软件包前缀	位置
android.hardware.*	hardware/interfaces/*
android.frameworks.*	frameworks/hardware/interfaces/*
android.system.*	system/hardware/interfaces/*
android.hidl.*	system/libhidl/transport/*

       软件包目录中包含扩展名为 .hal 的文件。每个文件均必须包含一个指定文件所属的软件包和版本的 package 语句。文件 types.hal（如果存在）并不定义接口，而是定义软件包中每个接口可以访问的数据类型。

接口定义

       除了 types.hal 之外，其他 .hal 文件均定义一个接口。接口通常定义如下：

interface IBar extends IFoo { // IFoo is another interface
    // embedded types
    struct MyStruct {/*...*/};

    // interface methods
    create(int32_t id) generates (MyStruct s);
    close();
};

       不含显式 extends 声明的接口会从 [email protected]::IBase（类似于 Java 中的 java.lang.Object）隐式扩展。隐式导入的 IBase 接口声明了多种不应也不能在用户定义的接口中重新声明或以其他方式使用的预留方法。这些方法包括：

• ping
• interfaceChain
• interfaceDescriptor
• notifySyspropsChanged
• linkToDeath
• unlinkToDeath
• setHALInstrumentation
• getDebugInfo
• debug
• getHashChain

导入

  import 语句是用于访问其他软件包中的软件包接口和类型的 HIDL 机制。import 语句本身涉及两个实体：

• 导入实体：可以是软件包或接口；
• 被导入实体：也可以是软件包或接口。

       导入实体由 import 语句的位置决定。当该语句位于软件包的 types.hal 中时，导入的内容对整个软件包是可见的；这是软件包级导入。当该语句位于接口文件中时，导入实体是接口本身；这是接口级导入。

       被导入实体由 import 关键字后面的值决定。该值不必是完全限定名称；如果某个组成部分被删除了，系统会自动使用当前软件包中的信息填充该组成部分。 对于完全限定值，支持的导入情形有以下几种：

• 完整软件包导入。如果该值是一个软件包名称和版本（语法见下文），则系统会将整个软件包导入至导入实体中。
• 部分导入。如果值为：
  • 一个接口，则系统会将该软件包的 types.hal 和该接口导入至导入实体中。
  • 在 types.hal 中定义的 UDT，则系统仅会将该 UDT 导入至导入实体中（不导入 types.hal 中的其他类型）。
• 仅类型导入。如果该值将上文所述的“部分导入”的语法与关键字 types 而不是接口名称配合使用，则系统仅会导入指定软件包的 types.hal 中的 UDT。

       导入实体可以访问以下各项的组合：

• types.hal 中定义的被导入软件包的常见 UDT；
• 被导入的软件包的接口（完整软件包导入）或指定接口（部分导入），以便调用它们、向其传递句柄和/或从其继承句柄。

       导入语句使用完全限定类型名称语法来提供被导入的软件包或接口的名称和版本：

import [email protected];            // import a whole package
import [email protected]::IQuux; // import an interface and types.hal
import [email protected]::types; // import just types.hal

接口继承

       接口可以是之前定义的接口的扩展。扩展可以是以下三种类型中的一种：

• 接口可以向其他接口添加功能，并按原样纳入其 API。
• 软件包可以向其他软件包添加功能，并按原样纳入其 API。
• 接口可以从软件包或特定接口导入类型。

      接口只能扩展一个其他接口（不支持多重继承）。具有非零 Minor 版本号的软件包中的每个接口必须扩展一个以前版本的软件包中的接口。例如，如果 4.0 版本的软件包 derivative 中的接口 IBar 是基于（扩展了）1.2 版本的软件包 original 中的接口 IFoo，并且您又创建了 1.3 版本的软件包 original，则 4.1 版本的 IBar 不能扩展 1.3 版本的 IFoo。相反，4.1 版本的 IBar 必须扩展 4.0 版本的 IBar，因为后者是与 1.2 版本的 IFoo 绑定的。 如果需要，5.0 版本的 IBar 可以扩展 1.3 版本的 IFoo。

       接口扩展并不意味着生成的代码中存在代码库依赖关系或跨 HAL 包含关系，接口扩展只是在 HIDL 级别导入数据结构和方法定义。HAL 中的每个方法必须在相应 HAL 中实现。

供应商扩展

       在某些情况下，供应商扩展会作为以下基础对象的子类予以实现：代表其扩展的核心接口的基础对象。同一对象会同时在基础 HAL 名称和版本下，以及扩展的（供应商）HAL 名称和版本下注册。

版本编号

       软件包分版本，且接口的版本和其软件包的版本相同。版本用两个整数表示：major.minor。

• Major 版本不向后兼容。递增 Major 版本号将会使 Minor 版本号重置为 0。
• Minor 版本向后兼容。如果递增 Minor 版本号，则意味着较新版本完全向后兼容之前的版本。您可以添加新的数据结构和方法，但不能更改现有的数据结构或方法签名。

       为实现与框架的更广泛的兼容性，可同时在一台设备上提供 HAL 的多个 Major 版本。虽然也可以同时在一台设备上提供多个 Minor 版本，但是由于 Minor 版本向后兼容，因此不必在最新 Minor 版本以外，为各个 Major 版本提供其他额外支持。有关版本编号和供应商扩展的更多详细信息，请参阅 HIDL 版本编号。

接口布局总结

       本部分总结了如何管理 HIDL 接口软件包（如 hardware/interfaces）并整合了整个 HIDL 部分提供的信息。在阅读之前，请确保您熟悉 HIDL 版本控制、使用 hidl-gen 添加哈希中的哈希概念、在一般情况下使用 HIDL 的详细信息以及以下定义：

术语	定义
应用二进制接口 (ABI)	应用编程接口 + 所需的任何二进制链接。
完全限定名称 (fqName)	用于区分 hidl 类型的名称。例如：[email protected]::IFoo。
软件包	包含 HIDL 接口和类型的软件包。例如：[email protected]。
软件包根目录	包含 HIDL 接口的根目录软件包。例如：HIDL 接口 android.hardware在软件包根目录 [email protected] 中。
软件包根目录路径	软件包根目录映射到的 Android 源代码树中的位置。

       有关更多定义，请参阅 HIDL 术语。

每个文件都可以通过软件包根目录映射及其完全限定名称找到

       软件包根目录以参数 -r android.hardware:hardware/interfaces 的形式指定给 hidl-gen。例如，如果软件包为 [email protected]::IFoo 并且向 hidl-gen 发送了 -r vendor.awesome:some/device/independent/path/interfaces，那么接口文件应该位于 $ANDROID_BUILD_TOP/some/device/independent/path/interfaces/foo/1.0/IFoo.hal。

       在实践中，建议称为 awesome 的供应商或原始设备制造商 (OEM) 将其标准接口放在 vendor.awesome 中。在选择了软件包路径之后，不能再更改该路径，因为它已写入接口的 ABI。

软件包路径映射不得重复

       例如，如果您有 -rsome.package:$PATH_A 和 -rsome.package:$PATH_B，则 $PATH_A 必须等于 $PATH_B 以实现一致的接口目录（这也使得接口版本控制起来更简单）。

软件包根目录必须有版本控制文件

       如果您创建一个软件包路径（如 -r vendor.awesome:vendor/awesome/interfaces），则还应创建文件 $ANDROID_BUILD_TOP/vendor/awesome/interfaces/current.txt，它应包含使用 hidl-gen（在使用 hidl-gen 添加哈希中广泛进行了讨论）中的 -Lhash 选项创建的接口的哈希。

       注意：请谨慎管理所有更改！如果接口未冻结，则供应商测试套件 (VTS) 将失败，并且对接口进行的与 ABI 不兼容的更改将导致仅限框架的 OTA 失败。

接口位于设备无关的位置

       在实践中，建议在分支之间共享接口。这样可以最大限度地重复使用代码，并在不同的设备和用例中对代码进行最大程度的测试。

 

转载自：https://source.android.com/devices/architecture/hidl/interfaces