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