Skip to content

D
Docs

OpenHarmony / Docs
大约 1 年 前同步成功

通知 159
Star 292
Fork 28
D
Docs

体验新版 GitCode，发现更多精彩内容 >>

未验证 提交 dd75ff0d 编写于 作者: O openharmony_ci 提交者： Gitee
浏览文件
操作

!6619 驱动规范性检查（1） 

Merge pull request !6619 from liyan/master
上级 485a32d6 6d474372
隐藏空白更改
内联 并排
Showing with 123 addition and 111 deletion
zh-cn/device-dev/driver/driver-hdf-development.md
浏览文件 @ dd75ff0d
......@@ -3,7 +3,7 @@
## 驱动模型介绍
HDF（Hardware Driver Foundation）框架以组件化的驱动模型作为核心设计思路，为开发者提供更精细化的驱动管理，让驱动开发和部署更加规范。HDF框架将一类设备驱动放在同一个host里面，开发者也可以将驱动功能分层独立开发和部署，支持一个驱动多个node。HDF驱动模型如下图所示：
HDF（Hardware Driver Foundation）框架以组件化的驱动模型作为核心设计思路，为开发者提供更精细化的驱动管理，让驱动开发和部署更加规范。HDF框架将一类设备驱动放在同一个Host里面，开发者也可以将驱动功能分层独立开发和部署，支持一个驱动多个Node。HDF驱动模型如下图所示：
**图1** HDF驱动模型
......@@ -12,28 +12,28 @@ HDF（Hardware Driver Foundation）框架以组件化的驱动模型作为核心
## 驱动开发步骤
基于HDF框架进行驱动的开发主要分为两个部分，驱动实现和驱动配置。详细开发流程如下所示：
基于HDF框架的驱动开发主要分为三个部分：驱动实现、驱动编译和驱动配置。详细开发流程如下所示：
1. 驱动实现
驱动实现包含驱动业务代码和驱动入口注册，具体写法如下：
驱动实现包含驱动业务代码实现和驱动入口注册，具体写法如下：
- 驱动业务代码
```
#include "hdf_device_desc.h" // HDF框架对驱动开发相关能力接口的头文件
#include "hdf_log.h" // HDF框架提供的日志接口头文件
#include "hdf_device_desc.h" // HDF框架对驱动开发相关能力接口的头文件
#include "hdf_log.h" // HDF框架提供的日志接口头文件
#define HDF_LOG_TAG "sample_driver" // 打印日志所包含的标签，如果不定义则用默认定义的HDF_TAG标签
#define HDF_LOG_TAG "sample_driver" // 打印日志所包含的标签，如果不定义则用默认定义的HDF_TAG标签。
// 驱动对外提供的服务能力，将相关的服务接口绑定到HDF框架
// 驱动对外提供的服务能力，将相关的服务接口绑定到HDF框架。
int32_t HdfSampleDriverBind(struct HdfDeviceObject *deviceObject)
{
HDF_LOGD("Sample driver bind success");
return 0;
}
// 驱动自身业务初始的接口
// 驱动自身业务初始化的接口
int32_t HdfSampleDriverInit(struct HdfDeviceObject *deviceObject)
{
HDF_LOGD("Sample driver Init success");
......@@ -50,7 +50,7 @@ HDF（Hardware Driver Foundation）框架以组件化的驱动模型作为核心
- 驱动入口注册到HDF框架
```
// 定义驱动入口的对象，必须为HdfDriverEntry（在hdf_device_desc.h中定义）类型的全局变量
// 定义驱动入口的对象，必须为HdfDriverEntry（在hdf_device_desc.h中定义）类型的全局变量。
struct HdfDriverEntry g_sampleDriverEntry = {
.moduleVersion = 1,
.moduleName = "sample_driver",
......@@ -59,93 +59,94 @@ HDF（Hardware Driver Foundation）框架以组件化的驱动模型作为核心
.Release = HdfSampleDriverRelease,
};
// 调用HDF_INIT将驱动入口注册到HDF框架中，在加载驱动时HDF框架会先调用Bind函数,再调用Init函数加载该驱动，当Init调用异常时，HDF框架会调用Release释放驱动资源并退出
// 调用HDF_INIT将驱动入口注册到HDF框架中。在加载驱动时HDF框架会先调用Bind函数，再调用Init函数加载该驱动；当Init调用异常时，HDF框架会调用Release释放驱动资源并退出。
HDF_INIT(g_sampleDriverEntry);
```
2. 驱动编译
- liteos
涉及makefile和BUILD.gn修改：
- LiteOS
- makefile部分：
涉及Makefile和BUILD.gn修改：
驱动代码的编译必须要使用HDF框架提供的Makefile模板进行编译。
- Makefile部分：
```
include $(LITEOSTOPDIR)/../../drivers/adapter/khdf/liteos/lite.mk #导入hdf预定义内容，必需
MODULE_NAME := #生成的结果文件
LOCAL_INCLUDE := #本驱动的头文件目录
LOCAL_SRCS := #本驱动的源代码文件
LOCAL_CFLAGS ：= #自定义的编译选项
include $(HDF_DRIVER) #导入Makefile模板完成编译
```
驱动代码的编译必须要使用HDF框架提供的Makefile模板进行编译。
```
include $(LITEOSTOPDIR)/../../drivers/adapter/khdf/liteos/lite.mk # 【必需】导入hdf预定义内容
MODULE_NAME := #生成的结果文件
LOCAL_INCLUDE := #本驱动的头文件目录
LOCAL_SRCS := #本驱动的源代码文件
LOCAL_CFLAGS ：= #自定义的编译选项
include $(HDF_DRIVER) #导入Makefile模板完成编译
```
编译结果文件链接到内核镜像，添加到drivers/adapter/khdf/liteos目录下的hdf_lite.mk里面，示例如下：
编译结果文件链接到内核镜像，添加到**drivers/adapter/khdf/liteos**目录下的**hdf_lite.mk**里面，示例如下：
```
LITEOS_BASELIB += -lxxx #链接生成的静态库
LIB_SUBDIRS += #驱动代码Makefile的目录
```
```
LITEOS_BASELIB += -lxxx #链接生成的静态库
LIB_SUBDIRS += #驱动代码Makefile的目录
```
- BUILD.gn部分：
- BUILD.gn部分：
添加模块BUILD.gn参考定义如下内容：
添加模块BUILD.gn参考定义如下内容：
```
import("//build/lite/config/component/lite_component.gni")
import("//drivers/adapter/khdf/liteos/hdf.gni")
module_switch = defined(LOSCFG_DRIVERS_HDF_xxx)
module_name = "xxx"
hdf_driver(module_name) {
sources = [
"xxx/xxx/xxx.c", #模块要编译的源码文件
]
public_configs = [ ":public" ] #使用依赖的头文件配置
}
config("public") { #定义依赖的头文件配置
include_dirs = [
"xxx/xxx/xxx", #依赖的头文件目录
]
}
```
把新增模块的BUILD.gn所在的目录添加到/drivers/adapter/khdf/liteos/BUILD.gn里面：
```
import("//build/lite/config/component/lite_component.gni")
import("//drivers/adapter/khdf/liteos/hdf.gni")
module_switch = defined(LOSCFG_DRIVERS_HDF_xxx)
module_name = "xxx"
hdf_driver(module_name) {
sources = [
"xxx/xxx/xxx.c", #模块要编译的源码文件
]
public_configs = [ ":public" ] #使用依赖的头文件配置
}
config("public") { #定义依赖的头文件配置
include_dirs = [
"xxx/xxx/xxx", #依赖的头文件目录
]
}
```
把新增模块的BUILD.gn所在的目录添加到**/drivers/adapter/khdf/liteos/BUILD.gn**里面：
```
group("liteos") {
public_deps = [ ":$module_name" ]
deps = [
"xxx/xxx", #新增模块BUILD.gn所在的目录，目录结构相对于/drivers/adapter/khdf/liteos
]
}
```
- linux
如果需要定义模块控制宏，需要在模块目录xxx里面添加Kconfig文件，并把Kconfig文件路径添加到drivers/adapter/khdf/linux/Kconfig里面：
```
group("liteos") {
public_deps = [ ":$module_name" ]
deps = [
"xxx/xxx", #新增模块BUILD.gn所在的目录，目录结构相对于/drivers/adapter/khdf/liteos
]
}
```
- Linux
如果需要定义模块控制宏，需要在模块目录xxx里面添加Kconfig文件，并把Kconfig文件路径添加到**drivers/adapter/khdf/linux/Kconfig**里面：
```
source "drivers/hdf/khdf/xxx/Kconfig" #目录为hdf模块软链接到kernel里面的目录
```
```
source "drivers/hdf/khdf/xxx/Kconfig" #目录为hdf模块软链接到kernel里面的目录
```
添加模块目录到drivers/adapter/khdf/linux/Makefile：
添加模块目录到**drivers/adapter/khdf/linux/Makefile**：
```
obj-$(CONFIG_DRIVERS_HDF) += xxx/
```
```
obj-$(CONFIG_DRIVERS_HDF) += xxx/
```
在模块目录xxx里面添加Makefile文件，在Makefile文件里面添加模块代码编译规则：
在模块目录xxx里面添加Makefile文件，在Makefile文件里面添加模块代码编译规则：
```
obj-y += xxx.o
```
```
obj-y += xxx.o
```
3. 驱动配置
......@@ -155,19 +156,19 @@ HDF（Hardware Driver Foundation）框架以组件化的驱动模型作为核心
- 驱动设备描述（必选）
HDF框架加载驱动所需要的信息来源于HDF框架定义的驱动设备描述，因此基于HDF框架开发的驱动必须要在HDF框架定义的device_info.hcs配置文件中添加对应的设备描述，驱动的设备描述填写如下所示：
HDF框架加载驱动所需要的信息来源于HDF框架定义的驱动设备描述，因此基于HDF框架开发的驱动必须要在HDF框架定义的device_info.hcs配置文件中添加对应的设备描述。驱动的设备描述填写如下所示：
```
root {
device_info {
match_attr = "hdf_manager";
template host { // host模板，继承该模板的节点（如下sample_host）如果使用模板中的默认值，则节点字段可以缺省
template host { // host模板，继承该模板的节点（如下sample_host）如果使用模板中的默认值，则节点字段可以缺省。
hostName = "";
priority = 100;
uid = ""; // 用户态进程uid，缺省为空，会被配置为hostName的定义值，即普通用户
gid = ""; // 用户态进程gid，缺省为空，会被配置为hostName的定义值，即普通用户组
caps = [""]; // 用户态进程Linux capabilities配置，缺省为空，需要业务模块按照业务需要进行配置
uid = ""; // 用户态进程uid，缺省为空，会被配置为hostName的定义值，即普通用户。
gid = ""; // 用户态进程gid，缺省为空，会被配置为hostName的定义值，即普通用户组。
caps = [""]; // 用户态进程Linux capabilities配置，缺省为空，需要业务模块按照业务需要进行配置。
template device {
template deviceNode {
policy = 0;
......@@ -181,39 +182,41 @@ HDF（Hardware Driver Foundation）框架以组件化的驱动模型作为核心
}
}
sample_host :: host{
hostName = "host0"; // host名称，host节点是用来存放某一类驱动的容器
priority = 100; // host启动优先级（0-200），值越大优先级越低，建议默认配100，优先级相同则不保证host的加载顺序
caps = ["DAC_OVERRIDE", "DAC_READ_SEARCH"]; // 用户态进程Linux capabilities配置
hostName = "host0"; // host名称，host节点是用来存放某一类驱动的容器。
priority = 100; // host启动优先级（0-200），值越大优先级越低，建议默认配100，优先级相同则不保证host的加载顺序。
caps = ["DAC_OVERRIDE", "DAC_READ_SEARCH"]; // 用户态进程Linux capabilities配置。
device_sample :: device { // sample设备节点
device0 :: deviceNode { // sample驱动的DeviceNode节点
policy = 1; // policy字段是驱动服务发布的策略，在驱动服务管理章节有详细介绍
priority = 100; // 驱动启动优先级（0-200），值越大优先级越低，建议默认配100，优先级相同则不保证device的加载顺序
preload = 0; // 驱动按需加载字段，在本章节最后的说明有详细介绍
policy = 1; // policy字段是驱动服务发布的策略，在驱动服务管理章节有详细介绍。
priority = 100; // 驱动启动优先级（0-200），值越大优先级越低，建议默认配100，优先级相同则不保证device的加载顺序。
preload = 0; // 驱动按需加载字段，在本章节最后的说明有详细介绍。
permission = 0664; // 驱动创建设备节点权限
moduleName = "sample_driver"; // 驱动名称，该字段的值必须和驱动入口结构的moduleName值一致
serviceName = "sample_service"; // 驱动对外发布服务的名称，必须唯一
deviceMatchAttr = "sample_config"; // 驱动私有数据匹配的关键字，必须和驱动私有数据配置表中的match_attr值相等
moduleName = "sample_driver"; // 驱动名称，该字段的值必须和驱动入口结构的moduleName值一致。
serviceName = "sample_service"; // 驱动对外发布服务的名称，必须唯一。
deviceMatchAttr = "sample_config"; // 驱动私有数据匹配的关键字，必须和驱动私有数据配置表中的match_attr值相等。
}
}
}
}
}
```
说明：
uid、gid、caps等配置项是用户态驱动的启动配置，内核态不用配置。
根据进程权限最小化设计原则，业务模块uid、gid不用配置，如上面的sample_host，使用普通用户权限，即uid和gid被定义为hostName的定义值。
如果普通用户权限不能满足业务要求，需要把uid、gid定义为system或者root权限时，请找安全专家进行评审。
进程的uid在文件base/startup/init_lite/services/etc/passwd中配置，进程的gid在文件base/startup/init_lite/services/etc/group中配置，进程uid和gid配置参考：[系统服务用户组添加方法](https://gitee.com/openharmony/startup_init_lite/wikis)。
> ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：**<br>
>
> - uid、gid、caps等配置项是用户态驱动的启动配置，内核态不用配置。
>
> - 根据进程权限最小化设计原则，业务模块uid、gid不用配置，如上面的sample_host，使用普通用户权限，即uid和gid被定义为hostName的定义值。
>
> - 如果普通用户权限不能满足业务要求，需要把uid、gid定义为system或者root权限时，请找安全专家进行评审。
>
> - 进程的uid在文件**base/startup/init_lite/services/etc/passwd**中配置，进程的gid在文件**base/startup/init_lite/services/etc/group**中配置，进程uid和gid配置参考：[系统服务用户组添加方法](https://gitee.com/openharmony/startup_init_lite/wikis)。
>
> - caps值：比如业务模块要配置CAP_DAC_OVERRIDE，此处需要填写caps = ["DAC_OVERRIDE"]，不能填写为caps = ["CAP_DAC_OVERRIDE"]。
caps值：比如业务模块要配置CAP_DAC_OVERRIDE，此处需要填写 caps = ["DAC_OVERRIDE"]，不能填写为caps = ["CAP_DAC_OVERRIDE"]。
- 驱动私有配置信息（可选）
如果驱动有私有配置，则可以添加一个驱动的配置文件，用来填写一些驱动的默认配置信息，HDF框架在加载驱动的时候，会将对应的配置信息获取并保存在HdfDeviceObject中的property里面，通过Bind和Init（参考步骤1）传递给驱动，驱动的配置信息示例如下：
如果驱动有私有配置，则可以添加一个驱动的配置文件，用来填写一些驱动的默认配置信息。HDF框架在加载驱动的时候，会将对应的配置信息获取并保存在HdfDeviceObject中的property里面，通过Bind和Init（参考步骤1）传递给驱动。驱动的配置信息示例如下：
```
......@@ -249,7 +252,12 @@ HDF（Hardware Driver Foundation）框架以组件化的驱动模型作为核心
> } DevicePreload;
> ```
>
> 配置文件中preload字段配成0（DEVICE_PRELOAD_ENABLE），则系统启动过程中默认加载；配成1（DEVICE_PRELOAD_ENABLE_STEP2），当系统支持快启的时候，则在系统完成之后再加载这一类驱动，否则和DEVICE_PRELOAD_ENABLE含义相同；配成2（DEVICE_PRELOAD_DISABLE），则系统启动过程中默认不加载，支持后续动态加载，当用户态获取驱动服务（参考[消息机制](../driver/driver-hdf-message-management.md)）时，如果驱动服务不存在，HDF框架会尝试动态加载该驱动。
> - 配置文件中preload字段配成0（DEVICE_PRELOAD_ENABLE），则系统启动过程中默认加载。
>
> - 配成1（DEVICE_PRELOAD_ENABLE_STEP2），当系统支持快启的时候，则在系统完成之后再加载这一类驱动，否则和DEVICE_PRELOAD_ENABLE含义相同。
>
> - 配成2（DEVICE_PRELOAD_DISABLE），则系统启动过程中默认不加载，支持后续动态加载，当用户态获取驱动服务（参考[消息机制](../driver/driver-hdf-message-management.md)）时，如果驱动服务不存在，HDF框架会尝试动态加载该驱动。
>
> - 按序加载（需要驱动为默认加载）
>
> 配置文件中的priority（取值范围为整数0到200）是用来表示host和驱动的优先级。不同的host内的驱动，host的priority值越小，驱动加载优先级越高；同一个host内驱动的priority值越小，加载优先级越高。
zh-cn/device-dev/driver/driver-hdf-overview.md
浏览文件 @ dd75ff0d
......@@ -11,9 +11,11 @@ HDF（Hardware Driver Foundation）驱动框架，为驱动开发者提供驱动
HDF驱动加载包括按需加载和按序加载。
- 按需加载
HDF框架支持驱动在系统启动过程中默认加载，或者在系统启动之后动态加载。
- 按序加载
HDF框架支持驱动在系统启动的过程中按照驱动的优先级进行加载。
......
zh-cn/device-dev/driver/driver-hdf-servicemanage.md
浏览文件 @ dd75ff0d
......@@ -4,7 +4,7 @@
驱动服务是HDF驱动设备对外提供能力的对象，由HDF框架统一管理。驱动服务管理主要包含驱动服务的发布和获取。
HDF框架定义了驱动对外发布服务的策略，是由配置文件中的policy字段来控制，policy字段的取值范围以及含义如下：
HDF框架定义了驱动对外发布服务的策略，由配置文件中的policy字段来控制，policy字段的取值范围以及含义如下：
......@@ -39,26 +39,26 @@ typedef enum {
| 方法 | 描述 |
| -------- | -------- |
| int32_t&nbsp;(\*Bind)(struct&nbsp;HdfDeviceObject&nbsp;\*deviceObject); | 需要驱动开发者实现Bind函数，将自己的服务接口绑定到HDF框架中。 |
| const&nbsp;struct&nbsp;HdfObject&nbsp;\*DevSvcManagerClntGetService(const&nbsp;char&nbsp;\*svcName); | 获取驱动的服务。 |
| int&nbsp;HdfDeviceSubscribeService(<br/>struct&nbsp;HdfDeviceObject&nbsp;\*deviceObject,&nbsp;const&nbsp;char&nbsp;\*serviceName,&nbsp;struct&nbsp;SubscriberCallback&nbsp;callback); | 订阅驱动的服务。 |
| int32_t&nbsp;(\*Bind)(struct&nbsp;HdfDeviceObject&nbsp;\*deviceObject) | 需要驱动开发者实现Bind函数，将自己的服务接口绑定到HDF框架中。 |
| const&nbsp;struct&nbsp;HdfObject&nbsp;\*DevSvcManagerClntGetService(const&nbsp;char&nbsp;\*svcName)| 获取驱动的服务。 |
|int&nbsp;HdfDeviceSubscribeService(<br/>struct&nbsp;HdfDeviceObject&nbsp;\*deviceObject,&nbsp;const&nbsp;char&nbsp;\*serviceName,&nbsp;struct&nbsp;SubscriberCallback&nbsp;callback) | 订阅驱动的服务。 |
## 开发步骤
驱动服务管理的开发包括驱动服务的编写、绑定、获取或者订阅，详细步骤如下。
1. 驱动服务发布。
1. 驱动服务编写。
```
驱动服务结构的定义
// 驱动服务结构的定义
struct ISampleDriverService {
struct IDeviceIoService ioService; // 服务结构的首个成员必须是IDeviceIoService类型的成员
int32_t (*ServiceA)(void); // 驱动的第一个服务接口
int32_t (*ServiceB)(uint32_t inputCode); // 驱动的第二个服务接口，有多个可以依次往下累加
struct IDeviceIoService ioService; // 服务结构的首个成员必须是IDeviceIoService类型的成员。
int32_t (*ServiceA)(void); // 驱动的第一个服务接口。
int32_t (*ServiceB)(uint32_t inputCode); // 驱动的第二个服务接口，有多个可以依次往下累加。
};
驱动服务接口的实现
// 驱动服务接口的实现
int32_t SampleDriverServiceA(void)
{
// 驱动开发者实现业务逻辑
......@@ -77,7 +77,7 @@ typedef enum {
```
int32_t SampleDriverBind(struct HdfDeviceObject *deviceObject)
{
// deviceObject为HDF框架给每一个驱动创建的设备对象，用来保存设备相关的私有数据和服务接口
// deviceObject为HDF框架给每一个驱动创建的设备对象，用来保存设备相关的私有数据和服务接口。
if (deviceObject == NULL) {
HDF_LOGE("Sample device object is null!");
return -1;
......@@ -92,10 +92,11 @@ typedef enum {
```
3. 驱动服务获取。
驱动服务的获取有两种方式，HDF框架提供接口直接获取和HDF框架提供订阅机制获取。
驱动服务的获取有两种方式，HDF框架提供接口直接获取和订阅机制获取。
- 通过HDF接口直接获取
当明确驱动已经加载完成时，获取该驱动的服务可以通过HDF框架提供的能力接口直接获取，如下所示：
当明确驱动已经加载完成时，获取该驱动的服务可以通过HDF框架提供的能力接口直接获取，如下所示：
```
......@@ -108,7 +109,8 @@ typedef enum {
sampleService->ServiceB(5);
```
- 通过HDF提供的订阅机制获取
当内核态对驱动（同一个host）加载的时机不感知时，可以通过HDF框架提供的订阅机制来订阅该驱动，当该驱动加载完成时，HDF框架会将被订阅的驱动服务发布给订阅者，实现方式如下所示：
当内核态对驱动（同一个host）加载的时机不感知时，可以通过HDF框架提供的订阅机制来订阅该驱动。当该驱动加载完成时，HDF框架会将被订阅的驱动服务发布给订阅者，实现方式如下所示：
```
......
Markdown is supported
0% 或 .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑！
想要评论请 注册 或