1/* $NetBSD: ds1687reg.h,v 1.13 2022/05/20 19:34:22 andvar 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 Semiconductor 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 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 accessible 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 /* auxiliary 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 */ 203u_int ds1687_read(void *, u_int); 204void ds1687_write(void *, u_int, u_int); 205 206/* 207 * A collection of TOD/Alarm registers. 208 */ 209typedef 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); 262