Generic RTC Driver. More...

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.

Collaboration diagram for RTC Driver:

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.
#define	RTC_ALARMS 2
	Number of alarms available.
#define	RTC_HAS_STORAGE FALSE
	Presence of a local persistent storage.

PLATFORM configuration options
#define	PLATFORM_RTC_USE_RTC1 FALSE
	RTCD1 driver enable switch.

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

Macros
#define	RTC_BASE_YEAR 1980U
	Base year of the calendar.
#define	_rtc_driver_methods _base_pers_storage_methods
	BasePersistentStorage specific methods.
#define	rtc_lld_driver_fields uint32_t dummy;
	Implementation-specific `RTCDriver` fields.

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

Enumerations
enum	rtcevent_t { RTC_EVENT_SECOND = 0 }
	Type of an RTC event. More...

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

Variables
static const uint8_t	month_len [12]
static const uint16_t	accu_month_len [12]

Macro Definition Documentation

◆ RTC_BASE_YEAR

#define RTC_BASE_YEAR 1980U

Base year of the calendar.

Definition at line 45 of file hal_rtc.h.

Referenced by rtcConvertDateTimeToStructTm(), and rtcConvertStructTmToDateTime().

◆ RTC_FAT_TIME_SECONDS_MASK

#define RTC_FAT_TIME_SECONDS_MASK 0x0000001FU

Definition at line 51 of file hal_rtc.h.

◆ RTC_FAT_TIME_MINUTES_MASK

#define RTC_FAT_TIME_MINUTES_MASK 0x000007E0U

Definition at line 52 of file hal_rtc.h.

◆ RTC_FAT_TIME_HOURS_MASK

#define RTC_FAT_TIME_HOURS_MASK 0x0000F800U

Definition at line 53 of file hal_rtc.h.

◆ RTC_FAT_DATE_DAYS_MASK

#define RTC_FAT_DATE_DAYS_MASK 0x001F0000U

Definition at line 54 of file hal_rtc.h.

◆ RTC_FAT_DATE_MONTHS_MASK

#define RTC_FAT_DATE_MONTHS_MASK 0x01E00000U

Definition at line 55 of file hal_rtc.h.

◆ RTC_FAT_DATE_YEARS_MASK

#define RTC_FAT_DATE_YEARS_MASK 0xFE000000U

Definition at line 56 of file hal_rtc.h.

◆ RTC_DAY_CATURDAY

#define RTC_DAY_CATURDAY 0U

Definition at line 63 of file hal_rtc.h.

◆ RTC_DAY_MONDAY

#define RTC_DAY_MONDAY 1U

Definition at line 64 of file hal_rtc.h.

◆ RTC_DAY_TUESDAY

#define RTC_DAY_TUESDAY 2U

Definition at line 65 of file hal_rtc.h.

◆ RTC_DAY_WEDNESDAY

#define RTC_DAY_WEDNESDAY 3U

Definition at line 66 of file hal_rtc.h.

◆ RTC_DAY_THURSDAY

#define RTC_DAY_THURSDAY 4U

Definition at line 67 of file hal_rtc.h.

◆ RTC_DAY_FRIDAY

#define RTC_DAY_FRIDAY 5U

Definition at line 68 of file hal_rtc.h.

◆ RTC_DAY_SATURDAY

#define RTC_DAY_SATURDAY 6U

Definition at line 69 of file hal_rtc.h.

◆ RTC_DAY_SUNDAY

#define RTC_DAY_SUNDAY 7U

Definition at line 70 of file hal_rtc.h.

◆ _rtc_driver_methods

#define _rtc_driver_methods _base_pers_storage_methods

BasePersistentStorage specific methods.

Definition at line 112 of file hal_rtc.h.

◆ RTC_SUPPORTS_CALLBACKS

#define RTC_SUPPORTS_CALLBACKS TRUE

Callback support int the driver.

Definition at line 45 of file hal_rtc_lld.h.

◆ RTC_ALARMS

#define RTC_ALARMS 2

Number of alarms available.

Definition at line 50 of file hal_rtc_lld.h.

Referenced by rtcGetAlarm(), and rtcSetAlarm().

◆ RTC_HAS_STORAGE

#define RTC_HAS_STORAGE FALSE

Presence of a local persistent storage.

Definition at line 55 of file hal_rtc_lld.h.

◆ PLATFORM_RTC_USE_RTC1

#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 72 of file hal_rtc_lld.h.

◆ rtc_lld_driver_fields

#define rtc_lld_driver_fields uint32_t dummy;

Implementation-specific RTCDriver fields.

Definition at line 109 of file hal_rtc_lld.h.

Typedef Documentation

◆ RTCDriver

typedef struct RTCDriver RTCDriver

Type of a structure representing an RTC driver.

Definition at line 88 of file hal_rtc.h.

◆ rtcalarm_t

typedef unsigned int rtcalarm_t

Type of an RTC alarm number.

Definition at line 93 of file hal_rtc.h.

◆ rtccb_t

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

Type of a generic RTC callback.

Definition at line 95 of file hal_rtc_lld.h.

Enumeration Type Documentation

◆ rtcevent_t

enum rtcevent_t

Type of an RTC event.

Enumerator
RTC_EVENT_SECOND

Definition at line 88 of file hal_rtc_lld.h.

Function Documentation

◆ rtcInit()

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:: Object or module nitializer function.

Definition at line 71 of file hal_rtc.c.

References rtc_lld_init().

Referenced by halInit().

Here is the call graph for this function:

◆ rtcObjectInit()

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] rtcp pointer to RTC driver structure

Function Class:: Object or module nitializer function.

Definition at line 85 of file hal_rtc.c.

References RTCDriver::vmt.

Referenced by rtc_lld_init().

◆ rtcSetTime()

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]	rtcp	pointer to RTC driver structure
[in]	timespec	pointer to a `RTCDateTime` structure

Function Class:: Special function, this function has special requirements see the notes.

Definition at line 108 of file hal_rtc.c.

References osalDbgCheck, and rtc_lld_set_time().

Here is the call graph for this function:

◆ rtcGetTime()

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]	rtcp	pointer to RTC driver structure
[out]	timespec	pointer to a `RTCDateTime` structure

Function Class:: Special function, this function has special requirements see the notes.

Definition at line 129 of file hal_rtc.c.

References osalDbgCheck, and rtc_lld_get_time().

Here is the call graph for this function:

◆ rtcSetAlarm()

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]	rtcp	pointer to RTC driver structure
[in]	alarm	alarm identifier
[in]	alarmspec	pointer to a `RTCAlarm` structure or `NULL`

Function Class:: Special function, this function has special requirements see the notes.

Definition at line 152 of file hal_rtc.c.

References osalDbgCheck, RTC_ALARMS, and rtc_lld_set_alarm().

Here is the call graph for this function:

◆ rtcGetAlarm()

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]	rtcp	pointer to RTC driver structure
[in]	alarm	alarm identifier
[out]	alarmspec	pointer to a `RTCAlarm` structure

Function Class:: Special function, this function has special requirements see the notes.

Definition at line 178 of file hal_rtc.c.

References osalDbgCheck, RTC_ALARMS, and rtc_lld_get_alarm().

Here is the call graph for this function:

◆ rtcSetCallback()

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]	rtcp	pointer to RTC driver structure
[in]	callback	callback function pointer or `NULL`

Function Class:: Special function, this function has special requirements see the notes.

Definition at line 207 of file hal_rtc.c.

References osalDbgCheck, and rtc_lld_set_callback().

Here is the call graph for this function:

◆ rtcConvertDateTimeToStructTm()

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

Convert RTCDateTime to broken-down time structure.

Parameters

[in]	timespec	pointer to a `RTCDateTime` structure
[out]	timp	pointer to a broken-down time structure
[out]	tv_msec	pointer 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 224 of file hal_rtc.c.

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

◆ rtcConvertStructTmToDateTime()

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

Convert broken-down time structure to RTCDateTime.

Parameters

[in]	timp	pointer to a broken-down time structure
[in]	tv_msec	milliseconds value
[out]	timespec	pointer 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 265 of file hal_rtc.c.

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

◆ rtcConvertDateTimeToFAT()

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] timespec pointer 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 299 of file hal_rtc.c.

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

◆ rtc_lld_init()

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:

◆ rtc_lld_set_time()

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]	rtcp	pointer to RTC driver structure
[in]	timespec	pointer 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().

◆ rtc_lld_get_time()

void rtc_lld_get_time	(	RTCDriver *	rtcp,
		RTCDateTime *	timespec )

Get current time.

Note: The function can be called from any context.

Parameters

[in]	rtcp	pointer to RTC driver structure
[out]	timespec	pointer 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().

◆ rtc_lld_set_alarm()

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]	rtcp	pointer to RTC driver structure.
[in]	alarm	alarm identifier. Can be 1 or 2.
[in]	alarmspec	pointer 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().

◆ rtc_lld_get_alarm()

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]	rtcp	pointer to RTC driver structure
[in]	alarm	alarm identifier
[out]	alarmspec	pointer 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().

◆ rtc_lld_set_callback()

void rtc_lld_set_callback	(	RTCDriver *	rtcp,
		rtccb_t	callback )

Referenced by rtcSetCallback().

Variable Documentation

◆ month_len

const uint8_t month_len[12]

static

Initial value:

= {
  31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31
}

Definition at line 48 of file hal_rtc.c.

Referenced by rtcConvertDateTimeToFAT().

◆ accu_month_len

const uint16_t accu_month_len[12]

static

Initial value:

= {
  0, 31, 59,  90, 120, 151, 181, 212, 243, 273, 304, 334
}

Definition at line 52 of file hal_rtc.c.

Referenced by rtcConvertDateTimeToStructTm().

Detailed Description

Date/Time bit masks for FAT format

Day of week encoding

Implementation capabilities

PLATFORM configuration options

Data Structures

Macros

Typedefs

Enumerations

Functions

Variables

Macro Definition Documentation

◆ RTC_BASE_YEAR

◆ RTC_FAT_TIME_SECONDS_MASK

◆ RTC_FAT_TIME_MINUTES_MASK

◆ RTC_FAT_TIME_HOURS_MASK

◆ RTC_FAT_DATE_DAYS_MASK

◆ RTC_FAT_DATE_MONTHS_MASK

◆ RTC_FAT_DATE_YEARS_MASK

◆ RTC_DAY_CATURDAY

◆ RTC_DAY_MONDAY

◆ RTC_DAY_TUESDAY

◆ RTC_DAY_WEDNESDAY

◆ RTC_DAY_THURSDAY

◆ RTC_DAY_FRIDAY

◆ RTC_DAY_SATURDAY

◆ RTC_DAY_SUNDAY

◆ _rtc_driver_methods

◆ RTC_SUPPORTS_CALLBACKS

◆ RTC_ALARMS

◆ RTC_HAS_STORAGE

◆ PLATFORM_RTC_USE_RTC1

◆ rtc_lld_driver_fields

Typedef Documentation

◆ RTCDriver

◆ rtcalarm_t

◆ rtccb_t

Enumeration Type Documentation

◆ rtcevent_t

Function Documentation

◆ rtcInit()

◆ rtcObjectInit()

◆ rtcSetTime()

◆ rtcGetTime()

◆ rtcSetAlarm()

◆ rtcGetAlarm()

◆ rtcSetCallback()

◆ rtcConvertDateTimeToStructTm()

◆ rtcConvertStructTmToDateTime()

◆ rtcConvertDateTimeToFAT()

◆ rtc_lld_init()

◆ rtc_lld_set_time()

◆ rtc_lld_get_time()

◆ rtc_lld_set_alarm()

◆ rtc_lld_get_alarm()

◆ rtc_lld_set_callback()

Variable Documentation

◆ month_len

◆ accu_month_len