OpenHarmony-3.驱动HDF

• OpenHarmony HDF 框架

1.OpenHarmony HDF 框架概述

  OpenHarmony驱动子系统采用C面向对象编程模型构建，通过平台解耦、内核解耦，兼容不同内核，提供了归一化的驱动平台底座，旨在为开发者提供更精准、更高效的开发环境，力求做到一次开发，多系统部署。

  HDF驱动框架架构图

  HDF驱动架构主要组成部分：

• HDI（Hardware Device Interface，硬件设备统一接口）层：通过规范化的设备接口标准，为系统提供统一、稳定的硬件设备操作接口。

• HDF驱动框架：提供统一的硬件资源管理、驱动加载管理、设备节点管理、设备电源管理以及驱动服务模型等功能，需要包含设备管理、服务管理、DeviceHost、PnPManager等模块。

• 统一的配置界面：支持硬件资源的抽象描述，屏蔽硬件差异，可以支撑开发者开发出与配置信息不绑定的通用驱动代码，提升开发及迁移效率，并可通过HC-Gen等工具快捷生成配置文件。

• 操作系统抽象层（OSAL，Operating System Abstraction Layer）：提供统一封装的内核操作相关接口，屏蔽不同系统操作差异，包含内存、锁、线程、信号量等接口。

• 平台驱动：为外设驱动提供Board硬件（如：I2C/SPI/UART总线等平台资源）操作统一接口，同时对Board硬件操作进行统一的适配接口抽象以便于不同平台迁移。

• 外设驱动模型：面向外设驱动，提供常见的驱动抽象模型，主要达成两个目的，提供标准化的器件驱动，开发者无需独立开发，通过配置即可完成驱动的部署；提供驱动模型抽象，屏蔽驱动与不同系统组件间的交互，使得驱动更具备通用性。

2.HDF 架构

  OpenHarmony驱动框架采用主从架构设计模式，围绕着框架、模型、能力库和工具四个维度能力展开构建。

• 驱动框架 -位于framework/core目录
  提供驱动框架能力，主要完成驱动加载和启动功能。
  通过对象管理器方式可实现驱动框架的弹性化部署和扩展。

• 驱动模型 - 位于framework/model目录
  提供了模型化驱动能力，如网络设备模型。

• 驱动能力库 - 位于framework/ability目录
  提供基础驱动能力模型，如IO通信能力模型。

• 驱动工具 - 位于framework/tools目录
  提供HDI接口转换、驱动配置编译等工具。

• 驱动接口 - 位于lite/hdi目录
  提供规范化的驱动接口。

• Support - 位于framework/support目录
  提供规范化的平台驱动接口和系统接口抽象能力。

2.1.HDF 驱动框架

  OpenHarmony 系统 HDF 驱动框架主要由：

• 驱动基础框架
  HDF 驱动基础框架提供统一的硬件资源管理，驱动加载管理以及设备节点管理等功能。驱动框架采用的是主从模式设置，由 device manager 和 device host 组成。device manager 提供了统一的驱动管理，device manager 启动时根据 device information 提供驱动设备信息加载相应的驱动 device host，并控制 host 完成驱动的加载。 device host 提供驱动运行的环境，同时预置 host framework 与 device manager 进行协同，完成驱动加载和调用。根据业务的需求 device host 可以有多个实例。
• 驱动程序
  驱动程序实现驱动具体的功能，每个驱动由一个或者多个驱动程序组成，每个驱动程序都对应着一个 driver entry。driver entry 主要完成驱动的初始化和驱动接口绑定功能。
• 驱动配置文件
  驱动配置文件（.hcs），主要由设备信息（device information）和设备资源（device resource）组成，device information 完成设备信息的配置（如配置接口发布策略，驱动加载方式等）。device resource 完成设备资源的配置（如 GPIO 管脚、寄存器等资源信息配置等）。
• 驱动接口
  驱动接口（HDI），提供标准化的接口定义和实现，驱动框架提供 IO services 和 IO dispatcher 机制，是的不同部署形态下驱动接口趋于形式一致。

2.2.驱动框架交互流程

  驱动框架完成大部分驱动加载的动作，用户只需注册自己所需的接口和配置，然后驱动框架就会解析配置的内容，完成驱动加载和初始化动作。

  开发者基于HDF驱动框架开发的驱动主要包含三大部分：

1. 驱动程序部分 - 完成驱动的功能逻辑。
2. 驱动配置信息 - 指示驱动的加载信息内容。
3. 驱动资源配置 - 配置驱动的硬件配置信息。

2.3.驱动开发

2.3.1.平台驱动

  OpenHarmony平台驱动（Platform Driver），即平台设备（Platform Device）驱动，为系统及外设驱动提供访问接口。这里的平台设备，泛指I2C/UART等总线、以及GPIO/RTC等特定硬件资源。平台驱动框架是OpenHarmony驱动框架的重要组成部分，它基于HDF驱动框架、操作系统适配层以及驱动配置管理机制，为各类平台设备驱动的实现提供标准模型。平台驱动框架为外设提供了标准的平台设备访问接口，使其不必关注具体硬件；同时为平台设备驱动提供统一的适配接口，使其只关注自身硬件的控制。

  平台驱动框架提供如下特性：

• 统一的平台设备访问接口：对平台设备操作接口进行统一封装，屏蔽不同SoC平台硬件差异以及不同OS形态差异。

• 统一的平台驱动适配接口：为平台设备驱动提供统一的适配接口，使其只关注自身硬件的控制，而不必关注设备管理及公共业务流程。

• 提供设备注册、管理、访问控制等与SoC无关的公共能力。

  平台驱动框架目前支持的设备类型包括但不限于：ADC、DAC、GPIO、HDMI、I2C、I3C、MIPI_CSI、MIPI_DSI、MMC、Pin、PWM、Regulator、RTC、SDIO、SPI、UART、WatchDog等。

2.3.2.外设驱动
  OpenHarmony在HDF驱动框架及平台驱动框架的基础上，面向外设器件驱动，提供常见的驱动抽象模型。它提供标准化的外设器件驱动，可以减少重复开发；同时提供统一的外设驱动模型抽象，屏蔽驱动与不同系统组件间的交互，使得驱动更具备通用性。

  OpenHarmony当前支持的外设设备类型包括但不限于：Audio、Camera、Codec、Face_auth、Fingerprint_auth、LCD、Light、Motion、Pin_auth、Sensor、Touchscreen、USB、User_auth、Vibrator、WLAN等。

2.3.3.驱动代码

  HDF驱动架构实现根据功能和模块分为多个代码仓，如下表所示。

代码下载：

https://gitee.com/openharmony/drivers_hdf_core.git

• framework 目录代码结构如下：

/drivers/hdf_core/framework
├── core           #实现驱动框架的核心代码
│   ├── adapter    #实现对内核操作接口适配，提供抽象化的接口供开发者使用
│   ├── common     #驱动框架公共基础代码
│   ├── host       #驱动宿主环境模块
│   ├── manager    #驱动框架管理模块
│   └── shared     #host和manager共享模块代码
├── include        #驱动框架对外提供能力的头文件
│   ├── audio      #AUDIO对外提供能力的头文件
│   ├── bluetooth  #蓝牙对外提供能力的头文件
│   ├── core       #驱动框架对外提供的头文件
│   ├── ethernnet  #以太网操作相关的头文件
│   ├── net        #网络数据操作相关的头文件
│   ├── osal       #系统适配相关接口的头文件
│   ├── platform   #平台设备相关接口的头文件
│   ├── utils      #驱动框架公共能力的头文件
│   └── wifi       #WLAN对外提供能力的头文件
├── model          #提供驱动通用框架模型
│   ├── audio      #AUDIO框架模型
│   ├── display    #显示框架模型
│   ├── input      #输入框架模型
│   ├── misc       #杂项设备框架模型，包括dsoftbus、light、vibrator
│   ├── network    #WLAN框架模型
│   └── sensor     #Sensor驱动模型
│   └── storage    #存储驱动模型
│   └── usb        #USB驱动模型
├── sample         #HCS配置描述示例及HDF驱动示例
├── support        #提系统的基础能力 
│   └── platform   #平台设备驱动框架及访问接口，范围包括GPIO、I2C、SPI等
│   └── posix      #posix框架及访问接口，范围包括Mem、Mutex、Sem、Spinlock、Thread、Time等
├── test           #测试用例
├── tools          #hdf框架工具相关的源码
│   └── hc-gen     #配置管理工具源码
│   └── hcs-view   #
│   └── hdf-dbg    #
│   └── hdf-dev_eco_tool #
│   └── hdf-gen    #
│   └── idl-gen    #
│   └── leagecy    #
└── utils          #提供基础数据结构和算法等

• adapter 目录代码结构如下：

 14 /drivers/hdf_core/adapter15 ├── khdf/liteos         # HDF dependent adapter for LiteOS-A kernel16 ├── khdf/liteos_m       # HDF dependent adapter for LiteOS-M kernel17 ├── uhdf                # HDF user mode interface dependent adapter18 └── uhdf2               # HDF user mode dependent adapter

2.3.4. Input 驱动框架

2.4.HDF驱动加载过程

  OpenHarmony 驱动主要部署在内核态，根据驱动程序部署的不同方式，存在两种驱动加载方式：

• 动态加载方式：采用传统的so（共享库）加载方式，驱动程序通过指定Symbol方式找到驱动函数入口进行加载。
• 静态加载方式：采用将驱动程序通过Scatter编译到指定的Section,再通过访问指定Section对应的地址，找到驱动函数入口进行加载。

  当前主要采用静态链接方式，随内核子系统编译和系统镜像打包。

2.4.1. 驱动加载

  HDF驱动框架提供把和配置的设备列表匹配成功的驱动程序加载起来的功能，支持按需加载和按序加载两种策略，具体设备的加载策略由配置文件中的preload字段来控制，配置值参考如下：

 drivers/hdf_core/interfaces/inner_api/host/shared/hdf_device_desc.h：77 typedef enum {78     DEVICE_PRELOAD_ENABLE = 0, /**< The driver is loaded during system startup by default. */79     DEVICE_PRELOAD_ENABLE_STEP2, /**< The driver is loaded after OS startup if quick start is enabled. */80     DEVICE_PRELOAD_DISABLE,     /**< The driver is not loaded during system startup by default. */81     DEVICE_PRELOAD_INVALID     /**< The loading policy is incorrect. */82 } DevicePreload;

• 按需加载是HDF框架支持驱动在系统启动过程中默认加载，或者在系统启动之后动态加载。

  HDF框架定义的驱动按需加载方式的策略是由配置文件中的 preload 字段来控制，preload 字段的取值范围以及含义如下：
  

• 按序加载是HDF框架支持驱动在系统启动的过程中按照驱动的优先级进行加载。
  驱动的按序加载是通过配置文件中的 priority（取值范围为整数 0 到 200）来决定的，priority 值越小，表示的优先级越高。驱动的加载顺序，优先根据 host 的 priority 决定，如果host 的 priority 相同，再根据 host 内的驱动 priority 值来决定加载顺序。

2.4.2.HdfDriverEntry 结构体

  HdfDriverEntry 称为HDF驱动入口结构体，代表设备驱动的入口。

drivers/hdf_core/interfaces/inner_api/host/shared/hdf_device_desc.h:
struct HdfDriverEntry {//驱动程序的版本号int32_t moduleVersion;//驱动程序的名称，必须与驱动配置文件device_info.hcs中设备节点的moduleName属性保持一致。const char *moduleName;//三个函数指针，指向设备驱动的三个入口函数。int32_t (*Bind)(struct HdfDeviceObject *deviceObject);int32_t (*Init)(struct HdfDeviceObject *deviceObject);void (*Release)(struct HdfDeviceObject *deviceObject);
};

  在结构体HdfDriverEntry中，三个函数指针所指向的函数被称为 驱动入口函数 ，由驱动开发者负责编写，被HDF驱动框架调用。

• Bind函数
  用于向HDF驱动框架告知（注册）驱动程序的驱动服务入口。

• Init函数
  主要是用来完成驱动的一些初始化动作，比如：通过HDF提供的接口获取设备的配置信息、初始化设备、订阅驱动提供的服务等等。

• Release函数
  用来释放驱动程序所占用资源。

  HDF驱动框架在加载驱动的过程中，首先调用Bind函数，然后再调用Init函数。当加载驱动的过程中出现异常，或者当驱动被卸载的时候，HDF驱动框架会调用Release函数释放驱动所占用的资源。

  案例：

  通过HDF_INIT将驱动入口注册到HDF框架中，在加载驱动时HDF框架会先调用Bind函数,再调用Init函数加载该驱动，当Init调用异常时，HDF框架会调用Release释放驱动资源并退出。

• HDF_INIT宏展开

#define HDF_INIT(module)  HDF_DRIVER_INIT(module)#define USED_ATTR __attribute__((used))
#define HDF_SECTION __attribute__((section(".hdf.driver")))
#define HDF_DRIVER_INIT(module) \const size_t USED_ATTR module##HdfEntry HDF_SECTION = (size_t)(&(module))

  HDF_INIT 宏是定义了一个“驱动模块名+HdfEntry”的符号放到".hdf.driver"所在 section，该符号指向的内存地址即为驱动程序入口结构体的地址。这个特殊的 section 将用于开机启动时查找设备驱动。

2.4.3.驱动配置

  驱动配置包含两部分，HDF框架定义的驱动设备描述和驱动的私有配置信息。HDF使用HCS作为配置描述源码，内容以 Key-Value 键值对为主要形式。它实现了配置代码与驱动代码解耦，便于开发者进行配置管理。HC-GEN (全称 HDF Configuration Generator) 是 HCS 配置转换工具，可以将 HDF 配置文件转换为软件可读取的文件格式：在弱性能环境中，转换为配置树源码，驱动可直接调用 C代码获取配置；在高性能环境中，转换为 HCB(HDF Configuration Binary)二进制文件，驱动可使用 HDF框架提供的配置解析接口获取配置。
HCS经过HC-GEN编译生成HCB文件，HDF驱动框架中的HCS Parser模块会从HCB文件中重建配置树，HDF驱动模块使用HCS Parser提供的配置读取接口获取配置内容。驱动配置过程的原理图如下所示：

• 驱动设备描述（必选）
  HDF框架加载驱动所需要的信息来源于HDF框架定义的驱动设备描述，因此基于HDF框架开发的驱动必须要在HDF框架定义的device_info.hcs配置文件中添加对应的设备描述，驱动的设备描述填写如下所示：

sample_host :: host{hostName = "host0"; //host名称，host节点是用来存放某一类驱动的容器。priority = 100; //host启动优先级（0-200），值越大优先级越低，建议默认配100，优先级相同则不保证host的加载顺序。device_sample :: device { //sample设备节点。device0 :: deviceNode { //sample驱动的DeviceNode节点。policy = 1; //驱动服务发布的策略priority = 100; //驱动启动优先级（0-200），值越大优先级越低，建议默认配 100，优先级相同则不保证 device 的加载顺序preload = 0; //驱动按需加载字段permission = 0664;//驱动创建设备节点权限moduleName = "sample_driver"; //驱动名称，该字段的值必须和驱动入口结构的moduleName值一致serviceName = "sample_service"; //驱动对外发布服务的名称，必须唯一deviceMatchAttr = "sample_config";//驱动私有数据匹配的关键字，必须和驱动私有数据配置表中的match_attr值相等。}}
}

• 驱动私有配置信息（可选）
  如果驱动有私有配置，则可以添加一个驱动的配置文件，用来填写一些驱动的默认配置信息，HDF框架在加载驱动的时候，会将对应的配置信息获取并保存在HdfDeviceObject 中的property里面，通过Bind和Init传递给驱动，驱动的配置信息示例如下：

root {  SampleDriverConfig {sample_version = 1; sample_bus = "I2C_0"; match_attr = "sample_config";   //该字段的值必须和device_info.hcs中的deviceMatchAttr值一致}
}

2.4.4.获取驱动列表

  HDF驱动框架通过将驱动程序入口符号的地址集中存放到一个特殊的 section 来实现对驱动的索引，这个section的开头和末尾插入了_hdf_drivers_start、_hdf_drivers_end两个特殊符号，用于标记这个 section 的范围，两个特殊符号之间的数据即为驱动实现指针。

2.4.5.获取设备列表

  配置文本编译后会变成二进制格式的配置文件，其中设备相关信息被存放在一个用“hdf_manager”标记的 device_info 配置块中，host的内容以块的形式在device_info 块中依次排列，host块中记录了host名称、启动优先级和设备列表信息**。设备信息中的 moduleName字段将用于和驱动程序入口中的moduleName进行匹配，从而为设备匹配到正确的驱动程序，完成设备与驱动的匹配**。

2.4.6.设备与驱动匹配

加载流程图如下：

2.4.7.驱动框架启动

drivers_hdf_core/adapter/khdf/linux/manager/src/devmgr_load.c:25 static int __init DeviceManagerInit(void)26 {27     int ret;2829     HDF_LOGD("%s enter", __func__);30     ret = DeviceManagerStart();31     if (ret < 0) {32         HDF_LOGE("%s start failed %d", __func__, ret);33     } else {34         HDF_LOGD("%s start success", __func__);35     }36     return ret;37 }3839 late_initcall(DeviceManagerInit);

总结：
1）在系统启动时，DeviceManagerInit通过late_initcall先启动。
2） Device Manager 根据 Device Information 信息，解析配置文件中的 Host 列表，根据 Host 列表中的信息来实例化对应的 Host 对象。
3）Host遍历设备列表去获取与之匹配的驱动程序名称，然后基于驱动程序名称遍历.hdf.driver section 获得驱动程序地址。
4）设备与驱动匹配成功之后，获取指定驱动的入口地址，加载对应的设备驱动程序。
5）调用指定驱动的 Bind 接口，用于关联设备和服务实例。
6）调用指定驱动的 Init 接口，用于完成驱动的相关初始化工作。
7）如果驱动被卸载或者因为硬件等原因 Init 接口返回失败，Release 将被调用，用于释放驱动申请的各类资源。

refer to

• https://zhuanlan.zhihu.com/p/716011047
• https://gitee.com/openharmony/drivers_framework/blob/master/README_zh.md
• https://gitee.com/openharmony/docs/blob/master/zhcn/readme/%E9%A9%B1%E5%8A%A8%E5%AD%90%E7%B3%BB%E7%BB%9F.md
• https://gitee.com/openharmony/docs/blob/master/zh-cn/device-dev/driver/driver-overview-foundation.md