1 /*-
2 * SPDX-License-Identifier: BSD-2-Clause
3 *
4 * Copyright (c) 2017 Ian Lepore <ian@freebsd.org>
5 *
6 * Redistribution and use in source and binary forms, with or without
7 * modification, are permitted provided that the following conditions
8 * are met:
9 * 1. Redistributions of source code must retain the above copyright
10 * notice, this list of conditions and the following disclaimer.
11 * 2. Redistributions in binary form must reproduce the above copyright
12 * notice, this list of conditions and the following disclaimer in the
13 * documentation and/or other materials provided with the distribution.
14 *
15 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
16 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
17 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
18 * ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
19 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
20 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
21 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
22 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
23 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
24 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
25 * SUCH DAMAGE.
26 */
27
28 #include <sys/cdefs.h>
29 /*
30 * Driver for Dallas/Maxim DS13xx real-time clock/calendar chips:
31 *
32 * - DS1307 = Original/basic rtc + 56 bytes ram; 5v only.
33 * - DS1308 = Updated 1307, available in 1.8v-5v variations.
34 * - DS1337 = Like 1308, integrated xtal, 32khz output on at powerup.
35 * - DS1338 = Like 1308, integrated xtal.
36 * - DS1339 = Like 1337, integrated xtal, integrated trickle charger.
37 * - DS1340 = Like 1338, ST M41T00 compatible.
38 * - DS1341 = Like 1338, can slave-sync osc to external clock signal.
39 * - DS1342 = Like 1341 but requires different xtal.
40 * - DS1371 = 32-bit binary counter, watchdog timer.
41 * - DS1372 = 32-bit binary counter, 64-bit unique id in rom.
42 * - DS1374 = 32-bit binary counter, watchdog timer, trickle charger.
43 * - DS1375 = Like 1308 but only 16 bytes ram.
44 * - DS1388 = Rtc, watchdog timer, 512 bytes eeprom (not sram).
45 *
46 * This driver supports only basic timekeeping functions. It provides no access
47 * to or control over any other functionality provided by the chips.
48 */
49
50 #include "opt_platform.h"
51
52 #include <sys/param.h>
53 #include <sys/systm.h>
54 #include <sys/bus.h>
55 #include <sys/clock.h>
56 #include <sys/endian.h>
57 #include <sys/kernel.h>
58 #include <sys/libkern.h>
59 #include <sys/module.h>
60
61 #include <dev/iicbus/iicbus.h>
62 #include <dev/iicbus/iiconf.h>
63 #ifdef FDT
64 #include <dev/ofw/openfirm.h>
65 #include <dev/ofw/ofw_bus.h>
66 #include <dev/ofw/ofw_bus_subr.h>
67 #endif
68
69 #include "clock_if.h"
70 #include "iicbus_if.h"
71
72 /*
73 * I2C address 1101 000x
74 */
75 #define DS13xx_ADDR 0xd0
76
77 /*
78 * Registers, bits within them, and masks for the various chip types.
79 */
80
81 #define DS13xx_R_NONE 0xff /* Placeholder */
82
83 #define DS130x_R_CONTROL 0x07
84 #define DS133x_R_CONTROL 0x0e
85 #define DS1340_R_CONTROL 0x07
86 #define DS1341_R_CONTROL 0x0e
87 #define DS1371_R_CONTROL 0x07
88 #define DS1372_R_CONTROL 0x07
89 #define DS1374_R_CONTROL 0x07
90 #define DS1375_R_CONTROL 0x0e
91 #define DS1388_R_CONTROL 0x0c
92
93 #define DS13xx_R_SECOND 0x00
94 #define DS1388_R_SECOND 0x01
95
96 #define DS130x_R_STATUS DS13xx_R_NONE
97 #define DS133x_R_STATUS 0x0f
98 #define DS1340_R_STATUS 0x09
99 #define DS137x_R_STATUS 0x08
100 #define DS1388_R_STATUS 0x0b
101
102 #define DS13xx_B_STATUS_OSF 0x80 /* OSF is 1<<7 in status and sec regs */
103 #define DS13xx_B_HOUR_AMPM 0x40 /* AMPM mode is bit 1<<6 */
104 #define DS13xx_B_HOUR_PM 0x20 /* PM hours indicated by 1<<5 */
105 #define DS13xx_B_MONTH_CENTURY 0x80 /* 21st century indicated by 1<<7 */
106
107 #define DS13xx_M_SECOND 0x7f /* Masks for all BCD time regs... */
108 #define DS13xx_M_MINUTE 0x7f
109 #define DS13xx_M_12HOUR 0x1f
110 #define DS13xx_M_24HOUR 0x3f
111 #define DS13xx_M_DAY 0x3f
112 #define DS13xx_M_MONTH 0x1f
113 #define DS13xx_M_YEAR 0xff
114
115 /*
116 * The chip types we support.
117 */
118 enum {
119 TYPE_NONE,
120 TYPE_DS1307,
121 TYPE_DS1308,
122 TYPE_DS1337,
123 TYPE_DS1338,
124 TYPE_DS1339,
125 TYPE_DS1340,
126 TYPE_DS1341,
127 TYPE_DS1342,
128 TYPE_DS1371,
129 TYPE_DS1372,
130 TYPE_DS1374,
131 TYPE_DS1375,
132 TYPE_DS1388,
133
134 TYPE_COUNT
135 };
136 static const char *desc_strings[] = {
137 "",
138 "Dallas/Maxim DS1307 RTC",
139 "Dallas/Maxim DS1308 RTC",
140 "Dallas/Maxim DS1337 RTC",
141 "Dallas/Maxim DS1338 RTC",
142 "Dallas/Maxim DS1339 RTC",
143 "Dallas/Maxim DS1340 RTC",
144 "Dallas/Maxim DS1341 RTC",
145 "Dallas/Maxim DS1342 RTC",
146 "Dallas/Maxim DS1371 RTC",
147 "Dallas/Maxim DS1372 RTC",
148 "Dallas/Maxim DS1374 RTC",
149 "Dallas/Maxim DS1375 RTC",
150 "Dallas/Maxim DS1388 RTC",
151 };
152 CTASSERT(nitems(desc_strings) == TYPE_COUNT);
153
154 /*
155 * The time registers in the order they are laid out in hardware.
156 */
157 struct time_regs {
158 uint8_t sec, min, hour, wday, day, month, year;
159 };
160
161 struct ds13rtc_softc {
162 device_t dev;
163 device_t busdev;
164 u_int chiptype; /* Type of DS13xx chip */
165 uint8_t secaddr; /* Address of seconds register */
166 uint8_t osfaddr; /* Address of register with OSF */
167 bool use_ampm; /* Use AM/PM mode. */
168 bool use_century; /* Use the Century bit. */
169 bool is_binary_counter; /* Chip has 32-bit binary counter. */
170 };
171
172 /*
173 * We use the compat_data table to look up hint strings in the non-FDT case, so
174 * define the struct locally when we don't get it from ofw_bus_subr.h.
175 */
176 #ifdef FDT
177 typedef struct ofw_compat_data ds13_compat_data;
178 #else
179 typedef struct {
180 const char *ocd_str;
181 uintptr_t ocd_data;
182 } ds13_compat_data;
183 #endif
184
185 static ds13_compat_data compat_data[] = {
186 {"dallas,ds1307", TYPE_DS1307},
187 {"dallas,ds1308", TYPE_DS1308},
188 {"dallas,ds1337", TYPE_DS1337},
189 {"dallas,ds1338", TYPE_DS1338},
190 {"dallas,ds1339", TYPE_DS1339},
191 {"dallas,ds1340", TYPE_DS1340},
192 {"dallas,ds1341", TYPE_DS1341},
193 {"dallas,ds1342", TYPE_DS1342},
194 {"dallas,ds1371", TYPE_DS1371},
195 {"dallas,ds1372", TYPE_DS1372},
196 {"dallas,ds1374", TYPE_DS1374},
197 {"dallas,ds1375", TYPE_DS1375},
198 {"dallas,ds1388", TYPE_DS1388},
199
200 {NULL, TYPE_NONE},
201 };
202
203 static int
read_reg(struct ds13rtc_softc * sc,uint8_t reg,uint8_t * val)204 read_reg(struct ds13rtc_softc *sc, uint8_t reg, uint8_t *val)
205 {
206
207 return (iicdev_readfrom(sc->dev, reg, val, sizeof(*val), IIC_WAIT));
208 }
209
210 static int
write_reg(struct ds13rtc_softc * sc,uint8_t reg,uint8_t val)211 write_reg(struct ds13rtc_softc *sc, uint8_t reg, uint8_t val)
212 {
213
214 return (iicdev_writeto(sc->dev, reg, &val, sizeof(val), IIC_WAIT));
215 }
216
217 static int
read_timeregs(struct ds13rtc_softc * sc,struct time_regs * tregs)218 read_timeregs(struct ds13rtc_softc *sc, struct time_regs *tregs)
219 {
220 int err;
221
222 if ((err = iicdev_readfrom(sc->dev, sc->secaddr, tregs,
223 sizeof(*tregs), IIC_WAIT)) != 0)
224 return (err);
225
226 return (err);
227 }
228
229 static int
write_timeregs(struct ds13rtc_softc * sc,struct time_regs * tregs)230 write_timeregs(struct ds13rtc_softc *sc, struct time_regs *tregs)
231 {
232
233 return (iicdev_writeto(sc->dev, sc->secaddr, tregs,
234 sizeof(*tregs), IIC_WAIT));
235 }
236
237 static int
read_timeword(struct ds13rtc_softc * sc,time_t * secs)238 read_timeword(struct ds13rtc_softc *sc, time_t *secs)
239 {
240 int err;
241 uint8_t buf[4];
242
243 if ((err = iicdev_readfrom(sc->dev, sc->secaddr, buf, sizeof(buf),
244 IIC_WAIT)) == 0)
245 *secs = le32dec(buf);
246
247 return (err);
248 }
249
250 static int
write_timeword(struct ds13rtc_softc * sc,time_t secs)251 write_timeword(struct ds13rtc_softc *sc, time_t secs)
252 {
253 uint8_t buf[4];
254
255 le32enc(buf, (uint32_t)secs);
256 return (iicdev_writeto(sc->dev, sc->secaddr, buf, sizeof(buf),
257 IIC_WAIT));
258 }
259
260 static void
ds13rtc_start(void * arg)261 ds13rtc_start(void *arg)
262 {
263 struct ds13rtc_softc *sc;
264 uint8_t ctlreg, statreg;
265
266 sc = arg;
267
268 /*
269 * Every chip in this family can be usefully initialized by writing 0 to
270 * the control register, except DS1375 which has an external oscillator
271 * controlled by values in the ctlreg that we know nothing about, so
272 * we'd best leave them alone. For all other chips, writing 0 enables
273 * the oscillator, disables signals/outputs in battery-backed mode
274 * (saves power) and disables features like watchdog timers and alarms.
275 */
276 switch (sc->chiptype) {
277 case TYPE_DS1307:
278 case TYPE_DS1308:
279 case TYPE_DS1338:
280 case TYPE_DS1340:
281 case TYPE_DS1371:
282 case TYPE_DS1372:
283 case TYPE_DS1374:
284 ctlreg = DS130x_R_CONTROL;
285 break;
286 case TYPE_DS1337:
287 case TYPE_DS1339:
288 ctlreg = DS133x_R_CONTROL;
289 break;
290 case TYPE_DS1341:
291 case TYPE_DS1342:
292 ctlreg = DS1341_R_CONTROL;
293 break;
294 case TYPE_DS1375:
295 ctlreg = DS13xx_R_NONE;
296 break;
297 case TYPE_DS1388:
298 ctlreg = DS1388_R_CONTROL;
299 break;
300 default:
301 device_printf(sc->dev, "missing init code for this chiptype\n");
302 return;
303 }
304 if (ctlreg != DS13xx_R_NONE)
305 write_reg(sc, ctlreg, 0);
306
307 /*
308 * Common init. Read the OSF/CH status bit and report stopped clocks to
309 * the user. The status bit will be cleared the first time we write
310 * valid time to the chip (and must not be cleared before that).
311 */
312 if (read_reg(sc, sc->osfaddr, &statreg) != 0) {
313 device_printf(sc->dev, "cannot read RTC clock status bit\n");
314 return;
315 }
316 if (statreg & DS13xx_B_STATUS_OSF) {
317 device_printf(sc->dev,
318 "WARNING: RTC battery failed; time is invalid\n");
319 }
320
321 /*
322 * Figure out whether the chip is configured for AM/PM mode. On all
323 * chips that do AM/PM mode, the flag bit is in the hours register,
324 * which is secaddr+2.
325 */
326 if ((sc->chiptype != TYPE_DS1340) && !sc->is_binary_counter) {
327 if (read_reg(sc, sc->secaddr + 2, &statreg) != 0) {
328 device_printf(sc->dev,
329 "cannot read RTC clock AM/PM bit\n");
330 return;
331 }
332 if (statreg & DS13xx_B_HOUR_AMPM)
333 sc->use_ampm = true;
334 }
335
336 /*
337 * Everything looks good if we make it to here; register as an RTC.
338 * Schedule RTC updates to happen just after top-of-second.
339 */
340 clock_register_flags(sc->dev, 1000000, CLOCKF_SETTIME_NO_ADJ);
341 clock_schedule(sc->dev, 1);
342 }
343
344 static int
ds13rtc_gettime(device_t dev,struct timespec * ts)345 ds13rtc_gettime(device_t dev, struct timespec *ts)
346 {
347 struct bcd_clocktime bct;
348 struct time_regs tregs;
349 struct ds13rtc_softc *sc;
350 int err;
351 uint8_t statreg, hourmask;
352
353 sc = device_get_softc(dev);
354
355 /* Read the OSF/CH bit; if the clock stopped we can't provide time. */
356 if ((err = read_reg(sc, sc->osfaddr, &statreg)) != 0) {
357 return (err);
358 }
359 if (statreg & DS13xx_B_STATUS_OSF)
360 return (EINVAL); /* hardware is good, time is not. */
361
362 /* If the chip counts time in binary, we just read and return it. */
363 if (sc->is_binary_counter) {
364 ts->tv_nsec = 0;
365 return (read_timeword(sc, &ts->tv_sec));
366 }
367
368 /*
369 * Chip counts in BCD, read and decode it...
370 */
371 if ((err = read_timeregs(sc, &tregs)) != 0) {
372 device_printf(dev, "cannot read RTC time\n");
373 return (err);
374 }
375
376 if (sc->use_ampm)
377 hourmask = DS13xx_M_12HOUR;
378 else
379 hourmask = DS13xx_M_24HOUR;
380
381 bct.nsec = 0;
382 bct.ispm = tregs.hour & DS13xx_B_HOUR_PM;
383 bct.sec = tregs.sec & DS13xx_M_SECOND;
384 bct.min = tregs.min & DS13xx_M_MINUTE;
385 bct.hour = tregs.hour & hourmask;
386 bct.day = tregs.day & DS13xx_M_DAY;
387 bct.mon = tregs.month & DS13xx_M_MONTH;
388 bct.year = tregs.year & DS13xx_M_YEAR;
389
390 /*
391 * If this chip has a century bit, honor it. Otherwise let
392 * clock_ct_to_ts() infer the century from the 2-digit year.
393 */
394 if (sc->use_century)
395 bct.year += (tregs.month & DS13xx_B_MONTH_CENTURY) ? 0x100 : 0;
396
397 clock_dbgprint_bcd(sc->dev, CLOCK_DBG_READ, &bct);
398 err = clock_bcd_to_ts(&bct, ts, sc->use_ampm);
399
400 return (err);
401 }
402
403 static int
ds13rtc_settime(device_t dev,struct timespec * ts)404 ds13rtc_settime(device_t dev, struct timespec *ts)
405 {
406 struct bcd_clocktime bct;
407 struct time_regs tregs;
408 struct ds13rtc_softc *sc;
409 int err;
410 uint8_t cflag, statreg, pmflags;
411
412 sc = device_get_softc(dev);
413
414 /*
415 * We request a timespec with no resolution-adjustment. That also
416 * disables utc adjustment, so apply that ourselves.
417 */
418 ts->tv_sec -= utc_offset();
419
420 /* If the chip counts time in binary, store tv_sec and we're done. */
421 if (sc->is_binary_counter)
422 return (write_timeword(sc, ts->tv_sec));
423
424 clock_ts_to_bcd(ts, &bct, sc->use_ampm);
425 clock_dbgprint_bcd(sc->dev, CLOCK_DBG_WRITE, &bct);
426
427 /* If the chip is in AMPM mode deal with the PM flag. */
428 pmflags = 0;
429 if (sc->use_ampm) {
430 pmflags = DS13xx_B_HOUR_AMPM;
431 if (bct.ispm)
432 pmflags |= DS13xx_B_HOUR_PM;
433 }
434
435 /* If the chip has a century bit, set it as needed. */
436 cflag = 0;
437 if (sc->use_century) {
438 if (bct.year >= 2000)
439 cflag |= DS13xx_B_MONTH_CENTURY;
440 }
441
442 tregs.sec = bct.sec;
443 tregs.min = bct.min;
444 tregs.hour = bct.hour | pmflags;
445 tregs.day = bct.day;
446 tregs.month = bct.mon | cflag;
447 tregs.year = bct.year & 0xff;
448 tregs.wday = bct.dow;
449
450 /*
451 * Set the time. Reset the OSF bit if it is on and it is not part of
452 * the time registers (in which case writing time resets it).
453 */
454 if ((err = write_timeregs(sc, &tregs)) != 0)
455 goto errout;
456 if (sc->osfaddr != sc->secaddr) {
457 if ((err = read_reg(sc, sc->osfaddr, &statreg)) != 0)
458 goto errout;
459 if (statreg & DS13xx_B_STATUS_OSF) {
460 statreg &= ~DS13xx_B_STATUS_OSF;
461 err = write_reg(sc, sc->osfaddr, statreg);
462 }
463 }
464
465 errout:
466
467 if (err != 0)
468 device_printf(dev, "cannot update RTC time\n");
469
470 return (err);
471 }
472
473 static int
ds13rtc_get_chiptype(device_t dev)474 ds13rtc_get_chiptype(device_t dev)
475 {
476 #ifdef FDT
477
478 return (ofw_bus_search_compatible(dev, compat_data)->ocd_data);
479 #else
480 ds13_compat_data *cdata;
481 const char *htype;
482
483 /*
484 * We can only attach if provided a chiptype hint string.
485 */
486 if (resource_string_value(device_get_name(dev),
487 device_get_unit(dev), "compatible", &htype) != 0)
488 return (TYPE_NONE);
489
490 /*
491 * Loop through the ofw compat data comparing the hinted chip type to
492 * the compat strings.
493 */
494 for (cdata = compat_data; cdata->ocd_str != NULL; ++cdata) {
495 if (strcmp(htype, cdata->ocd_str) == 0)
496 break;
497 }
498 return (cdata->ocd_data);
499 #endif
500 }
501
502 static int
ds13rtc_probe(device_t dev)503 ds13rtc_probe(device_t dev)
504 {
505 int chiptype, goodrv;
506
507 #ifdef FDT
508 if (!ofw_bus_status_okay(dev))
509 return (ENXIO);
510 goodrv = BUS_PROBE_GENERIC;
511 #else
512 goodrv = BUS_PROBE_NOWILDCARD;
513 #endif
514
515 chiptype = ds13rtc_get_chiptype(dev);
516 if (chiptype == TYPE_NONE)
517 return (ENXIO);
518
519 device_set_desc(dev, desc_strings[chiptype]);
520 return (goodrv);
521 }
522
523 static int
ds13rtc_attach(device_t dev)524 ds13rtc_attach(device_t dev)
525 {
526 struct ds13rtc_softc *sc;
527
528 sc = device_get_softc(dev);
529 sc->dev = dev;
530 sc->busdev = device_get_parent(dev);
531
532 /*
533 * We need to know what kind of chip we're driving.
534 */
535 if ((sc->chiptype = ds13rtc_get_chiptype(dev)) == TYPE_NONE) {
536 device_printf(dev, "impossible: cannot determine chip type\n");
537 return (ENXIO);
538 }
539
540 /* The seconds register is in the same place on all except DS1388. */
541 if (sc->chiptype == TYPE_DS1388)
542 sc->secaddr = DS1388_R_SECOND;
543 else
544 sc->secaddr = DS13xx_R_SECOND;
545
546 /*
547 * The OSF/CH (osc failed/clock-halted) bit appears in different
548 * registers for different chip types. The DS1375 has no OSF indicator
549 * because it has no internal oscillator; we just point to an always-
550 * zero bit in the status register for that chip.
551 */
552 switch (sc->chiptype) {
553 case TYPE_DS1307:
554 case TYPE_DS1308:
555 case TYPE_DS1338:
556 sc->osfaddr = DS13xx_R_SECOND;
557 break;
558 case TYPE_DS1337:
559 case TYPE_DS1339:
560 case TYPE_DS1341:
561 case TYPE_DS1342:
562 case TYPE_DS1375:
563 sc->osfaddr = DS133x_R_STATUS;
564 sc->use_century = true;
565 break;
566 case TYPE_DS1340:
567 sc->osfaddr = DS1340_R_STATUS;
568 break;
569 case TYPE_DS1371:
570 case TYPE_DS1372:
571 case TYPE_DS1374:
572 sc->osfaddr = DS137x_R_STATUS;
573 sc->is_binary_counter = true;
574 break;
575 case TYPE_DS1388:
576 sc->osfaddr = DS1388_R_STATUS;
577 break;
578 }
579
580 /*
581 * We have to wait until interrupts are enabled. Sometimes I2C read
582 * and write only works when the interrupts are available.
583 */
584 config_intrhook_oneshot(ds13rtc_start, sc);
585
586 return (0);
587 }
588
589 static int
ds13rtc_detach(device_t dev)590 ds13rtc_detach(device_t dev)
591 {
592
593 clock_unregister(dev);
594 return (0);
595 }
596
597 static device_method_t ds13rtc_methods[] = {
598 DEVMETHOD(device_probe, ds13rtc_probe),
599 DEVMETHOD(device_attach, ds13rtc_attach),
600 DEVMETHOD(device_detach, ds13rtc_detach),
601
602 DEVMETHOD(clock_gettime, ds13rtc_gettime),
603 DEVMETHOD(clock_settime, ds13rtc_settime),
604
605 DEVMETHOD_END
606 };
607
608 static driver_t ds13rtc_driver = {
609 "ds13rtc",
610 ds13rtc_methods,
611 sizeof(struct ds13rtc_softc),
612 };
613
614 DRIVER_MODULE(ds13rtc, iicbus, ds13rtc_driver, NULL, NULL);
615 MODULE_VERSION(ds13rtc, 1);
616 MODULE_DEPEND(ds13rtc, iicbus, IICBB_MINVER, IICBB_PREFVER, IICBB_MAXVER);
617 IICBUS_FDT_PNP_INFO(compat_data);
618