LCOV - code coverage report
Current view: top level - zephyr/drivers/rtc - maxim_ds3231.h Coverage Total Hit
Test: new.info Lines: 100.0 % 47 47
Test Date: 2025-09-05 16:43:28

            Line data    Source code
       1            1 : /*
       2              :  * Copyright (c) 2019 Peter Bigot Consulting, LLC
       3              :  *
       4              :  * SPDX-License-Identifier: Apache-2.0
       5              :  */
       6              : 
       7              : /**
       8              :  * @file
       9              :  * @brief Real-time clock control based on the DS3231 counter API.
      10              :  *
      11              :  * The [Maxim
      12              :  * DS3231](https://www.maximintegrated.com/en/products/analog/real-time-clocks/DS3231.html)
      13              :  * is a high-precision real-time clock with temperature-compensated
      14              :  * crystal oscillator and support for configurable alarms.
      15              :  *
      16              :  * The core Zephyr API to this device is as a counter, with the
      17              :  * following limitations:
      18              :  * * ``counter_read()`` and ``counter_*_alarm()`` cannot be invoked from
      19              :  *   interrupt context, as they require communication with the device
      20              :  *   over an I2C bus.
      21              :  * * many other counter APIs, such as start/stop/set_top_value are not
      22              :  *   supported as the clock is always running.
      23              :  * * two alarm channels are supported but are not equally capable:
      24              :  *   channel 0 supports alarms at 1 s resolution, while channel 1
      25              :  *   supports alarms at 1 minute resolution.
      26              :  *
      27              :  * Most applications for this device will need to use the extended
      28              :  * functionality exposed by this header to access the real-time-clock
      29              :  * features.  The majority of these functions must be invoked from
      30              :  * supervisor mode.
      31              :  */
      32              : #ifndef ZEPHYR_INCLUDE_DRIVERS_RTC_DS3231_H_
      33              : #define ZEPHYR_INCLUDE_DRIVERS_RTC_DS3231_H_
      34              : 
      35              : #include <time.h>
      36              : 
      37              : #include <zephyr/drivers/counter.h>
      38              : #include <zephyr/kernel.h>
      39              : #include <zephyr/types.h>
      40              : #include <zephyr/sys/notify.h>
      41              : 
      42              : #ifdef __cplusplus
      43              : extern "C" {
      44              : #endif
      45              : 
      46              : /** @brief Bit in ctrl or ctrl_stat associated with alarm 1. */
      47            1 : #define MAXIM_DS3231_ALARM1 BIT(0)
      48              : 
      49              : /** @brief Bit in ctrl or ctrl_stat associated with alarm 2. */
      50            1 : #define MAXIM_DS3231_ALARM2 BIT(1)
      51              : 
      52              : /* Constants corresponding to bits in the DS3231 control register at
      53              :  * 0x0E.
      54              :  *
      55              :  * See the datasheet for interpretation of these bits.
      56              :  */
      57              : /** @brief ctrl bit for alarm 1 interrupt enable. */
      58            1 : #define MAXIM_DS3231_REG_CTRL_A1IE MAXIM_DS3231_ALARM1
      59              : 
      60              : /** @brief ctrl bit for alarm 2 interrupt enable. */
      61            1 : #define MAXIM_DS3231_REG_CTRL_A2IE MAXIM_DS3231_ALARM2
      62              : 
      63              : /** @brief ctrl bit for ISQ functionality.
      64              :  *
      65              :  * When clear the ISW signal provides a square wave.  When set the ISW
      66              :  * signal indicates alarm events.
      67              :  *
      68              :  * @note The driver expects to be able to control this bit.
      69              :  */
      70            1 : #define MAXIM_DS3231_REG_CTRL_INTCN BIT(2)
      71              : 
      72              : /** @brief ctrl bit offset for square wave output frequency.
      73              :  *
      74              :  * @note The driver will control the content of this field.
      75              :  */
      76            1 : #define MAXIM_DS3231_REG_CTRL_RS_Pos 3
      77              : 
      78              : /** @brief ctrl mask to isolate RS bits. */
      79            1 : #define MAXIM_DS3231_REG_CTRL_RS_Msk (0x03 << MAXIM_DS3231_REG_CTRL_RS_Pos)
      80              : 
      81              : /** @brief ctrl RS field value for 1 Hz square wave. */
      82            1 : #define MAXIM_DS3231_REG_CTRL_RS_1Hz 0x00
      83              : 
      84              : /** @brief ctrl RS field value for 1024 Hz square wave. */
      85            1 : #define MAXIM_DS3231_REG_CTRL_RS_1KiHz 0x01
      86              : 
      87              : /** @brief ctrl RS field value for 4096 Hz square wave. */
      88            1 : #define MAXIM_DS3231_REG_CTRL_RS_4KiHz 0x02
      89              : 
      90              : /** @brief ctrl RS field value for 8192 Hz square wave. */
      91            1 : #define MAXIM_DS3231_REG_CTRL_RS_8KiHz 0x03
      92              : 
      93              : /** @brief ctrl bit to write to trigger temperature conversion. */
      94            1 : #define MAXIM_DS3231_REG_CTRL_CONV BIT(5)
      95              : 
      96              : /** @brief ctrl bit to write to enable square wave output in battery mode. */
      97            1 : #define MAXIM_DS3231_REG_CTRL_BBSQW BIT(6)
      98              : 
      99              : /** @brief ctrl bit to write to disable the oscillator. */
     100            1 : #define MAXIM_DS3231_REG_CTRL_EOSCn BIT(7),
     101              : 
     102              : /** @brief ctrl_stat bit indicating alarm1 has triggered.
     103              :  *
     104              :  * If an alarm callback handler is registered this bit is
     105              :  * cleared prior to invoking the callback with the flags
     106              :  * indicating which alarms are ready.
     107              :  */
     108            1 : #define MAXIM_DS3231_REG_STAT_A1F MAXIM_DS3231_ALARM1
     109              : 
     110              : /** @brief ctrl_stat bit indicating alarm2 has triggered.
     111              :  *
     112              :  * If an alarm callback handler is registered this bit is
     113              :  * cleared prior to invoking the callback with the flags
     114              :  * indicating which alarms are ready.
     115              :  */
     116            1 : #define MAXIM_DS3231_REG_STAT_A2F MAXIM_DS3231_ALARM2
     117              : 
     118              : /** @brief Flag indicating a temperature conversion is in progress. */
     119            1 : #define MAXIM_DS3231_REG_STAT_BSY BIT(2)
     120              : 
     121              : /** @brief Set to enable 32 KiHz open drain signal.
     122              :  *
     123              :  * @note This is a control bit, though it is positioned within the
     124              :  * ctrl_stat register which otherwise contains status bits.
     125              :  */
     126            1 : #define MAXIM_DS3231_REG_STAT_EN32kHz BIT(3)
     127              : 
     128              : /** @brief Flag indicating the oscillator has been off since last cleared. */
     129            1 : #define MAXIM_DS3231_REG_STAT_OSF BIT(7)
     130              : 
     131              : /** @brief Control alarm behavior on match in seconds field.
     132              :  *
     133              :  * If clear the alarm fires only when the RTC seconds matches the
     134              :  * alarm seconds.
     135              :  *
     136              :  * If set the alarm seconds field is ignored and an alarm will be
     137              :  * triggered every second.  The bits for IGNMN, IGNHR, and IGNDA must
     138              :  * all be set.
     139              :  *
     140              :  * This bit must be clear for the second alarm instance.
     141              :  *
     142              :  * Bit maps to A1M1 and is used in
     143              :  * maxim_ds3231_alarm_configuration::alarm_flags.
     144              :  */
     145            1 : #define MAXIM_DS3231_ALARM_FLAGS_IGNSE BIT(0)
     146              : 
     147              : /** @brief Control alarm behavior on match in minutes field.
     148              :  *
     149              :  * If clear the alarm fires only when the RTC minutes matches the
     150              :  * alarm minutes.  The bit for IGNSE must be clear.
     151              :  *
     152              :  * If set the alarm minutes field is ignored and alarms will be
     153              :  * triggered based on IGNSE. The bits for IGNHR and IGNDA must both be
     154              :  * set.
     155              :  *
     156              :  * Bit maps to A1M2 or A2M2 and is used in
     157              :  * maxim_ds3231_alarm_configuration::alarm_flags.
     158              :  */
     159            1 : #define MAXIM_DS3231_ALARM_FLAGS_IGNMN BIT(1)
     160              : 
     161              : /** @brief Control alarm behavior on match in hours field.
     162              :  *
     163              :  * If clear the alarm fires only when the RTC hours matches the
     164              :  * alarm hours.  The bits for IGNMN and IGNSE must be clear.
     165              :  *
     166              :  * If set the alarm hours field is ignored and alarms will be
     167              :  * triggered based on IGNMN and IGNSE.  The bit for IGNDA must be set.
     168              :  *
     169              :  * Bit maps to A1M3 or A2M3 and is used in
     170              :  * maxim_ds3231_alarm_configuration::alarm_flags.
     171              :  */
     172            1 : #define MAXIM_DS3231_ALARM_FLAGS_IGNHR BIT(2)
     173              : 
     174              : /** @brief Control alarm behavior on match in day/date field.
     175              :  *
     176              :  * If clear the alarm fires only when the RTC day/date matches the
     177              :  * alarm day/date, mediated by MAXIM_DS3231_ALARM_FLAGS_DAY.  The bits
     178              :  * for IGNHR, IGNMN, and IGNSE must be clear
     179              :  *
     180              :  * If set the alarm day/date field is ignored and an alarm will be
     181              :  * triggered based on IGNHR, IGNMN, and IGNSE.
     182              :  *
     183              :  * Bit maps to A1M4 or A2M4 and is used in
     184              :  * maxim_ds3231_alarm_configuration::alarm_flags.
     185              :  */
     186            1 : #define MAXIM_DS3231_ALARM_FLAGS_IGNDA BIT(3)
     187              : 
     188              : /** @brief Control match on day of week versus day of month
     189              :  *
     190              :  * Set the flag to match on day of week; clear it to match on day of
     191              :  * month.
     192              :  *
     193              :  * Bit maps to DY/DTn in corresponding
     194              :  * maxim_ds3231_alarm_configuration::alarm_flags.
     195              :  */
     196            1 : #define MAXIM_DS3231_ALARM_FLAGS_DOW BIT(4)
     197              : 
     198              : /** @brief Indicates that the alarm should be disabled once it fires.
     199              :  *
     200              :  * Set the flag in the maxim_ds3231_alarm_configuration::alarm_flags
     201              :  * field to cause the alarm to be disabled when the interrupt fires,
     202              :  * prior to invoking the corresponding handler.
     203              :  *
     204              :  * Leave false to allow the alarm to remain enabled so it will fire
     205              :  * again on the next match.
     206              :  */
     207            1 : #define MAXIM_DS3231_ALARM_FLAGS_AUTODISABLE BIT(7)
     208              : 
     209              : /**
     210              :  * @brief Interface for Maxim DS3231 RTC (using counter API).
     211              :  * @defgroup rtc_ds3231_interface RTC DS3231 (legacy).
     212              :  * @ingroup misc_interfaces
     213              :  * @deprecated Use MFD driver instead. See `maxim,ds3231-rtc` compatible.
     214              :  * @{
     215              :  */
     216              : 
     217              : /** @brief Signature for DS3231 alarm callbacks.
     218              :  *
     219              :  * The alarm callback is invoked from the system work queue thread.
     220              :  * At the point the callback is invoked the corresponding alarm flags
     221              :  * will have been cleared from the device status register.  The
     222              :  * callback is permitted to invoke operations on the device.
     223              :  *
     224              :  * @param dev the device from which the callback originated
     225              :  * @param id the alarm id
     226              :  * @param syncclock the value from maxim_ds3231_read_syncclock() at the
     227              :  * time the alarm interrupt was processed.
     228              :  * @param user_data the corresponding parameter from
     229              :  * maxim_ds3231_alarm::user_data.
     230              :  */
     231            1 : typedef void (*maxim_ds3231_alarm_callback_handler_t)(const struct device *dev,
     232              :                                                       uint8_t id,
     233              :                                                       uint32_t syncclock,
     234              :                                                       void *user_data);
     235              : 
     236              : /** @brief Signature used to notify a user of the DS3231 that an
     237              :  * asynchronous operation has completed.
     238              :  *
     239              :  * Functions compatible with this type are subject to all the
     240              :  * constraints of #sys_notify_generic_callback.
     241              :  *
     242              :  * @param dev the DS3231 device pointer
     243              :  *
     244              :  * @param notify the notification structure provided in the call
     245              :  *
     246              :  * @param res the result of the operation.
     247              :  */
     248            1 : typedef void (*maxim_ds3231_notify_callback)(const struct device *dev,
     249              :                                              struct sys_notify *notify,
     250              :                                              int res);
     251              : 
     252              : /** @brief Information defining the alarm configuration.
     253              :  *
     254              :  * DS3231 alarms can be set to fire at specific times or at the
     255              :  * rollover of minute, hour, day, or day of week.
     256              :  *
     257              :  * When an alarm is configured with a handler an interrupt will be
     258              :  * generated and the handler called from the system work queue.
     259              :  *
     260              :  * When an alarm is configured without a handler, or a persisted alarm
     261              :  * is present, alarms can be read using maxim_ds3231_check_alarms().
     262              :  */
     263            1 : struct maxim_ds3231_alarm {
     264              :         /** @brief Time specification for an RTC alarm.
     265              :          *
     266              :          * Though specified as a UNIX time, the alarm parameters are
     267              :          * determined by converting to civil time and interpreting the
     268              :          * component hours, minutes, seconds, day-of-week, and
     269              :          * day-of-month fields, mediated by the corresponding #flags.
     270              :          *
     271              :          * The year and month are ignored, but be aware that gmtime()
     272              :          * determines day-of-week based on calendar date.  Decoded
     273              :          * alarm times will fall within 1978-01 since 1978-01-01
     274              :          * (first of month) was a Sunday (first of week).
     275              :          */
     276            1 :         time_t time;
     277              : 
     278              :         /** @brief Handler to be invoked when alarms are signalled.
     279              :          *
     280              :          * If this is null the alarm will not be triggered by the
     281              :          * INTn/SQW GPIO.  This is a "persisted" alarm from its role
     282              :          * in using the DS3231 to trigger a wake from deep sleep.  The
     283              :          * application should use maxim_ds3231_check_alarms() to
     284              :          * determine whether such an alarm has been triggered.
     285              :          *
     286              :          * If this is not null the driver will monitor the ISW GPIO
     287              :          * for alarm signals and will invoke the handler with a
     288              :          * parameter carrying the value returned by
     289              :          * maxim_ds3231_check_alarms().  The corresponding status flags
     290              :          * will be cleared in the device before the handler is
     291              :          * invoked.
     292              :          *
     293              :          * The handler will be invoked from the system work queue.
     294              :          */
     295            1 :         maxim_ds3231_alarm_callback_handler_t handler;
     296              : 
     297              :         /** @brief User-provided pointer passed to alarm callback. */
     298            1 :         void *user_data;
     299              : 
     300              :         /** @brief Flags controlling configuration of the alarm alarm.
     301              :          *
     302              :          * See MAXIM_DS3231_ALARM_FLAGS_IGNSE and related constants.
     303              :          *
     304              :          * Note that as described the alarm mask fields require that
     305              :          * if a unit is not ignored, higher-precision units must also
     306              :          * not be ignored.  For example, if match on hours is enabled,
     307              :          * match on minutes and seconds must also be enabled.  Failure
     308              :          * to comply with this requirement will cause
     309              :          * maxim_ds3231_set_alarm() to return an error, leaving the
     310              :          * alarm configuration unchanged.
     311              :          */
     312            1 :         uint8_t flags;
     313              : };
     314              : 
     315              : /** @brief Register the RTC clock against system clocks.
     316              :  *
     317              :  * This captures the same instant in both the RTC time scale and a
     318              :  * stable system clock scale, allowing conversion between those
     319              :  * scales.
     320              :  */
     321            1 : struct maxim_ds3231_syncpoint {
     322              :         /** @brief Time from the DS3231.
     323              :          *
     324              :          * This maybe in UTC, TAI, or local offset depending on how
     325              :          * the RTC is maintained.
     326              :          */
     327            1 :         struct timespec rtc;
     328              : 
     329              :         /** @brief Value of a local clock at the same instant as #rtc.
     330              :          *
     331              :          * This is captured from a stable monotonic system clock
     332              :          * running at between 1 kHz and 1 MHz, allowing for
     333              :          * microsecond to millisecond accuracy in synchronization.
     334              :          */
     335            1 :         uint32_t syncclock;
     336              : };
     337              : 
     338              : /** @brief Read the local synchronization clock.
     339              :  *
     340              :  * Synchronization aligns the DS3231 real-time clock with a stable
     341              :  * monotonic local clock which should have a frequency between 1 kHz
     342              :  * and 1 MHz and be itself synchronized with the primary system time
     343              :  * clock.  The accuracy of the alignment and the maximum time between
     344              :  * synchronization updates is affected by the resolution of this
     345              :  * clock.
     346              :  *
     347              :  * On some systems the hardware clock from k_cycles_get_32() is
     348              :  * suitable, but on others that clock advances too quickly.  The
     349              :  * frequency of the target-specific clock is provided by
     350              :  * maxim_ds3231_syncclock_frequency().
     351              :  *
     352              :  * At this time the value is captured from `k_uptime_get_32()`; future
     353              :  * kernel extensions may make a higher-resolution clock available.
     354              :  *
     355              :  * @note This function is *isr-ok*.
     356              :  *
     357              :  * @param dev the DS3231 device pointer
     358              :  *
     359              :  * @return the current value of the synchronization clock.
     360              :  */
     361            1 : static inline uint32_t maxim_ds3231_read_syncclock(const struct device *dev)
     362              : {
     363              :         return k_uptime_get_32();
     364              : }
     365              : 
     366              : /** @brief Get the frequency of the synchronization clock.
     367              :  *
     368              :  * Provides the frequency of the clock used in maxim_ds3231_read_syncclock().
     369              :  *
     370              :  * @param dev the DS3231 device pointer
     371              :  *
     372              :  * @return the frequency of the selected synchronization clock.
     373              :  */
     374            1 : static inline uint32_t maxim_ds3231_syncclock_frequency(const struct device *dev)
     375              : {
     376              :         return 1000U;
     377              : }
     378              : 
     379              : /**
     380              :  * @brief Set and clear specific bits in the control register.
     381              :  *
     382              :  * @note This function assumes the device register cache is valid.  It
     383              :  * will not read the register value, and it will write to the device
     384              :  * only if the value changes as a result of applying the set and clear
     385              :  * changes.
     386              :  *
     387              :  * @note Unlike maxim_ds3231_stat_update() the return value from this
     388              :  * function indicates the register value after changes were made.
     389              :  * That return value is cached for use in subsequent operations.
     390              :  *
     391              :  * @note This function is *supervisor*.
     392              :  *
     393              :  * @return the non-negative updated value of the register, or a
     394              :  * negative error code from an I2C transaction.
     395              :  */
     396            1 : int maxim_ds3231_ctrl_update(const struct device *dev,
     397              :                              uint8_t set_bits,
     398              :                              uint8_t clear_bits);
     399              : 
     400              : /**
     401              :  * @brief Read the ctrl_stat register then set and clear bits in it.
     402              :  *
     403              :  * The content of the ctrl_stat register will be read, then the set
     404              :  * and clear bits applied and the result written back to the device
     405              :  * (regardless of whether there appears to be a change in value).
     406              :  *
     407              :  * OSF, A1F, and A2F will be written with 1s if the corresponding bits
     408              :  * do not appear in either @p set_bits or @p clear_bits.  This ensures
     409              :  * that if any flag becomes set between the read and the write that
     410              :  * indicator will not be cleared.
     411              :  *
     412              :  * @note Unlike maxim_ds3231_ctrl_update() the return value from this
     413              :  * function indicates the register value before any changes were made.
     414              :  *
     415              :  * @note This function is *supervisor*.
     416              :  *
     417              :  * @param dev the DS3231 device pointer
     418              :  *
     419              :  * @param set_bits bits to be set when writing back.  Setting bits
     420              :  * other than @ref MAXIM_DS3231_REG_STAT_EN32kHz will have no effect.
     421              :  *
     422              :  * @param clear_bits bits to be cleared when writing back.  Include
     423              :  * the bits for the status flags you want to clear.
     424              :  *
     425              :  * @return the non-negative register value as originally read
     426              :  * (disregarding the effect of clears and sets), or a negative error
     427              :  * code from an I2C transaction.
     428              :  */
     429            1 : int maxim_ds3231_stat_update(const struct device *dev,
     430              :                              uint8_t set_bits,
     431              :                              uint8_t clear_bits);
     432              : 
     433              : /** @brief Read a DS3231 alarm configuration.
     434              :  *
     435              :  * The alarm configuration data is read from the device and
     436              :  * reconstructed into the output parameter.
     437              :  *
     438              :  * @note This function is *supervisor*.
     439              :  *
     440              :  * @param dev the DS3231 device pointer.
     441              :  *
     442              :  * @param id the alarm index, which must be 0 (for the 1 s resolution
     443              :  * alarm) or 1 (for the 1 min resolution alarm).
     444              :  *
     445              :  * @param cfg a pointer to a structure into which the configured alarm
     446              :  * data will be stored.
     447              :  *
     448              :  * @return a non-negative value indicating successful conversion, or a
     449              :  * negative error code from an I2C transaction or invalid parameter.
     450              :  */
     451            1 : int maxim_ds3231_get_alarm(const struct device *dev,
     452              :                            uint8_t id,
     453              :                            struct maxim_ds3231_alarm *cfg);
     454              : 
     455              : /** @brief Configure a DS3231 alarm.
     456              :  *
     457              :  * The alarm configuration is validated and stored into the device.
     458              :  *
     459              :  * To cancel an alarm use counter_cancel_channel_alarm().
     460              :  *
     461              :  * @note This function is *supervisor*.
     462              :  *
     463              :  * @param dev the DS3231 device pointer.
     464              :  *
     465              :  * @param id 0 Analog to counter index.  @c ALARM1 is 0 and has 1 s
     466              :  * resolution, @c ALARM2 is 1 and has 1 minute resolution.
     467              :  *
     468              :  * @param cfg a pointer to the desired alarm configuration.  Both
     469              :  * alarms are configured; if only one is to change the application
     470              :  * must supply the existing configuration for the other.
     471              :  *
     472              :  * @return a non-negative value on success, or a negative error code
     473              :  * from an I2C transaction or an invalid parameter.
     474              :  */
     475            1 : int maxim_ds3231_set_alarm(const struct device *dev,
     476              :                            uint8_t id,
     477              :                            const struct maxim_ds3231_alarm *cfg);
     478              : 
     479              : /** @brief Synchronize the RTC against the local clock.
     480              :  *
     481              :  * The RTC advances one tick per second with no access to sub-second
     482              :  * precision.  Synchronizing clocks at sub-second resolution requires
     483              :  * enabling a 1pps signal then capturing the system clocks in a GPIO
     484              :  * callback.  This function provides that operation.
     485              :  *
     486              :  * Synchronization is performed in asynchronously, and may take as
     487              :  * long as 1 s to complete; notification of completion is provided
     488              :  * through the @p notify parameter.
     489              :  *
     490              :  * Applications should use maxim_ds3231_get_syncpoint() to retrieve the
     491              :  * synchronization data collected by this operation.
     492              :  *
     493              :  * @note This function is *supervisor*.
     494              :  *
     495              :  * @param dev the DS3231 device pointer.
     496              :  *
     497              :  * @param notify pointer to the object used to specify asynchronous
     498              :  * function behavior and store completion information.
     499              :  *
     500              :  * @retval non-negative on success
     501              :  * @retval -EBUSY if a synchronization or set is currently in progress
     502              :  * @retval -EINVAL if notify is not provided
     503              :  * @retval -ENOTSUP if the required interrupt is not configured
     504              :  */
     505            1 : int maxim_ds3231_synchronize(const struct device *dev,
     506              :                              struct sys_notify *notify);
     507              : 
     508              : /** @brief Request to update the synchronization point.
     509              :  *
     510              :  * This is a variant of maxim_ds3231_synchronize() for use from user
     511              :  * threads.
     512              :  *
     513              :  * @param dev the DS3231 device pointer.
     514              :  *
     515              :  * @param signal pointer to a valid and ready-to-be-signalled
     516              :  * k_poll_signal.  May be NULL to request a synchronization point be
     517              :  * collected without notifying when it has been updated.
     518              :  *
     519              :  * @retval non-negative on success
     520              :  * @retval -EBUSY if a synchronization or set is currently in progress
     521              :  * @retval -ENOTSUP if the required interrupt is not configured
     522              :  */
     523            1 : __syscall int maxim_ds3231_req_syncpoint(const struct device *dev,
     524              :                                          struct k_poll_signal *signal);
     525              : 
     526              : /** @brief Retrieve the most recent synchronization point.
     527              :  *
     528              :  * This function returns the synchronization data last captured using
     529              :  * maxim_ds3231_synchronize().
     530              :  *
     531              :  * @param dev the DS3231 device pointer.
     532              :  *
     533              :  * @param syncpoint where to store the synchronization data.
     534              :  *
     535              :  * @retval non-negative on success
     536              :  * @retval -ENOENT if no syncpoint has been captured
     537              :  */
     538            1 : __syscall int maxim_ds3231_get_syncpoint(const struct device *dev,
     539              :                                          struct maxim_ds3231_syncpoint *syncpoint);
     540              : 
     541              : /** @brief Set the RTC to a time consistent with the provided
     542              :  * synchronization.
     543              :  *
     544              :  * The RTC advances one tick per second with no access to sub-second
     545              :  * precision, and setting the clock resets the internal countdown
     546              :  * chain.  This function implements the magic necessary to set the
     547              :  * clock while retaining as much sub-second accuracy as possible.  It
     548              :  * requires a synchronization point that pairs sub-second resolution
     549              :  * civil time with a local synchronization clock captured at the same
     550              :  * instant.  The set operation may take as long as 1 second to
     551              :  * complete; notification of completion is provided through the @p
     552              :  * notify parameter.
     553              :  *
     554              :  * @note This function is *supervisor*.
     555              :  *
     556              :  * @param dev the DS3231 device pointer.
     557              :  *
     558              :  * @param syncpoint the structure providing the synchronization point.
     559              :  *
     560              :  * @param notify pointer to the object used to specify asynchronous
     561              :  * function behavior and store completion information.
     562              :  *
     563              :  * @retval non-negative on success
     564              :  * @retval -EINVAL if syncpoint or notify are null
     565              :  * @retval -ENOTSUP if the required interrupt signal is not configured
     566              :  * @retval -EBUSY if a synchronization or set is currently in progress
     567              :  */
     568            1 : int maxim_ds3231_set(const struct device *dev,
     569              :                      const struct maxim_ds3231_syncpoint *syncpoint,
     570              :                      struct sys_notify *notify);
     571              : 
     572              : /** @brief Check for and clear flags indicating that an alarm has
     573              :  * fired.
     574              :  *
     575              :  * Returns a mask indicating alarms that are marked as having fired,
     576              :  * and clears from stat the flags that it found set.  Alarms that have
     577              :  * been configured with a callback are not represented in the return
     578              :  * value.
     579              :  *
     580              :  * This API may be used when a persistent alarm has been programmed.
     581              :  *
     582              :  * @note This function is *supervisor*.
     583              :  *
     584              :  * @param dev the DS3231 device pointer.
     585              :  *
     586              :  * @return a non-negative value that may have MAXIM_DS3231_ALARM1 and/or
     587              :  * MAXIM_DS3231_ALARM2 set, or a negative error code.
     588              :  */
     589            1 : int maxim_ds3231_check_alarms(const struct device *dev);
     590              : 
     591              : /**
     592              :  * @}
     593              :  */
     594              : 
     595              : #ifdef __cplusplus
     596              : }
     597              : #endif
     598              : 
     599              : /* @todo this should be syscalls/drivers/rtc/maxim_ds3231.h */
     600              : #include <zephyr/syscalls/maxim_ds3231.h>
     601              : 
     602              : #endif /* ZEPHYR_INCLUDE_DRIVERS_RTC_DS3231_H_ */
        

Generated by: LCOV version 2.0-1