RTC使用指导

使用流程

在操作系统启动过程中，驱动管理模块根据配置文件加载RTC驱动，RTC驱动会检测RTC器件并初始化驱动。

使用RTC设备的一般流程如图1所示。

图 1 RTC设备使用流程图

创建RTC设备句柄

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

说明： 当前操作系统支持一个RTC设备。

struct DevHandle *RtcOpen(void);

表 1 RtcOpen参数和返回值描述

1. struct DevHandle * handle = NULL;

3. /* 获取RTC句柄 */
4. handle = RtcOpen();
5. if (handle  == NULL) {
6. /* 错误处理 */
7. }

销毁RTC设备句柄

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

void RtcClose(struct DevHandle *handle);

表 2 RtcClose参数描述

1. /* 销毁RTC句柄 */
2. RtcClose(handle);

注册RTC定时报警回调函数

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

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

表 3 RtcRegisterAlarmCallback参数和返回值描述

注册RTC_ALARM_INDEX_A的定时报警处理函数， 示例如下：

1. /* 用户注册RTC定时报警回调函数的方法 */
2. int32_t RtcAlarmACallback(enum RtcAlarmIndex alarmIndex)
3. {
4. if (alarmIndex == RTC_ALARM_INDEX_A) {
5. /* 报警A的处理 */
6. } else if (alarmIndex == RTC_ALARM_INDEX_B) {
7. /* 报警B的处理 */
8. } else {
9. /* 错误处理 */
10. }
11. return 0;
12. }
13. int32_t ret;
14. /* 注册报警A的定时回调函数 */
15. ret = RtcRegisterAlarmCallback(handle, RTC_ALARM_INDEX_A, RtcAlarmACallback);
16. if (ret != 0) {
17. /* 错误处理 */
18. }

操作RTC

• 读取RTC时间。

系统从RTC读取时间信息，包括年、月、星期、日、时、分、秒、毫秒，则可以通过以下函数完成：

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

表 4 RtcReadTime参数和返回值描述

1. int32_t ret;
2. struct RtcTime tm;

4. /* 系统从RTC读取时间信息 */
5. ret = RtcReadTime(handle, &tm);
6. if (ret != 0) {
7. /* 错误处理 */
8. }

• 设置RTC时间

设置RTC时间，则可以通过以下函数完成:

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

表 5 RtcWriteTime参数和返回值描述

说明： RTC起始时间为UTC 1970/01/01 Thursday 00:00:00，年的最大取值按照用户器件手册要求计算配置，星期不用配置。

1. int32_t ret;
2. struct RtcTime tm;

4. /* 设置RTC时间为 UTC 2020/01/01 00:59:00 .000 */
5. tm.year = 2020;
6. tm.month = 01;
7. tm.day = 01;
8. tm.hour= 00;
9. tm.minute = 59;
10. tm.second = 00;
11. tm.millisecond = 0;
12. /* 写RTC时间信息 */
13. ret = RtcWriteTime(handle, &tm);
14. if (ret != 0) {
15. /* 错误处理 */
16. }

• 读取RTC报警时间

如果需要读取定时报警时间，则可以通过以下函数完成：

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

表 6 RtcReadAlarm参数和返回值描述

1. int32_t ret;
2. struct RtcTime alarmTime;

4. /* 读RTC_ALARM_INDEX_A索引的RTC定时报警时间信息 */
5. ret = RtcReadAlarm(handle, RTC_ALARM_INDEX_A, &alarmTime);
6. if (ret != 0) {
7. /* 错误处理 */
8. }

• 设置RTC报警时间

根据报警索引设置RTC报警时间，通过以下函数完成：

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

表 7 RtcWriteAlarm参数和返回值描述

说明： RTC起始时间为UTC 1970/01/01 Thursday 00:00:00，年的最大取值按照用户器件手册要求计算配置，星期不用配置。

1. int32_t ret;
2. struct RtcTime alarmTime;

4. /* 设置RTC报警时间为2020/01/01 00:59:59 .000 */
5. alarmTime.year = 2020;
6. alarmTime.month = 01;
7. alarmTime.day = 01;
8. alarmTime.hour = 00;
9. alarmTime.minute = 59;
10. alarmTime.second = 59;
11. alarmTime.millisecond = 0;
12. /* 设置RTC_ALARM_INDEX_A索引的定时报警时间 */
13. ret = RtcWriteAlarm(handle, RTC_ALARM_INDEX_A, &alarmTime);
14. if (ret != 0) {
15. /* 错误处理 */
16. }

• 设置定时报警中断使能或去使能

在启动报警操作前，需要先设置报警中断使能，报警超时后会触发告警回调函数，可以通过以下函数完成：

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

表 8 RtcAlarmInterruptEnable参数和返回值描述

1. int32_t ret;

3. /* 设置RTC报警中断使能 */
4. ret = RtcAlarmInterruptEnable(handle, RTC_ALARM_INDEX_A, 1);
5. if (ret != 0) {
6. /* 错误处理 */
7. }

• 读取RTC外频

读取RTC外接晶体振荡频率，可以通过以下函数完成：

int32_t RtcGetFreq(struct DevHandle *handle, uint32_t *freq);

表 9 RtcGetFreq参数和返回值描述

1. int32_t ret;
2. uint32_t freq = 0;

4. /* 读取RTC外接晶体振荡频率 */
5. ret = RtcGetFreq(handle, &freq);
6. if (ret != 0) {
7. /* 错误处理 */
8. }

• 配置RTC外频

配置RTC外接晶体振荡频率，可以通过以下函数完成：

int32_t RtcSetFreq(struct DevHandle *handle, uint32_t freq);

表 10 RtcSetFreq参数和返回值描述

1. int32_t ret;
2. uint32_t freq = 32768; /* 32768 Hz */

4. /* 设置RTC外接晶体振荡频率，注意按照器件手册要求配置RTC外频 */
5. ret = RtcSetFreq(handle, freq);
6. if (ret != 0) {
7. /* 错误处理 */
8. }

• 复位RTC

复位RTC，复位RTC后各配置寄存器恢复默认值，可以通过以下函数完成：

int32_t RtcReset(struct DevHandle *handle);

表 11 RtcReset参数和返回值描述

1. int32_t ret;

3. /* 复位RTC，复位RTC后各配置寄存器恢复默认值 */
4. ret = RtcReset(handle);
5. if (ret != 0) {
6. /* 错误处理 */
7. }

• 读取RTC自定义寄存器配置

按照用户定义的寄存器索引，读取对应的寄存器配置，一个索引对应一字节的配置值，通过以下函数完成：

int32_t RtcReadReg(struct DevHandle *handle, uint8_t usrDefIndex, uint8_t *value);

表 12 RtcReadReg参数和返回值描述

1. int32_t ret;
2. uint8_t usrDefIndex = 0; /* 定义0索引对应用户定义的第一个寄存器*/
3. uint8_t value = 0;

5. /* 按照用户定义的寄存器索引，读取对应的寄存器配置，一个索引对应一字节的配置值 */
6. ret = RtcReadReg(handle, usrDefIndex, &value);
7. if (ret != 0) {
8. /* 错误处理 */
9. }

• 设置RTC自定义寄存器配置

按照用户定义的寄存器索引，设置对应的寄存器配置，一个索引对应一字节的配置值，通过以下函数完成：

int32_t RtcWriteReg(struct DevHandle *handle, uint8_t usrDefIndex, uint8_t value);

表 13 RtcWriteReg参数和返回值描述

1. int32_t ret;
2. uint8_t usrDefIndex = 0; /* 定义0索引对应用户定义第一个寄存器*/
3. uint8_t value = 0x10;

5. /* 按照用户的定义的寄存器索引，设置对应的寄存器配置，一个索引对应一字节的配置值 */
6. ret = RtcWriteReg(handle, usrDefIndex, value);
7. if (ret != 0) {
8. /* 错误处理 */
9. }