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