ChibiOS/HAL  6.1.0
RTC Driver

Generic RTC Driver. More...

Collaboration diagram for RTC Driver:

Detailed Description

Generic RTC Driver.

This module defines an abstract interface for a Real Time Clock Peripheral.

Precondition
In order to use the RTC driver the HAL_USE_RTC option must be enabled in halconf.h.

Macros

#define RTC_BASE_YEAR   1980U
 Base year of the calendar. More...
 
#define _rtc_driver_methods   _file_stream_methods
 FileStream specific methods. More...
 

Date/Time bit masks for FAT format

#define RTC_FAT_TIME_SECONDS_MASK   0x0000001FU
 
#define RTC_FAT_TIME_MINUTES_MASK   0x000007E0U
 
#define RTC_FAT_TIME_HOURS_MASK   0x0000F800U
 
#define RTC_FAT_DATE_DAYS_MASK   0x001F0000U
 
#define RTC_FAT_DATE_MONTHS_MASK   0x01E00000U
 
#define RTC_FAT_DATE_YEARS_MASK   0xFE000000U
 

Day of week encoding

#define RTC_DAY_CATURDAY   0U
 
#define RTC_DAY_MONDAY   1U
 
#define RTC_DAY_TUESDAY   2U
 
#define RTC_DAY_WEDNESDAY   3U
 
#define RTC_DAY_THURSDAY   4U
 
#define RTC_DAY_FRIDAY   5U
 
#define RTC_DAY_SATURDAY   6U
 
#define RTC_DAY_SUNDAY   7U
 

Implementation capabilities

#define RTC_SUPPORTS_CALLBACKS   TRUE
 Callback support int the driver. More...
 
#define RTC_ALARMS   2
 Number of alarms available. More...
 
#define RTC_HAS_STORAGE   FALSE
 Presence of a local persistent storage. More...
 

PLATFORM configuration options

#define PLATFORM_RTC_USE_RTC1   FALSE
 RTCD1 driver enable switch. More...
 

Typedefs

typedef struct RTCDriver RTCDriver
 Type of a structure representing an RTC driver. More...
 
typedef uint32_t rtcalarm_t
 Type of an RTC alarm number. More...
 
typedef void(* rtccb_t) (RTCDriver *rtcp, rtcevent_t event)
 Type of a generic RTC callback. More...
 

Data Structures

struct  RTCDateTime
 Type of a structure representing an RTC date/time stamp. More...
 
struct  RTCAlarm
 Type of a structure representing an RTC alarm time stamp. More...
 
struct  RTCDriverVMT
 RTCDriver virtual methods table. More...
 
struct  RTCDriver
 Structure representing an RTC driver. More...
 

Functions

void rtcInit (void)
 RTC Driver initialization. More...
 
void rtcObjectInit (RTCDriver *rtcp)
 Initializes a generic RTC driver object. More...
 
void rtcSetTime (RTCDriver *rtcp, const RTCDateTime *timespec)
 Set current time. More...
 
void rtcGetTime (RTCDriver *rtcp, RTCDateTime *timespec)
 Get current time. More...
 
void rtcSetAlarm (RTCDriver *rtcp, rtcalarm_t alarm, const RTCAlarm *alarmspec)
 Set alarm time. More...
 
void rtcGetAlarm (RTCDriver *rtcp, rtcalarm_t alarm, RTCAlarm *alarmspec)
 Get current alarm. More...
 
void rtcSetCallback (RTCDriver *rtcp, rtccb_t callback)
 Enables or disables RTC callbacks. More...
 
void rtcConvertDateTimeToStructTm (const RTCDateTime *timespec, struct tm *timp, uint32_t *tv_msec)
 Convert RTCDateTime to broken-down time structure. More...
 
void rtcConvertStructTmToDateTime (const struct tm *timp, uint32_t tv_msec, RTCDateTime *timespec)
 Convert broken-down time structure to RTCDateTime. More...
 
uint32_t rtcConvertDateTimeToFAT (const RTCDateTime *timespec)
 Get current time in format suitable for usage in FAT file system. More...
 
void rtc_lld_init (void)
 RTC driver identifier. More...
 
void rtc_lld_set_time (RTCDriver *rtcp, const RTCDateTime *timespec)
 Set current time. More...
 
void rtc_lld_get_time (RTCDriver *rtcp, RTCDateTime *timespec)
 Get current time. More...
 
void rtc_lld_set_alarm (RTCDriver *rtcp, rtcalarm_t alarm, const RTCAlarm *alarmspec)
 Set alarm time. More...
 
void rtc_lld_get_alarm (RTCDriver *rtcp, rtcalarm_t alarm, RTCAlarm *alarmspec)
 Get alarm time. More...
 

Enumerations

Macro Definition Documentation

#define RTC_BASE_YEAR   1980U

Base year of the calendar.

Definition at line 45 of file hal_rtc.h.

#define RTC_SUPPORTS_CALLBACKS   TRUE

Callback support int the driver.

Definition at line 44 of file hal_rtc_lld.h.

#define RTC_ALARMS   2

Number of alarms available.

Definition at line 49 of file hal_rtc_lld.h.

Referenced by rtcGetAlarm(), and rtcSetAlarm().

#define RTC_HAS_STORAGE   FALSE

Presence of a local persistent storage.

Definition at line 54 of file hal_rtc_lld.h.

#define PLATFORM_RTC_USE_RTC1   FALSE

RTCD1 driver enable switch.

If set to TRUE the support for RTC1 is included.

Note
The default is FALSE.

Definition at line 71 of file hal_rtc_lld.h.

#define _rtc_driver_methods   _file_stream_methods

FileStream specific methods.

Definition at line 86 of file hal_rtc_lld.h.

Typedef Documentation

typedef struct RTCDriver RTCDriver

Type of a structure representing an RTC driver.

Definition at line 88 of file hal_rtc.h.

typedef uint32_t rtcalarm_t

Type of an RTC alarm number.

Definition at line 92 of file hal_rtc_lld.h.

typedef void(* rtccb_t) (RTCDriver *rtcp, rtcevent_t event)

Type of a generic RTC callback.

Definition at line 105 of file hal_rtc_lld.h.

Enumeration Type Documentation

enum rtcevent_t

Type of an RTC event.

Definition at line 98 of file hal_rtc_lld.h.

Function Documentation

void rtcInit ( void  )

RTC Driver initialization.

Note
This function is implicitly invoked by halInit(), there is no need to explicitly initialize the driver.
Function Class:Initializer, this function just initializes an object and can be invoked before the kernel is initialized.

Definition at line 67 of file hal_rtc.c.

References rtc_lld_init().

Referenced by halInit().

Here is the call graph for this function:

void rtcObjectInit ( RTCDriver rtcp)

Initializes a generic RTC driver object.

The HW dependent part of the initialization has to be performed outside, usually in the hardware initialization code.

Parameters
[out]rtcppointer to RTC driver structure
Function Class:Initializer, this function just initializes an object and can be invoked before the kernel is initialized.

Definition at line 81 of file hal_rtc.c.

References RTCDriver::vmt.

Referenced by rtc_lld_init().

void rtcSetTime ( RTCDriver rtcp,
const RTCDateTime timespec 
)

Set current time.

Note
This function can be called from any context but limitations could be imposed by the low level implementation. It is guaranteed that the function can be called from thread context.
The function can be reentrant or not reentrant depending on the low level implementation.
Parameters
[in]rtcppointer to RTC driver structure
[in]timespecpointer to a RTCDateTime structure
Function Class:Special function, this function has special requirements see the notes.

Definition at line 104 of file hal_rtc.c.

References osalDbgCheck, and rtc_lld_set_time().

Here is the call graph for this function:

void rtcGetTime ( RTCDriver rtcp,
RTCDateTime timespec 
)

Get current time.

Note
This function can be called from any context but limitations could be imposed by the low level implementation. It is guaranteed that the function can be called from thread context.
The function can be reentrant or not reentrant depending on the low level implementation.
Parameters
[in]rtcppointer to RTC driver structure
[out]timespecpointer to a RTCDateTime structure
Function Class:Special function, this function has special requirements see the notes.

Definition at line 125 of file hal_rtc.c.

References osalDbgCheck, and rtc_lld_get_time().

Here is the call graph for this function:

void rtcSetAlarm ( RTCDriver rtcp,
rtcalarm_t  alarm,
const RTCAlarm alarmspec 
)

Set alarm time.

Note
This function can be called from any context but limitations could be imposed by the low level implementation. It is guaranteed that the function can be called from thread context.
The function can be reentrant or not reentrant depending on the low level implementation.
Parameters
[in]rtcppointer to RTC driver structure
[in]alarmalarm identifier
[in]alarmspecpointer to a RTCAlarm structure or NULL
Function Class:Special function, this function has special requirements see the notes.

Definition at line 148 of file hal_rtc.c.

References osalDbgCheck, RTC_ALARMS, and rtc_lld_set_alarm().

Here is the call graph for this function:

void rtcGetAlarm ( RTCDriver rtcp,
rtcalarm_t  alarm,
RTCAlarm alarmspec 
)

Get current alarm.

Note
If an alarm has not been set then the returned alarm specification is not meaningful.
This function can be called from any context but limitations could be imposed by the low level implementation. It is guaranteed that the function can be called from thread context.
The function can be reentrant or not reentrant depending on the low level implementation.
Parameters
[in]rtcppointer to RTC driver structure
[in]alarmalarm identifier
[out]alarmspecpointer to a RTCAlarm structure
Function Class:Special function, this function has special requirements see the notes.

Definition at line 174 of file hal_rtc.c.

References osalDbgCheck, RTC_ALARMS, and rtc_lld_get_alarm().

Here is the call graph for this function:

void rtcSetCallback ( RTCDriver rtcp,
rtccb_t  callback 
)

Enables or disables RTC callbacks.

This function enables or disables the callback, use a NULL pointer in order to disable it.

Note
This function can be called from any context but limitations could be imposed by the low level implementation. It is guaranteed that the function can be called from thread context.
The function can be reentrant or not reentrant depending on the low level implementation.
Parameters
[in]rtcppointer to RTC driver structure
[in]callbackcallback function pointer or NULL
Function Class:Special function, this function has special requirements see the notes.

Definition at line 203 of file hal_rtc.c.

References osalDbgCheck.

void rtcConvertDateTimeToStructTm ( const RTCDateTime timespec,
struct tm *  timp,
uint32_t *  tv_msec 
)

Convert RTCDateTime to broken-down time structure.

Parameters
[in]timespecpointer to a RTCDateTime structure
[out]timppointer to a broken-down time structure
[out]tv_msecpointer to milliseconds value or NULL
Function Class:Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 220 of file hal_rtc.c.

References RTCDateTime::day, RTCDateTime::dayofweek, RTCDateTime::dstflag, RTCDateTime::millisecond, RTCDateTime::month, and RTCDateTime::year.

void rtcConvertStructTmToDateTime ( const struct tm *  timp,
uint32_t  tv_msec,
RTCDateTime timespec 
)

Convert broken-down time structure to RTCDateTime.

Parameters
[in]timppointer to a broken-down time structure
[in]tv_msecmilliseconds value
[out]timespecpointer to a RTCDateTime structure
Function Class:Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 251 of file hal_rtc.c.

References RTCDateTime::day, RTCDateTime::dayofweek, RTCDateTime::dstflag, RTCDateTime::millisecond, RTCDateTime::month, and RTCDateTime::year.

uint32_t rtcConvertDateTimeToFAT ( const RTCDateTime timespec)

Get current time in format suitable for usage in FAT file system.

Note
The information about day of week and DST is lost in DOS format, the second field loses its least significant bit.
Parameters
[out]timespecpointer to a RTCDateTime structure
Returns
FAT date/time value.
Function Class:Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 284 of file hal_rtc.c.

References RTCDateTime::day, RTCDateTime::dstflag, RTCDateTime::millisecond, RTCDateTime::month, and RTCDateTime::year.

void rtc_lld_init ( void  )

RTC driver identifier.

Enable access to registers.

Function Class:Not an API, this function is for internal use only.

Definition at line 69 of file hal_rtc_lld.c.

References rtcObjectInit().

Referenced by rtcInit().

Here is the call graph for this function:

void rtc_lld_set_time ( RTCDriver rtcp,
const RTCDateTime timespec 
)

Set current time.

Note
Fractional part will be silently ignored. There is no possibility to set it on PLATFORM platform.
The function can be called from any context.
Parameters
[in]rtcppointer to RTC driver structure
[in]timespecpointer to a RTCDateTime structure
Function Class:Not an API, this function is for internal use only.

Definition at line 88 of file hal_rtc_lld.c.

Referenced by rtcSetTime().

void rtc_lld_get_time ( RTCDriver rtcp,
RTCDateTime timespec 
)

Get current time.

Note
The function can be called from any context.
Parameters
[in]rtcppointer to RTC driver structure
[out]timespecpointer to a RTCDateTime structure
Function Class:Not an API, this function is for internal use only.

Definition at line 103 of file hal_rtc_lld.c.

Referenced by rtcGetTime().

void rtc_lld_set_alarm ( RTCDriver rtcp,
rtcalarm_t  alarm,
const RTCAlarm alarmspec 
)

Set alarm time.

Note
Default value after BKP domain reset for both comparators is 0.
Function does not performs any checks of alarm time validity.
The function can be called from any context.
Parameters
[in]rtcppointer to RTC driver structure.
[in]alarmalarm identifier. Can be 1 or 2.
[in]alarmspecpointer to a RTCAlarm structure.
Function Class:Not an API, this function is for internal use only.

Definition at line 122 of file hal_rtc_lld.c.

Referenced by rtcSetAlarm().

void rtc_lld_get_alarm ( RTCDriver rtcp,
rtcalarm_t  alarm,
RTCAlarm alarmspec 
)

Get alarm time.

Note
The function can be called from any context.
Parameters
[in]rtcppointer to RTC driver structure
[in]alarmalarm identifier
[out]alarmspecpointer to a RTCAlarm structure
Function Class:Not an API, this function is for internal use only.

Definition at line 141 of file hal_rtc_lld.c.

Referenced by rtcGetAlarm().