RTC HAL APIs

Data Structures
struct	IotRtcDatetime_t
	RTC date and time format info. More...

Macros
#define	IOT_RTC_SUCCESS   ( 0 )
	Return values used by RTC driver. More...
#define	IOT_RTC_INVALID_VALUE   ( 1 )
#define	IOT_RTC_NOT_STARTED   ( 2 )
#define	IOT_RTC_GET_FAILED   ( 3 )
#define	IOT_RTC_SET_FAILED   ( 4 )
#define	IOT_RTC_FUNCTION_NOT_SUPPORTED   ( 5 )

Typedefs
typedef struct IotRtcDescriptor_t *	IotRtcHandle_t
	IotRtcHandle_t type is the RTC handle returned by calling iot_rtc_open() this is initialized in open and returned to caller. Caller must pass this pointer to the rest of the APIs.
typedef void(*	IotRtcCallback_t) (IotRtcStatus_t xStatus, void *pvUserContext)
	RTC notification callback type. This callback is passed to the driver by using iot_rtc_set_callback API. The callback is used to get the notifications for Alarm and Wakeup timers. More...

Enumerations
enum	IotRtcStatus_t { eRtcTimerStopped, eRtcTimerRunning, eRtcTimerAlarmTriggered, eRtcTimerWakeupTriggered }
	RTC driver status values. More...
enum	IotRtcIoctlRequest_t {   eSetRtcAlarm, eGetRtcAlarm, eCancelRtcAlarm, eSetRtcWakeupTime,   eGetRtcWakeupTime, eCancelRtcWakeup, eGetRtcStatus }
	Ioctl request types. More...

Functions
IotRtcHandle_t	iot_rtc_open (int32_t lRtcInstance)
	iot_rtc_open is used to initialize the RTC timer. It usually resets the RTC timer, sets up the clock for RTC etc... More...
void	iot_rtc_set_callback (IotRtcHandle_t const pxRtcHandle, IotRtcCallback_t xCallback, void *pvUserContext)
	iot_rtc_set_callback is used to set the callback to be called when alarmTime triggers. The caller must set the Alarm time using IOCTL to get the callback. More...
int32_t	iot_rtc_ioctl (IotRtcHandle_t const pxRtcHandle, IotRtcIoctlRequest_t xRequest, void *const pvBuffer)
	iot_rtc_ioctl is used to set RTC configuration and RTC properties like Wakeup time, alarms etc. Supported IOCTL requests are defined in iot_RtcIoctlRequest_t More...
int32_t	iot_rtc_set_datetime (IotRtcHandle_t const pxRtcHandle, const IotRtcDatetime_t *pxDatetime)
	iot_rtc_set_date_time is used to set the current time as a reference in RTC timer counter. More...
int32_t	iot_rtc_get_datetime (IotRtcHandle_t const pxRtcHandle, IotRtcDatetime_t *pxDatetime)
	iot_rtc_get_datetime is used to get the current time from the RTC counter. The time must be set first as a reference to get the time. More...
int32_t	iot_rtc_close (IotRtcHandle_t const pxRtcHandle)
	iot_rtc_close is used to de-Initialize RTC Timer. it resets the RTC timer and may stop the timer. More...

Detailed Description

Macro Definition Documentation

IOT_RTC_SUCCESS

#define IOT_RTC_SUCCESS   ( 0 )

Return values used by RTC driver.

RTC operation completed successfully.

IOT_RTC_INVALID_VALUE

#define IOT_RTC_INVALID_VALUE   ( 1 )

At least one parameter is invalid.

IOT_RTC_NOT_STARTED

#define IOT_RTC_NOT_STARTED   ( 2 )

RTC not started.

IOT_RTC_GET_FAILED

#define IOT_RTC_GET_FAILED   ( 3 )

RTC get operation failed.

IOT_RTC_SET_FAILED

#define IOT_RTC_SET_FAILED   ( 4 )

RTC set operation failed.

IOT_RTC_FUNCTION_NOT_SUPPORTED

#define IOT_RTC_FUNCTION_NOT_SUPPORTED   ( 5 )

RTC operation not supported.

Typedef Documentation

IotRtcCallback_t

typedef void( * IotRtcCallback_t) (IotRtcStatus_t xStatus, void *pvUserContext)

RTC notification callback type. This callback is passed to the driver by using iot_rtc_set_callback API. The callback is used to get the notifications for Alarm and Wakeup timers.

Parameters

[out]	xStatus	RTC timer status.
[in]	pvUserContext	User Context passed when setting the callback. This is not used by the driver, but just passed back to the user in the callback.

Enumeration Type Documentation

IotRtcStatus_t

enum IotRtcStatus_t

RTC driver status values.

Enumerator
eRtcTimerStopped	RTC Timer status: stopped.
eRtcTimerRunning	RTC Timer status: running.
eRtcTimerAlarmTriggered	RTC Timer status: alarm triggered.
eRtcTimerWakeupTriggered	RTC Timer status: wakeup triggered.

IotRtcIoctlRequest_t

enum IotRtcIoctlRequest_t

Ioctl request types.

Note

: WakeupTime is a timer, in milliseconds in the future. AlarmTime is an exact time in the future.

Enumerator
eSetRtcAlarm	Set Alarm, date&time when Alarm need to occur. Takes input type IotRtcDatetime_t Warning time must be in the future.
eGetRtcAlarm	Get Alarm, gives the date&time when Alarm will occur. Returns IotRtcDatetime_t
eCancelRtcAlarm	Cancel any scheduled Alarm
eSetRtcWakeupTime	Set Wakeup time in miliseconds. Maximum number of miliseconds depend on the platform. Value is uint32_t
eGetRtcWakeupTime	Get Wakeup time in milli-seconds
eCancelRtcWakeup	Cancel any scheduled wake-up
eGetRtcStatus	Get the RTC timer status value. Returns IotRtcStatus_t type

Function Documentation

iot_rtc_open()

IotRtcHandle_t iot_rtc_open

(

int32_t

lRtcInstance

)

iot_rtc_open is used to initialize the RTC timer. It usually resets the RTC timer, sets up the clock for RTC etc...

Parameters

[in]

lRtcInstance

The instance of the RTC timer to initialize.

Returns

• the handle IotRtcHandle_t on success
• NULL if
  • if instance is already open
  • invalid instance

iot_rtc_set_callback()

void iot_rtc_set_callback	(	IotRtcHandle_t const	pxRtcHandle,
		IotRtcCallback_t	xCallback,
		void *	pvUserContext
	)

iot_rtc_set_callback is used to set the callback to be called when alarmTime triggers. The caller must set the Alarm time using IOCTL to get the callback.

Note

Single callback is used for both rtc_alarm, and rtc_wakeup features.

Newly set callback overrides the one previously set

This callback is per handle. Each instance has its own callback.

Parameters

[in]	pxRtcHandle	handle to RTC driver returned in iot_rtc_open()
[in]	xCallback	callback function to be called.
[in]	pvUserContext	user context to be passed when callback is called.

iot_rtc_ioctl()

int32_t iot_rtc_ioctl	(	IotRtcHandle_t const	pxRtcHandle,
		IotRtcIoctlRequest_t	xRequest,
		void *const	pvBuffer
	)

iot_rtc_ioctl is used to set RTC configuration and RTC properties like Wakeup time, alarms etc. Supported IOCTL requests are defined in iot_RtcIoctlRequest_t

Parameters

[in]	pxRtcHandle	handle to RTC driver returned in iot_rtc_open()
[in]	xRequest	configuration request of type IotRtcIoctlRequest_t
[in,out]	pvBuffer	buffer holding RTC set and get values.

Returns

• IOT_RTC_SUCCESS on success
• IOT_RTC_INVALID_VALUE if
  • pxRtcHandle == NULL
  • xRequest is invalid
  • pvBuffer == NULL (excluding eCancelRtcAlarm, eCancelRtcWakeup)
  • if date/time is set in the past for eSetRtcAlarm
• IOT_RTC_NOT_STARTED on error
• IOT_RTC_FUNCTION_NOT_SUPPORTED if feature not supported
  • Only valid for eCancelRtcAlarm, eCancelRtcWakeup

iot_rtc_set_datetime()

int32_t iot_rtc_set_datetime	(	IotRtcHandle_t const	pxRtcHandle,
		const IotRtcDatetime_t *	pxDatetime
	)

iot_rtc_set_date_time is used to set the current time as a reference in RTC timer counter.

Parameters

[in]	pxRtcHandle	handle to RTC driver returned in iot_rtc_open()
[in]	pxDatetime	pointer to IotRtcDatetime_t structure to set the date&time to be set in RTC counter.

Returns

• IOT_RTC_SUCCESS on success
• IOT_RTC_INVALID_VALUE if pxRtcHandle == NULL or pxDatetime == NULL
• IOT_RTC_SET_FAILED on error.

iot_rtc_get_datetime()

int32_t iot_rtc_get_datetime	(	IotRtcHandle_t const	pxRtcHandle,
		IotRtcDatetime_t *	pxDatetime
	)

iot_rtc_get_datetime is used to get the current time from the RTC counter. The time must be set first as a reference to get the time.

Parameters

[in]	pxRtcHandle	handle to RTC driver returned in iot_rtc_open()
[in]	pxDatetime	pointer to IotRtcDatetime_t structure to get the date&time from RTC counter.

Returns

• IOT_RTC_SUCCESS on success
• IOT_RTC_INVALID_VALUE if pxRtcHandle == NULL or pxDatetime == NULL
• IOT_RTC_NOT_STARTED on error

iot_rtc_close()

int32_t iot_rtc_close

(

IotRtcHandle_t const

pxRtcHandle

)

iot_rtc_close is used to de-Initialize RTC Timer. it resets the RTC timer and may stop the timer.

Parameters

[in]

pxRtcHandle

handle to RTC interface.

Returns

• IOT_RTC_SUCCESS on success
• IOT_RTC_INVALID_VALUE if
  • pxRtcHandle == NULL
  • not in open state (already closed).