OpenHarmony:全流程講解如何編寫RTC平臺驅動以及應用程序
一、程序介紹
本程序是基于OpenHarmony標準系統(tǒng)編寫的平臺驅動案例:RTC目前已在凌蒙派-RK3568開發(fā)板跑通。詳細資料請參考官網(wǎng):https://gitee.com/Lockzhiner-Electronics/lockzhiner-rk3568-openharmony/tree/master/samples/b09_platform_device_rtc詳細資料請參考官網(wǎng):
- RTC平臺驅動開發(fā)
- RTC應用程序開發(fā)
二、基礎知識
1、RTC簡介
RTC(real-time clock)為操作系統(tǒng)中的實時時鐘設備,為操作系統(tǒng)提供精準的實時時間和定時報警功能。當設備下電后,通過外置電池供電,RTC繼續(xù)記錄操作系統(tǒng)時間;設備上電后,RTC提供實時時鐘給操作系統(tǒng),確保斷電后系統(tǒng)時間的連續(xù)性。
2、RTC驅動開發(fā)
在HDF框架中,RTC的接口適配模式采用獨立服務模式,在這種模式下,每一個設備對象會獨立發(fā)布一個設備服務來處理外部訪問,設備管理器收到API的訪問請求之后,通過提取該請求的參數(shù),達到調(diào)用實際設備對象的相應內(nèi)部方法的目的。獨立服務模式可以直接借助HDFDeviceManager的服務管理能力,但需要為每個設備單獨配置設備節(jié)點,增加內(nèi)存占用。
獨立服務模式下,核心層不會統(tǒng)一發(fā)布一個服務供上層使用,因此這種模式下驅動要為每個控制器發(fā)布一個服務,具體表現(xiàn)為:
- 驅動適配者需要實現(xiàn)HdfDriverEntry的Bind鉤子函數(shù)以綁定服務。
- device_info.hcs文件中deviceNode的policy字段為1或2,不能為0。
(1)RTC驅動開發(fā)接口
為了保證上層在調(diào)用RTC接口時能夠正確的操作硬件,核心層在//drivers/hdf_core/framework/support/platform/include/rtc/rtc_core.h中定義了以下鉤子函數(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結構體成員的鉤子函數(shù)功能說明:
(2)RTC驅動開發(fā)步驟
RTC模塊適配HDF框架包含以下四個步驟:
- 實例化驅動入口。
- 配置屬性文件。
- 實例化RTC控制器對象。
- 驅動調(diào)試。
我們以//drivers/hdf_core/adapter/khdf/linux/platform/rtc/rtc_adapter.c為例(該rtc驅動是建立于Linux rtc子系統(tǒng)基礎上創(chuàng)建)。
驅動實例化驅動入口
驅動入口必須為HdfDriverEntry(在hdf_device_desc.h中定義)類型的全局變量,且moduleName要和device_info.hcs中保持一致。
HDF框架會將所有加載的驅動的HdfDriverEntry對象首地址匯總,形成一個類似數(shù)組的段地址空間,方便上層調(diào)用。
一般在加載驅動時HDF會先調(diào)用Bind函數(shù),再調(diào)用Init函數(shù)加載該驅動。當Init調(diào)用異常時,HDF框架會調(diào)用Release釋放驅動資源并退出。
rtc驅動入口參考:
struct HdfDriverEntry g_rtcDriverEntry = {
.moduleVersion = 1,
.Bind = HiRtcBind,
.Init = HiRtcInit,
.Release = HiRtcRelease,
.moduleName = "HDF_PLATFORM_RTC", //【必要且與HCS文件中里面的moduleName匹配】
};
/* 調(diào)用HDF_INIT將驅動入口注冊到HDF框架中 */
HDF_INIT(g_rtcDriverEntry);
配置屬性文件
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; // 驅動服務發(fā)布的策略,policy大于等于1(用戶態(tài)可見為2,僅內(nèi)核態(tài)可見為1)
priority = 30; // 驅動啟動優(yōu)先級
permission = 0644; // 驅動創(chuàng)建設備節(jié)點權限
moduleName = "HDF_PLATFORM_RTC"; // 驅動名稱,該字段的值必須和驅動入口結構的moduleName值一致
serviceName = "HDF_PLATFORM_RTC"; // 驅動對外發(fā)布服務的名稱,必須唯一
deviceMatchAttr = ""; // 驅動私有數(shù)據(jù)匹配的關鍵字,必須和驅動私有數(shù)據(jù)配置表中的match_attr值一致
}
}
實例化RTC控制器對象
完成屬性文件配置之后,下一步就是以核心層RtcHost對象的初始化為核心,包括驅動適配者自定義結構體(傳遞參數(shù)和數(shù)據(jù)),實例化RtcHost成員RtcMethod(讓用戶可以通過接口來調(diào)用驅動底層函數(shù)),實現(xiàn)HdfDriverEntry成員函數(shù)(Bind、Init、Release)。
RtcHost成員鉤子函數(shù)結構體RtcMethod的實例化,其他成員在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結構體變量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匹配】
};
/* 調(diào)用HDF_INIT將驅動入口注冊到HDF框架中 */
HDF_INIT(g_rtcDriverEntry);
驅動調(diào)試
建議先在Linux下修改確認,再移植到OpenHarmony。
3、RTC應用開發(fā)
RTC主要用于提供實時時間和定時報警功能。
(1)接口說明
RTC模塊提供的主要接口如表1所示,具體API詳見//drivers/hdf_core/framework/include/platform/rtc_if.h。
RTC驅動API接口功能介紹如下所示:
RtcOpen
RTC驅動加載成功后,使用驅動框架提供的查詢接口并調(diào)用RTC設備驅動接口。
DevHandle RtcOpen(void);
RtcOpen參數(shù)定義如下:
RtcOpen返回值定義如下:
假設系統(tǒng)中的RTC設備總線號為0,片選號為0,獲取該RTC設備句柄的示例如下:
DevHandle handle = NULL;
/* 獲取RTC句柄 */
handle = RtcOpen();
if (handle == NULL) {
/* 錯誤處理 */
}
RtcClose
void RtcClose(DevHandle handle);
RtcClose返回值定義如下:
RtcReadTime
系統(tǒng)從RTC讀取時間信息,包括年、月、星期、日、時、分、秒、毫秒。
int32_t RtcReadTime(DevHandle handle, struct RtcTime *time);
RtcReadTime參數(shù)定義如下:
RtcReadTime返回值定義如下:
RtcWriteTime
設置RTC時間。
int32_t RtcWriteTime(DevHandle handle, struct RtcTime *time);
RtcWriteTime參數(shù)定義如下:
RtcWriteTime返回值定義如下:
RtcReadAlarm
從rtc模塊中讀取定時報警時間。
int32_t RtcReadAlarm(DevHandle handle, enum RtcAlarmIndex alarmIndex, struct RtcTime *time);
RtcReadAlarm參數(shù)定義如下:
RtcReadAlarm返回值定義如下:
RtcWriteAlarm
根據(jù)報警索引設置RTC報警時間。
int32_t RtcWriteAlarm(DevHandle handle, enum RtcAlarmIndex alarmIndex, struct RtcTime \*time);
RtcWriteAlarm參數(shù)定義如下:
RtcWriteAlarm返回值定義如下:
RtcRegisterAlarmCallback
系統(tǒng)啟動后需要注冊RTC定時報警回調(diào)函數(shù),報警超時后觸發(fā)回調(diào)函數(shù)。
int32_t RtcRegisterAlarmCallback(DevHandle handle, enum RtcAlarmIndex alarmIndex, RtcAlarmCallback cb);
RtcRegisterAlarmCallback參數(shù)定義如下:
RtcRegisterAlarmCallback返回值定義如下:
RtcAlarmInterruptEnable
在啟動報警操作前,需要先設置報警中斷使能,報警超時后會觸發(fā)告警回調(diào)函數(shù)。
int32_t RtcAlarmInterruptEnable(DevHandle handle, enum RtcAlarmIndex alarmIndex, uint8_t enable);
RtcAlarmInterruptEnable參數(shù)定義如下:
RtcAlarmInterruptEnable返回值定義如下:
(2)開發(fā)流程
使用rtc的一般流程如下圖所示:
三、程序解析
1、準備工作
無
2、Linux內(nèi)核解析
(1)創(chuàng)建Linux內(nèi)核Git
請參考《OpenHarmony如何為內(nèi)核打patch》(即Git倉庫的//docs/OpenHarmony如何為內(nèi)核打patch.docx)。
(2)修改設備樹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 = <RK_PD3 IRQ_TYPE_LEVEL_LOW>;
};
}
設備樹中默認是開啟rtc模塊的hym8563,讀者不用修改。
(3)創(chuàng)建內(nèi)核patch
請參考《OpenHarmony如何為內(nèi)核打patch》(即Git倉庫的//docs/OpenHarmony如何為內(nèi)核打patch.docx)。
(4)替換OpenHarmony的內(nèi)核patch
將制作出的kernel.patch替換到//kernel/linux/patches/linux-5.10/rk3568_patch/kernel.patch即可。
(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設備名稱定義,具體如下所示:
CONFIG_RTC_SYSTOHC_DEVICE="rtc0"
3、OpenHarmony配置樹配置
(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,表示對內(nèi)核態(tài)和用戶態(tài)提供服務。否則,應用程序無法調(diào)用。
4、OpenHarmony RTC平臺驅動
在//drivers/hdf_core/adapter/khdf/linux/platform/rtc/rtc_adapter.c已編寫對接Linux RTC驅動的相關代碼,具體內(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設備接口
static inline struct rtc_device *HdfGetRtcDevice(void)
{
// 獲取Linux環(huán)境下的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環(huán)境下的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環(huán)境下的rtc設備接口
(void)host;
if (dev == NULL) {
return HDF_FAILURE;
}
ret = rtc_read_time(dev, &linuxTime); // 直接對Linux環(huán)境下的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;
}
該部分代碼不細述,感興趣的讀者可以去詳讀。
5、應用程序
(1)rtc_test.c
rtc相關頭文件如下所示:
#include "rtc_if.h" // rtc標準接口頭文件
主函數(shù)定義RTC接口調(diào)用,具體如下:
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的定時回調(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;
}
// 設置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定時器響應函數(shù)接口,故rtc定時回調(diào)功能暫時關閉
(2)BUILD.gn
編寫應用程序的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)參與應用程序編譯
編輯//vendor/lockzhiner/rk3568/samples/BUILD.gn,開啟編譯選項。具體如下:
"b09_platform_device_rtc/app:rk3568_rtc_test",
四、程序編譯
建議使用docker編譯方法,運行如下:
hb set -root .
hb set
# 選擇lockzhiner下的rk3568編譯分支。
hb build -f
五、運行結果
運行如下:
# rk3568_rtc_test
RtcReadTime successful
year = 2017
month = 8
day = 5
hour = 10
minute = 58
second = 9
millisecond = 0
RtcWriteTime successful
year = 2023
month = 8
day = 28
hour = 17
minute = 45
second = 0
millisecond = 0
#
開發(fā)板重啟,可以發(fā)現(xiàn)系統(tǒng)相關時間已經(jīng)變更為我們案例中的配置。