Zephyr API Documentation 3.7.99
A Scalable Open Source RTOS
Loading...
Searching...
No Matches
RTC Interface

RTC Interface . More...

Data Structures

struct  rtc_time
 Structure for storing date and time values with sub-second precision. More...
 

Typedefs

typedef void(* rtc_update_callback) (const struct device *dev, void *user_data)
 RTC update event callback.
 
typedef void(* rtc_alarm_callback) (const struct device *dev, uint16_t id, void *user_data)
 RTC alarm triggered callback.
 

Functions

int rtc_set_time (const struct device *dev, const struct rtc_time *timeptr)
 API for setting RTC time.
 
int rtc_get_time (const struct device *dev, struct rtc_time *timeptr)
 API for getting RTC time.
 

RTC Interface Alarm

int rtc_alarm_get_supported_fields (const struct device *dev, uint16_t id, uint16_t *mask)
 API for getting the supported fields of the RTC alarm time.
 
int rtc_alarm_set_time (const struct device *dev, uint16_t id, uint16_t mask, const struct rtc_time *timeptr)
 API for setting RTC alarm time.
 
int rtc_alarm_get_time (const struct device *dev, uint16_t id, uint16_t *mask, struct rtc_time *timeptr)
 API for getting RTC alarm time.
 
int rtc_alarm_is_pending (const struct device *dev, uint16_t id)
 API for testing if RTC alarm is pending.
 
int rtc_alarm_set_callback (const struct device *dev, uint16_t id, rtc_alarm_callback callback, void *user_data)
 API for setting alarm callback.
 

RTC Interface Update

int rtc_update_set_callback (const struct device *dev, rtc_update_callback callback, void *user_data)
 API for setting update callback.
 

RTC Interface Calibration

int rtc_set_calibration (const struct device *dev, int32_t calibration)
 API for setting RTC calibration.
 
int rtc_get_calibration (const struct device *dev, int32_t *calibration)
 API for getting RTC calibration.
 

RTC Interface Helpers

static struct tmrtc_time_to_tm (struct rtc_time *timeptr)
 Convenience function for safely casting a rtc_time pointer to a tm pointer.
 
static int32_t rtc_calibration_from_frequency (uint32_t frequency)
 Determine required calibration to 1 Hertz from frequency.
 

RTC Alarm Time Mask

Mask for alarm time fields to enable when setting alarm time

#define RTC_ALARM_TIME_MASK_SECOND   BIT(0)
 
#define RTC_ALARM_TIME_MASK_MINUTE   BIT(1)
 
#define RTC_ALARM_TIME_MASK_HOUR   BIT(2)
 
#define RTC_ALARM_TIME_MASK_MONTHDAY   BIT(3)
 
#define RTC_ALARM_TIME_MASK_MONTH   BIT(4)
 
#define RTC_ALARM_TIME_MASK_YEAR   BIT(5)
 
#define RTC_ALARM_TIME_MASK_WEEKDAY   BIT(6)
 
#define RTC_ALARM_TIME_MASK_YEARDAY   BIT(7)
 
#define RTC_ALARM_TIME_MASK_NSEC   BIT(8)
 

Detailed Description

RTC Interface .

Since
3.4
Version
0.1.0

Macro Definition Documentation

◆ RTC_ALARM_TIME_MASK_HOUR

#define RTC_ALARM_TIME_MASK_HOUR   BIT(2)

◆ RTC_ALARM_TIME_MASK_MINUTE

#define RTC_ALARM_TIME_MASK_MINUTE   BIT(1)

◆ RTC_ALARM_TIME_MASK_MONTH

#define RTC_ALARM_TIME_MASK_MONTH   BIT(4)

◆ RTC_ALARM_TIME_MASK_MONTHDAY

#define RTC_ALARM_TIME_MASK_MONTHDAY   BIT(3)

◆ RTC_ALARM_TIME_MASK_NSEC

#define RTC_ALARM_TIME_MASK_NSEC   BIT(8)

◆ RTC_ALARM_TIME_MASK_SECOND

#define RTC_ALARM_TIME_MASK_SECOND   BIT(0)

◆ RTC_ALARM_TIME_MASK_WEEKDAY

#define RTC_ALARM_TIME_MASK_WEEKDAY   BIT(6)

◆ RTC_ALARM_TIME_MASK_YEAR

#define RTC_ALARM_TIME_MASK_YEAR   BIT(5)

◆ RTC_ALARM_TIME_MASK_YEARDAY

#define RTC_ALARM_TIME_MASK_YEARDAY   BIT(7)

Typedef Documentation

◆ rtc_alarm_callback

typedef void(* rtc_alarm_callback) (const struct device *dev, uint16_t id, void *user_data)

#include <zephyr/drivers/rtc.h>

RTC alarm triggered callback.

Parameters
devDevice instance invoking the handler
idAlarm id
user_dataOptional user data passed with the alarm configuration

◆ rtc_update_callback

typedef void(* rtc_update_callback) (const struct device *dev, void *user_data)

#include <zephyr/drivers/rtc.h>

RTC update event callback.

Parameters
devDevice instance invoking the handler
user_dataOptional user data provided when update irq callback is set

Function Documentation

◆ rtc_alarm_get_supported_fields()

int rtc_alarm_get_supported_fields ( const struct device * dev,
uint16_t id,
uint16_t * mask )

#include <zephyr/drivers/rtc.h>

API for getting the supported fields of the RTC alarm time.

Parameters
devDevice instance
idId of the alarm
maskMask of fields in the alarm time which are supported
Note
Bits in the mask param are defined here RTC_ALARM_TIME_MASK.
Returns
0 if successful
-EINVAL if id is out of range or time is invalid
-ENOTSUP if API is not supported by hardware
-errno code if failure

◆ rtc_alarm_get_time()

int rtc_alarm_get_time ( const struct device * dev,
uint16_t id,
uint16_t * mask,
struct rtc_time * timeptr )

#include <zephyr/drivers/rtc.h>

API for getting RTC alarm time.

Parameters
devDevice instance
idId of the alarm
maskDestination for mask of fields which are enabled in the alarm time
timeptrDestination for the alarm time
Note
Bits in the mask param are defined here RTC_ALARM_TIME_MASK
Returns
0 if successful
-EINVAL if id is out of range
-ENOTSUP if API is not supported by hardware
-errno code if failure

◆ rtc_alarm_is_pending()

int rtc_alarm_is_pending ( const struct device * dev,
uint16_t id )

#include <zephyr/drivers/rtc.h>

API for testing if RTC alarm is pending.

Test whether or not the alarm with id is pending. If the alarm is pending, the pending status is cleared.

Parameters
devDevice instance
idId of the alarm to test
Returns
1 if alarm was pending
0 if alarm was not pending
-EINVAL if id is out of range
-ENOTSUP if API is not supported by hardware
-errno code if failure

◆ rtc_alarm_set_callback()

int rtc_alarm_set_callback ( const struct device * dev,
uint16_t id,
rtc_alarm_callback callback,
void * user_data )

#include <zephyr/drivers/rtc.h>

API for setting alarm callback.

Setting the alarm callback for an alarm, will enable the alarm callback. When the callback for an alarm is enabled, the alarm triggered event will invoke the callback, after which the alarm pending status will be cleared automatically. The alarm will remain enabled until manually disabled using rtc_alarm_set_time().

To disable the alarm callback for an alarm, the callback and user_data parameters must be set to NULL. When the alarm callback for an alarm is disabled, the alarm triggered event will set the alarm status to "pending". To check if the alarm status is "pending", use rtc_alarm_is_pending().

Parameters
devDevice instance
idId of the alarm for which the callback shall be set
callbackCallback called when alarm occurs
user_dataOptional user data passed to callback
Returns
0 if successful
-EINVAL if id is out of range
-ENOTSUP if API is not supported by hardware
-errno code if failure

◆ rtc_alarm_set_time()

int rtc_alarm_set_time ( const struct device * dev,
uint16_t id,
uint16_t mask,
const struct rtc_time * timeptr )

#include <zephyr/drivers/rtc.h>

API for setting RTC alarm time.

To enable an RTC alarm, one or more fields of the RTC alarm time must be enabled. The mask designates which fields of the RTC alarm time to enable. If the mask parameter is 0, the alarm will be disabled. The RTC alarm will trigger when all enabled fields of the alarm time match the RTC time.

Parameters
devDevice instance
idId of the alarm
maskMask of fields in the alarm time to enable
timeptrThe alarm time to set
Note
The timeptr param may be NULL if the mask param is 0
Only the enabled fields in the timeptr param need to be configured
Bits in the mask param are defined here RTC_ALARM_TIME_MASK
Returns
0 if successful
-EINVAL if id is out of range or time is invalid
-ENOTSUP if API is not supported by hardware
-errno code if failure

◆ rtc_calibration_from_frequency()

static int32_t rtc_calibration_from_frequency ( uint32_t frequency)
inlinestatic

#include <zephyr/drivers/rtc.h>

Determine required calibration to 1 Hertz from frequency.

Parameters
frequencyFrequency of the RTC in nano Hertz
Returns
The required calibration in parts per billion

◆ rtc_get_calibration()

int rtc_get_calibration ( const struct device * dev,
int32_t * calibration )

#include <zephyr/drivers/rtc.h>

API for getting RTC calibration.

Parameters
devDevice instance
calibrationDestination for calibration in parts per billion
Returns
0 if successful
-ENOTSUP if API is not supported by hardware
-errno code if failure

◆ rtc_get_time()

int rtc_get_time ( const struct device * dev,
struct rtc_time * timeptr )

#include <zephyr/drivers/rtc.h>

API for getting RTC time.

Parameters
devDevice instance
timeptrDestination for the time
Returns
0 if successful
-ENODATA if RTC time has not been set
-errno code if failure

◆ rtc_set_calibration()

int rtc_set_calibration ( const struct device * dev,
int32_t calibration )

#include <zephyr/drivers/rtc.h>

API for setting RTC calibration.

Calibration is applied to the RTC clock input. A positive calibration value will increase the frequency of the RTC clock, a negative value will decrease the frequency of the RTC clock.

See also
rtc_calibration_from_frequency()
Parameters
devDevice instance
calibrationCalibration to set in parts per billion
Returns
0 if successful
-EINVAL if calibration is out of range
-ENOTSUP if API is not supported by hardware
-errno code if failure

◆ rtc_set_time()

int rtc_set_time ( const struct device * dev,
const struct rtc_time * timeptr )

#include <zephyr/drivers/rtc.h>

API for setting RTC time.

Parameters
devDevice instance
timeptrThe time to set
Returns
0 if successful
-EINVAL if RTC time is invalid or exceeds hardware capabilities
-errno code if failure

◆ rtc_time_to_tm()

static struct tm * rtc_time_to_tm ( struct rtc_time * timeptr)
inlinestatic

#include <zephyr/drivers/rtc.h>

Convenience function for safely casting a rtc_time pointer to a tm pointer.

◆ rtc_update_set_callback()

int rtc_update_set_callback ( const struct device * dev,
rtc_update_callback callback,
void * user_data )

#include <zephyr/drivers/rtc.h>

API for setting update callback.

Setting the update callback will enable the update callback. The update callback will be invoked every time the RTC clock is updated by 1 second. It can be used to synchronize the RTC clock with other clock sources.

To disable the update callback for the RTC clock, the callback and user_data parameters must be set to NULL.

Parameters
devDevice instance
callbackCallback called when update occurs
user_dataOptional user data passed to callback
Returns
0 if successful
-ENOTSUP if API is not supported by hardware
-errno code if failure