2 * Copyright (c) 2017 Ian Lepore <ian@freebsd.org>
5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted provided that the following conditions
8 * 1. Redistributions of source code must retain the above copyright
9 * notice, this list of conditions and the following disclaimer.
10 * 2. Redistributions in binary form must reproduce the above copyright
11 * notice, this list of conditions and the following disclaimer in the
12 * documentation and/or other materials provided with the distribution.
14 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
15 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
16 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
17 * ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
18 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
19 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
20 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
21 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
22 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
23 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
27 #include <sys/cdefs.h>
28 __FBSDID("$FreeBSD$");
31 * Driver for Dallas/Maxim DS13xx real-time clock/calendar chips:
33 * - DS1307 = Original/basic rtc + 56 bytes ram; 5v only.
34 * - DS1308 = Updated 1307, available in 1.8v-5v variations.
35 * - DS1337 = Like 1308, integrated xtal, 32khz output on at powerup.
36 * - DS1338 = Like 1308, integrated xtal.
37 * - DS1339 = Like 1337, integrated xtal, integrated trickle charger.
38 * - DS1340 = Like 1338, ST M41T00 compatible.
39 * - DS1341 = Like 1338, can slave-sync osc to external clock signal.
40 * - DS1342 = Like 1341 but requires different xtal.
41 * - DS1371 = 32-bit binary counter, watchdog timer.
42 * - DS1372 = 32-bit binary counter, 64-bit unique id in rom.
43 * - DS1374 = 32-bit binary counter, watchdog timer, trickle charger.
44 * - DS1375 = Like 1308 but only 16 bytes ram.
45 * - DS1388 = Rtc, watchdog timer, 512 bytes eeprom (not sram).
47 * This driver supports only basic timekeeping functions. It provides no access
48 * to or control over any other functionality provided by the chips.
51 #include "opt_platform.h"
53 #include <sys/param.h>
54 #include <sys/systm.h>
56 #include <sys/clock.h>
57 #include <sys/endian.h>
58 #include <sys/kernel.h>
59 #include <sys/libkern.h>
60 #include <sys/module.h>
62 #include <dev/iicbus/iicbus.h>
63 #include <dev/iicbus/iiconf.h>
65 #include <dev/ofw/openfirm.h>
66 #include <dev/ofw/ofw_bus.h>
67 #include <dev/ofw/ofw_bus_subr.h>
71 #include "iicbus_if.h"
74 * I2C address 1101 000x
76 #define DS13xx_ADDR 0xd0
79 * Registers, bits within them, and masks for the various chip types.
82 #define DS13xx_R_NONE 0xff /* Placeholder */
84 #define DS130x_R_CONTROL 0x07
85 #define DS133x_R_CONTROL 0x0e
86 #define DS1340_R_CONTROL 0x07
87 #define DS1341_R_CONTROL 0x0e
88 #define DS1371_R_CONTROL 0x07
89 #define DS1372_R_CONTROL 0x07
90 #define DS1374_R_CONTROL 0x07
91 #define DS1375_R_CONTROL 0x0e
92 #define DS1388_R_CONTROL 0x0c
94 #define DS13xx_R_SECOND 0x00
95 #define DS1388_R_SECOND 0x01
97 #define DS130x_R_STATUS DS13xx_R_NONE
98 #define DS133x_R_STATUS 0x0f
99 #define DS1340_R_STATUS 0x09
100 #define DS137x_R_STATUS 0x08
101 #define DS1388_R_STATUS 0x0b
103 #define DS13xx_B_STATUS_OSF 0x80 /* OSF is 1<<7 in status and sec regs */
104 #define DS13xx_B_HOUR_AMPM 0x40 /* AMPM mode is bit 1<<6 */
105 #define DS13xx_B_HOUR_PM 0x20 /* PM hours indicated by 1<<5 */
106 #define DS13xx_B_MONTH_CENTURY 0x80 /* 21st century indicated by 1<<7 */
108 #define DS13xx_M_SECOND 0x7f /* Masks for all BCD time regs... */
109 #define DS13xx_M_MINUTE 0x7f
110 #define DS13xx_M_12HOUR 0x1f
111 #define DS13xx_M_24HOUR 0x3f
112 #define DS13xx_M_DAY 0x3f
113 #define DS13xx_M_MONTH 0x1f
114 #define DS13xx_M_YEAR 0xff
117 * The chip types we support.
137 static const char *desc_strings[] = {
139 "Dallas/Maxim DS1307 RTC",
140 "Dallas/Maxim DS1308 RTC",
141 "Dallas/Maxim DS1337 RTC",
142 "Dallas/Maxim DS1338 RTC",
143 "Dallas/Maxim DS1339 RTC",
144 "Dallas/Maxim DS1340 RTC",
145 "Dallas/Maxim DS1341 RTC",
146 "Dallas/Maxim DS1342 RTC",
147 "Dallas/Maxim DS1371 RTC",
148 "Dallas/Maxim DS1372 RTC",
149 "Dallas/Maxim DS1374 RTC",
150 "Dallas/Maxim DS1375 RTC",
151 "Dallas/Maxim DS1388 RTC",
153 CTASSERT(nitems(desc_strings) == TYPE_COUNT);
156 * The time registers in the order they are laid out in hardware.
159 uint8_t sec, min, hour, wday, day, month, year;
162 struct ds13rtc_softc {
165 u_int flags; /* SC_F_* flags */
166 u_int chiptype; /* Type of DS13xx chip */
167 uint8_t secaddr; /* Address of seconds register */
168 uint8_t osfaddr; /* Address of register with OSF */
171 #define SC_F_BINARY (1u << 0) /* Time is 32-bit binary counter */
172 #define SC_F_AMPM (1u << 1) /* Use PM flag in hours reg */
173 #define SC_F_CENTURY (1u << 2) /* Use century bit */
176 * We use the compat_data table to look up hint strings in the non-FDT case, so
177 * define the struct locally when we don't get it from ofw_bus_subr.h.
180 typedef struct ofw_compat_data ds13_compat_data;
188 static ds13_compat_data compat_data[] = {
189 {"dallas,ds1307", TYPE_DS1307},
190 {"dallas,ds1308", TYPE_DS1308},
191 {"dallas,ds1337", TYPE_DS1337},
192 {"dallas,ds1338", TYPE_DS1338},
193 {"dallas,ds1339", TYPE_DS1339},
194 {"dallas,ds1340", TYPE_DS1340},
195 {"dallas,ds1341", TYPE_DS1341},
196 {"dallas,ds1342", TYPE_DS1342},
197 {"dallas,ds1371", TYPE_DS1371},
198 {"dallas,ds1372", TYPE_DS1372},
199 {"dallas,ds1374", TYPE_DS1374},
200 {"dallas,ds1375", TYPE_DS1375},
201 {"dallas,ds1388", TYPE_DS1388},
207 read_reg(struct ds13rtc_softc *sc, uint8_t reg, uint8_t *val)
210 return (iicdev_readfrom(sc->dev, reg, val, sizeof(*val), IIC_WAIT));
214 write_reg(struct ds13rtc_softc *sc, uint8_t reg, uint8_t val)
217 return (iicdev_writeto(sc->dev, reg, &val, sizeof(val), IIC_WAIT));
221 read_timeregs(struct ds13rtc_softc *sc, struct time_regs *tregs)
225 if ((err = iicdev_readfrom(sc->dev, sc->secaddr, tregs,
226 sizeof(*tregs), IIC_WAIT)) != 0)
233 write_timeregs(struct ds13rtc_softc *sc, struct time_regs *tregs)
236 return (iicdev_writeto(sc->dev, sc->secaddr, tregs,
237 sizeof(*tregs), IIC_WAIT));
241 read_timeword(struct ds13rtc_softc *sc, time_t *secs)
246 if ((err = iicdev_readfrom(sc->dev, sc->secaddr, buf, sizeof(buf),
248 *secs = le32dec(buf);
254 write_timeword(struct ds13rtc_softc *sc, time_t secs)
258 le32enc(buf, (uint32_t)secs);
259 return (iicdev_writeto(sc->dev, sc->secaddr, buf, sizeof(buf),
264 ds13rtc_start(void *arg)
266 struct ds13rtc_softc *sc;
267 uint8_t ctlreg, statreg;
272 * Every chip in this family can be usefully initialized by writing 0 to
273 * the control register, except DS1375 which has an external oscillator
274 * controlled by values in the ctlreg that we know nothing about, so
275 * we'd best leave them alone. For all other chips, writing 0 enables
276 * the oscillator, disables signals/outputs in battery-backed mode
277 * (saves power) and disables features like watchdog timers and alarms.
279 switch (sc->chiptype) {
287 ctlreg = DS130x_R_CONTROL;
291 ctlreg = DS133x_R_CONTROL;
295 ctlreg = DS1341_R_CONTROL;
298 ctlreg = DS13xx_R_NONE;
301 ctlreg = DS1388_R_CONTROL;
304 device_printf(sc->dev, "missing init code for this chiptype\n");
307 if (ctlreg != DS13xx_R_NONE)
308 write_reg(sc, ctlreg, 0);
311 * Common init. Read the OSF/CH status bit and report stopped clocks to
312 * the user. The status bit will be cleared the first time we write
313 * valid time to the chip (and must not be cleared before that).
315 if (read_reg(sc, sc->osfaddr, &statreg) != 0) {
316 device_printf(sc->dev, "cannot read RTC clock status bit\n");
319 if (statreg & DS13xx_B_STATUS_OSF) {
320 device_printf(sc->dev,
321 "WARNING: RTC battery failed; time is invalid\n");
325 * Figure out whether the chip is configured for AM/PM mode. On all
326 * chips that do AM/PM mode, the flag bit is in the hours register,
327 * which is secaddr+2.
329 if ((sc->chiptype != TYPE_DS1340) && !(sc->flags & SC_F_BINARY)) {
330 if (read_reg(sc, sc->secaddr + 2, &statreg) != 0) {
331 device_printf(sc->dev,
332 "cannot read RTC clock AM/PM bit\n");
335 if (statreg & DS13xx_B_HOUR_AMPM)
336 sc->flags |= SC_F_AMPM;
340 * Everything looks good if we make it to here; register as an RTC.
341 * Schedule RTC updates to happen just after top-of-second.
343 clock_register_flags(sc->dev, 1000000, CLOCKF_SETTIME_NO_ADJ);
344 clock_schedule(sc->dev, 1);
348 ds13rtc_gettime(device_t dev, struct timespec *ts)
351 struct time_regs tregs;
352 struct ds13rtc_softc *sc;
354 uint8_t statreg, hourmask;
356 sc = device_get_softc(dev);
358 /* Read the OSF/CH bit; if the clock stopped we can't provide time. */
359 if ((err = read_reg(sc, sc->osfaddr, &statreg)) != 0) {
362 if (statreg & DS13xx_B_STATUS_OSF)
363 return (EINVAL); /* hardware is good, time is not. */
365 /* If the chip counts time in binary, we just read and return it. */
366 if (sc->flags & SC_F_BINARY) {
367 if ((err = read_timeword(sc, &ts->tv_sec)) != 0)
373 * Chip counts in BCD, read and decode it...
375 if ((err = read_timeregs(sc, &tregs)) != 0) {
376 device_printf(dev, "cannot read RTC time\n");
380 if (sc->flags & SC_F_AMPM)
381 hourmask = DS13xx_M_12HOUR;
383 hourmask = DS13xx_M_24HOUR;
385 ct.sec = FROMBCD(tregs.sec & DS13xx_M_SECOND);
386 ct.min = FROMBCD(tregs.min & DS13xx_M_MINUTE);
387 ct.hour = FROMBCD(tregs.hour & hourmask);
388 ct.day = FROMBCD(tregs.day & DS13xx_M_DAY);
389 ct.mon = FROMBCD(tregs.month & DS13xx_M_MONTH);
390 ct.year = FROMBCD(tregs.year & DS13xx_M_YEAR);
393 if (sc->flags & SC_F_AMPM) {
396 if (tregs.hour & DS13xx_B_HOUR_PM)
401 * If this chip has a century bit, honor it. Otherwise let
402 * clock_ct_to_ts() infer the century from the 2-digit year.
404 if (sc->flags & SC_F_CENTURY)
405 ct.year += (tregs.month & DS13xx_B_MONTH_CENTURY) ? 2000 : 1900;
407 err = clock_ct_to_ts(&ct, ts);
413 ds13rtc_settime(device_t dev, struct timespec *ts)
416 struct time_regs tregs;
417 struct ds13rtc_softc *sc;
419 uint8_t cflag, statreg, pmflag;
421 sc = device_get_softc(dev);
424 * We request a timespec with no resolution-adjustment. That also
425 * disables utc adjustment, so apply that ourselves.
427 ts->tv_sec -= utc_offset();
429 /* If the chip counts time in binary, store tv_sec and we're done. */
430 if (sc->flags & SC_F_BINARY)
431 return (write_timeword(sc, ts->tv_sec));
433 clock_ts_to_ct(ts, &ct);
435 /* If the chip is in AMPM mode deal with the PM flag. */
437 if (sc->flags & SC_F_AMPM) {
440 pmflag = DS13xx_B_HOUR_PM;
446 /* If the chip has a century bit, set it as needed. */
448 if (sc->flags & SC_F_CENTURY) {
450 cflag |= DS13xx_B_MONTH_CENTURY;
453 tregs.sec = TOBCD(ct.sec);
454 tregs.min = TOBCD(ct.min);
455 tregs.hour = TOBCD(ct.hour) | pmflag;
456 tregs.day = TOBCD(ct.day);
457 tregs.month = TOBCD(ct.mon) | cflag;
458 tregs.year = TOBCD(ct.year % 100);
462 * Set the time. Reset the OSF bit if it is on and it is not part of
463 * the time registers (in which case writing time resets it).
465 if ((err = write_timeregs(sc, &tregs)) != 0)
467 if (sc->osfaddr != sc->secaddr) {
468 if ((err = read_reg(sc, sc->osfaddr, &statreg)) != 0)
470 if (statreg & DS13xx_B_STATUS_OSF) {
471 statreg &= ~DS13xx_B_STATUS_OSF;
472 err = write_reg(sc, sc->osfaddr, statreg);
479 device_printf(dev, "cannot update RTC time\n");
485 ds13rtc_get_chiptype(device_t dev)
489 return (ofw_bus_search_compatible(dev, compat_data)->ocd_data);
491 ds13_compat_data *cdata;
495 * We can only attach if provided a chiptype hint string.
497 if (resource_string_value(device_get_name(dev),
498 device_get_unit(dev), "compatible", &htype) != 0)
502 * Loop through the ofw compat data comparing the hinted chip type to
503 * the compat strings.
505 for (cdata = compat_data; cdata->ocd_str != NULL; ++cdata) {
506 if (strcmp(htype, cdata->ocd_str) == 0)
509 return (cdata->ocd_data);
514 ds13rtc_probe(device_t dev)
516 int chiptype, goodrv;
519 if (!ofw_bus_status_okay(dev))
521 goodrv = BUS_PROBE_GENERIC;
523 goodrv = BUS_PROBE_NOWILDCARD;
526 chiptype = ds13rtc_get_chiptype(dev);
527 if (chiptype == TYPE_NONE)
530 device_set_desc(dev, desc_strings[chiptype]);
535 ds13rtc_attach(device_t dev)
537 struct ds13rtc_softc *sc;
539 sc = device_get_softc(dev);
541 sc->busdev = device_get_parent(dev);
544 * We need to know what kind of chip we're driving.
546 if ((sc->chiptype = ds13rtc_get_chiptype(dev)) == TYPE_NONE) {
547 device_printf(dev, "impossible: cannot determine chip type\n");
551 /* The seconds register is in the same place on all except DS1388. */
552 if (sc->chiptype == TYPE_DS1388)
553 sc->secaddr = DS1388_R_SECOND;
555 sc->secaddr = DS13xx_R_SECOND;
558 * The OSF/CH (osc failed/clock-halted) bit appears in different
559 * registers for different chip types. The DS1375 has no OSF indicator
560 * because it has no internal oscillator; we just point to an always-
561 * zero bit in the status register for that chip.
563 switch (sc->chiptype) {
567 sc->osfaddr = DS13xx_R_SECOND;
574 sc->osfaddr = DS133x_R_STATUS;
575 sc->flags |= SC_F_CENTURY;
578 sc->osfaddr = DS1340_R_STATUS;
583 sc->osfaddr = DS137x_R_STATUS;
584 sc->flags |= SC_F_BINARY;
587 sc->osfaddr = DS1388_R_STATUS;
592 * We have to wait until interrupts are enabled. Sometimes I2C read
593 * and write only works when the interrupts are available.
595 config_intrhook_oneshot(ds13rtc_start, sc);
601 ds13rtc_detach(device_t dev)
604 clock_unregister(dev);
608 static device_method_t ds13rtc_methods[] = {
609 DEVMETHOD(device_probe, ds13rtc_probe),
610 DEVMETHOD(device_attach, ds13rtc_attach),
611 DEVMETHOD(device_detach, ds13rtc_detach),
613 DEVMETHOD(clock_gettime, ds13rtc_gettime),
614 DEVMETHOD(clock_settime, ds13rtc_settime),
619 static driver_t ds13rtc_driver = {
622 sizeof(struct ds13rtc_softc),
625 static devclass_t ds13rtc_devclass;
627 DRIVER_MODULE(ds13rtc, iicbus, ds13rtc_driver, ds13rtc_devclass, NULL, NULL);
628 MODULE_VERSION(ds13rtc, 1);
629 MODULE_DEPEND(ds13rtc, iicbus, IICBB_MINVER, IICBB_PREFVER, IICBB_MAXVER);