OpenHarmony：全流程讲解如何编写RTC平台驱动以及应用程序

1、程序介绍

本程序是基于OpenHarmony标准系统编写的平台驱动案例：RTC

2、基础知识

2.1、RTC简介

RTC（real-time clock）为操作系统中的实时时钟设备，为操作系统提供精准的实时时间和定时报警功能。当设备下电后，通过外置电池供电，RTC继续记录操作系统时间；设备上电后，RTC提供实时时钟给操作系统，确保断电后系统时间的连续性。

2.2、RTC驱动开发

在HDF框架中，RTC的接口适配模式采用独立服务模式，在这种模式下，每一个设备对象会独立发布一个设备服务来处理外部访问，设备管理器收到API的访问请求之后，通过提取该请求的参数，达到调用实际设备对象的相应内部方法的目的。独立服务模式可以直接借助HDFDeviceManager的服务管理能力，但需要为每个设备单独配置设备节点，增加内存占用。

独立服务模式下，核心层不会统一发布一个服务供上层使用，因此这种模式下驱动要为每个控制器发布一个服务，具体表现为：

驱动适配者需要实现HdfDriverEntry的Bind钩子函数以绑定服务。

device_info.hcs文件中deviceNode的policy字段为1或2，不能为0。

2.2.1、RTC驱动开发接口

为了保证上层在调用RTC接口时能够正确的操作硬件，核心层在//drivers/hdf_core/framework/support/platform/include/rtc/rtc_core.h中定义了以下钩子函数。驱动适配者需要在适配层实现这些函数的具体功能，并与这些钩子函数挂接，从而完成接口层与核心层的交互。

RtcMethod定义：

struct RtcMethod { int32_t (*ReadTime)(struct RtcHost *host, struct RtcTime *time); int32_t (*WriteTime)(struct RtcHost *host, const struct RtcTime *time); int32_t (*ReadAlarm)(struct RtcHost *host, enum RtcAlarmIndex alarmIndex, struct RtcTime *time); int32_t (*WriteAlarm)(struct RtcHost *host, enum RtcAlarmIndex alarmIndex, const struct RtcTime *time); int32_t (*RegisterAlarmCallback)(struct RtcHost *host, enum RtcAlarmIndex alarmIndex, RtcAlarmCallback cb); int32_t (*AlarmInterruptEnable)(struct RtcHost *host, enum RtcAlarmIndex alarmIndex, uint8_t enable); int32_t (*GetFreq)(struct RtcHost *host, uint32_t *freq); int32_t (*SetFreq)(struct RtcHost *host, uint32_t freq); int32_t (*Reset)(struct RtcHost *host); int32_t (*ReadReg)(struct RtcHost *host, uint8_t usrDefIndex, uint8_t *value); int32_t (*WriteReg)(struct RtcHost *host, uint8_t usrDefIndex, uint8_t value);};

RtcMethod结构体成员的钩子函数功能说明：

2.2.2、RTC驱动开发步骤

RTC模块适配HDF框架包含以下四个步骤：

实例化驱动入口。

配置属性文件。

实例化RTC控制器对象。

驱动调试。

我们以//drivers/hdf_core/adapter/khdf/linux/platform/rtc/rtc_adapter.c为例（该rtc驱动是建立于Linux rtc子系统基础上创建）。

2.2.2.1、驱动实例化驱动入口

驱动入口必须为HdfDriverEntry（在hdf_device_desc.h中定义）类型的全局变量，且moduleName要和device_info.hcs中保持一致。

HDF框架会将所有加载的驱动的HdfDriverEntry对象首地址汇总，形成一个类似数组的段地址空间，方便上层调用。

一般在加载驱动时HDF会先调用Bind函数，再调用Init函数加载该驱动。当Init调用异常时，HDF框架会调用Release释放驱动资源并退出。

rtc驱动入口参考：

struct HdfDriverEntry g_rtcDriverEntry = { .moduleVersion = 1, .Bind = HiRtcBind, .Init = HiRtcInit, .Release = HiRtcRelease, .moduleName = "HDF_PLATFORM_RTC", //【必要且与HCS文件中里面的moduleName匹配】};/* 调用HDF_INIT将驱动入口注册到HDF框架中 */HDF_INIT(g_rtcDriverEntry);

2.2.2.2、配置属性文件

deviceNode信息与驱动入口注册相关，器件属性值与核心层RTCCntlr成员的默认值或限制范围有密切关系。

本例只有一个RTC控制器，如有多个器件信息，则需要在device_info.hcs文件增加deviceNode信息。

本次案例以rk3568为案例（即文件//vendor/lockzhiner/rk3568/hdf_config/khdf/device_info/device_info.hcs），添加deviceNode描述，具体修改如下：

device_rtc :: device { device0 :: deviceNode { policy = 2; // 驱动服务发布的策略，policy大于等于1（用户态可见为2，仅内核态可见为1） priority = 30; // 驱动启动优先级 permission = 0644; // 驱动创建设备节点权限 moduleName = "HDF_PLATFORM_RTC"; // 驱动名称，该字段的值必须和驱动入口结构的moduleName值一致 serviceName = "HDF_PLATFORM_RTC"; // 驱动对外发布服务的名称，必须唯一 deviceMatchAttr = ""; // 驱动私有数据匹配的关键字，必须和驱动私有数据配置表中的match_attr值一致 }}

2.2.2.3、实例化RTC控制器对象

完成属性文件配置之后，下一步就是以核心层RtcHost对象的初始化为核心，包括驱动适配者自定义结构体（传递参数和数据），实例化RtcHost成员RtcMethod（让用户可以通过接口来调用驱动底层函数），实现HdfDriverEntry成员函数（Bind、Init、Release）。

RtcHost成员钩子函数结构体RtcMethod的实例化，其他成员在Init函数中初始化。

static int32_t HiRtcReadTime(struct RtcHost *host, struct RtcTime *hdfTime);static int32_t HiRtcWriteTime(struct RtcHost *host, const struct RtcTime *hdfTime);static int32_t HiReadAlarm(struct RtcHost *host, enum RtcAlarmIndex alarmIndex, struct RtcTime *hdfTime);static int32_t HiWriteAlarm(struct RtcHost *host, enum RtcAlarmIndex alarmIndex, const struct RtcTime *hdfTime);static int32_t HiAlarmInterruptEnable(struct RtcHost *host, enum RtcAlarmIndex alarmIndex, uint8_t enable);// 定义RtcMethod结构体变量g_method，负责RTC相关接口static struct RtcMethod g_method = { .ReadTime = HiRtcReadTime, .WriteTime = HiRtcWriteTime, .ReadAlarm = HiReadAlarm, .WriteAlarm = HiWriteAlarm, .RegisterAlarmCallback = NULL, .AlarmInterruptEnable = HiAlarmInterruptEnable, .GetFreq = NULL, .SetFreq = NULL, .Reset = NULL, .ReadReg = NULL, .WriteReg = NULL,};

static int32_t HiRtcBind(struct HdfDeviceObject *device);static int32_t HiRtcInit(struct HdfDeviceObject *device);static void HiRtcRelease(struct HdfDeviceObject *device);struct HdfDriverEntry g_rtcDriverEntry = { .moduleVersion = 1, .Bind = HiRtcBind, .Init = HiRtcInit, .Release = HiRtcRelease, .moduleName = "HDF_PLATFORM_RTC", //【必要且与HCS文件中里面的moduleName匹配】};/* 调用HDF_INIT将驱动入口注册到HDF框架中 */HDF_INIT(g_rtcDriverEntry);

2.2.2.4、驱动调试

建议先在Linux下修改确认，再移植到OpenHarmony。

2.3、RTC应用开发

RTC主要用于提供实时时间和定时报警功能。

2.3.1、接口说明

RTC模块提供的主要接口如表1所示，具体API详见//drivers/hdf_core/framework/include/platform/rtc_if.h。

RTC驱动API接口功能介绍如下所示：

（1）RtcOpen

RTC驱动加载成功后，使用驱动框架提供的查询接口并调用RTC设备驱动接口。

DevHandle RtcOpen(void);

RtcOpen参数定义如下：

RtcOpen返回值定义如下：

假设系统中的RTC设备总线号为0，片选号为0，获取该RTC设备句柄的示例如下：

DevHandle handle = NULL;

/* 获取RTC句柄 */handle = RtcOpen();if (handle == NULL) { /* 错误处理 */}

（2）RtcClose

销毁RTC设备句柄，系统释放对应的资源。

void RtcClose(DevHandle handle);

RtcClose返回值定义如下：

（3）RtcReadTime

系统从RTC读取时间信息，包括年、月、星期、日、时、分、秒、毫秒。

int32_t RtcReadTime(DevHandle handle, struct RtcTime *time);

RtcReadTime参数定义如下：

RtcReadTime返回值定义如下：

（4）RtcWriteTime

设置RTC时间。

int32_t RtcWriteTime(DevHandle handle, struct RtcTime *time);

RtcWriteTime参数定义如下：

RtcWriteTime返回值定义如下：

（5）RtcReadAlarm

从rtc模块中读取定时报警时间。

int32_t RtcReadAlarm(DevHandle handle, enum RtcAlarmIndex alarmIndex, struct RtcTime *time);

RtcReadAlarm参数定义如下：

RtcReadAlarm返回值定义如下：

（6）RtcWriteAlarm

根据报警索引设置RTC报警时间。

int32_t RtcWriteAlarm(DevHandle handle, enum RtcAlarmIndex alarmIndex, struct RtcTime \*time);

RtcWriteAlarm参数定义如下：

RtcWriteAlarm返回值定义如下：

（7）RtcRegisterAlarmCallback

系统启动后需要注册RTC定时报警回调函数，报警超时后触发回调函数。

int32_t RtcRegisterAlarmCallback(DevHandle handle, enum RtcAlarmIndex alarmIndex, RtcAlarmCallback cb);

RtcRegisterAlarmCallback参数定义如下：

RtcRegisterAlarmCallback返回值定义如下：

（8）RtcAlarmInterruptEnable

在启动报警操作前，需要先设置报警中断使能，报警超时后会触发告警回调函数。

int32_t RtcAlarmInterruptEnable(DevHandle handle, enum RtcAlarmIndex alarmIndex, uint8_t enable);

RtcAlarmInterruptEnable参数定义如下：

RtcAlarmInterruptEnable返回值定义如下：

2.2.2、开发流程

使用rtc的一般流程如下图所示：

3、程序解析

3.1、准备工作

无

3.2、Linux内核解析

3.2.1、创建Linux内核Git

请参考《OpenHarmony如何为内核打patch》（即Git仓库的//docs/OpenHarmony如何为内核打patch.docx）。

3.2.2、修改设备树PWM7配置

修改//arch/arm64/boot/dts/rockchip/rk3568-lockzhiner-x0.dtsi（即该目录是指已打Patch后的Linux内核，不是OpenHarmony主目录），具体如下所示：

&i2c5 {status = "okay";......
hym8563: hym8563@51 {compatible = "haoyu,hym8563";reg = <0x51>;pinctrl-names = "default";pinctrl-0 = <&rtc_int>;

interrupt-parent = <&gpio0>;interrupts = ;};}

设备树中默认是开启rtc模块的hym8563，读者不用修改。

3.2.3、创建内核patch

请参考《OpenHarmony如何为内核打patch》（即Git仓库的//docs/OpenHarmony如何为内核打patch.docx）。

3.2.4、替换OpenHarmony的内核patch

将制作出的kernel.patch替换到//kernel/linux/patches/linux-5.10/rk3568_patch/kernel.patch即可。

3.2.5、开启内核配置

修改///kernel/linux/config/linux-5.10/arch/arm64/configs/rk3568_standard_defconfig（即该目录是指OpenHarmony主目录），将CONFIG_DRIVERS_HDF_PLATFORM_RTC功能开启，具体如下所示：

CONFIG_DRIVERS_HDF_PLATFORM_RTC=y

另外，Linux配置文件中需要定义rtc设备名称定义，具体如下所示：

CONFIG_RTC_SYSTOHC_DEVICE="rtc0"

3.3、OpenHarmony配置树配置

3.3.1、device_info.hcs

//vendor/lockzhiner/rk3568/hdf_config/khdf/device_info/device_info.hcs已定义好，具体如下：

device_rtc :: device { device0 :: deviceNode { policy = 2; priority = 30; permission = 0644; moduleName = "HDF_PLATFORM_RTC"; serviceName = "HDF_PLATFORM_RTC"; deviceMatchAttr = ""; }}

注意：

device0是rtc模块，一般只需要1个rtc设备即可。

policy必须为2，表示对内核态和用户态提供服务。否则，应用程序无法调用。

3.4、OpenHarmony RTC平台驱动

在//drivers/hdf_core/adapter/khdf/linux/platform/rtc/rtc_adapter.c已编写对接Linux RTC驱动的相关代码，具体内容如下：

static inline void HdfTimeToLinuxTime(const struct RtcTime *hdfTime, struct rtc_time *linuxTime){ linuxTime->tm_sec = hdfTime->second; linuxTime->tm_min = hdfTime->minute; linuxTime->tm_hour = hdfTime->hour; linuxTime->tm_mday = hdfTime->day; linuxTime->tm_mon = hdfTime->month - MONTH_DIFF; linuxTime->tm_year = hdfTime->year - YEAR_BASE; linuxTime->tm_wday = hdfTime->weekday; linuxTime->tm_yday = rtc_year_days(linuxTime->tm_mday, linuxTime->tm_mon, linuxTime->tm_year);}

static inline void LinuxTimeToHdfTime(struct RtcTime *hdfTime, const struct rtc_time *linuxTime){ hdfTime->second = linuxTime->tm_sec; hdfTime->minute = linuxTime->tm_min; hdfTime->hour = linuxTime->tm_hour; hdfTime->day = linuxTime->tm_mday; hdfTime->month = linuxTime->tm_mon + MONTH_DIFF; hdfTime->year = linuxTime->tm_year + YEAR_BASE; hdfTime->weekday = linuxTime->tm_wday;}

// 获取Linux环境下的rtc设备接口static inline struct rtc_device *HdfGetRtcDevice(void){ // 获取Linux环境下的rtc设备接口 struct rtc_device *dev = rtc_class_open(CONFIG_RTC_SYSTOHC_DEVICE); if (dev == NULL) { HDF_LOGE("%s: failed to get rtc device", __func__); } return dev;}

// 释放Linux环境下的rtc设备接口static inline void HdfPutRtcDevice(struct rtc_device *dev){ rtc_class_close(dev);}

static int32_t HiRtcReadTime(struct RtcHost *host, struct RtcTime *hdfTime){ int32_t ret; struct rtc_time linuxTime = {0}; struct rtc_device *dev = HdfGetRtcDevice(); // 获取Linux环境下的rtc设备接口

(void)host; if (dev == NULL) { return HDF_FAILURE; } ret = rtc_read_time(dev, &linuxTime); // 直接对Linux环境下的rtc设备接口进行读操作 if (ret < 0) { HDF_LOGE("%s: rtc_read_time error, ret is %d", __func__, ret); return ret; } HdfPutRtcDevice(dev); LinuxTimeToHdfTime(hdfTime, &linuxTime); return HDF_SUCCESS;}

该部分代码不细述，感兴趣的读者可以去详读。

3.5、应用程序

3.5.1、rtc_test.c

rtc相关头文件如下所示：

#include "rtc_if.h" // rtc标准接口头文件

主函数定义RTC接口调用，具体如下：

int main(int argc, char* argv[]){ int32_t ret = 0; DevHandle handle = NULL; struct RtcTime curTime; struct RtcTime alarmTime;

// 获取RTC设备句柄 handle = RtcOpen(); if (handle == NULL) { PRINT_ERROR("RtcOpen failed\n"); return -1; }

// 读取RTC实时时间 ret = RtcReadTime(handle, &curTime); if (ret != 0) { PRINT_ERROR("RtcReadTime failed and ret = %d\n", ret); goto out; } printf("RtcReadTime successful\n"); printf(" year = %d\n", curTime.year); printf(" month = %d\n", curTime.month); printf(" day = %d\n", curTime.day); printf(" hour = %d\n", curTime.hour); printf(" minute = %d\n", curTime.minute); printf(" second = %d\n", curTime.second); printf(" millisecond = %d\n", curTime.millisecond); // 设置RTC时间 curTime.year = 2023; curTime.month = 8; curTime.day = 28; curTime.hour = 17; curTime.minute = 45; curTime.second = 0; curTime.millisecond = 0; // 写RTC时间信息 ret = RtcWriteTime(handle, &curTime); if (ret != 0) { PRINT_ERROR("RtcWriteTime failed and ret = %d\n", ret); goto out; } printf("RtcWriteTime successful\n"); printf(" year = %d\n", curTime.year); printf(" month = %d\n", curTime.month); printf(" day = %d\n", curTime.day); printf(" hour = %d\n", curTime.hour); printf(" minute = %d\n", curTime.minute); printf(" second = %d\n", curTime.second); printf(" millisecond = %d\n", curTime.millisecond);

// 该部分代码，驱动尚未完成#if 0 // 注册报警A的定时回调函数 ret = RtcRegisterAlarmCallback(handle, RTC_ALARM_INDEX_A, RtcAlarmCallback_DefaultFunc); if (ret != 0) { PRINT_ERROR("RtcRegisterAlarmCallback failed and ret = %d\n", ret); goto out; }

// 设置RTC报警时间 alarmTime.year = curTime.year; alarmTime.month = curTime.month; alarmTime.day = curTime.day; alarmTime.hour = curTime.hour; alarmTime.minute = curTime.minute; alarmTime.second = curTime.second + SLEEP_SEC; alarmTime.millisecond = curTime.millisecond; // 设置RTC_ALARM_INDEX_A索引定时器报警 ret = RtcWriteAlarm(handle, RTC_ALARM_INDEX_A, &alarmTime); if (ret != 0) { PRINT_ERROR("RtcWriteAlarm failed and ret = %d\n", ret); goto out; }

// 设置RTC报警中断使能 ret = RtcAlarmInterruptEnable(handle, RTC_ALARM_INDEX_A, 1); if (ret != 0) { PRINT_ERROR("RtcAlarmInterruptEnable failed and ret = %d\n", ret); goto out; }

sleep(SLEEP_SEC + 5);#endif

out: RtcClose(handle); return ret;}

注意：由于目前rtc平台驱动没有定义rtc定时器响应函数接口，故rtc定时回调功能暂时关闭

3.5.2、BUILD.gn

编写应用程序的BUILD.gn，具体内容如下：

import("//build/ohos.gni")import("//drivers/hdf_core/adapter/uhdf2/uhdf.gni")

print("samples: compile rk3568_rtc_test")ohos_executable("rk3568_rtc_test") { sources = [ "rtc_test.c" ] include_dirs = [ "$hdf_framework_path/include", "$hdf_framework_path/include/core", "$hdf_framework_path/include/osal", "$hdf_framework_path/include/platform", "$hdf_framework_path/include/utils", "$hdf_uhdf_path/osal/include", "$hdf_uhdf_path/ipc/include", "//base/hiviewdfx/hilog/interfaces/native/kits/include", "//third_party/bounds_checking_function/include", ]

deps = [ "$hdf_uhdf_path/platform:libhdf_platform", "$hdf_uhdf_path/utils:libhdf_utils", "//base/hiviewdfx/hilog/interfaces/native/innerkits:libhilog", ]

cflags = [ "-Wall", "-Wextra", "-Werror", "-Wno-format", "-Wno-format-extra-args", ]

part_name = "product_rk3568" install_enable = true}

3.5.3、参与应用程序编译

编辑//vendor/lockzhiner/rk3568/samples/BUILD.gn，开启编译选项。具体如下：

"b09_platform_device_rtc/app:rk3568_rtc_test",

4、程序编译

建议使用docker编译方法，运行如下：

hb set -root .hb set# 选择lockzhiner下的rk3568编译分支。hb build -f

5、运行结果

运行如下：

# rk3568_rtc_testRtcReadTime successful year = 2017 month = 8 day = 5 hour = 10 minute = 58 second = 9 millisecond = 0RtcWriteTime successful year = 2023 month = 8 day = 28 hour = 17 minute = 45 second = 0 millisecond = 0#

开发板重启，可以发现系统相关时间已经变更为我们案例中的配置。