RTC

Overview

This is a placeholder for API specific to real-time clocks. Currently all RTC peripherals are implemented through Counter with device-specific API for counters with real-time support.

API Reference

group rtc_interface

RTC DS3231 Driver-Specific API.

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.

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.

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

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 compatible with this type are subject to all the constraints of sys_notify_generic_callback.

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

Functions

static inline uint32_t maxim_ds3231_read_syncclock(const struct device *dev)

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.

static inline uint32_t maxim_ds3231_syncclock_frequency(const struct device *dev)

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.

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.

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.

Note

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.

Note

This function is supervisor.

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

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.

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.

Note

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.

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

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.

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

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.

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

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

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

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

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

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

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.

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

int maxim_ds3231_check_alarms(const struct device *dev)

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.

struct maxim_ds3231_alarm

#include <maxim_ds3231.h>

Information defining the alarm configuration.

DS3231 alarms can be set to fire at specific times or at the rollover of minute, hour, day, or day of week.

When an alarm is configured with a handler an interrupt will be generated and the handler called from the system work queue.

When an alarm is configured without a handler, or a persisted alarm is present, alarms can be read using maxim_ds3231_check_alarms().

Public Members

time_t time

Time specification for an RTC alarm.

Though specified as a UNIX time, the alarm parameters are determined by converting to civil time and interpreting the component hours, minutes, seconds, day-of-week, and day-of-month fields, mediated by the corresponding flags.

The year and month are ignored, but be aware that gmtime() determines day-of-week based on calendar date. Decoded alarm times will fall within 1978-01 since 1978-01-01 (first of month) was a Sunday (first of week).

maxim_ds3231_alarm_callback_handler_t handler

Handler to be invoked when alarms are signalled.

If this is null the alarm will not be triggered by the INTn/SQW GPIO. This is a “persisted” alarm from its role in using the DS3231 to trigger a wake from deep sleep. The application should use maxim_ds3231_check_alarms() to determine whether such an alarm has been triggered.

If this is not null the driver will monitor the ISW GPIO for alarm signals and will invoke the handler with a parameter carrying the value returned by maxim_ds3231_check_alarms(). The corresponding status flags will be cleared in the device before the handler is invoked.

The handler will be invoked from the system work queue.

void *user_data: User-provided pointer passed to alarm callback.

uint8_t flags

Flags controlling configuration of the alarm alarm.

See MAXIM_DS3231_ALARM_FLAGS_IGNSE and related constants.

Note that as described the alarm mask fields require that if a unit is not ignored, higher-precision units must also not be ignored. For example, if match on hours is enabled, match on minutes and seconds must also be enabled. Failure to comply with this requirement will cause maxim_ds3231_set_alarm() to return an error, leaving the alarm configuration unchanged.

struct maxim_ds3231_syncpoint

#include <maxim_ds3231.h>

Register the RTC clock against system clocks.

This captures the same instant in both the RTC time scale and a stable system clock scale, allowing conversion between those scales.

Public Members

struct timespec rtc

Time from the DS3231.

This maybe in UTC, TAI, or local offset depending on how the RTC is maintained.

uint32_t syncclock

Value of a local clock at the same instant as rtc.

This is captured from a stable monotonic system clock running at between 1 kHz and 1 MHz, allowing for microsecond to millisecond accuracy in synchronization.