RTC使用指导

使用流程

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

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

图 1 RTC设备使用流程图

RTC使用指导 - 图1

创建RTC设备句柄

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

RTC使用指导 - 图2说明: 当前操作系统支持一个RTC设备。

struct DevHandle *RtcOpen(void);

表 1 RtcOpen参数和返回值描述

参数

参数描述

void

NA

返回值

返回值描述

handle

操作成功返回 指针类型

NULL

操作失败

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

销毁RTC设备句柄

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

void RtcClose(struct DevHandle *handle);

表 2 RtcClose参数描述

参数

参数描述

handle

RTC设备句柄

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

注册RTC定时报警回调函数

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

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

表 3 RtcRegisterAlarmCallback参数和返回值描述

参数

参数描述

handle

RTC设备句柄

alarmIndex

报警索引

cb

定时报警回调函数

返回值

返回值描述

0

操作成功

负数

操作失败

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

  1. /* 用户注册RTC定时报警回调函数的方法 */
  2. int32_tRtcAlarmACallback(enumRtcAlarmIndex alarmIndex)
  3. {
  4. if(alarmIndex == RTC_ALARM_INDEX_A){
  5. /* 报警A的处理 */
  6. }elseif(alarmIndex == RTC_ALARM_INDEX_B){
  7. /* 报警B的处理 */
  8. }else{
  9. /* 错误处理 */
  10. }
  11. return0;
  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参数和返回值描述

参数

参数描述

handle

RTC设备句柄

time

RTC读取时间信息,包括年、月、星期、日、时、分、秒、毫秒

返回值

返回值描述

0

操作成功

负数

操作失败

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

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

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

表 5 RtcWriteTime参数和返回值描述

参数

参数描述

handle

RTC设备句柄

time

写RTC时间信息,包括年、月、星期、日、时、分、秒、毫秒

返回值

返回值描述

0

操作成功

负数

操作失败

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

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

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

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

表 6 RtcReadAlarm参数和返回值描述

参数

参数描述

handle

RTC设备句柄

alarmIndex

报警索引

time

RTC报警时间信息,包括年、月、星期、日、时、分、秒、毫秒

返回值

返回值描述

0

操作成功

负数

操作失败

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

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

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

表 7 RtcWriteAlarm参数和返回值描述

参数

参数描述

handle

RTC设备句柄

alarmIndex

报警索引

time

RTC报警时间信息,包括年、月、星期、日、时、分、秒、毫秒

返回值

返回值描述

0

操作成功

负数

操作失败

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

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

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

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

表 8 RtcAlarmInterruptEnable参数和返回值描述

参数

参数描述

handle

RTC设备句柄

alarmIndex

报警索引

enable

RTC报警中断配置,1:使能,0:去使能

返回值

返回值描述

0

操作成功

负数

操作失败

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

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

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

表 9 RtcGetFreq参数和返回值描述

参数

参数描述

handle

RTC设备句柄

freq

RTC的外接晶体振荡频率,单位(HZ)

返回值

返回值描述

0

操作成功

负数

操作失败

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

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

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

表 10 RtcSetFreq参数和返回值描述

参数

参数描述

handle

RTC设备句柄

freq

RTC的外接晶体振荡频率,单位(HZ)

返回值

返回值描述

0

操作成功

负数

操作失败

  1. int32_t ret;
  2. uint32_t freq =32768;/* 32768 Hz */
  3. /* 设置RTC外接晶体振荡频率,注意按照器件手册要求配置RTC外频 */
  4. ret =RtcSetFreq(handle, freq);
  5. if(ret !=0){
  6. /* 错误处理 */
  7. }
  • 复位RTC

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

int32_t RtcReset(struct DevHandle *handle);

表 11 RtcReset参数和返回值描述

参数

参数描述

handle

RTC设备句柄

返回值

返回值描述

0

操作成功

负数

操作失败

  1. int32_t ret;
  2. /* 复位RTC,复位RTC后各配置寄存器恢复默认值 */
  3. ret =RtcReset(handle);
  4. if(ret !=0){
  5. /* 错误处理 */
  6. }
  • 读取RTC自定义寄存器配置

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

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

表 12 RtcReadReg参数和返回值描述

参数

参数描述

handle

RTC设备句柄

usrDefIndex

用户定义的寄存器对应索引

value

寄存器值

返回值

返回值描述

0

操作成功

负数

操作失败

  1. int32_t ret;
  2. uint8_t usrDefIndex =0;/* 定义0索引对应用户定义的第一个寄存器*/
  3. uint8_t value =0;
  4. /* 按照用户定义的寄存器索引,读取对应的寄存器配置,一个索引对应一字节的配置值 */
  5. ret =RtcReadReg(handle, usrDefIndex,&value);
  6. if(ret !=0){
  7. /* 错误处理 */
  8. }
  • 设置RTC自定义寄存器配置

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

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

表 13 RtcWriteReg参数和返回值描述

参数

参数描述

handle

RTC设备句柄

usrDefIndex

用户定义的寄存器对应索引

value

寄存器值

返回值

返回值描述

0

操作成功

负数

操作失败

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