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 tm *	rtc_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)

#include <zephyr/drivers/rtc.h>

◆ RTC_ALARM_TIME_MASK_MINUTE

#define RTC_ALARM_TIME_MASK_MINUTE BIT(1)

#include <zephyr/drivers/rtc.h>

◆ RTC_ALARM_TIME_MASK_MONTH

#define RTC_ALARM_TIME_MASK_MONTH BIT(4)

#include <zephyr/drivers/rtc.h>

◆ RTC_ALARM_TIME_MASK_MONTHDAY

#define RTC_ALARM_TIME_MASK_MONTHDAY BIT(3)

#include <zephyr/drivers/rtc.h>

◆ RTC_ALARM_TIME_MASK_NSEC

#define RTC_ALARM_TIME_MASK_NSEC BIT(8)

#include <zephyr/drivers/rtc.h>

◆ RTC_ALARM_TIME_MASK_SECOND

#define RTC_ALARM_TIME_MASK_SECOND BIT(0)

#include <zephyr/drivers/rtc.h>

◆ RTC_ALARM_TIME_MASK_WEEKDAY

#define RTC_ALARM_TIME_MASK_WEEKDAY BIT(6)

#include <zephyr/drivers/rtc.h>

◆ RTC_ALARM_TIME_MASK_YEAR

#define RTC_ALARM_TIME_MASK_YEAR BIT(5)

#include <zephyr/drivers/rtc.h>

◆ RTC_ALARM_TIME_MASK_YEARDAY

#define RTC_ALARM_TIME_MASK_YEARDAY BIT(7)

#include <zephyr/drivers/rtc.h>

Typedef Documentation

◆ rtc_alarm_callback

rtc_alarm_callback

#include <zephyr/drivers/rtc.h>

RTC alarm triggered callback.

Parameters

dev	Device instance invoking the handler
id	Alarm id
user_data	Optional user data passed with the alarm configuration

◆ rtc_update_callback

rtc_update_callback

#include <zephyr/drivers/rtc.h>

RTC update event callback.

Parameters

dev	Device instance invoking the handler
user_data	Optional 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

dev	Device instance
id	Id of the alarm
mask	Mask 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

dev	Device instance
id	Id of the alarm
mask	Destination for mask of fields which are enabled in the alarm time
timeptr	Destination 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

dev	Device instance
id	Id 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

dev	Device instance
id	Id of the alarm for which the callback shall be set
callback	Callback called when alarm occurs
user_data	Optional 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

dev	Device instance
id	Id of the alarm
mask	Mask of fields in the alarm time to enable
timeptr	The 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

frequency Frequency 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

dev	Device instance
calibration	Destination 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

dev	Device instance
timeptr	Destination 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

dev	Device instance
calibration	Calibration 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

dev	Device instance
timeptr	The 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

dev	Device instance
callback	Callback called when update occurs
user_data	Optional user data passed to callback

Returns: 0 if successful; -ENOTSUP if API is not supported by hardware; -errno code if failure

Data Structures

Typedefs

Functions

RTC Interface Alarm

RTC Interface Update

RTC Interface Calibration

RTC Interface Helpers

RTC Alarm Time Mask

Detailed Description

Macro Definition Documentation

◆ RTC_ALARM_TIME_MASK_HOUR

◆ RTC_ALARM_TIME_MASK_MINUTE

◆ RTC_ALARM_TIME_MASK_MONTH

◆ RTC_ALARM_TIME_MASK_MONTHDAY

◆ RTC_ALARM_TIME_MASK_NSEC

◆ RTC_ALARM_TIME_MASK_SECOND

◆ RTC_ALARM_TIME_MASK_WEEKDAY

◆ RTC_ALARM_TIME_MASK_YEAR

◆ RTC_ALARM_TIME_MASK_YEARDAY

Typedef Documentation

◆ rtc_alarm_callback

◆ rtc_update_callback

Function Documentation

◆ rtc_alarm_get_supported_fields()

◆ rtc_alarm_get_time()

◆ rtc_alarm_is_pending()

◆ rtc_alarm_set_callback()

◆ rtc_alarm_set_time()

◆ rtc_calibration_from_frequency()

◆ rtc_get_calibration()

◆ rtc_get_time()

◆ rtc_set_calibration()

◆ rtc_set_time()

◆ rtc_time_to_tm()

◆ rtc_update_set_callback()