linux/rtc/ds1685.h

0001 /* SPDX-License-Identifier: GPL-2.0-only */
0002 /*
0003  * Definitions for the registers, addresses, and platform data of the
0004  * DS1685/DS1687-series RTC chips.
0005  *
0006  * This Driver also works for the DS17X85/DS17X87 RTC chips.  Functionally
0007  * similar to the DS1685/DS1687, they support a few extra features which
0008  * include larger, battery-backed NV-SRAM, burst-mode access, and an RTC
0009  * write counter.
0010  *
0011  * Copyright (C) 2011-2014 Joshua Kinard <kumba@gentoo.org>.
0012  * Copyright (C) 2009 Matthias Fuchs <matthias.fuchs@esd-electronics.com>.
0013  *
0014  * References:
0015  *    DS1685/DS1687 3V/5V Real-Time Clocks, 19-5215, Rev 4/10.
0016  *    DS17x85/DS17x87 3V/5V Real-Time Clocks, 19-5222, Rev 4/10.
0017  *    DS1689/DS1693 3V/5V Serialized Real-Time Clocks, Rev 112105.
0018  *    Application Note 90, Using the Multiplex Bus RTC Extended Features.
0019  */
0020
0021 #ifndef _LINUX_RTC_DS1685_H_
0022 #define _LINUX_RTC_DS1685_H_
0023
0024 #include <linux/rtc.h>
0025 #include <linux/platform_device.h>
0026 #include <linux/workqueue.h>
0027
0028 /**
0029  * struct ds1685_priv - DS1685 private data structure.
0030  * @dev: pointer to the rtc_device structure.
0031  * @regs: iomapped base address pointer of the RTC registers.
0032  * @regstep: padding/step size between registers (optional).
0033  * @baseaddr: base address of the RTC device.
0034  * @size: resource size.
0035  * @lock: private lock variable for spin locking/unlocking.
0036  * @work: private workqueue.
0037  * @irq: IRQ number assigned to the RTC device.
0038  * @prepare_poweroff: pointer to platform pre-poweroff function.
0039  * @wake_alarm: pointer to platform wake alarm function.
0040  * @post_ram_clear: pointer to platform post ram-clear function.
0041  */
0042 struct ds1685_priv {
0043     struct rtc_device *dev;
0044     void __iomem *regs;
0045     void __iomem *data;
0046     u32 regstep;
0047     int irq_num;
0048     bool bcd_mode;
0049     u8 (*read)(struct ds1685_priv *, int);
0050     void (*write)(struct ds1685_priv *, int, u8);
0051     void (*prepare_poweroff)(void);
0052     void (*wake_alarm)(void);
0053     void (*post_ram_clear)(void);
0054 };
0055
0056
0057 /**
0058  * struct ds1685_rtc_platform_data - platform data structure.
0059  * @plat_prepare_poweroff: platform-specific pre-poweroff function.
0060  * @plat_wake_alarm: platform-specific wake alarm function.
0061  * @plat_post_ram_clear: platform-specific post ram-clear function.
0062  *
0063  * If your platform needs to use a custom padding/step size between
0064  * registers, or uses one or more of the extended interrupts and needs special
0065  * handling, then include this header file in your platform definition and
0066  * set regstep and the plat_* pointers as appropriate.
0067  */
0068 struct ds1685_rtc_platform_data {
0069     const u32 regstep;
0070     const bool bcd_mode;
0071     const bool no_irq;
0072     const bool uie_unsupported;
0073     void (*plat_prepare_poweroff)(void);
0074     void (*plat_wake_alarm)(void);
0075     void (*plat_post_ram_clear)(void);
0076     enum {
0077         ds1685_reg_direct,
0078         ds1685_reg_indirect
0079     } access_type;
0080 };
0081
0082
0083 /*
0084  * Time Registers.
0085  */
0086 #define RTC_SECS        0x00    /* Seconds 00-59 */
0087 #define RTC_SECS_ALARM      0x01    /* Alarm Seconds 00-59 */
0088 #define RTC_MINS        0x02    /* Minutes 00-59 */
0089 #define RTC_MINS_ALARM      0x03    /* Alarm Minutes 00-59 */
0090 #define RTC_HRS         0x04    /* Hours 01-12 AM/PM || 00-23 */
0091 #define RTC_HRS_ALARM       0x05    /* Alarm Hours 01-12 AM/PM || 00-23 */
0092 #define RTC_WDAY        0x06    /* Day of Week 01-07 */
0093 #define RTC_MDAY        0x07    /* Day of Month 01-31 */
0094 #define RTC_MONTH       0x08    /* Month 01-12 */
0095 #define RTC_YEAR        0x09    /* Year 00-99 */
0096 #define RTC_CENTURY     0x48    /* Century 00-99 */
0097 #define RTC_MDAY_ALARM      0x49    /* Alarm Day of Month 01-31 */
0098
0099
0100 /*
0101  * Bit masks for the Time registers in BCD Mode (DM = 0).
0102  */
0103 #define RTC_SECS_BCD_MASK   0x7f    /* - x x x x x x x */
0104 #define RTC_MINS_BCD_MASK   0x7f    /* - x x x x x x x */
0105 #define RTC_HRS_12_BCD_MASK 0x1f    /* - - - x x x x x */
0106 #define RTC_HRS_24_BCD_MASK 0x3f    /* - - x x x x x x */
0107 #define RTC_MDAY_BCD_MASK   0x3f    /* - - x x x x x x */
0108 #define RTC_MONTH_BCD_MASK  0x1f    /* - - - x x x x x */
0109 #define RTC_YEAR_BCD_MASK   0xff    /* x x x x x x x x */
0110
0111 /*
0112  * Bit masks for the Time registers in BIN Mode (DM = 1).
0113  */
0114 #define RTC_SECS_BIN_MASK   0x3f    /* - - x x x x x x */
0115 #define RTC_MINS_BIN_MASK   0x3f    /* - - x x x x x x */
0116 #define RTC_HRS_12_BIN_MASK 0x0f    /* - - - - x x x x */
0117 #define RTC_HRS_24_BIN_MASK 0x1f    /* - - - x x x x x */
0118 #define RTC_MDAY_BIN_MASK   0x1f    /* - - - x x x x x */
0119 #define RTC_MONTH_BIN_MASK  0x0f    /* - - - - x x x x */
0120 #define RTC_YEAR_BIN_MASK   0x7f    /* - x x x x x x x */
0121
0122 /*
0123  * Bit masks common for the Time registers in BCD or BIN Mode.
0124  */
0125 #define RTC_WDAY_MASK       0x07    /* - - - - - x x x */
0126 #define RTC_CENTURY_MASK    0xff    /* x x x x x x x x */
0127 #define RTC_MDAY_ALARM_MASK 0xff    /* x x x x x x x x */
0128 #define RTC_HRS_AMPM_MASK   BIT(7)  /* Mask for the AM/PM bit */
0129
0130
0131
0132 /*
0133  * Control Registers.
0134  */
0135 #define RTC_CTRL_A      0x0a    /* Control Register A */
0136 #define RTC_CTRL_B      0x0b    /* Control Register B */
0137 #define RTC_CTRL_C      0x0c    /* Control Register C */
0138 #define RTC_CTRL_D      0x0d    /* Control Register D */
0139 #define RTC_EXT_CTRL_4A     0x4a    /* Extended Control Register 4A */
0140 #define RTC_EXT_CTRL_4B     0x4b    /* Extended Control Register 4B */
0141
0142
0143 /*
0144  * Bit names in Control Register A.
0145  */
0146 #define RTC_CTRL_A_UIP      BIT(7)  /* Update In Progress */
0147 #define RTC_CTRL_A_DV2      BIT(6)  /* Countdown Chain */
0148 #define RTC_CTRL_A_DV1      BIT(5)  /* Oscillator Enable */
0149 #define RTC_CTRL_A_DV0      BIT(4)  /* Bank Select */
0150 #define RTC_CTRL_A_RS2      BIT(2)  /* Rate-Selection Bit 2 */
0151 #define RTC_CTRL_A_RS3      BIT(3)  /* Rate-Selection Bit 3 */
0152 #define RTC_CTRL_A_RS1      BIT(1)  /* Rate-Selection Bit 1 */
0153 #define RTC_CTRL_A_RS0      BIT(0)  /* Rate-Selection Bit 0 */
0154 #define RTC_CTRL_A_RS_MASK  0x0f    /* RS3 + RS2 + RS1 + RS0 */
0155
0156 /*
0157  * Bit names in Control Register B.
0158  */
0159 #define RTC_CTRL_B_SET      BIT(7)  /* SET Bit */
0160 #define RTC_CTRL_B_PIE      BIT(6)  /* Periodic-Interrupt Enable */
0161 #define RTC_CTRL_B_AIE      BIT(5)  /* Alarm-Interrupt Enable */
0162 #define RTC_CTRL_B_UIE      BIT(4)  /* Update-Ended Interrupt-Enable */
0163 #define RTC_CTRL_B_SQWE     BIT(3)  /* Square-Wave Enable */
0164 #define RTC_CTRL_B_DM       BIT(2)  /* Data Mode */
0165 #define RTC_CTRL_B_2412     BIT(1)  /* 12-Hr/24-Hr Mode */
0166 #define RTC_CTRL_B_DSE      BIT(0)  /* Daylight Savings Enable */
0167 #define RTC_CTRL_B_PAU_MASK 0x70    /* PIE + AIE + UIE */
0168
0169
0170 /*
0171  * Bit names in Control Register C.
0172  *
0173  * BIT(0), BIT(1), BIT(2), & BIT(3) are unused, always return 0, and cannot
0174  * be written to.
0175  */
0176 #define RTC_CTRL_C_IRQF     BIT(7)  /* Interrupt-Request Flag */
0177 #define RTC_CTRL_C_PF       BIT(6)  /* Periodic-Interrupt Flag */
0178 #define RTC_CTRL_C_AF       BIT(5)  /* Alarm-Interrupt Flag */
0179 #define RTC_CTRL_C_UF       BIT(4)  /* Update-Ended Interrupt Flag */
0180 #define RTC_CTRL_C_PAU_MASK 0x70    /* PF + AF + UF */
0181
0182
0183 /*
0184  * Bit names in Control Register D.
0185  *
0186  * BIT(0) through BIT(6) are unused, always return 0, and cannot
0187  * be written to.
0188  */
0189 #define RTC_CTRL_D_VRT      BIT(7)  /* Valid RAM and Time */
0190
0191
0192 /*
0193  * Bit names in Extended Control Register 4A.
0194  *
0195  * On the DS1685/DS1687/DS1689/DS1693, BIT(4) and BIT(5) are reserved for
0196  * future use.  They can be read from and written to, but have no effect
0197  * on the RTC's operation.
0198  *
0199  * On the DS17x85/DS17x87, BIT(5) is Burst-Mode Enable (BME), and allows
0200  * access to the extended NV-SRAM by automatically incrementing the address
0201  * register when they are read from or written to.
0202  */
0203 #define RTC_CTRL_4A_VRT2    BIT(7)  /* Auxillary Battery Status */
0204 #define RTC_CTRL_4A_INCR    BIT(6)  /* Increment-in-Progress Status */
0205 #define RTC_CTRL_4A_PAB     BIT(3)  /* Power-Active Bar Control */
0206 #define RTC_CTRL_4A_RF      BIT(2)  /* RAM-Clear Flag */
0207 #define RTC_CTRL_4A_WF      BIT(1)  /* Wake-Up Alarm Flag */
0208 #define RTC_CTRL_4A_KF      BIT(0)  /* Kickstart Flag */
0209 #if !defined(CONFIG_RTC_DRV_DS1685) && !defined(CONFIG_RTC_DRV_DS1689)
0210 #define RTC_CTRL_4A_BME     BIT(5)  /* Burst-Mode Enable */
0211 #endif
0212 #define RTC_CTRL_4A_RWK_MASK    0x07    /* RF + WF + KF */
0213
0214
0215 /*
0216  * Bit names in Extended Control Register 4B.
0217  */
0218 #define RTC_CTRL_4B_ABE     BIT(7)  /* Auxillary Battery Enable */
0219 #define RTC_CTRL_4B_E32K    BIT(6)  /* Enable 32.768Hz on SQW Pin */
0220 #define RTC_CTRL_4B_CS      BIT(5)  /* Crystal Select */
0221 #define RTC_CTRL_4B_RCE     BIT(4)  /* RAM Clear-Enable */
0222 #define RTC_CTRL_4B_PRS     BIT(3)  /* PAB Reset-Select */
0223 #define RTC_CTRL_4B_RIE     BIT(2)  /* RAM Clear-Interrupt Enable */
0224 #define RTC_CTRL_4B_WIE     BIT(1)  /* Wake-Up Alarm-Interrupt Enable */
0225 #define RTC_CTRL_4B_KSE     BIT(0)  /* Kickstart Interrupt-Enable */
0226 #define RTC_CTRL_4B_RWK_MASK    0x07    /* RIE + WIE + KSE */
0227
0228
0229 /*
0230  * Misc register names in Bank 1.
0231  *
0232  * The DV0 bit in Control Register A must be set to 1 for these registers
0233  * to become available, including Extended Control Registers 4A & 4B.
0234  */
0235 #define RTC_BANK1_SSN_MODEL 0x40    /* Model Number */
0236 #define RTC_BANK1_SSN_BYTE_1    0x41    /* 1st Byte of Serial Number */
0237 #define RTC_BANK1_SSN_BYTE_2    0x42    /* 2nd Byte of Serial Number */
0238 #define RTC_BANK1_SSN_BYTE_3    0x43    /* 3rd Byte of Serial Number */
0239 #define RTC_BANK1_SSN_BYTE_4    0x44    /* 4th Byte of Serial Number */
0240 #define RTC_BANK1_SSN_BYTE_5    0x45    /* 5th Byte of Serial Number */
0241 #define RTC_BANK1_SSN_BYTE_6    0x46    /* 6th Byte of Serial Number */
0242 #define RTC_BANK1_SSN_CRC   0x47    /* Serial CRC Byte */
0243 #define RTC_BANK1_RAM_DATA_PORT 0x53    /* Extended RAM Data Port */
0244
0245
0246 /*
0247  * Model-specific registers in Bank 1.
0248  *
0249  * The addresses below differ depending on the model of the RTC chip
0250  * selected in the kernel configuration.  Not all of these features are
0251  * supported in the main driver at present.
0252  *
0253  * DS1685/DS1687   - Extended NV-SRAM address (LSB only).
0254  * DS1689/DS1693   - Vcc, Vbat, Pwr Cycle Counters & Customer-specific S/N.
0255  * DS17x85/DS17x87 - Extended NV-SRAM addresses (MSB & LSB) & Write counter.
0256  */
0257 #if defined(CONFIG_RTC_DRV_DS1685)
0258 #define RTC_BANK1_RAM_ADDR  0x50    /* NV-SRAM Addr */
0259 #elif defined(CONFIG_RTC_DRV_DS1689)
0260 #define RTC_BANK1_VCC_CTR_LSB   0x54    /* Vcc Counter Addr (LSB) */
0261 #define RTC_BANK1_VCC_CTR_MSB   0x57    /* Vcc Counter Addr (MSB) */
0262 #define RTC_BANK1_VBAT_CTR_LSB  0x58    /* Vbat Counter Addr (LSB) */
0263 #define RTC_BANK1_VBAT_CTR_MSB  0x5b    /* Vbat Counter Addr (MSB) */
0264 #define RTC_BANK1_PWR_CTR_LSB   0x5c    /* Pwr Cycle Counter Addr (LSB) */
0265 #define RTC_BANK1_PWR_CTR_MSB   0x5d    /* Pwr Cycle Counter Addr (MSB) */
0266 #define RTC_BANK1_UNIQ_SN   0x60    /* Customer-specific S/N */
0267 #else /* DS17x85/DS17x87 */
0268 #define RTC_BANK1_RAM_ADDR_LSB  0x50    /* NV-SRAM Addr (LSB) */
0269 #define RTC_BANK1_RAM_ADDR_MSB  0x51    /* NV-SRAM Addr (MSB) */
0270 #define RTC_BANK1_WRITE_CTR 0x5e    /* RTC Write Counter */
0271 #endif
0272
0273
0274 /*
0275  * Model numbers.
0276  *
0277  * The DS1688/DS1691 and DS1689/DS1693 chips share the same model number
0278  * and the manual doesn't indicate any major differences.  As such, they
0279  * are regarded as the same chip in this driver.
0280  */
0281 #define RTC_MODEL_DS1685    0x71    /* DS1685/DS1687 */
0282 #define RTC_MODEL_DS17285   0x72    /* DS17285/DS17287 */
0283 #define RTC_MODEL_DS1689    0x73    /* DS1688/DS1691/DS1689/DS1693 */
0284 #define RTC_MODEL_DS17485   0x74    /* DS17485/DS17487 */
0285 #define RTC_MODEL_DS17885   0x78    /* DS17885/DS17887 */
0286
0287
0288 /*
0289  * Periodic Interrupt Rates / Square-Wave Output Frequency
0290  *
0291  * Periodic rates are selected by setting the RS3-RS0 bits in Control
0292  * Register A and enabled via either the E32K bit in Extended Control
0293  * Register 4B or the SQWE bit in Control Register B.
0294  *
0295  * E32K overrides the settings of RS3-RS0 and outputs a frequency of 32768Hz
0296  * on the SQW pin of the RTC chip.  While there are 16 possible selections,
0297  * the 1-of-16 decoder is only able to divide the base 32768Hz signal into 13
0298  * smaller frequencies.  The values 0x01 and 0x02 are not used and are
0299  * synonymous with 0x08 and 0x09, respectively.
0300  *
0301  * When E32K is set to a logic 1, periodic interrupts are disabled and reading
0302  * /dev/rtc will return -EINVAL.  This also applies if the periodic interrupt
0303  * frequency is set to 0Hz.
0304  *
0305  * Not currently used by the rtc-ds1685 driver because the RTC core removed
0306  * support for hardware-generated periodic-interrupts in favour of
0307  * hrtimer-generated interrupts.  But these defines are kept around for use
0308  * in userland, as documentation to the hardware, and possible future use if
0309  * hardware-generated periodic interrupts are ever added back.
0310  */
0311                     /* E32K RS3 RS2 RS1 RS0 */
0312 #define RTC_SQW_8192HZ      0x03    /*  0    0   0   1   1  */
0313 #define RTC_SQW_4096HZ      0x04    /*  0    0   1   0   0  */
0314 #define RTC_SQW_2048HZ      0x05    /*  0    0   1   0   1  */
0315 #define RTC_SQW_1024HZ      0x06    /*  0    0   1   1   0  */
0316 #define RTC_SQW_512HZ       0x07    /*  0    0   1   1   1  */
0317 #define RTC_SQW_256HZ       0x08    /*  0    1   0   0   0  */
0318 #define RTC_SQW_128HZ       0x09    /*  0    1   0   0   1  */
0319 #define RTC_SQW_64HZ        0x0a    /*  0    1   0   1   0  */
0320 #define RTC_SQW_32HZ        0x0b    /*  0    1   0   1   1  */
0321 #define RTC_SQW_16HZ        0x0c    /*  0    1   1   0   0  */
0322 #define RTC_SQW_8HZ     0x0d    /*  0    1   1   0   1  */
0323 #define RTC_SQW_4HZ     0x0e    /*  0    1   1   1   0  */
0324 #define RTC_SQW_2HZ     0x0f    /*  0    1   1   1   1  */
0325 #define RTC_SQW_0HZ     0x00    /*  0    0   0   0   0  */
0326 #define RTC_SQW_32768HZ     32768   /*  1    -   -   -   -  */
0327 #define RTC_MAX_USER_FREQ   8192
0328
0329
0330 /*
0331  * NVRAM data & addresses:
0332  *   - 50 bytes of NVRAM are available just past the clock registers.
0333  *   - 64 additional bytes are available in Bank0.
0334  *
0335  * Extended, battery-backed NV-SRAM:
0336  *   - DS1685/DS1687    - 128 bytes.
0337  *   - DS1689/DS1693    - 0 bytes.
0338  *   - DS17285/DS17287  - 2048 bytes.
0339  *   - DS17485/DS17487  - 4096 bytes.
0340  *   - DS17885/DS17887  - 8192 bytes.
0341  */
0342 #define NVRAM_TIME_BASE     0x0e    /* NVRAM Addr in Time regs */
0343 #define NVRAM_BANK0_BASE    0x40    /* NVRAM Addr in Bank0 regs */
0344 #define NVRAM_SZ_TIME       50
0345 #define NVRAM_SZ_BANK0      64
0346 #if defined(CONFIG_RTC_DRV_DS1685)
0347 #  define NVRAM_SZ_EXTND    128
0348 #elif defined(CONFIG_RTC_DRV_DS1689)
0349 #  define NVRAM_SZ_EXTND    0
0350 #elif defined(CONFIG_RTC_DRV_DS17285)
0351 #  define NVRAM_SZ_EXTND    2048
0352 #elif defined(CONFIG_RTC_DRV_DS17485)
0353 #  define NVRAM_SZ_EXTND    4096
0354 #elif defined(CONFIG_RTC_DRV_DS17885)
0355 #  define NVRAM_SZ_EXTND    8192
0356 #endif
0357 #define NVRAM_TOTAL_SZ_BANK0    (NVRAM_SZ_TIME + NVRAM_SZ_BANK0)
0358 #define NVRAM_TOTAL_SZ      (NVRAM_TOTAL_SZ_BANK0 + NVRAM_SZ_EXTND)
0359
0360
0361 /*
0362  * Function Prototypes.
0363  */
0364 extern void __noreturn
0365 ds1685_rtc_poweroff(struct platform_device *pdev);
0366
0367 #endif /* _LINUX_RTC_DS1685_H_ */