Zephyr API Documentation 3.7.99
A Scalable Open Source RTOS
|
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>
Go to the source code of this file.
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. | |
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.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.
#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_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.
#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.
#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.
#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.
#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.
#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.
#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_BBSQW BIT(6) |
ctrl bit to write to enable square wave output in battery mode.
#define MAXIM_DS3231_REG_CTRL_CONV BIT(5) |
ctrl bit to write to trigger temperature conversion.
#define MAXIM_DS3231_REG_CTRL_EOSCn BIT(7), |
ctrl bit to write to disable the oscillator.
#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.
#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_RS_Msk (0x03 << MAXIM_DS3231_REG_CTRL_RS_Pos) |
ctrl mask to isolate RS bits.
#define MAXIM_DS3231_REG_CTRL_RS_Pos 3 |
ctrl bit offset for square wave output frequency.
#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.
#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.
#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.