ds13rtc.c revision 322473 
1/*-
2 * Copyright (c) 2017 Ian Lepore <ian@freebsd.org>
3 * All rights reserved.
4 *
5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted provided that the following conditions
7 * are met:
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.
13 *
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
24 * SUCH DAMAGE.
25 */
26
27#include <sys/cdefs.h>
28__FBSDID("$FreeBSD: head/sys/dev/iicbus/ds13rtc.c 322473 2017-08-13 21:02:40Z ian $");
29
30/*
31 * Driver for Dallas/Maxim DS13xx real-time clock/calendar chips:
32 *
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).
46 *
47 * This driver supports only basic timekeeping functions.  It provides no access
48 * to or control over any other functionality provided by the chips.
49 */
50
51#include "opt_platform.h"
52
53#include <sys/param.h>
54#include <sys/systm.h>
55#include <sys/bus.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>
61
62#include <dev/iicbus/iicbus.h>
63#include <dev/iicbus/iiconf.h>
64#ifdef FDT
65#include <dev/ofw/openfirm.h>
66#include <dev/ofw/ofw_bus.h>
67#include <dev/ofw/ofw_bus_subr.h>
68#endif
69
70#include "clock_if.h"
71#include "iicbus_if.h"
72
73/*
74 * I2C address 1101 000x
75 */
76#define	DS13xx_ADDR		0xd0
77
78/*
79 * Registers, bits within them, and masks for the various chip types.
80 */
81
82#define	DS13xx_R_NONE		0xff	/* Placeholder */
83
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
93
94#define	DS13xx_R_SECOND		0x00
95#define	DS1388_R_SECOND		0x01
96
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
102
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 */
107
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
115
116/*
117 * The chip types we support.
118 */
119enum {
120	TYPE_NONE,
121	TYPE_DS1307,
122	TYPE_DS1308,
123	TYPE_DS1337,
124	TYPE_DS1338,
125	TYPE_DS1339,
126	TYPE_DS1340,
127	TYPE_DS1341,
128	TYPE_DS1342,
129	TYPE_DS1371,
130	TYPE_DS1372,
131	TYPE_DS1374,
132	TYPE_DS1375,
133	TYPE_DS1388,
134
135	TYPE_COUNT
136};
137static const char *desc_strings[] = {
138	"",
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",
152};
153CTASSERT(nitems(desc_strings) == TYPE_COUNT);
154
155/*
156 * The time registers in the order they are laid out in hardware.
157 */
158struct time_regs {
159	uint8_t sec, min, hour, wday, day, month, year;
160};
161
162struct ds13rtc_softc {
163	device_t	dev;
164	device_t	busdev;
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 */
169};
170
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 */
174
175/*
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.
178 */
179#ifdef FDT
180typedef struct ofw_compat_data ds13_compat_data;
181#else
182typedef struct {
183	const char *ocd_str;
184	uintptr_t  ocd_data;
185} ds13_compat_data;
186#endif
187
188static 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},
202
203	{NULL,              TYPE_NONE},
204};
205
206static int
207read_reg(struct ds13rtc_softc *sc, uint8_t reg, uint8_t *val)
208{
209
210	return (iicdev_readfrom(sc->dev, reg, val, sizeof(*val), IIC_WAIT));
211}
212
213static int
214write_reg(struct ds13rtc_softc *sc, uint8_t reg, uint8_t val)
215{
216
217	return (iicdev_writeto(sc->dev, reg, &val, sizeof(val), IIC_WAIT));
218}
219
220static int
221read_timeregs(struct ds13rtc_softc *sc, struct time_regs *tregs)
222{
223	int err;
224
225	if ((err = iicdev_readfrom(sc->dev, sc->secaddr, tregs,
226	    sizeof(*tregs), IIC_WAIT)) != 0)
227		return (err);
228
229	return (err);
230}
231
232static int
233write_timeregs(struct ds13rtc_softc *sc, struct time_regs *tregs)
234{
235
236	return (iicdev_writeto(sc->dev, sc->secaddr, tregs,
237	    sizeof(*tregs), IIC_WAIT));
238}
239
240static int
241read_timeword(struct ds13rtc_softc *sc, time_t *secs)
242{
243	int err;
244	uint8_t buf[4];
245
246	if ((err = iicdev_readfrom(sc->dev, sc->secaddr, buf, sizeof(buf),
247	    IIC_WAIT)) == 0)
248		*secs = le32dec(buf);
249
250	return (err);
251}
252
253static int
254write_timeword(struct ds13rtc_softc *sc, time_t secs)
255{
256	uint8_t buf[4];
257
258	le32enc(buf, (uint32_t)secs);
259	return (iicdev_writeto(sc->dev, sc->secaddr, buf, sizeof(buf),
260	    IIC_WAIT));
261}
262
263static void
264ds13rtc_start(void *arg)
265{
266	struct ds13rtc_softc *sc;
267	uint8_t ctlreg, statreg;
268
269	sc = arg;
270
271	/*
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.
278	 */
279	switch (sc->chiptype) {
280	case TYPE_DS1307:
281	case TYPE_DS1308:
282	case TYPE_DS1338:
283	case TYPE_DS1340:
284	case TYPE_DS1371:
285	case TYPE_DS1372:
286	case TYPE_DS1374:
287		ctlreg = DS130x_R_CONTROL;
288		break;
289	case TYPE_DS1337:
290	case TYPE_DS1339:
291		ctlreg = DS133x_R_CONTROL;
292		break;
293	case TYPE_DS1341:
294	case TYPE_DS1342:
295		ctlreg = DS1341_R_CONTROL;
296		break;
297	case TYPE_DS1375:
298		ctlreg = DS13xx_R_NONE;
299		break;
300	case TYPE_DS1388:
301		ctlreg = DS1388_R_CONTROL;
302		break;
303	default:
304		device_printf(sc->dev, "missing init code for this chiptype\n");
305		return;
306	}
307	if (ctlreg != DS13xx_R_NONE)
308		write_reg(sc, ctlreg, 0);
309
310	/*
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).
314	 */
315	if (read_reg(sc, sc->osfaddr, &statreg) != 0) {
316		device_printf(sc->dev, "cannot read RTC clock status bit\n");
317		return;
318	}
319	if (statreg & DS13xx_B_STATUS_OSF) {
320		device_printf(sc->dev,
321		    "WARNING: RTC battery failed; time is invalid\n");
322	}
323
324	/*
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.
328	 */
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");
333			return;
334		}
335		if (statreg & DS13xx_B_HOUR_AMPM)
336			sc->flags |= SC_F_AMPM;
337	}
338
339	/*
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.
342	 */
343	clock_register_flags(sc->dev, 1000000, CLOCKF_SETTIME_NO_ADJ);
344	clock_schedule(sc->dev, 1);
345}
346
347static int
348ds13rtc_gettime(device_t dev, struct timespec *ts)
349{
350	struct clocktime ct;
351	struct time_regs tregs;
352	struct ds13rtc_softc *sc;
353	int err;
354	uint8_t statreg, hourmask;
355
356	sc = device_get_softc(dev);
357
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) {
360		return (err);
361	}
362	if (statreg & DS13xx_B_STATUS_OSF)
363		return (EINVAL); /* hardware is good, time is not. */
364
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)
368			return (err);
369		ts->tv_nsec = 0;
370	}
371
372	/*
373	 * Chip counts in BCD, read and decode it...
374	 */
375	if ((err = read_timeregs(sc, &tregs)) != 0) {
376		device_printf(dev, "cannot read RTC time\n");
377		return (err);
378	}
379
380	if (sc->flags & SC_F_AMPM)
381		hourmask = DS13xx_M_12HOUR;
382	else
383		hourmask = DS13xx_M_24HOUR;
384
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);
391	ct.nsec = 0;
392
393	if (sc->flags & SC_F_AMPM) {
394		if (ct.hour == 12)
395			ct.hour = 0;
396		if (tregs.hour & DS13xx_B_HOUR_PM)
397			ct.hour += 12;
398	}
399
400	/*
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.
403	 */
404	if (sc->flags & SC_F_CENTURY)
405		ct.year += (tregs.month & DS13xx_B_MONTH_CENTURY) ? 2000 : 1900;
406
407	err = clock_ct_to_ts(&ct, ts);
408
409	return (err);
410}
411
412static int
413ds13rtc_settime(device_t dev, struct timespec *ts)
414{
415	struct clocktime ct;
416	struct time_regs tregs;
417	struct ds13rtc_softc *sc;
418	int err;
419	uint8_t cflag, statreg, pmflag;
420
421	sc = device_get_softc(dev);
422
423	/*
424	 * We request a timespec with no resolution-adjustment.  That also
425	 * disables utc adjustment, so apply that ourselves.
426	 */
427	ts->tv_sec -= utc_offset();
428
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));
432
433	clock_ts_to_ct(ts, &ct);
434
435	/* If the chip is in AMPM mode deal with the PM flag. */
436	pmflag = 0;
437	if (sc->flags & SC_F_AMPM) {
438		if (ct.hour >= 12) {
439			ct.hour -= 12;
440			pmflag = DS13xx_B_HOUR_PM;
441		}
442		if (ct.hour == 0)
443			ct.hour = 12;
444	}
445
446	/* If the chip has a century bit, set it as needed. */
447	cflag = 0;
448	if (sc->flags & SC_F_CENTURY) {
449		if (ct.year >= 2000)
450			cflag |= DS13xx_B_MONTH_CENTURY;
451	}
452
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);
459	tregs.wday  = ct.dow;
460
461	/*
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).
464	 */
465	if ((err = write_timeregs(sc, &tregs)) != 0)
466		goto errout;
467	if (sc->osfaddr != sc->secaddr) {
468		if ((err = read_reg(sc, sc->osfaddr, &statreg)) != 0)
469			goto errout;
470		if (statreg & DS13xx_B_STATUS_OSF) {
471			statreg &= ~DS13xx_B_STATUS_OSF;
472			err = write_reg(sc, sc->osfaddr, statreg);
473		}
474	}
475
476errout:
477
478	if (err != 0)
479		device_printf(dev, "cannot update RTC time\n");
480
481	return (err);
482}
483
484static int
485ds13rtc_get_chiptype(device_t dev)
486{
487#ifdef FDT
488
489	return (ofw_bus_search_compatible(dev, compat_data)->ocd_data);
490#else
491	ds13_compat_data *cdata;
492	const char *htype;
493
494	/*
495	 * We can only attach if provided a chiptype hint string.
496	 */
497	if (resource_string_value(device_get_name(dev),
498	    device_get_unit(dev), "chiptype", &htype) != 0)
499		return (TYPE_NONE);
500
501	/*
502	 * Loop through the ofw compat data comparing the hinted chip type to
503	 * the compat strings.
504	 */
505	for (cdata = compat_data; cdata->ocd_str != NULL; ++cdata) {
506		if (strcmp(htype, cdata->ocd_str) == 0)
507			break;
508	}
509	return (cdata->ocd_data);
510#endif
511}
512
513static int
514ds13rtc_probe(device_t dev)
515{
516	int chiptype, goodrv;
517
518#ifdef FDT
519	if (!ofw_bus_status_okay(dev))
520		return (ENXIO);
521	goodrv = BUS_PROBE_GENERIC;
522#else
523	goodrv = BUS_PROBE_NOWILDCARD;
524#endif
525
526	chiptype = ds13rtc_get_chiptype(dev);
527	if (chiptype == TYPE_NONE)
528		return (ENXIO);
529
530	device_set_desc(dev, desc_strings[chiptype]);
531	return (goodrv);
532}
533
534static int
535ds13rtc_attach(device_t dev)
536{
537	struct ds13rtc_softc *sc;
538
539	sc = device_get_softc(dev);
540	sc->dev = dev;
541	sc->busdev = device_get_parent(dev);
542
543	/*
544	 * We need to know what kind of chip we're driving.
545	 */
546	if ((sc->chiptype = ds13rtc_get_chiptype(dev)) == TYPE_NONE) {
547		device_printf(dev, "impossible: cannot determine chip type\n");
548		return (ENXIO);
549	}
550
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;
554	else
555		sc->secaddr = DS13xx_R_SECOND;
556
557	/*
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.
562	 */
563	switch (sc->chiptype) {
564	case TYPE_DS1307:
565	case TYPE_DS1308:
566	case TYPE_DS1338:
567		sc->osfaddr = DS13xx_R_SECOND;
568		break;
569	case TYPE_DS1337:
570	case TYPE_DS1339:
571	case TYPE_DS1341:
572	case TYPE_DS1342:
573	case TYPE_DS1375:
574		sc->osfaddr = DS133x_R_STATUS;
575		sc->flags  |= SC_F_CENTURY;
576		break;
577	case TYPE_DS1340:
578		sc->osfaddr = DS1340_R_STATUS;
579		break;
580	case TYPE_DS1371:
581	case TYPE_DS1372:
582	case TYPE_DS1374:
583		sc->osfaddr = DS137x_R_STATUS;
584		sc->flags  |= SC_F_BINARY;
585		break;
586	case TYPE_DS1388:
587		sc->osfaddr = DS1388_R_STATUS;
588		break;
589	}
590
591	/*
592	 * We have to wait until interrupts are enabled.  Sometimes I2C read
593	 * and write only works when the interrupts are available.
594	 */
595	config_intrhook_oneshot(ds13rtc_start, sc);
596
597	return (0);
598}
599
600static int
601ds13rtc_detach(device_t dev)
602{
603
604	clock_unregister(dev);
605	return (0);
606}
607
608static device_method_t ds13rtc_methods[] = {
609	DEVMETHOD(device_probe,		ds13rtc_probe),
610	DEVMETHOD(device_attach,	ds13rtc_attach),
611	DEVMETHOD(device_detach,	ds13rtc_detach),
612
613	DEVMETHOD(clock_gettime,	ds13rtc_gettime),
614	DEVMETHOD(clock_settime,	ds13rtc_settime),
615
616	DEVMETHOD_END
617};
618
619static driver_t ds13rtc_driver = {
620	"ds13rtc",
621	ds13rtc_methods,
622	sizeof(struct ds13rtc_softc),
623};
624
625static devclass_t ds13rtc_devclass;
626
627DRIVER_MODULE(ds13rtc, iicbus, ds13rtc_driver, ds13rtc_devclass, NULL, NULL);
628MODULE_VERSION(ds13rtc, 1);
629MODULE_DEPEND(ds13rtc, iicbus, IICBB_MINVER, IICBB_PREFVER, IICBB_MAXVER);
630