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