Real-time clock control based on the DS3231 counter API. More...

#include <time.h>
#include <zephyr/drivers/counter.h>
#include <zephyr/kernel.h>
#include <zephyr/types.h>
#include <zephyr/sys/notify.h>
#include <zephyr/syscalls/maxim_ds3231.h>

Data Structures
struct	maxim_ds3231_alarm
	Information defining the alarm configuration. More...

struct	maxim_ds3231_syncpoint
	Register the RTC clock against system clocks. More...

Macros
#define	MAXIM_DS3231_ALARM1 BIT(0)
	Bit in ctrl or ctrl_stat associated with alarm 1.

#define	MAXIM_DS3231_ALARM2 BIT(1)
	Bit in ctrl or ctrl_stat associated with alarm 2.

#define	MAXIM_DS3231_REG_CTRL_A1IE MAXIM_DS3231_ALARM1
	ctrl bit for alarm 1 interrupt enable.

#define	MAXIM_DS3231_REG_CTRL_A2IE MAXIM_DS3231_ALARM2
	ctrl bit for alarm 2 interrupt enable.

#define	MAXIM_DS3231_REG_CTRL_INTCN BIT(2)
	ctrl bit for ISQ functionality.

#define	MAXIM_DS3231_REG_CTRL_RS_Pos 3
	ctrl bit offset for square wave output frequency.

#define	MAXIM_DS3231_REG_CTRL_RS_Msk (0x03 << MAXIM_DS3231_REG_CTRL_RS_Pos)
	ctrl mask to isolate RS bits.

#define	MAXIM_DS3231_REG_CTRL_RS_1Hz 0x00
	ctrl RS field value for 1 Hz square wave.

#define	MAXIM_DS3231_REG_CTRL_RS_1KiHz 0x01
	ctrl RS field value for 1024 Hz square wave.

#define	MAXIM_DS3231_REG_CTRL_RS_4KiHz 0x02
	ctrl RS field value for 4096 Hz square wave.

#define	MAXIM_DS3231_REG_CTRL_RS_8KiHz 0x03
	ctrl RS field value for 8192 Hz square wave.

#define	MAXIM_DS3231_REG_CTRL_CONV BIT(5)
	ctrl bit to write to trigger temperature conversion.

#define	MAXIM_DS3231_REG_CTRL_BBSQW BIT(6)
	ctrl bit to write to enable square wave output in battery mode.

#define	MAXIM_DS3231_REG_CTRL_EOSCn BIT(7),
	ctrl bit to write to disable the oscillator.

#define	MAXIM_DS3231_REG_STAT_A1F MAXIM_DS3231_ALARM1
	ctrl_stat bit indicating alarm1 has triggered.

#define	MAXIM_DS3231_REG_STAT_A2F MAXIM_DS3231_ALARM2
	ctrl_stat bit indicating alarm2 has triggered.

#define	MAXIM_DS3231_REG_STAT_BSY BIT(2)
	Flag indicating a temperature conversion is in progress.

#define	MAXIM_DS3231_REG_STAT_EN32kHz BIT(3)
	Set to enable 32 KiHz open drain signal.

#define	MAXIM_DS3231_REG_STAT_OSF BIT(7)
	Flag indicating the oscillator has been off since last cleared.

#define	MAXIM_DS3231_ALARM_FLAGS_IGNSE BIT(0)
	Control alarm behavior on match in seconds field.

#define	MAXIM_DS3231_ALARM_FLAGS_IGNMN BIT(1)
	Control alarm behavior on match in minutes field.

#define	MAXIM_DS3231_ALARM_FLAGS_IGNHR BIT(2)
	Control alarm behavior on match in hours field.

#define	MAXIM_DS3231_ALARM_FLAGS_IGNDA BIT(3)
	Control alarm behavior on match in day/date field.

#define	MAXIM_DS3231_ALARM_FLAGS_DOW BIT(4)
	Control match on day of week versus day of month.

#define	MAXIM_DS3231_ALARM_FLAGS_AUTODISABLE BIT(7)
	Indicates that the alarm should be disabled once it fires.

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

Real-time clock control based on the DS3231 counter API.

The Maxim DS3231 is a high-precision real-time clock with temperature-compensated crystal oscillator and support for configurable alarms.

The core Zephyr API to this device is as a counter, with the following limitations:

counter_read() and counter_*_alarm() cannot be invoked from interrupt context, as they require communication with the device over an I2C bus.
many other counter APIs, such as start/stop/set_top_value are not supported as the clock is always running.
two alarm channels are supported but are not equally capable: channel 0 supports alarms at 1 s resolution, while channel 1 supports alarms at 1 minute resolution.

Most applications for this device will need to use the extended functionality exposed by this header to access the real-time-clock features. The majority of these functions must be invoked from supervisor mode.

Macro Definition Documentation

◆ MAXIM_DS3231_ALARM1

#define MAXIM_DS3231_ALARM1 BIT(0)

Bit in ctrl or ctrl_stat associated with alarm 1.

◆ MAXIM_DS3231_ALARM2

#define MAXIM_DS3231_ALARM2 BIT(1)

Bit in ctrl or ctrl_stat associated with alarm 2.

◆ MAXIM_DS3231_ALARM_FLAGS_AUTODISABLE

#define MAXIM_DS3231_ALARM_FLAGS_AUTODISABLE BIT(7)

Indicates that the alarm should be disabled once it fires.

Set the flag in the maxim_ds3231_alarm_configuration::alarm_flags field to cause the alarm to be disabled when the interrupt fires, prior to invoking the corresponding handler.

Leave false to allow the alarm to remain enabled so it will fire again on the next match.

◆ MAXIM_DS3231_ALARM_FLAGS_DOW

#define MAXIM_DS3231_ALARM_FLAGS_DOW BIT(4)

Control match on day of week versus day of month.

Set the flag to match on day of week; clear it to match on day of month.

Bit maps to DY/DTn in corresponding maxim_ds3231_alarm_configuration::alarm_flags.

◆ MAXIM_DS3231_ALARM_FLAGS_IGNDA

#define MAXIM_DS3231_ALARM_FLAGS_IGNDA BIT(3)

Control alarm behavior on match in day/date field.

If clear the alarm fires only when the RTC day/date matches the alarm day/date, mediated by MAXIM_DS3231_ALARM_FLAGS_DAY. The bits for IGNHR, IGNMN, and IGNSE must be clear

If set the alarm day/date field is ignored and an alarm will be triggered based on IGNHR, IGNMN, and IGNSE.

Bit maps to A1M4 or A2M4 and is used in maxim_ds3231_alarm_configuration::alarm_flags.

◆ MAXIM_DS3231_ALARM_FLAGS_IGNHR

#define MAXIM_DS3231_ALARM_FLAGS_IGNHR BIT(2)

Control alarm behavior on match in hours field.

If clear the alarm fires only when the RTC hours matches the alarm hours. The bits for IGNMN and IGNSE must be clear.

If set the alarm hours field is ignored and alarms will be triggered based on IGNMN and IGNSE. The bit for IGNDA must be set.

Bit maps to A1M3 or A2M3 and is used in maxim_ds3231_alarm_configuration::alarm_flags.

◆ MAXIM_DS3231_ALARM_FLAGS_IGNMN

#define MAXIM_DS3231_ALARM_FLAGS_IGNMN BIT(1)

Control alarm behavior on match in minutes field.

If clear the alarm fires only when the RTC minutes matches the alarm minutes. The bit for IGNSE must be clear.

If set the alarm minutes field is ignored and alarms will be triggered based on IGNSE. The bits for IGNHR and IGNDA must both be set.

Bit maps to A1M2 or A2M2 and is used in maxim_ds3231_alarm_configuration::alarm_flags.

◆ MAXIM_DS3231_ALARM_FLAGS_IGNSE

#define MAXIM_DS3231_ALARM_FLAGS_IGNSE BIT(0)

Control alarm behavior on match in seconds field.

If clear the alarm fires only when the RTC seconds matches the alarm seconds.

If set the alarm seconds field is ignored and an alarm will be triggered every second. The bits for IGNMN, IGNHR, and IGNDA must all be set.

This bit must be clear for the second alarm instance.

Bit maps to A1M1 and is used in maxim_ds3231_alarm_configuration::alarm_flags.

◆ MAXIM_DS3231_REG_CTRL_A1IE

#define MAXIM_DS3231_REG_CTRL_A1IE MAXIM_DS3231_ALARM1

ctrl bit for alarm 1 interrupt enable.

◆ MAXIM_DS3231_REG_CTRL_A2IE

#define MAXIM_DS3231_REG_CTRL_A2IE MAXIM_DS3231_ALARM2

ctrl bit for alarm 2 interrupt enable.

◆ MAXIM_DS3231_REG_CTRL_BBSQW

#define MAXIM_DS3231_REG_CTRL_BBSQW BIT(6)

ctrl bit to write to enable square wave output in battery mode.

◆ MAXIM_DS3231_REG_CTRL_CONV

#define MAXIM_DS3231_REG_CTRL_CONV BIT(5)

ctrl bit to write to trigger temperature conversion.

◆ MAXIM_DS3231_REG_CTRL_EOSCn

#define MAXIM_DS3231_REG_CTRL_EOSCn BIT(7),

ctrl bit to write to disable the oscillator.

◆ MAXIM_DS3231_REG_CTRL_INTCN

#define MAXIM_DS3231_REG_CTRL_INTCN BIT(2)

ctrl bit for ISQ functionality.

When clear the ISW signal provides a square wave. When set the ISW signal indicates alarm events.

Note: The driver expects to be able to control this bit.

◆ MAXIM_DS3231_REG_CTRL_RS_1Hz

#define MAXIM_DS3231_REG_CTRL_RS_1Hz 0x00

ctrl RS field value for 1 Hz square wave.

◆ MAXIM_DS3231_REG_CTRL_RS_1KiHz

#define MAXIM_DS3231_REG_CTRL_RS_1KiHz 0x01

ctrl RS field value for 1024 Hz square wave.

◆ MAXIM_DS3231_REG_CTRL_RS_4KiHz

#define MAXIM_DS3231_REG_CTRL_RS_4KiHz 0x02

ctrl RS field value for 4096 Hz square wave.

◆ MAXIM_DS3231_REG_CTRL_RS_8KiHz

#define MAXIM_DS3231_REG_CTRL_RS_8KiHz 0x03

ctrl RS field value for 8192 Hz square wave.

◆ MAXIM_DS3231_REG_CTRL_RS_Msk

#define MAXIM_DS3231_REG_CTRL_RS_Msk (0x03 << MAXIM_DS3231_REG_CTRL_RS_Pos)

ctrl mask to isolate RS bits.

◆ MAXIM_DS3231_REG_CTRL_RS_Pos

#define MAXIM_DS3231_REG_CTRL_RS_Pos 3

ctrl bit offset for square wave output frequency.

Note: The driver will control the content of this field.

◆ MAXIM_DS3231_REG_STAT_A1F

#define MAXIM_DS3231_REG_STAT_A1F MAXIM_DS3231_ALARM1

ctrl_stat bit indicating alarm1 has triggered.

If an alarm callback handler is registered this bit is cleared prior to invoking the callback with the flags indicating which alarms are ready.

◆ MAXIM_DS3231_REG_STAT_A2F

#define MAXIM_DS3231_REG_STAT_A2F MAXIM_DS3231_ALARM2

ctrl_stat bit indicating alarm2 has triggered.

If an alarm callback handler is registered this bit is cleared prior to invoking the callback with the flags indicating which alarms are ready.

◆ MAXIM_DS3231_REG_STAT_BSY

#define MAXIM_DS3231_REG_STAT_BSY BIT(2)

Flag indicating a temperature conversion is in progress.

◆ MAXIM_DS3231_REG_STAT_EN32kHz

#define MAXIM_DS3231_REG_STAT_EN32kHz BIT(3)

Set to enable 32 KiHz open drain signal.

Note: This is a control bit, though it is positioned within the ctrl_stat register which otherwise contains status bits.

◆ MAXIM_DS3231_REG_STAT_OSF

#define MAXIM_DS3231_REG_STAT_OSF BIT(7)

Flag indicating the oscillator has been off since last cleared.

Data Structures

Macros

Typedefs

Functions