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.

Parameters

  • dev: the device from which the callback originated

  • 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.

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.

Parameters

  • dev: the DS3231 device pointer

  • notify: the notification structure provided in the call

  • res: the result of the operation.

Functions

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.

Return

the current value of the synchronization clock.

Parameters

  • dev: the DS3231 device pointer

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().

Return

the frequency of the selected synchronization clock.

Parameters

  • dev: the DS3231 device pointer

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.

Return

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.

Return

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

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.

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.

Return

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

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.

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.

Return

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

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.

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 Value

  • 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 Value

  • 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 Value

  • 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 Value

  • 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.

Return

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

Parameters

  • dev: the DS3231 device pointer.

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().

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.