sys/dev/ic/ds1687reg.h

   1 /*      $NetBSD: ds1687reg.h,v 1.9 2007/09/26 05:47:41 macallan Exp $   */
   2
   3 /*
   4  * Copyright (c) 2003 The NetBSD Foundation, Inc.
   5  * All rights reserved.
   6  *
   7  * This code is derived from software contributed to The NetBSD Foundation
   8  * by Rafal K. Boni.
   9  *
  10  * Redistribution and use in source and binary forms, with or without
  11  * modification, are permitted provided that the following conditions
  12  * are met:
  13  * 1. Redistributions of source code must retain the above copyright
  14  *    notice, this list of conditions and the following disclaimer.
  15  * 2. Redistributions in binary form must reproduce the above copyright
  16  *    notice, this list of conditions and the following disclaimer in the
  17  *    documentation and/or other materials provided with the distribution.
  18  *
  19  * THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  20  * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  21  * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  22  * PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  23  * BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  24  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  25  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  26  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  27  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  28  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  29  * POSSIBILITY OF SUCH DAMAGE.
  30  */
  31
  32 /*
  33  * Originally based on mc146818reg.h, with the following license:
  34  *
  35  * Copyright (c) 1995 Carnegie-Mellon University.
  36  * All rights reserved.
  37  *
  38  * Permission to use, copy, modify and distribute this software and
  39  * its documentation is hereby granted, provided that both the copyright
  40  * notice and this permission notice appear in all copies of the
  41  * software, derivative works or modified versions, and any portions
  42  * thereof, and that both notices appear in supporting documentation.
  43  *
  44  * CARNEGIE MELLON ALLOWS FREE USE OF THIS SOFTWARE IN ITS "AS IS"
  45  * CONDITION.  CARNEGIE MELLON DISCLAIMS ANY LIABILITY OF ANY KIND
  46  * FOR ANY DAMAGES WHATSOEVER RESULTING FROM THE USE OF THIS SOFTWARE.
  47  *
  48  * Carnegie Mellon requests users of this software to return to
  49  *
  50  *  Software Distribution Coordinator  or  Software.Distribution@CS.CMU.EDU
  51  *  School of Computer Science
  52  *  Carnegie Mellon University
  53  *  Pittsburgh PA 15213-3890
  54  *
  55  * any improvements or extensions that they make and grant Carnegie the
  56  * rights to redistribute these changes.
  57  */
  58
  59 /*
  60  * Definitions for the Dallas Semiconductor DS1687 Real Time Clock.
  61  *
  62  * The DS1687 and follow-on RTC chips are Y2k-compliant successors to the
  63  * DS1287, which in turn is register-compatible with the MC146818 and/or
  64  * MC146818A RTCs.
  65  *
  66  * Plucked right from the Dallas Semicomductor specs available at:
  67  *      http://pdfserv.maxim-ic.com/arpdf/DS1685-DS1687.pdf
  68  *
  69  * The DS1686 contains 14 basic clock-related registers and 50 bytes of
  70  * user RAM laid out for compatibility with the register layout of the
  71  * DS1287/MC14818 chips.  It also includes an extended mode which allows
  72  * access to these same basic registers as well an an extended register
  73  * set and NVRAM area; this extended register set includes a century
  74  * register for Y2k compliant date storage.
  75  *
  76  * Since the locations of these ports and the method used to access them
  77  * can be machine-dependent, the low-level details of reading and writing
  78  * writing the RTC's registers are handled by machine-specific functions.
  79  *
  80  * The Dallas chip can store time-of-day and alarm data in BCD or binary;
  81  * this setting applies to *all* values stored in the clock chip and a
  82  * change from one mode to the other requires *all* of the clock data to
  83  * be re-written.   The "hours" time-of-year and alarm registers can be
  84  * stored either in an AM/PM or a 24-hour format; the format is set
  85  * globally and changing it requires re-writing both the hours time-of-
  86  * year and alarm registers.  In AM/PM mode, the hour must be in the
  87  * range of 1-12 (and stored as either BCD or binary), with the high-
  88  * bit cleared to indicate AM and set to indicate PM.  In 24-hour mode,
  89  * hours must be in the range 0-23.
  90  *
  91  * In order to support extended features like the century register and
  92  * an embedded silicon serial number while keeping backwards compatibility
  93  * with the DS1287/MC146818, the DS1687 provides a bank-switching method
  94  * which allows the user to switch the RTC between a "compatible" mode in
  95  * bank 0 and an extended mode in bank 1.
  96  *
  97  * Both banks provide access to the 14 timekeeping/alarm registers and
  98  * to 50 bytes of user RAM.  In addition, bank 0 provides access to an
  99  * additional 64 bytes of user RAM in the upper half of the RTC address
 100  * space.
 101  *
 102  * Bank 1, on the other hand, provides access to an extended register set,
 103  * including a silicon serial number -- including a model ID byte, century
 104  * register for Y2k compatibility and memory address/data registers which
 105  * allow indirect access to a larger extended user RAM address space.  It
 106  * is worth noting that the extended user RAM is distinct from the "basic"
 107  * 114 bytes of user RAM which are accesible in bank 0.
 108  */
 109
 110 /*
 111  * The registers, and the bits within each register.
 112  */
 113
 114 #define DS1687_SEC      0x00    /* Time of year: seconds (0-59) */
 115 #define DS1687_ASEC     0x01    /* Alarm: seconds */
 116 #define DS1687_MIN      0x02    /* Time of year: minutes (0-59) */
 117 #define DS1687_AMIN     0x03    /* Alarm: minutes */
 118 #define DS1687_HOUR     0x04    /* Time of year: hour (see above) */
 119 #define DS1687_AHOUR    0x05    /* Alarm: hour (see above) */
 120 #define DS1687_DOW      0x06    /* Time of year: day of week (1-7, 1 = Sun) */
 121 #define DS1687_DOM      0x07    /* Time of year: day of month (1-31) */
 122 #define DS1687_MONTH    0x08    /* Time of year: month (1-12) */
 123 #define DS1687_YEAR     0x09    /* Time of year: year in century (0-99) */
 124
 125 #define DS1687_CONTROLA 0x0a    /* Control Register A */
 126
 127 #define DS1687_UIP      0x80    /* Update in progress: RO */
 128 #define DS1687_DV2      0x40    /* Countdown chain: 0 = on,  1 = reset if DV1 */
 129 #define DS1687_DV1      0x20    /* Oscillator enable */
 130 #define DS1687_BANK1    0x10    /* Bank select: 0 = bank0, 1 = bank1 */
 131 #define DS1687_RATEMASK 0x0f    /* Rate select bits for sq. wave and PIE */
 132
 133 #define DS1687_CONTROLB 0x0b    /* Control Register B */
 134
 135 #define DS1687_SET      0x80    /* Clock update control: 1 = disable update */
 136 #define DS1687_PIE      0x40    /* Periodic interrupt enable */
 137 #define DS1687_AIE      0x20    /* Alarm interrupt enable */
 138 #define DS1687_UIE      0x10    /* Update-ended interrupt enable */
 139 #define DS1687_SQWE     0x08    /* Enable sq. wave output on SQW pin */
 140 #define DS1687_BINARY   0x04    /* Data mode: 0 = BCD, 1 = binary data */
 141 #define DS1687_24HRS    0x02    /* Hour format: 1 = 24hrs, 0 = 12hrs */
 142 #define DS1687_DSE      0x01    /* Daylight savings enable */
 143
 144 #define DS1687_CONTROLC 0x0c    /* Control register C: Read-only */
 145                                 /* Note: PF, AF, UF cleared on read */
 146
 147 #define DS1687_IRQF     0x80    /* IRQ present: set when any IRQ is active */
 148 #define DS1687_PF       0x40    /* Periodic interrupt: independent of PIE */
 149 #define DS1687_AF       0x20    /* Alarm reached: independent of AIE */
 150 #define DS1687_UF       0x10    /* Update ended: independent of UIE */
 151
 152 #define DS1687_CONTROLD 0x0d    /* Control register D: Read-only */
 153
 154 #define DS1687_VRT      0x80    /* Valid RAM and time: battery bad if 0 */
 155
 156 #define DS1687_NVRAM_START      0x0e    /* Start of user ram: offset 14 */
 157 #define DS1687_NVRAM_SIZE       0x72    /* 114 bytes of user RAM */
 158
 159 #define DS1687_BANK1_START      0x40    /* BANK1: Start of BANK1 registers */
 160 #define DS1687_BANK1_CENTURY    0x48    /* BANK1: Time of yr: Century (0-99) */
 161 #define DS1687_BANK1_ADATE      0x49    /* BANK1: Alarm: Date (1-31) */
 162 #define DS1687_BANK1_XCTRL4A    0x4a
 163         #define DS1687_X4A_VRT  0x80    /* valid RAM / time */
 164         #define DS1687_X4A_INCR 0x40    /* increment status */
 165         #define DS1687_X4A_BME  0x20    /* burst mode enable */
 166         #define DS1687_X4A_PAB  0x08    /* power active bar */
 167         #define DS1687_X4A_RCF  0x04    /* read clear flag */
 168         #define DS1687_X4A_WAF  0x02    /* wakeup alarm flag */
 169         #define DS1687_X4A_KF   0x01    /* kickstart flag */
 170 #define DS1687_BANK1_XCTRL4B    0x4b
 171         #define DS1687_X4B_ABE  0x80    /* auxillary battery enable */
 172         #define DS1687_X4B_E32K 0x40    /* enable 32.768kHz output */
 173         #define DS1687_X4B_CS   0x20    /* chrystal select */
 174         #define DS1687_X4B_RCE  0x10    /* RAM clear enable */
 175         #define DS1687_X4B_PRS  0x08    /* PAB reset select */
 176         #define DS1687_X4B_RCIE 0x04    /* RAM clear interrupt enable */
 177         #define DS1687_X4B_WIE  0x02    /* wakeup interrupt enable */
 178         #define DS1687_X4B_KIE  0x01    /* kickstart interrupt enable */
 179
 180 #define DS1687_NBASEREGS        0x0d    /* 14 registers; CMOS follows */
 181
 182 /* Layout of software shadow copy of TOD registers */
 183 #define DS1687_NHDW_TODREGS     0x0a    /* 10 basic TOD registers */
 184 #define DS1687_NSOFT_TODREGS    0x0c    /* ...plus shadow CENTURY, ADATE */
 185
 186 #define DS1687_SOFT_SEC         0x00
 187 #define DS1687_SOFT_ASEC        0x01
 188 #define DS1687_SOFT_MIN         0x02
 189 #define DS1687_SOFT_AMIN        0x03
 190 #define DS1687_SOFT_HOUR        0x04
 191 #define DS1687_SOFT_AHOUR       0x05
 192 #define DS1687_SOFT_DOW         0x06
 193 #define DS1687_SOFT_DOM         0x07
 194 #define DS1687_SOFT_MONTH       0x08
 195 #define DS1687_SOFT_YEAR        0x09
 196 #define DS1687_SOFT_CENTURY     0x0a
 197 #define DS1687_SOFT_ADATE       0x0b
 198
 199 /*
 200  * RTC register/NVRAM read and write functions -- machine-dependent.
 201  * Appropriately manipulate RTC registers to get/put data values.
 202  */
 203 u_int ds1687_read(void *, u_int);
 204 void ds1687_write(void *, u_int, u_int);
 205
 206 /*
 207  * A collection of TOD/Alarm registers.
 208  */
 209 typedef u_int ds1687_todregs[DS1687_NSOFT_TODREGS];
 210
 211 /*
 212  * Get all of the TOD/Alarm registers
 213  * Must be called at splhigh(), and with the RTC properly set up.
 214  */
 215 #define DS1687_GETTOD(sc, regs)                                         \
 216         do {                                                            \
 217                 int i;                                                  \
 218                 u_int ctl;                                              \
 219                                                                         \
 220                 /* turn off update for now */                           \
 221                 ctl = ds1687_read(sc, DS1687_CONTROLB);                 \
 222                 ds1687_write(sc, DS1687_CONTROLB, ctl | DS1687_SET);    \
 223                                                                         \
 224                 /* read all of the tod/alarm regs */                    \
 225                 for (i = 0; i < DS1687_NHDW_TODREGS; i++)               \
 226                         (*regs)[i] = ds1687_read(sc, i);                \
 227                                                                         \
 228                 (*regs)[DS1687_SOFT_CENTURY] =                          \
 229                                 ds1687_read(sc, DS1687_BANK1_CENTURY);  \
 230                 (*regs)[DS1687_SOFT_ADATE] =                            \
 231                                 ds1687_read(sc, DS1687_BANK1_ADATE);    \
 232                                                                         \
 233                 /* turn update back on */                               \
 234                 ds1687_write(sc, DS1687_CONTROLB, ctl);                 \
 235         } while (0);
 236
 237 /*
 238  * Set all of the TOD/Alarm registers
 239  * Must be called at splhigh(), and with the RTC properly set up.
 240  */
 241 #define DS1687_PUTTOD(sc, regs)                                         \
 242         do {                                                            \
 243                 int i;                                                  \
 244                 u_int ctl;                                              \
 245                                                                         \
 246                 /* turn off update for now */                           \
 247                 ctl = ds1687_read(sc, DS1687_CONTROLB);                 \
 248                 ds1687_write(sc, DS1687_CONTROLB, ctl | DS1687_SET);    \
 249                                                                         \
 250                 /* write all of the tod/alarm regs */                   \
 251                 for (i = 0; i < DS1687_NHDW_TODREGS; i++)               \
 252                         ds1687_write(sc, i, (*regs)[i]);                \
 253                                                                         \
 254                 ds1687_write(sc, DS1687_BANK1_CENTURY,                  \
 255                                         (*regs)[DS1687_SOFT_CENTURY]);  \
 256                 ds1687_write(sc, DS1687_BANK1_ADATE,                    \
 257                                         (*regs)[DS1687_SOFT_ADATE]);    \
 258                                                                         \
 259                 /* turn update back on */                               \
 260                 ds1687_write(sc, DS1687_CONTROLB, ctl);                 \
 261         } while (0);