include/linux/rtc/ds1685.h

   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_ */