Android HIDL 简介

Android HIDL 简介

Qidi　2017.08.01 (Markdown & Haroopad)

---

注意：本文基于 Android 8.0 进行分析。

---

0、特别声明

本文是在 HIDL 刚出现、官方还没对外发布正式文档时撰写的。如今 Google 已经全面修订并公开了本文涉及的所有内容，对此话题感兴趣的朋友可以直接前往 https://source.android.com/devices/architecture/hidl 进行学习。

2021.01.26 Qidi

---

1、HIDL 的概念

HIDL 读作 hide-l，全称是 Hardware Interface Definition Language。它在 Android Project Treble 中被起草，在 Android 8.0 中被全面使用，其诞生目的是使 Android 可以在不重新编译 HAL 的情况下对 Framework 进行 OTA 升级。
　　HIDL 与 Android Vendor Test Suite (VTS) 测试有紧密的联系。关于 VTS 的介绍可以看我写的《Android Vendor Test Suite (VTS) 的概念、作用及测试方法》这篇文章。
　　使用 HIDL 描述的 HAL 描述文件替换旧的用头文件描述的 HAL 文件的过程称为 *** HAL 的 binder 化（binderization）。所有运行 Android O 的设备都必须只支持 binder 化后的 HAL 模块。**
　　已发布的 HIDL package包位于 Android 代码库的hardware/interfaces/或vendor/<vendorName>目录下。使用 HDIL 描述的 HAL 接口存放在这些目录下的.hal文件中。比如我们可以在hardware/interfaces/audio/2.0/目录下找到部分 Audio HAL 描述文件，如下：

Android.bp
Android.mk
IDevice.hal
IDevicesFactory.hal
IPrimaryDevice.hal
IStream.hal
IStreamIn.hal
IStreamOutCallback.hal
IStreamOut.hal
types.hal

---

2、HIDL 基础语法

HIDL 的语法和 C 语言有点类似，支持嵌套声明，但不支持前向声明和预处理指令。以下是一些常用标记符和数据类型：

• 标记符

• /* */　　　多行注释
• //　　　　单行注释
• [empty]　　表明当前项的值为空
• ?　　　　 放置在项前，表明该项为可选项
• …　　　　表明该序列包含0个或多个如前述使用分隔符隔开的项
• ,　　　　　逗号用于分隔序列中的元素
• ;　　　　　分号用于标记每个元素的结束位置
• @entry　　　当前HAL模块被使用时应当被最先调用的接口
• @exit　　　当前HAL模块被调用时应当被最后调用的接口
• @callflow(next={“name_a”, “name_b”, “name_c”})　　当前接口被调用后可能被调用的接口列表。其中name_a接口被调用的概率最大，name_c接口被调用的概率最小。如果只存在1个可能被调用的接口，那么花括号{ }可以省略不写。如果给定的接口名无效，则会导致VTS编译失败。
• @callflow(next={"*"})　　当前接口被调用后可能会调用任意接口

• 数据类型

• struct　　这个关键字定义一个结构体，格式与C++同
• union　　这个关键字定义一个联合体，格式与C++同
• MQDescriptorSync & MQDescriptorUnsync　　这2个关键字分别定义同步和非同步的FMQ(Fast Message Queue)描述符
• memory　　这个关键字用来声明HIDL中未被映射的共享内存
• pointer　　用这个关键字声明的pointer类型数据只能在HIDL内部使用
• bitfield< T>模板　　这个关键字用来定义一个与模板T相同的可进行位操作的数据。其中T是一个由用户定义的枚举数据类型
• 有限数组　　任何HIDL结构体中可被包含的数据类型都可以声明有限数组
• 字符串　　字符串在HIDL中以UTF8编码存储，所以在和由Java实现的接口进行交互时需要将编码格式转换为UTF16
• vec< T>模板　　这个关键字用来定义一个包含模板T的可变大小的buffer数据。其中T可以是除句柄外的任何HIDL内建或用户自定义数据类型
• 用户自定义数据类型　　用户可以自定义enum、struct、union类型的数据。定义enum数据的格式与C++11同，定义struct数据的格式与C同，定义union数据的格式与C同

• 关键字

• interface　　用于声明HAL模块中的一个接口，是构成.hal文件的基本单元，可以从其它interface继承而来
• package　　用于声明当前.hal文件中各interface接口所属的包
• import　　用于导入其它包里声明的interface或数据类型，以便在当前.hal文件中使用

• 示例

• 结构体声明

struct Point {
　　int32_t x;
　　int32_t y;
};

• 嵌套声明

interface IFoo {
　　uint32_t[3][4][5][6] multidimArray;
　　vec<vec<vec<int8_t>>> multidimVector;
　　vec<bool[4]> arrayVec;
　　struct foo {
　　　　struct bar {
　　　　　　uint32_t val;
　　　　};
　　　　bar b;
　　}
　　struct baz {
　　　　foo f;
　　　　foo.bar fb; // HIDL uses dots to access nested type names
　　}
　　…

• bitfield< T> 数据声明

enum Flag : uint8_t {  // 用户定义的枚举类型数据
　　HAS_FOO = 1 << 0,
　　HAS_BAR = 1 << 1,
　　HAS_BAZ = 1 << 2
};
typedef bitfield<Flag> Flags;  // 声明一个可进行位操作的数据
setFlags(Flags flags) generates (bool success);

• 有限数组声明

struct foo {
　　uint32_t[3] x; // array is contained in foo
};

• 用户自定义enum数据

enum Color : uint32_t { RED = 0, GREEN, BLUE = 2 } // GREEN == 1

• 一个完整的.hal文件

package android.hardware.audio@2.0;  // 当前package包名
import android.hardware.audio.common@2.0;  // 导入其它package包
import IDevice;  // 导入其它.hal
interface IDevicesFactory {  // 定义一个interface
　　typedef android.hardware.audio@2.0::Result Result;
　　enum Device : int32_t {  // 定义数据类型
　　　　PRIMARY,
　　　　A2DP,
　　　　USB,
　　　　R_SUBMIX,
　　　　STUB
　　};
　　/**
　　　* Opens an audio device. To close the device, it is necessary to release
　　　* references to the returned device object.
　　　*
　　　* @param device device type.
　　　* @return retval operation completion status. Returns INVALID_ARGUMENTS
　　　*         if there is no corresponding hardware module found,
　　　*         NOT_INITIALIZED if an error occured while opening the hardware
　　　*         module.
　　　* @return result the interface for the created device.
　　　*/
　　　openDevice(Device device) generates (Result retval, IDevice result);  // 定义一个方法
};

3、HIDL 文件的组织结构

每个 HIDL package包里都含有一个名为types.hal的文件，该文件中定义了这个包里所有 interface 共享的用户自定义数据类型，并且一般也会导入需要用到的其它包里的数据类型。
　　当前包中新的定义的 interface 可以继承自从其它包里导入的 interface，这样的继承关系可以使用extend关键字实现。比如下面示例中的 1.1 版本包中的 IQuux 接口就继承自 1.0 版本包中的 IQuux 接口：

// types.hal
package android.hardware.example@1.1
import android.hardware.example@1.0  // 导入1.0的包

// IQuux.hal
package android.hardware.example@1.1
interface IQuux extends @1.0::IQuux {  // 继承1.0包中的接口
　　fromBarToFoo(foo.bar b) generates (foo f);  // 直接使用fromBarToFoo方法而不再在当前包中声明
}

由 Google 提供的包叫做core package，包名始终以android.hardware.开头，以子系统名加以区分。比如 NFC 包的名字就应该为android.hardware.nfc，摄像头包的名字就应该为android.hardware.camera。这些 core包存放于hardware/interfaces/目录下。由各芯片厂商和 ODM厂商提供的包叫做non-core package，包名形式一般以vendor.$(vendorName).hardware.开头，比如vendor.samsung.hardware.。这些 non-core包一般存放于vendor/$(vendorName)/interfaces/目录下。
　　包的版本使用主、次版本号进行描述，紧随包名之后。比如android.hardware.audio@2.0表述这个 audio 包的版本是 2.0，主版本号是 2，次版本号是 0。
　　此外，每个 HIDL 包在被发布后就不能再对其内容进行变动了，如果要增加或修改这个包里的接口或数据类型，应该新建一个新版本的包，在这个新版本的包里进行变更。

---

参考资料：
[1] 《HIDL_General_Users_Guide_1_17_17.pdf》
[2] 《VTSAnnotationsinHIDL.pdf》
[3] 《HIDLHALVersioningandExtensions.pdf》