K1 OH5.0 驱动开发说明
修订记录
| 修订版本 | 修订日期 | 修订说明 |
| 001 | 2025-01-13 | 初始版本 |
1. Sensor 驱动开发
1.1 概述
Sensor 是常见的输入设备，用于感知环境状态并触发相应的响应。相比传统的 Linux 驱动模式，OH 在 HDF（Hardware Driver Foundation）层实现了 Sensor 驱动。
这种方式可实现一次开发、多内核部署，支持轻量系统、小型系统和标准 Linux 系统。同时，HDF 框架对不同驱动进行统一管理，每个驱动都能以服务形式对外提供能力。应用层可通过 HDI（Hardware Device Interface）接口直接访问，无需关注底层实现。
1.2 Sensor 驱动模型
OpenHarmony 中基于 HDF 驱动框架的 Sensor 驱动模型如下：
Sensor 驱动模型屏蔽硬件器件差异，为上层 Sensor 服务系统提供稳定的 Sensor 基础能力接口，包括 Sensor 列表查询、Sensor 启停、Sensor 订阅及取消订阅、Sensor 参数配置等功能。
Sensor 驱动开发基于 HDF 框架，并结合操作系统抽象层（OSAL，Operating System Abstraction Layer）和平台驱动接口（如 I2C、SPI、UART 等总线资源），实现跨系统和跨平台的一致性，达到“一次开发，多系统部署”的目标。
OpenHarmony 中 Sensor 驱动模型分为以下层级：
- Hardware：定义 Sensor 设备与 CPU 的连接方式，以及所使用的通信接口（如 I2C、SPI、GPIO 等）。
- Driver：实现硬件外设驱动逻辑，包括
HdfDriverEntry中的bindInit、realese函数，以及数据OpsCall里面的ReadData。 - HDI：定义并实现接口。接口主要包括所有 Sensor 信息查询、Sensor 启停、Sensor 订阅/取消订阅、Sensor 参数配置等稳定的接口，简化服务开发。
- Framework：上层 Sensor 服务。
1.3 HCS 配置
针对不同平台，需要在对应平台目录中修改相应的 .hcs 文件。以下示例展示在 MusePaper 平台下新增 Sensor 模 块的配置方法。
1.3.1 配置 device_info.hcs
-
文件路径：
vendor/spacemit/musepaper2/hdf_config/khdf/device_info/device_info.hcs -
配置说明：在
device_info.hcs中添加以下信息。 -
主要字段说明：
policy：服务策略。0：不发布服务1：向内核态发布服务2：向用户态发布服务
- moduleName：与驱动实现的
HdfDriverEntry结构体中的moduleName相同。 - deviceMatchAttr：驱动的私有配置信息。
- serviceName：服务名称，最终会在
/dev/节点下生成serviceName的节点（生成节点的前提条件是policy配置为大于等于1）。
1.3.2 配置 sensor_config.hcs
-
文件路径：
vendor/spacemit/musepaper2/hdf_config/khdf/sensor/sensor_config.hcs -
配置说明：在
sensor_config.hcs中添加如下内容：#include"accel/accel_qm8658_config.hcs"
1.3.3 配置 accel_qm8658_config.hcs
- 文件路径：
vendor/spacemit/musepaper/hdf_config/khdf/sensor/accel/accel_qm8658_config.hcs - 配置说明：新增文件夹
accel，并新建文件accel_qm8658_config.hcs，文件内容如下：
#include"../sensor_common.hcs"
root{
accel_qm8658_chip_config:sensorConfig{
match_attr="hdf_sensor_accel_qm8658_driver";
sensorInfo::sensorDeviceInfo{
sensorName="accelerometer";
vendorName="qmi8658";//maxstringlengthis16bytes
sensorTypeId=1; //enum SensorTypeTag
sensorId=1;//userdefinesensorid
power=230;
}
sensorBusConfig::sensorBusInfo{
busType=0; //0:i2c1:spi
busNum=3;
busAddr=0x6a;
regWidth=1;//1btye
}
sensorIdAttr::sensorIdInfo{
chipName="qm8658";
chipIdRegister=0x00;
chipIdValue=0x05;
}
sensorRegConfig{
/*regAddr:registeraddress
value:configregistervalue
len:sizeofvalue
mask:maskofvalue
delay:configregisterdelaytime(ms)
opsType:enumSensorOpsType0-none1-read2-write3-read_check4-update_bit
calType:enumSensorBitCalType0-none1-set2-revert3-xor4-leftshift5-rightshift
shiftNum:shiftbits
debug:0-nodebug1-debug
save:0-nosave1-save
*/
/*regAddr,value,mask,len,delay,opsType,calType,shiftNum,debug,save*/
initSeqConfig=[
0x02,0x78, 0xff,1,5, 2,0,0,0,0,
0x03,0x26, 0xff,1,5, 2,0,0,0,0,
0x08,0x00,0x03,1,5, 2,0,0,0,0
];
enableSeqConfig=[
0x08,0x01,0x03,1,5, 2,0,0,0,0
];
disableSeqConfig=[
0x08,0x00,0x03,1,5, 2,0,0,0,0
];
}
}
}
1.4 编译选项修改
- 在
drivers/adapter/khdf/linux/model/sensor/Kconfig中添加以下内容：
config DRIVERS_HDF_SENSOR_ACCEL_QM8658
bool "Enable HDF accel qm8658 sensor driver"
default n
depends on DRIVERS_HDF_SENSOR_ACCEL
help
Answer Y to enable HDF accel qm8658 sensor driver.
- 在
drivers/adapter/khdf/linux/model/sensor/Makefile中添加以下内容：
obj-$(CONFIG_DRIVERS_HDF_SENSOR_ACCEL_QM8658)+=$(SENSOR_ROOT_DIR)/chipset/accel/accel_qm8658.o
-
修改 Makefile 对应的驱动实现文件如下：
drivers/framework/model/sensor/driver/chipset/accel/accel_qm8658.cdrivers/framework/model/sensor/driver/chipset/accel/accel_qm8658.h
-
内核 defconfig 配置
在 kernel/linux/spacemit_kernel-6.6/arch/riscv/configs/k1_defconfig 文件中添加以下内容：
CONFIG_DRIVERS_HDF_SENSOR=y
CONFIG_DRIVERS_HDF_SENSOR_ACCEL=y
CONFIG_DRIVERS_HDF_SENSOR_ACCEL_QM8658=y
1.5 应用代码目录说明
Sensor 驱动对外服务的接口实现均在 drivers/peripheral/sensor 路径下，该目录对应的功能说明如下：
/drivers/peripheral/sensor
├── hal
└── include
└── src
├── interfaces
└── include
├── test
└── unit
- hal：sensor 模块 hal 层代码
- include：sensor 模块 hal 层内部头文件
- src：sensor 模块 hal 层代码的实现
- interfaces：sensor 模块对上层服务提供的驱动能力接口
- include：sensor 模块对外提供的接口定义
- test：sensor 模块测试代码
- unit：sensor 模块单元测试代码
1.6 常见问题处理
- 确认 HCS 配置的准确性，包括 I2C 总线、Sensor 寄存器初始化、Sensor 使能等信息。
- 确认是否修改了编译选项，使其正常编译进系统。
- 若应用使能不上，确认模块是否要配置权限，以及是否要
touch hdf.hcs更改时间戳。
2. TouchScreen 驱动开发
2.1 概述
TouchScreen 是常见的输入设备，用于感知用户在屏幕上的触摸操作并作出相应响应。
相比传统的 Linux 驱动模式，OpenHarmony 在 HDF 层实现了 TouchScreen 驱动，使其具备“一次开发，多系统部署”的能力，可支持轻量级系统、小型系统以及标准 Linux 系统。
在 HDF 框架下，不同驱动可统一管理，并以服务形式对外提供能力。应用层只需通过调用 HDI 接口，即可访问 TouchScreen 驱动服务。
2.2 TouchScreen 驱动模型
OpenHarmony 中基于 HDF 驱动框架的 TouchScreen 驱动模型如下：
OpenHarmony 中的 TouchScreen 驱动模型分为以下层级：
- Hardware：定义 TouchScreen 设备与 CPU 的连接方式，以及外设的通信接口（如 I2C、SPI、UART 等）和 IO 口配置。
- Kernel：根据项目需求选择合适的内核（Linux / LiteOS / RTOS）。该层通过 OSAL API 统一不同内核的接口，为 HDF Drivers 层提供标准化的操作接口，最大限度的屏蔽了不同内核之间的差异导致上层的修改。
- HDF Drivers：实现硬件驱动逻辑，完成设备初始化与操作。如 TouchScreen 驱动需实现
struct TouchChipOps ops中的函数，如 Init、Detect、Resume、Suspend、DataHandle、UpdateFirmware 等。 - Input HDI：该层实现了 TouchScreen 设备管理、业务控制、数据上报等驱动接口能力，为上层提供硬件驱动服务。
- Framework：上层 TouchScreen 服务。
2.3 HCS 配置
对于不同的平台，需要在对应的平台目录修改对应的 .``hcs 文件，下面示例为 MUSEPaper 平台下新增 GT9271 触摸屏的修改方法。
2.3.1 配置 device_info.hcs
-
文件路径：
vendor/spacemit/musepaper/hdf_config/khdf/device_info/device_info.hcs -
配置说明：在
device_info.hcs中添加以下内容。 -
主要字段说明：
policy：服务策略。0：不发布服务1：向内核态发布服务2：向用户态发布服务
- moduleName：与驱动实现的
HdfDriverEntry结构体中的moduleName相同。 - deviceMatchAttr：驱动的私有配置信息。
- serviceName：服务名称，最终会在
/dev/节点下生成serviceName的节点（生成节点的前提条件是policy配置为大于等于1）。
2.3.2 配置 input_config.hcs
- 文件路径：
vendor/spacemit/musepaper/hdf_config/khdf/input/input_config.hcs - 配置说明：在
input_config.hcs中修改如下配置。
2.3.3 修改配置
在 chipConfig 字段中新增 chip4，表示新增的一个触摸屏驱动。
2.4 编译选项修改
下面以新增触摸屏 GT9271 的驱动为例介绍相关的编译选项修改。
在 drivers/adapter/khdf/linux/model/input/Kconfig 中新增如下内容：
config DRIVERS_HDF_TP_10P10_GT9271
bool "Enable HDF tp10P10 GT9271
3. UART 驱动开发
3.1 概述
UART（Universal Asynchronous Receiver/Transmitter，通用异步收发传输器）是一种常见的串行通信接口。在 HDF 框架中，UART 的接口适配模式采用独立服务模式。
在此模式下，每个 UART 设备对象会独立发布一个设备服务，用于处理外部访问。设备管理器在接收到 API 请求后，会根据请求参数调用对应设备对象的内部方法。
独立服务模式的优点是可直接借助 HDFDeviceManager 的服务管理能力；缺点是需要为每个设备单独配置设备节点，这会增加内存占用。
UART 独立服务模式结构图如下图所示。
3.2 DTS 配置
配置说明
配置相应的串口设备节点，例如配置串口 2：
&uart2 {
pinctrl-names = "default";
pinctrl-0 = <&pinctrl_uart2>;
status = "okay";
};
3.3 HCS 配置
对于不同的平台，需要在对应的平台目录修改对应的 .``hcs 文件。
3.3.1 配置 device_info.hcs
文件路径
vendor/spacemit/xxx/hdf_config/khdf/device_info/device_info.hcs
配置说明
在 device_info.hcs 中添加以下内容：
在配置过程中需要注意如下几点：
-
Policy：设置节点隐藏或显示。
- 取值
1表示隐藏，即在dev目录下不显示 HDF 节点； - 取值
2表示显示，即在dev目录下显示 HDF 节点。
- 取值
-
Permission：文件权限。
-
Priority：启动顺序，数值越大启动越晚。
-
serviceName： 设备服务名，例如
HDF_PLATFORM_UART_2，其中后缀2对应应用中open函数的port参数。 -
deviceMatchAttr：需与
rk3568_uart_config.hcs中的match_attr取值一致。
3.3.2 **配置 **rk3568_uart_config.hcs
文件路径
vendor/spacemit/xxx/hdf_config/khdf/platform/rk3568_uart_config.hcs
配置说明
在 rk3568_uart_config.hcs 修改如下：
在配置过程中需要注意如下几点：
-
device_uart_0x0002： 后缀
0x0002为串口编号，从0x0000起递增。 -
Num：与
driver_name值ttyS组成驱动设备名，例如ttyS9。 若驱动设备名不以ttyS开头，例如 RK3568A 板的串口 A ~ D 的驱动设备名以ttyXRUSB开头，此时需要额外增加对driver_name的修改。例如：device_uart_0x0002 :: uart_device {
num = 9;
driver_name = "ttyXRUSB"
match_attr = "rockchip_rk3568_uart_9";
}如果不增加对
driver_name的修改，则默认使用 template 中的driver_name值，即ttyS。
3.4 应用使用流程
UART 的 API 接口使用，详见 OHOS 的 API 文档。
常用的 UART API 说明如下：
- uartOpen(port: number)：其中，port 为 “配置
device_info.hcs” 章节中serviceName的后缀数字。 - uartSetBaud：设置指定串口的波特率。
- uartSetAttribute：设置指定串口的基本属性。
3.5 常见问题处理
- 确认
/dev/下面是否有tty的设备生成。如果没有生成，请参考 “DTS 配置” 章节检查配置。 - 确认
/dev/下面是否有HDF_PLATFORM_UART_x生成（x为配置的service_name）。如果没有生成，请参考 “HCS 配置” 章节检查配置。
数据读写不生效：
- 将 RX 和 TX 短接，通过两个 hdc 终端去测试，一个执行
cat tty节点，一个执行echo tty节点。如果cat端收不到数据：- 请确认“DTS 配置”章节中的 pinctrl - 0 选择了正确的串口 pin 脚。
- 检查并确保硬件电路正常。
发送正常，读数据丢失：
- 请检查是否有其他应用在抢数据。
- 检查是否存在硬件干扰。