RTC DS3231 Interface

RTC DS3231 Driver-Specific API . More...

Data Structures
struct	maxim_ds3231_alarm
	Information defining the alarm configuration. More...
struct	maxim_ds3231_syncpoint
	Register the RTC clock against system clocks. More...

Typedefs
typedef void(*	maxim_ds3231_alarm_callback_handler_t) (const struct device *dev, uint8_t id, uint32_t syncclock, void *user_data)
	Signature for DS3231 alarm callbacks.
typedef void(*	maxim_ds3231_notify_callback) (const struct device *dev, struct sys_notify *notify, int res)
	Signature used to notify a user of the DS3231 that an asynchronous operation has completed.

Functions
static uint32_t	maxim_ds3231_read_syncclock (const struct device *dev)
	Read the local synchronization clock.
static uint32_t	maxim_ds3231_syncclock_frequency (const struct device *dev)
	Get the frequency of the synchronization clock.
int	maxim_ds3231_ctrl_update (const struct device *dev, uint8_t set_bits, uint8_t clear_bits)
	Set and clear specific bits in the control register.
int	maxim_ds3231_stat_update (const struct device *dev, uint8_t set_bits, uint8_t clear_bits)
	Read the ctrl_stat register then set and clear bits in it.
int	maxim_ds3231_get_alarm (const struct device *dev, uint8_t id, struct maxim_ds3231_alarm *cfg)
	Read a DS3231 alarm configuration.
int	maxim_ds3231_set_alarm (const struct device *dev, uint8_t id, const struct maxim_ds3231_alarm *cfg)
	Configure a DS3231 alarm.
int	maxim_ds3231_synchronize (const struct device *dev, struct sys_notify *notify)
	Synchronize the RTC against the local clock.
int	maxim_ds3231_req_syncpoint (const struct device *dev, struct k_poll_signal *signal)
	Request to update the synchronization point.
int	maxim_ds3231_get_syncpoint (const struct device *dev, struct maxim_ds3231_syncpoint *syncpoint)
	Retrieve the most recent synchronization point.
int	maxim_ds3231_set (const struct device *dev, const struct maxim_ds3231_syncpoint *syncpoint, struct sys_notify *notify)
	Set the RTC to a time consistent with the provided synchronization.
int	maxim_ds3231_check_alarms (const struct device *dev)
	Check for and clear flags indicating that an alarm has fired.

Detailed Description

RTC DS3231 Driver-Specific API .

Typedef Documentation

maxim_ds3231_alarm_callback_handler_t

typedef void(* maxim_ds3231_alarm_callback_handler_t) (const struct device *dev, uint8_t id, uint32_t syncclock, void *user_data)

#include <zephyr/drivers/rtc/maxim_ds3231.h>

Signature for DS3231 alarm callbacks.

The alarm callback is invoked from the system work queue thread. At the point the callback is invoked the corresponding alarm flags will have been cleared from the device status register. The callback is permitted to invoke operations on the device.

Parameters

dev	the device from which the callback originated
id	the alarm id
syncclock	the value from maxim_ds3231_read_syncclock() at the time the alarm interrupt was processed.
user_data	the corresponding parameter from maxim_ds3231_alarm::user_data.

maxim_ds3231_notify_callback

typedef void(* maxim_ds3231_notify_callback) (const struct device *dev, struct sys_notify *notify, int res)

#include <zephyr/drivers/rtc/maxim_ds3231.h>

Signature used to notify a user of the DS3231 that an asynchronous operation has completed.

Functions compatible with this type are subject to all the constraints of sys_notify_generic_callback.

Parameters

dev	the DS3231 device pointer
notify	the notification structure provided in the call
res	the result of the operation.

Function Documentation

maxim_ds3231_check_alarms()

int maxim_ds3231_check_alarms

(

const struct device *

dev

)

#include <zephyr/drivers/rtc/maxim_ds3231.h>

Check for and clear flags indicating that an alarm has fired.

Returns a mask indicating alarms that are marked as having fired, and clears from stat the flags that it found set. Alarms that have been configured with a callback are not represented in the return value.

This API may be used when a persistent alarm has been programmed.

Note

This function is supervisor.

Parameters

dev	the DS3231 device pointer.

Returns

a non-negative value that may have MAXIM_DS3231_ALARM1 and/or MAXIM_DS3231_ALARM2 set, or a negative error code.

maxim_ds3231_ctrl_update()

int maxim_ds3231_ctrl_update	(	const struct device *	dev,
		uint8_t	set_bits,
		uint8_t	clear_bits )

#include <zephyr/drivers/rtc/maxim_ds3231.h>

Set and clear specific bits in the control register.

Note

This function assumes the device register cache is valid. It will not read the register value, and it will write to the device only if the value changes as a result of applying the set and clear changes.

Unlike maxim_ds3231_stat_update() the return value from this function indicates the register value after changes were made. That return value is cached for use in subsequent operations.

This function is supervisor.

Returns

the non-negative updated value of the register, or a negative error code from an I2C transaction.

maxim_ds3231_get_alarm()

int maxim_ds3231_get_alarm	(	const struct device *	dev,
		uint8_t	id,
		struct maxim_ds3231_alarm *	cfg )

#include <zephyr/drivers/rtc/maxim_ds3231.h>

Read a DS3231 alarm configuration.

The alarm configuration data is read from the device and reconstructed into the output parameter.

Note

This function is supervisor.

Parameters

dev	the DS3231 device pointer.
id	the alarm index, which must be 0 (for the 1 s resolution alarm) or 1 (for the 1 min resolution alarm).
cfg	a pointer to a structure into which the configured alarm data will be stored.

Returns

a non-negative value indicating successful conversion, or a negative error code from an I2C transaction or invalid parameter.

maxim_ds3231_get_syncpoint()

int maxim_ds3231_get_syncpoint	(	const struct device *	dev,
		struct maxim_ds3231_syncpoint *	syncpoint )

#include <zephyr/drivers/rtc/maxim_ds3231.h>

Retrieve the most recent synchronization point.

This function returns the synchronization data last captured using maxim_ds3231_synchronize().

Parameters

dev	the DS3231 device pointer.
syncpoint	where to store the synchronization data.

Return values

non-negative	on success
-ENOENT	if no syncpoint has been captured

maxim_ds3231_read_syncclock()

static uint32_t maxim_ds3231_read_syncclock ( const struct device * dev )

inlinestatic

#include <zephyr/drivers/rtc/maxim_ds3231.h>

Read the local synchronization clock.

Synchronization aligns the DS3231 real-time clock with a stable monotonic local clock which should have a frequency between 1 kHz and 1 MHz and be itself synchronized with the primary system time clock. The accuracy of the alignment and the maximum time between synchronization updates is affected by the resolution of this clock.

On some systems the hardware clock from k_cycles_get_32() is suitable, but on others that clock advances too quickly. The frequency of the target-specific clock is provided by maxim_ds3231_syncclock_frequency().

At this time the value is captured from k_uptime_get_32(); future kernel extensions may make a higher-resolution clock available.

Note

This function is isr-ok.

Parameters

dev	the DS3231 device pointer

Returns

the current value of the synchronization clock.

maxim_ds3231_req_syncpoint()

int maxim_ds3231_req_syncpoint	(	const struct device *	dev,
		struct k_poll_signal *	signal )

#include <zephyr/drivers/rtc/maxim_ds3231.h>

Request to update the synchronization point.

This is a variant of maxim_ds3231_synchronize() for use from user threads.

Parameters

dev	the DS3231 device pointer.
signal	pointer to a valid and ready-to-be-signalled k_poll_signal. May be NULL to request a synchronization point be collected without notifying when it has been updated.

Return values

non-negative	on success
-EBUSY	if a synchronization or set is currently in progress
-ENOTSUP	if the required interrupt is not configured

maxim_ds3231_set()

int maxim_ds3231_set	(	const struct device *	dev,
		const struct maxim_ds3231_syncpoint *	syncpoint,
		struct sys_notify *	notify )

#include <zephyr/drivers/rtc/maxim_ds3231.h>

Set the RTC to a time consistent with the provided synchronization.

The RTC advances one tick per second with no access to sub-second precision, and setting the clock resets the internal countdown chain. This function implements the magic necessary to set the clock while retaining as much sub-second accuracy as possible. It requires a synchronization point that pairs sub-second resolution civil time with a local synchronization clock captured at the same instant. The set operation may take as long as 1 second to complete; notification of completion is provided through the notify parameter.

Note

This function is supervisor.

Parameters

dev	the DS3231 device pointer.
syncpoint	the structure providing the synchronization point.
notify	pointer to the object used to specify asynchronous function behavior and store completion information.

Return values

non-negative	on success
-EINVAL	if syncpoint or notify are null
-ENOTSUP	if the required interrupt signal is not configured
-EBUSY	if a synchronization or set is currently in progress

maxim_ds3231_set_alarm()

int maxim_ds3231_set_alarm	(	const struct device *	dev,
		uint8_t	id,
		const struct maxim_ds3231_alarm *	cfg )

#include <zephyr/drivers/rtc/maxim_ds3231.h>

Configure a DS3231 alarm.

The alarm configuration is validated and stored into the device.

To cancel an alarm use counter_cancel_channel_alarm().

Note

This function is supervisor.

Parameters

dev	the DS3231 device pointer.
id	0 Analog to counter index. ALARM1 is 0 and has 1 s resolution, ALARM2 is 1 and has 1 minute resolution.
cfg	a pointer to the desired alarm configuration. Both alarms are configured; if only one is to change the application must supply the existing configuration for the other.

Returns

a non-negative value on success, or a negative error code from an I2C transaction or an invalid parameter.

maxim_ds3231_stat_update()

int maxim_ds3231_stat_update	(	const struct device *	dev,
		uint8_t	set_bits,
		uint8_t	clear_bits )

#include <zephyr/drivers/rtc/maxim_ds3231.h>

Read the ctrl_stat register then set and clear bits in it.

The content of the ctrl_stat register will be read, then the set and clear bits applied and the result written back to the device (regardless of whether there appears to be a change in value).

OSF, A1F, and A2F will be written with 1s if the corresponding bits do not appear in either set_bits or clear_bits. This ensures that if any flag becomes set between the read and the write that indicator will not be cleared.

Note

Unlike maxim_ds3231_ctrl_update() the return value from this function indicates the register value before any changes were made.

This function is supervisor.

Parameters

dev	the DS3231 device pointer
set_bits	bits to be set when writing back. Setting bits other than MAXIM_DS3231_REG_STAT_EN32kHz will have no effect.
clear_bits	bits to be cleared when writing back. Include the bits for the status flags you want to clear.

Returns

the non-negative register value as originally read (disregarding the effect of clears and sets), or a negative error code from an I2C transaction.

maxim_ds3231_syncclock_frequency()

static uint32_t maxim_ds3231_syncclock_frequency ( const struct device * dev )

inlinestatic

#include <zephyr/drivers/rtc/maxim_ds3231.h>

Get the frequency of the synchronization clock.

Provides the frequency of the clock used in maxim_ds3231_read_syncclock().

Parameters

dev	the DS3231 device pointer

Returns

the frequency of the selected synchronization clock.

maxim_ds3231_synchronize()

int maxim_ds3231_synchronize	(	const struct device *	dev,
		struct sys_notify *	notify )

#include <zephyr/drivers/rtc/maxim_ds3231.h>

Synchronize the RTC against the local clock.

The RTC advances one tick per second with no access to sub-second precision. Synchronizing clocks at sub-second resolution requires enabling a 1pps signal then capturing the system clocks in a GPIO callback. This function provides that operation.

Synchronization is performed in asynchronously, and may take as long as 1 s to complete; notification of completion is provided through the notify parameter.

Applications should use maxim_ds3231_get_syncpoint() to retrieve the synchronization data collected by this operation.

Note

This function is supervisor.

Parameters

dev	the DS3231 device pointer.
notify	pointer to the object used to specify asynchronous function behavior and store completion information.

Return values

non-negative	on success
-EBUSY	if a synchronization or set is currently in progress
-EINVAL	if notify is not provided
-ENOTSUP	if the required interrupt is not configured