1 /*
2  * SPDX-License-Identifier: Apache-2.0
3  *
4  * Copyright (c) 2024 Gergo Vari <work@gergovari.com>
5  */
6 
7 /*
8  * REGISTERS
9  */
10 
11 /* Time registers */
12 #define DS3231_REG_TIME_SECONDS     0x00
13 #define DS3231_REG_TIME_MINUTES     0x01
14 #define DS3231_REG_TIME_HOURS       0x02
15 #define DS3231_REG_TIME_DAY_OF_WEEK 0x03
16 #define DS3231_REG_TIME_DATE        0x04
17 #define DS3231_REG_TIME_MONTH       0x05
18 #define DS3231_REG_TIME_YEAR        0x06
19 
20 /* Alarm 1 registers */
21 #define DS3231_REG_ALARM_1_SECONDS 0x07
22 #define DS3231_REG_ALARM_1_MINUTES 0x08
23 #define DS3231_REG_ALARM_1_HOURS   0x09
24 #define DS3231_REG_ALARM_1_DATE    0x0A
25 
26 /* Alarm 2 registers */
27 /* Alarm 2 has no seconds to set, it only has minute accuracy. */
28 #define DS3231_REG_ALARM_2_MINUTES 0x0B
29 #define DS3231_REG_ALARM_2_HOURS   0x0C
30 #define DS3231_REG_ALARM_2_DATE    0x0D
31 
32 /* Control registers */
33 #define DS3231_REG_CTRL     0x0E
34 #define DS3231_REG_CTRL_STS 0x0F
35 
36 /* Aging offset register */
37 #define DS3231_REG_AGING_OFFSET 0x10
38 
39 /*
40  * BITMASKS
41  */
42 
43 /* Time bitmasks */
44 #define DS3231_BITS_TIME_SECONDS     GENMASK(6, 0)
45 #define DS3231_BITS_TIME_MINUTES     GENMASK(6, 0)
46 #define DS3231_BITS_TIME_HOURS       GENMASK(5, 0)
47 #define DS3231_BITS_TIME_PM          BIT(5)
48 #define DS3231_BITS_TIME_12HR        BIT(6)
49 #define DS3231_BITS_TIME_DAY_OF_WEEK GENMASK(2, 0)
50 #define DS3231_BITS_TIME_DATE        GENMASK(5, 0)
51 #define DS3231_BITS_TIME_MONTH       GENMASK(4, 0)
52 #define DS3231_BITS_TIME_CENTURY     BIT(7)
53 #define DS3231_BITS_TIME_YEAR        GENMASK(7, 0)
54 
55 /* Alarm bitmasks */
56 /* All alarm bitmasks match with time other than date and the alarm rate bit. */
57 #define DS3231_BITS_ALARM_RATE        BIT(7)
58 #define DS3231_BITS_ALARM_DATE_W_OR_M BIT(6)
59 
60 #define DS3231_BITS_SIGN       BIT(7)
61 /* Control bitmasks */
62 #define DS3231_BITS_CTRL_EOSC  BIT(7) /* enable oscillator, active low */
63 #define DS3231_BITS_CTRL_BBSQW BIT(6) /* enable battery-backed square-wave */
64 
65 /*  Setting the CONV bit to 1 forces the temperature sensor to
66  *  convert the temperature into digital code and
67  *  execute the TCXO algorithm to update
68  *  the capacitance array to the oscillator. This can only
69  *  happen when a conversion is not already in progress.
70  *  The user should check the status bit BSY before
71  *  forcing the controller to start a new TCXO execution.
72  *  A user-initiated temperature conversion
73  *  does not affect the internal 64-second update cycle.
74  */
75 #define DS3231_BITS_CTRL_CONV BIT(6)
76 
77 /* Rate selectors */
78 /* RS2 | RS1 | SQW FREQ
79  *  0  |  0  | 1Hz
80  *  0  |  1  | 1.024kHz
81  *  1  |  0  | 4.096kHz
82  *  1  |  1  | 8.192kHz
83  */
84 #define DS3231_BITS_CTRL_RS2 BIT(4)
85 #define DS3231_BITS_CTRL_RS1 BIT(3)
86 
87 #define DS3231_BITS_CTRL_INTCTRL    BIT(2)
88 #define DS3231_BITS_CTRL_ALARM_2_EN BIT(1)
89 #define DS3231_BITS_CTRL_ALARM_1_EN BIT(0)
90 
91 /* Control status bitmasks */
92 /* For some reason you can access OSF in both control and control status registers. */
93 #define DS3231_BITS_CTRL_STS_OSF          BIT(7) /* oscillator stop flag */ /* read only */
94 #define DS3231_BITS_CTRL_STS_32_EN        BIT(3)                            /* 32kHz square-wave */
95 /* set when TXCO is busy, see CONV flag: read only */
96 #define DS3231_BITS_CTRL_STS_BSY          BIT(2)
97 #define DS3231_BITS_CTRL_STS_ALARM_2_FLAG BIT(1) /* can only be set to 0 */
98 #define DS3231_BITS_CTRL_STS_ALARM_1_FLAG BIT(0) /* can only be set to 0 */
99 
100 /* Aging offset bitmask */
101 #define DS3231_BITS_DATA BIT(6, 0)
102 
103 /* Settings bitmasks */
104 #define DS3231_BITS_STS_OSC     BIT(0)
105 #define DS3231_BITS_STS_INTCTRL BIT(1)
106 #define DS3231_BITS_STS_SQW     BIT(2)
107 #define DS3231_BITS_STS_32KHZ   BIT(3)
108 #define DS3231_BITS_STS_ALARM_1 BIT(4)
109 #define DS3231_BITS_STS_ALARM_2 BIT(5)
110