OpenHarmony：全流程講解如何編寫RTC平臺(tái)驅(qū)動(dòng)以及應(yīng)用程序

1、程序介紹

本程序是基于OpenHarmony標(biāo)準(zhǔn)系統(tǒng)編寫的平臺(tái)驅(qū)動(dòng)案例：RTC

2、基礎(chǔ)知識(shí)

2.1、RTC簡介

RTC（real-time clock）為操作系統(tǒng)中的實(shí)時(shí)時(shí)鐘設(shè)備，為操作系統(tǒng)提供精準(zhǔn)的實(shí)時(shí)時(shí)間和定時(shí)報(bào)警功能。當(dāng)設(shè)備下電后，通過外置電池供電，RTC繼續(xù)記錄操作系統(tǒng)時(shí)間；設(shè)備上電后，RTC提供實(shí)時(shí)時(shí)鐘給操作系統(tǒng)，確保斷電后系統(tǒng)時(shí)間的連續(xù)性。

2.2、RTC驅(qū)動(dòng)開發(fā)

在HDF框架中，RTC的接口適配模式采用獨(dú)立服務(wù)模式，在這種模式下，每一個(gè)設(shè)備對象會(huì)獨(dú)立發(fā)布一個(gè)設(shè)備服務(wù)來處理外部訪問，設(shè)備管理器收到API的訪問請求之后，通過提取該請求的參數(shù)，達(dá)到調(diào)用實(shí)際設(shè)備對象的相應(yīng)內(nèi)部方法的目的。獨(dú)立服務(wù)模式可以直接借助HDFDeviceManager的服務(wù)管理能力，但需要為每個(gè)設(shè)備單獨(dú)配置設(shè)備節(jié)點(diǎn)，增加內(nèi)存占用。

獨(dú)立服務(wù)模式下，核心層不會(huì)統(tǒng)一發(fā)布一個(gè)服務(wù)供上層使用，因此這種模式下驅(qū)動(dòng)要為每個(gè)控制器發(fā)布一個(gè)服務(wù)，具體表現(xiàn)為：

驅(qū)動(dòng)適配者需要實(shí)現(xiàn)HdfDriverEntry的Bind鉤子函數(shù)以綁定服務(wù)。

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

2.2.1、RTC驅(qū)動(dòng)開發(fā)接口

為了保證上層在調(diào)用RTC接口時(shí)能夠正確的操作硬件，核心層在//drivers/hdf_core/framework/support/platform/include/rtc/rtc_core.h中定義了以下鉤子函數(shù)。驅(qū)動(dòng)適配者需要在適配層實(shí)現(xiàn)這些函數(shù)的具體功能，并與這些鉤子函數(shù)掛接，從而完成接口層與核心層的交互。

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結(jié)構(gòu)體成員的鉤子函數(shù)功能說明：

2.2.2、RTC驅(qū)動(dòng)開發(fā)步驟

RTC模塊適配HDF框架包含以下四個(gè)步驟：

實(shí)例化驅(qū)動(dòng)入口。

配置屬性文件。

實(shí)例化RTC控制器對象。

驅(qū)動(dòng)調(diào)試。

我們以//drivers/hdf_core/adapter/khdf/linux/platform/rtc/rtc_adapter.c為例（該rtc驅(qū)動(dòng)是建立于Linux rtc子系統(tǒng)基礎(chǔ)上創(chuàng)建）。

2.2.2.1、驅(qū)動(dòng)實(shí)例化驅(qū)動(dòng)入口

驅(qū)動(dòng)入口必須為HdfDriverEntry（在hdf_device_desc.h中定義）類型的全局變量，且moduleName要和device_info.hcs中保持一致。

HDF框架會(huì)將所有加載的驅(qū)動(dòng)的HdfDriverEntry對象首地址匯總，形成一個(gè)類似數(shù)組的段地址空間，方便上層調(diào)用。

一般在加載驅(qū)動(dòng)時(shí)HDF會(huì)先調(diào)用Bind函數(shù)，再調(diào)用Init函數(shù)加載該驅(qū)動(dòng)。當(dāng)Init調(diào)用異常時(shí)，HDF框架會(huì)調(diào)用Release釋放驅(qū)動(dòng)資源并退出。

rtc驅(qū)動(dòng)入口參考：

struct HdfDriverEntry g_rtcDriverEntry = { .moduleVersion = 1, .Bind = HiRtcBind, .Init = HiRtcInit, .Release = HiRtcRelease, .moduleName = "HDF_PLATFORM_RTC", //【必要且與HCS文件中里面的moduleName匹配】};/* 調(diào)用HDF_INIT將驅(qū)動(dòng)入口注冊到HDF框架中 */HDF_INIT(g_rtcDriverEntry);

2.2.2.2、配置屬性文件

deviceNode信息與驅(qū)動(dòng)入口注冊相關(guān)，器件屬性值與核心層RTCCntlr成員的默認(rèn)值或限制范圍有密切關(guān)系。

本例只有一個(gè)RTC控制器，如有多個(gè)器件信息，則需要在device_info.hcs文件增加deviceNode信息。

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

device_rtc :: device { device0 :: deviceNode { policy = 2; // 驅(qū)動(dòng)服務(wù)發(fā)布的策略，policy大于等于1（用戶態(tài)可見為2，僅內(nèi)核態(tài)可見為1） priority = 30; // 驅(qū)動(dòng)啟動(dòng)優(yōu)先級 permission = 0644; // 驅(qū)動(dòng)創(chuàng)建設(shè)備節(jié)點(diǎn)權(quán)限 moduleName = "HDF_PLATFORM_RTC"; // 驅(qū)動(dòng)名稱，該字段的值必須和驅(qū)動(dòng)入口結(jié)構(gòu)的moduleName值一致 serviceName = "HDF_PLATFORM_RTC"; // 驅(qū)動(dòng)對外發(fā)布服務(wù)的名稱，必須唯一 deviceMatchAttr = ""; // 驅(qū)動(dòng)私有數(shù)據(jù)匹配的關(guān)鍵字，必須和驅(qū)動(dòng)私有數(shù)據(jù)配置表中的match_attr值一致 }}

2.2.2.3、實(shí)例化RTC控制器對象

完成屬性文件配置之后，下一步就是以核心層RtcHost對象的初始化為核心，包括驅(qū)動(dòng)適配者自定義結(jié)構(gòu)體（傳遞參數(shù)和數(shù)據(jù)），實(shí)例化RtcHost成員RtcMethod（讓用戶可以通過接口來調(diào)用驅(qū)動(dòng)底層函數(shù)），實(shí)現(xiàn)HdfDriverEntry成員函數(shù)（Bind、Init、Release）。

RtcHost成員鉤子函數(shù)結(jié)構(gòu)體RtcMethod的實(shí)例化，其他成員在Init函數(shù)中初始化。

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結(jié)構(gòu)體變量g_method，負(fù)責(zé)RTC相關(guān)接口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匹配】};/* 調(diào)用HDF_INIT將驅(qū)動(dòng)入口注冊到HDF框架中 */HDF_INIT(g_rtcDriverEntry);

2.2.2.4、驅(qū)動(dòng)調(diào)試

建議先在Linux下修改確認(rèn)，再移植到OpenHarmony。

2.3、RTC應(yīng)用開發(fā)

RTC主要用于提供實(shí)時(shí)時(shí)間和定時(shí)報(bào)警功能。

2.3.1、接口說明

RTC模塊提供的主要接口如表1所示，具體API詳見//drivers/hdf_core/framework/include/platform/rtc_if.h。

RTC驅(qū)動(dòng)API接口功能介紹如下所示：

（1）RtcOpen

RTC驅(qū)動(dòng)加載成功后，使用驅(qū)動(dòng)框架提供的查詢接口并調(diào)用RTC設(shè)備驅(qū)動(dòng)接口。

DevHandle RtcOpen(void);

RtcOpen參數(shù)定義如下：

RtcOpen返回值定義如下：

假設(shè)系統(tǒng)中的RTC設(shè)備總線號(hào)為0，片選號(hào)為0，獲取該RTC設(shè)備句柄的示例如下：

DevHandle handle = NULL;

/* 獲取RTC句柄 */handle = RtcOpen();if (handle == NULL) { /* 錯(cuò)誤處理 */}

（2）RtcClose

銷毀RTC設(shè)備句柄，系統(tǒng)釋放對應(yīng)的資源。

void RtcClose(DevHandle handle);

RtcClose返回值定義如下：

（3）RtcReadTime

系統(tǒng)從RTC讀取時(shí)間信息，包括年、月、星期、日、時(shí)、分、秒、毫秒。

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

RtcReadTime參數(shù)定義如下：

RtcReadTime返回值定義如下：

（4）RtcWriteTime

設(shè)置RTC時(shí)間。

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

RtcWriteTime參數(shù)定義如下：

RtcWriteTime返回值定義如下：

（5）RtcReadAlarm

從rtc模塊中讀取定時(shí)報(bào)警時(shí)間。

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

RtcReadAlarm參數(shù)定義如下：

RtcReadAlarm返回值定義如下：

（6）RtcWriteAlarm

根據(jù)報(bào)警索引設(shè)置RTC報(bào)警時(shí)間。

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

RtcWriteAlarm參數(shù)定義如下：

RtcWriteAlarm返回值定義如下：

（7）RtcRegisterAlarmCallback

系統(tǒng)啟動(dòng)后需要注冊RTC定時(shí)報(bào)警回調(diào)函數(shù)，報(bào)警超時(shí)后觸發(fā)回調(diào)函數(shù)。

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

RtcRegisterAlarmCallback參數(shù)定義如下：

RtcRegisterAlarmCallback返回值定義如下：

（8）RtcAlarmInterruptEnable

在啟動(dòng)報(bào)警操作前，需要先設(shè)置報(bào)警中斷使能，報(bào)警超時(shí)后會(huì)觸發(fā)告警回調(diào)函數(shù)。

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

RtcAlarmInterruptEnable參數(shù)定義如下：

RtcAlarmInterruptEnable返回值定義如下：

2.2.2、開發(fā)流程

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

3、程序解析

3.1、準(zhǔn)備工作

無

3.2、Linux內(nèi)核解析

3.2.1、創(chuàng)建Linux內(nèi)核Git

請參考《OpenHarmony如何為內(nèi)核打patch》（即Git倉庫的//docs/OpenHarmony如何為內(nèi)核打patch.docx）。

3.2.2、修改設(shè)備樹PWM7配置

修改//arch/arm64/boot/dts/rockchip/rk3568-lockzhiner-x0.dtsi（即該目錄是指已打Patch后的Linux內(nèi)核，不是OpenHarmony主目錄），具體如下所示：

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

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

設(shè)備樹中默認(rèn)是開啟rtc模塊的hym8563，讀者不用修改。

3.2.3、創(chuàng)建內(nèi)核patch

請參考《OpenHarmony如何為內(nèi)核打patch》（即Git倉庫的//docs/OpenHarmony如何為內(nèi)核打patch.docx）。

3.2.4、替換OpenHarmony的內(nèi)核patch

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

3.2.5、開啟內(nèi)核配置

修改///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設(shè)備名稱定義，具體如下所示：

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個(gè)rtc設(shè)備即可。

policy必須為2，表示對內(nèi)核態(tài)和用戶態(tài)提供服務(wù)。否則，應(yīng)用程序無法調(diào)用。

3.4、OpenHarmony RTC平臺(tái)驅(qū)動(dòng)

在//drivers/hdf_core/adapter/khdf/linux/platform/rtc/rtc_adapter.c已編寫對接Linux RTC驅(qū)動(dòng)的相關(guān)代碼，具體內(nèi)容如下：

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環(huán)境下的rtc設(shè)備接口static inline struct rtc_device *HdfGetRtcDevice(void){ // 獲取Linux環(huán)境下的rtc設(shè)備接口 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環(huán)境下的rtc設(shè)備接口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環(huán)境下的rtc設(shè)備接口

(void)host; if (dev == NULL) { return HDF_FAILURE; } ret = rtc_read_time(dev, &linuxTime); // 直接對Linux環(huán)境下的rtc設(shè)備接口進(jìn)行讀操作 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;}

該部分代碼不細(xì)述，感興趣的讀者可以去詳讀。

3.5、應(yīng)用程序

3.5.1、rtc_test.c

rtc相關(guān)頭文件如下所示：

#include "rtc_if.h" // rtc標(biāo)準(zhǔn)接口頭文件

主函數(shù)定義RTC接口調(diào)用，具體如下：

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

// 獲取RTC設(shè)備句柄 handle = RtcOpen(); if (handle == NULL) { PRINT_ERROR("RtcOpen failed\n"); return -1; }

// 讀取RTC實(shí)時(shí)時(shí)間 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); // 設(shè)置RTC時(shí)間 curTime.year = 2023; curTime.month = 8; curTime.day = 28; curTime.hour = 17; curTime.minute = 45; curTime.second = 0; curTime.millisecond = 0; // 寫RTC時(shí)間信息 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);

// 該部分代碼，驅(qū)動(dòng)尚未完成#if 0 // 注冊報(bào)警A的定時(shí)回調(diào)函數(shù) ret = RtcRegisterAlarmCallback(handle, RTC_ALARM_INDEX_A, RtcAlarmCallback_DefaultFunc); if (ret != 0) { PRINT_ERROR("RtcRegisterAlarmCallback failed and ret = %d\n", ret); goto out; }

// 設(shè)置RTC報(bào)警時(shí)間 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; // 設(shè)置RTC_ALARM_INDEX_A索引定時(shí)器報(bào)警 ret = RtcWriteAlarm(handle, RTC_ALARM_INDEX_A, &alarmTime); if (ret != 0) { PRINT_ERROR("RtcWriteAlarm failed and ret = %d\n", ret); goto out; }

// 設(shè)置RTC報(bào)警中斷使能 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平臺(tái)驅(qū)動(dòng)沒有定義rtc定時(shí)器響應(yīng)函數(shù)接口，故rtc定時(shí)回調(diào)功能暫時(shí)關(guān)閉

3.5.2、BUILD.gn

編寫應(yīng)用程序的BUILD.gn，具體內(nèi)容如下：

import("http://build/ohos.gni")import("http://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", "http://base/hiviewdfx/hilog/interfaces/native/kits/include", "http://third_party/bounds_checking_function/include", ]

deps = [ "$hdf_uhdf_path/platform:libhdf_platform", "$hdf_uhdf_path/utils:libhdf_utils", "http://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、參與應(yīng)用程序編譯

編輯//vendor/lockzhiner/rk3568/samples/BUILD.gn，開啟編譯選項(xiàng)。具體如下：

"b09_platform_device_rtc/app:rk3568_rtc_test",

4、程序編譯

建議使用docker編譯方法，運(yùn)行如下：

hb set -root .hb set# 選擇lockzhiner下的rk3568編譯分支。hb build -f

5、運(yùn)行結(jié)果

運(yùn)行如下：

# 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#

開發(fā)板重啟，可以發(fā)現(xiàn)系統(tǒng)相關(guān)時(shí)間已經(jīng)變更為我們案例中的配置。