1 /* SPDX-License-Identifier: GPL-2.0-only */
2 /*
3 * Definitions for the registers, addresses, and platform data of the
4 * DS1685/DS1687-series RTC chips.
5 *
6 * This Driver also works for the DS17X85/DS17X87 RTC chips. Functionally
7 * similar to the DS1685/DS1687, they support a few extra features which
8 * include larger, battery-backed NV-SRAM, burst-mode access, and an RTC
9 * write counter.
10 *
11 * Copyright (C) 2011-2014 Joshua Kinard <kumba@gentoo.org>.
12 * Copyright (C) 2009 Matthias Fuchs <matthias.fuchs@esd-electronics.com>.
13 *
14 * References:
15 * DS1685/DS1687 3V/5V Real-Time Clocks, 19-5215, Rev 4/10.
16 * DS17x85/DS17x87 3V/5V Real-Time Clocks, 19-5222, Rev 4/10.
17 * DS1689/DS1693 3V/5V Serialized Real-Time Clocks, Rev 112105.
18 * Application Note 90, Using the Multiplex Bus RTC Extended Features.
19 */
20
21 #ifndef _LINUX_RTC_DS1685_H_
22 #define _LINUX_RTC_DS1685_H_
23
24 #include <linux/rtc.h>
25 #include <linux/platform_device.h>
26 #include <linux/workqueue.h>
27
28 /**
29 * struct ds1685_priv - DS1685 private data structure.
30 * @dev: pointer to the rtc_device structure.
31 * @regs: iomapped base address pointer of the RTC registers.
32 * @regstep: padding/step size between registers (optional).
33 * @baseaddr: base address of the RTC device.
34 * @size: resource size.
35 * @lock: private lock variable for spin locking/unlocking.
36 * @work: private workqueue.
37 * @irq: IRQ number assigned to the RTC device.
38 * @prepare_poweroff: pointer to platform pre-poweroff function.
39 * @wake_alarm: pointer to platform wake alarm function.
40 * @post_ram_clear: pointer to platform post ram-clear function.
41 */
42 struct ds1685_priv {
43 struct rtc_device *dev;
44 void __iomem *regs;
45 u32 regstep;
46 resource_size_t baseaddr;
47 size_t size;
48 int irq_num;
49 bool bcd_mode;
50 bool no_irq;
51 bool uie_unsupported;
52 bool alloc_io_resources;
53 u8 (*read)(struct ds1685_priv *, int);
54 void (*write)(struct ds1685_priv *, int, u8);
55 void (*prepare_poweroff)(void);
56 void (*wake_alarm)(void);
57 void (*post_ram_clear)(void);
58 };
59
60
61 /**
62 * struct ds1685_rtc_platform_data - platform data structure.
63 * @plat_prepare_poweroff: platform-specific pre-poweroff function.
64 * @plat_wake_alarm: platform-specific wake alarm function.
65 * @plat_post_ram_clear: platform-specific post ram-clear function.
66 *
67 * If your platform needs to use a custom padding/step size between
68 * registers, or uses one or more of the extended interrupts and needs special
69 * handling, then include this header file in your platform definition and
70 * set regstep and the plat_* pointers as appropriate.
71 */
72 struct ds1685_rtc_platform_data {
73 const u32 regstep;
74 const bool bcd_mode;
75 const bool no_irq;
76 const bool uie_unsupported;
77 const bool alloc_io_resources;
78 u8 (*plat_read)(struct ds1685_priv *, int);
79 void (*plat_write)(struct ds1685_priv *, int, u8);
80 void (*plat_prepare_poweroff)(void);
81 void (*plat_wake_alarm)(void);
82 void (*plat_post_ram_clear)(void);
83 };
84
85
86 /*
87 * Time Registers.
88 */
89 #define RTC_SECS 0x00 /* Seconds 00-59 */
90 #define RTC_SECS_ALARM 0x01 /* Alarm Seconds 00-59 */
91 #define RTC_MINS 0x02 /* Minutes 00-59 */
92 #define RTC_MINS_ALARM 0x03 /* Alarm Minutes 00-59 */
93 #define RTC_HRS 0x04 /* Hours 01-12 AM/PM || 00-23 */
94 #define RTC_HRS_ALARM 0x05 /* Alarm Hours 01-12 AM/PM || 00-23 */
95 #define RTC_WDAY 0x06 /* Day of Week 01-07 */
96 #define RTC_MDAY 0x07 /* Day of Month 01-31 */
97 #define RTC_MONTH 0x08 /* Month 01-12 */
98 #define RTC_YEAR 0x09 /* Year 00-99 */
99 #define RTC_CENTURY 0x48 /* Century 00-99 */
100 #define RTC_MDAY_ALARM 0x49 /* Alarm Day of Month 01-31 */
101
102
103 /*
104 * Bit masks for the Time registers in BCD Mode (DM = 0).
105 */
106 #define RTC_SECS_BCD_MASK 0x7f /* - x x x x x x x */
107 #define RTC_MINS_BCD_MASK 0x7f /* - x x x x x x x */
108 #define RTC_HRS_12_BCD_MASK 0x1f /* - - - x x x x x */
109 #define RTC_HRS_24_BCD_MASK 0x3f /* - - x x x x x x */
110 #define RTC_MDAY_BCD_MASK 0x3f /* - - x x x x x x */
111 #define RTC_MONTH_BCD_MASK 0x1f /* - - - x x x x x */
112 #define RTC_YEAR_BCD_MASK 0xff /* x x x x x x x x */
113
114 /*
115 * Bit masks for the Time registers in BIN Mode (DM = 1).
116 */
117 #define RTC_SECS_BIN_MASK 0x3f /* - - x x x x x x */
118 #define RTC_MINS_BIN_MASK 0x3f /* - - x x x x x x */
119 #define RTC_HRS_12_BIN_MASK 0x0f /* - - - - x x x x */
120 #define RTC_HRS_24_BIN_MASK 0x1f /* - - - x x x x x */
121 #define RTC_MDAY_BIN_MASK 0x1f /* - - - x x x x x */
122 #define RTC_MONTH_BIN_MASK 0x0f /* - - - - x x x x */
123 #define RTC_YEAR_BIN_MASK 0x7f /* - x x x x x x x */
124
125 /*
126 * Bit masks common for the Time registers in BCD or BIN Mode.
127 */
128 #define RTC_WDAY_MASK 0x07 /* - - - - - x x x */
129 #define RTC_CENTURY_MASK 0xff /* x x x x x x x x */
130 #define RTC_MDAY_ALARM_MASK 0xff /* x x x x x x x x */
131 #define RTC_HRS_AMPM_MASK BIT(7) /* Mask for the AM/PM bit */
132
133
134
135 /*
136 * Control Registers.
137 */
138 #define RTC_CTRL_A 0x0a /* Control Register A */
139 #define RTC_CTRL_B 0x0b /* Control Register B */
140 #define RTC_CTRL_C 0x0c /* Control Register C */
141 #define RTC_CTRL_D 0x0d /* Control Register D */
142 #define RTC_EXT_CTRL_4A 0x4a /* Extended Control Register 4A */
143 #define RTC_EXT_CTRL_4B 0x4b /* Extended Control Register 4B */
144
145
146 /*
147 * Bit names in Control Register A.
148 */
149 #define RTC_CTRL_A_UIP BIT(7) /* Update In Progress */
150 #define RTC_CTRL_A_DV2 BIT(6) /* Countdown Chain */
151 #define RTC_CTRL_A_DV1 BIT(5) /* Oscillator Enable */
152 #define RTC_CTRL_A_DV0 BIT(4) /* Bank Select */
153 #define RTC_CTRL_A_RS2 BIT(2) /* Rate-Selection Bit 2 */
154 #define RTC_CTRL_A_RS3 BIT(3) /* Rate-Selection Bit 3 */
155 #define RTC_CTRL_A_RS1 BIT(1) /* Rate-Selection Bit 1 */
156 #define RTC_CTRL_A_RS0 BIT(0) /* Rate-Selection Bit 0 */
157 #define RTC_CTRL_A_RS_MASK 0x0f /* RS3 + RS2 + RS1 + RS0 */
158
159 /*
160 * Bit names in Control Register B.
161 */
162 #define RTC_CTRL_B_SET BIT(7) /* SET Bit */
163 #define RTC_CTRL_B_PIE BIT(6) /* Periodic-Interrupt Enable */
164 #define RTC_CTRL_B_AIE BIT(5) /* Alarm-Interrupt Enable */
165 #define RTC_CTRL_B_UIE BIT(4) /* Update-Ended Interrupt-Enable */
166 #define RTC_CTRL_B_SQWE BIT(3) /* Square-Wave Enable */
167 #define RTC_CTRL_B_DM BIT(2) /* Data Mode */
168 #define RTC_CTRL_B_2412 BIT(1) /* 12-Hr/24-Hr Mode */
169 #define RTC_CTRL_B_DSE BIT(0) /* Daylight Savings Enable */
170 #define RTC_CTRL_B_PAU_MASK 0x70 /* PIE + AIE + UIE */
171
172
173 /*
174 * Bit names in Control Register C.
175 *
176 * BIT(0), BIT(1), BIT(2), & BIT(3) are unused, always return 0, and cannot
177 * be written to.
178 */
179 #define RTC_CTRL_C_IRQF BIT(7) /* Interrupt-Request Flag */
180 #define RTC_CTRL_C_PF BIT(6) /* Periodic-Interrupt Flag */
181 #define RTC_CTRL_C_AF BIT(5) /* Alarm-Interrupt Flag */
182 #define RTC_CTRL_C_UF BIT(4) /* Update-Ended Interrupt Flag */
183 #define RTC_CTRL_C_PAU_MASK 0x70 /* PF + AF + UF */
184
185
186 /*
187 * Bit names in Control Register D.
188 *
189 * BIT(0) through BIT(6) are unused, always return 0, and cannot
190 * be written to.
191 */
192 #define RTC_CTRL_D_VRT BIT(7) /* Valid RAM and Time */
193
194
195 /*
196 * Bit names in Extended Control Register 4A.
197 *
198 * On the DS1685/DS1687/DS1689/DS1693, BIT(4) and BIT(5) are reserved for
199 * future use. They can be read from and written to, but have no effect
200 * on the RTC's operation.
201 *
202 * On the DS17x85/DS17x87, BIT(5) is Burst-Mode Enable (BME), and allows
203 * access to the extended NV-SRAM by automatically incrementing the address
204 * register when they are read from or written to.
205 */
206 #define RTC_CTRL_4A_VRT2 BIT(7) /* Auxillary Battery Status */
207 #define RTC_CTRL_4A_INCR BIT(6) /* Increment-in-Progress Status */
208 #define RTC_CTRL_4A_PAB BIT(3) /* Power-Active Bar Control */
209 #define RTC_CTRL_4A_RF BIT(2) /* RAM-Clear Flag */
210 #define RTC_CTRL_4A_WF BIT(1) /* Wake-Up Alarm Flag */
211 #define RTC_CTRL_4A_KF BIT(0) /* Kickstart Flag */
212 #if !defined(CONFIG_RTC_DRV_DS1685) && !defined(CONFIG_RTC_DRV_DS1689)
213 #define RTC_CTRL_4A_BME BIT(5) /* Burst-Mode Enable */
214 #endif
215 #define RTC_CTRL_4A_RWK_MASK 0x07 /* RF + WF + KF */
216
217
218 /*
219 * Bit names in Extended Control Register 4B.
220 */
221 #define RTC_CTRL_4B_ABE BIT(7) /* Auxillary Battery Enable */
222 #define RTC_CTRL_4B_E32K BIT(6) /* Enable 32.768Hz on SQW Pin */
223 #define RTC_CTRL_4B_CS BIT(5) /* Crystal Select */
224 #define RTC_CTRL_4B_RCE BIT(4) /* RAM Clear-Enable */
225 #define RTC_CTRL_4B_PRS BIT(3) /* PAB Reset-Select */
226 #define RTC_CTRL_4B_RIE BIT(2) /* RAM Clear-Interrupt Enable */
227 #define RTC_CTRL_4B_WIE BIT(1) /* Wake-Up Alarm-Interrupt Enable */
228 #define RTC_CTRL_4B_KSE BIT(0) /* Kickstart Interrupt-Enable */
229 #define RTC_CTRL_4B_RWK_MASK 0x07 /* RIE + WIE + KSE */
230
231
232 /*
233 * Misc register names in Bank 1.
234 *
235 * The DV0 bit in Control Register A must be set to 1 for these registers
236 * to become available, including Extended Control Registers 4A & 4B.
237 */
238 #define RTC_BANK1_SSN_MODEL 0x40 /* Model Number */
239 #define RTC_BANK1_SSN_BYTE_1 0x41 /* 1st Byte of Serial Number */
240 #define RTC_BANK1_SSN_BYTE_2 0x42 /* 2nd Byte of Serial Number */
241 #define RTC_BANK1_SSN_BYTE_3 0x43 /* 3rd Byte of Serial Number */
242 #define RTC_BANK1_SSN_BYTE_4 0x44 /* 4th Byte of Serial Number */
243 #define RTC_BANK1_SSN_BYTE_5 0x45 /* 5th Byte of Serial Number */
244 #define RTC_BANK1_SSN_BYTE_6 0x46 /* 6th Byte of Serial Number */
245 #define RTC_BANK1_SSN_CRC 0x47 /* Serial CRC Byte */
246 #define RTC_BANK1_RAM_DATA_PORT 0x53 /* Extended RAM Data Port */
247
248
249 /*
250 * Model-specific registers in Bank 1.
251 *
252 * The addresses below differ depending on the model of the RTC chip
253 * selected in the kernel configuration. Not all of these features are
254 * supported in the main driver at present.
255 *
256 * DS1685/DS1687 - Extended NV-SRAM address (LSB only).
257 * DS1689/DS1693 - Vcc, Vbat, Pwr Cycle Counters & Customer-specific S/N.
258 * DS17x85/DS17x87 - Extended NV-SRAM addresses (MSB & LSB) & Write counter.
259 */
260 #if defined(CONFIG_RTC_DRV_DS1685)
261 #define RTC_BANK1_RAM_ADDR 0x50 /* NV-SRAM Addr */
262 #elif defined(CONFIG_RTC_DRV_DS1689)
263 #define RTC_BANK1_VCC_CTR_LSB 0x54 /* Vcc Counter Addr (LSB) */
264 #define RTC_BANK1_VCC_CTR_MSB 0x57 /* Vcc Counter Addr (MSB) */
265 #define RTC_BANK1_VBAT_CTR_LSB 0x58 /* Vbat Counter Addr (LSB) */
266 #define RTC_BANK1_VBAT_CTR_MSB 0x5b /* Vbat Counter Addr (MSB) */
267 #define RTC_BANK1_PWR_CTR_LSB 0x5c /* Pwr Cycle Counter Addr (LSB) */
268 #define RTC_BANK1_PWR_CTR_MSB 0x5d /* Pwr Cycle Counter Addr (MSB) */
269 #define RTC_BANK1_UNIQ_SN 0x60 /* Customer-specific S/N */
270 #else /* DS17x85/DS17x87 */
271 #define RTC_BANK1_RAM_ADDR_LSB 0x50 /* NV-SRAM Addr (LSB) */
272 #define RTC_BANK1_RAM_ADDR_MSB 0x51 /* NV-SRAM Addr (MSB) */
273 #define RTC_BANK1_WRITE_CTR 0x5e /* RTC Write Counter */
274 #endif
275
276
277 /*
278 * Model numbers.
279 *
280 * The DS1688/DS1691 and DS1689/DS1693 chips share the same model number
281 * and the manual doesn't indicate any major differences. As such, they
282 * are regarded as the same chip in this driver.
283 */
284 #define RTC_MODEL_DS1685 0x71 /* DS1685/DS1687 */
285 #define RTC_MODEL_DS17285 0x72 /* DS17285/DS17287 */
286 #define RTC_MODEL_DS1689 0x73 /* DS1688/DS1691/DS1689/DS1693 */
287 #define RTC_MODEL_DS17485 0x74 /* DS17485/DS17487 */
288 #define RTC_MODEL_DS17885 0x78 /* DS17885/DS17887 */
289
290
291 /*
292 * Periodic Interrupt Rates / Square-Wave Output Frequency
293 *
294 * Periodic rates are selected by setting the RS3-RS0 bits in Control
295 * Register A and enabled via either the E32K bit in Extended Control
296 * Register 4B or the SQWE bit in Control Register B.
297 *
298 * E32K overrides the settings of RS3-RS0 and outputs a frequency of 32768Hz
299 * on the SQW pin of the RTC chip. While there are 16 possible selections,
300 * the 1-of-16 decoder is only able to divide the base 32768Hz signal into 13
301 * smaller frequencies. The values 0x01 and 0x02 are not used and are
302 * synonymous with 0x08 and 0x09, respectively.
303 *
304 * When E32K is set to a logic 1, periodic interrupts are disabled and reading
305 * /dev/rtc will return -EINVAL. This also applies if the periodic interrupt
306 * frequency is set to 0Hz.
307 *
308 * Not currently used by the rtc-ds1685 driver because the RTC core removed
309 * support for hardware-generated periodic-interrupts in favour of
310 * hrtimer-generated interrupts. But these defines are kept around for use
311 * in userland, as documentation to the hardware, and possible future use if
312 * hardware-generated periodic interrupts are ever added back.
313 */
314 /* E32K RS3 RS2 RS1 RS0 */
315 #define RTC_SQW_8192HZ 0x03 /* 0 0 0 1 1 */
316 #define RTC_SQW_4096HZ 0x04 /* 0 0 1 0 0 */
317 #define RTC_SQW_2048HZ 0x05 /* 0 0 1 0 1 */
318 #define RTC_SQW_1024HZ 0x06 /* 0 0 1 1 0 */
319 #define RTC_SQW_512HZ 0x07 /* 0 0 1 1 1 */
320 #define RTC_SQW_256HZ 0x08 /* 0 1 0 0 0 */
321 #define RTC_SQW_128HZ 0x09 /* 0 1 0 0 1 */
322 #define RTC_SQW_64HZ 0x0a /* 0 1 0 1 0 */
323 #define RTC_SQW_32HZ 0x0b /* 0 1 0 1 1 */
324 #define RTC_SQW_16HZ 0x0c /* 0 1 1 0 0 */
325 #define RTC_SQW_8HZ 0x0d /* 0 1 1 0 1 */
326 #define RTC_SQW_4HZ 0x0e /* 0 1 1 1 0 */
327 #define RTC_SQW_2HZ 0x0f /* 0 1 1 1 1 */
328 #define RTC_SQW_0HZ 0x00 /* 0 0 0 0 0 */
329 #define RTC_SQW_32768HZ 32768 /* 1 - - - - */
330 #define RTC_MAX_USER_FREQ 8192
331
332
333 /*
334 * NVRAM data & addresses:
335 * - 50 bytes of NVRAM are available just past the clock registers.
336 * - 64 additional bytes are available in Bank0.
337 *
338 * Extended, battery-backed NV-SRAM:
339 * - DS1685/DS1687 - 128 bytes.
340 * - DS1689/DS1693 - 0 bytes.
341 * - DS17285/DS17287 - 2048 bytes.
342 * - DS17485/DS17487 - 4096 bytes.
343 * - DS17885/DS17887 - 8192 bytes.
344 */
345 #define NVRAM_TIME_BASE 0x0e /* NVRAM Addr in Time regs */
346 #define NVRAM_BANK0_BASE 0x40 /* NVRAM Addr in Bank0 regs */
347 #define NVRAM_SZ_TIME 50
348 #define NVRAM_SZ_BANK0 64
349 #if defined(CONFIG_RTC_DRV_DS1685)
350 # define NVRAM_SZ_EXTND 128
351 #elif defined(CONFIG_RTC_DRV_DS1689)
352 # define NVRAM_SZ_EXTND 0
353 #elif defined(CONFIG_RTC_DRV_DS17285)
354 # define NVRAM_SZ_EXTND 2048
355 #elif defined(CONFIG_RTC_DRV_DS17485)
356 # define NVRAM_SZ_EXTND 4096
357 #elif defined(CONFIG_RTC_DRV_DS17885)
358 # define NVRAM_SZ_EXTND 8192
359 #endif
360 #define NVRAM_TOTAL_SZ_BANK0 (NVRAM_SZ_TIME + NVRAM_SZ_BANK0)
361 #define NVRAM_TOTAL_SZ (NVRAM_TOTAL_SZ_BANK0 + NVRAM_SZ_EXTND)
362
363
364 /*
365 * Function Prototypes.
366 */
367 extern void __noreturn
368 ds1685_rtc_poweroff(struct platform_device *pdev);
369
370 #endif /* _LINUX_RTC_DS1685_H_ */