2 * rtc-ds1305.c -- driver for DS1305 and DS1306 SPI RTC chips
4 * Copyright (C) 2008 David Brownell
6 * This program is free software; you can redistribute it and/or modify
7 * it under the terms of the GNU General Public License version 2 as
8 * published by the Free Software Foundation.
11 #include <linux/kernel.h>
12 #include <linux/init.h>
13 #include <linux/bcd.h>
14 #include <linux/slab.h>
15 #include <linux/rtc.h>
16 #include <linux/workqueue.h>
18 #include <linux/spi/spi.h>
19 #include <linux/spi/ds1305.h>
20 #include <linux/module.h>
24 * Registers ... mask DS1305_WRITE into register address to write,
25 * otherwise you're reading it. All non-bitmask values are BCD.
27 #define DS1305_WRITE 0x80
30 /* RTC date/time ... the main special cases are that we:
31 * - Need fancy "hours" encoding in 12hour mode
32 * - Don't rely on the "day-of-week" field (or tm_wday)
33 * - Are a 21st-century clock (2000 <= year < 2100)
35 #define DS1305_RTC_LEN 7 /* bytes for RTC regs */
37 #define DS1305_SEC 0x00 /* register addresses */
38 #define DS1305_MIN 0x01
39 #define DS1305_HOUR 0x02
40 # define DS1305_HR_12 0x40 /* set == 12 hr mode */
41 # define DS1305_HR_PM 0x20 /* set == PM (12hr mode) */
42 #define DS1305_WDAY 0x03
43 #define DS1305_MDAY 0x04
44 #define DS1305_MON 0x05
45 #define DS1305_YEAR 0x06
48 /* The two alarms have only sec/min/hour/wday fields (ALM_LEN).
49 * DS1305_ALM_DISABLE disables a match field (some combos are bad).
51 * NOTE that since we don't use WDAY, we limit ourselves to alarms
52 * only one day into the future (vs potentially up to a week).
54 * NOTE ALSO that while we could generate once-a-second IRQs (UIE), we
55 * don't currently support them. We'd either need to do it only when
56 * no alarm is pending (not the standard model), or to use the second
57 * alarm (implying that this is a DS1305 not DS1306, *and* that either
58 * it's wired up a second IRQ we know, or that INTCN is set)
60 #define DS1305_ALM_LEN 4 /* bytes for ALM regs */
61 #define DS1305_ALM_DISABLE 0x80
63 #define DS1305_ALM0(r) (0x07 + (r)) /* register addresses */
64 #define DS1305_ALM1(r) (0x0b + (r))
67 /* three control registers */
68 #define DS1305_CONTROL_LEN 3 /* bytes of control regs */
70 #define DS1305_CONTROL 0x0f /* register addresses */
71 # define DS1305_nEOSC 0x80 /* low enables oscillator */
72 # define DS1305_WP 0x40 /* write protect */
73 # define DS1305_INTCN 0x04 /* clear == only int0 used */
74 # define DS1306_1HZ 0x04 /* enable 1Hz output */
75 # define DS1305_AEI1 0x02 /* enable ALM1 IRQ */
76 # define DS1305_AEI0 0x01 /* enable ALM0 IRQ */
77 #define DS1305_STATUS 0x10
78 /* status has just AEIx bits, mirrored as IRQFx */
79 #define DS1305_TRICKLE 0x11
80 /* trickle bits are defined in <linux/spi/ds1305.h> */
82 /* a bunch of NVRAM */
83 #define DS1305_NVRAM_LEN 96 /* bytes of NVRAM */
85 #define DS1305_NVRAM 0x20 /* register addresses */
89 struct spi_device *spi;
90 struct rtc_device *rtc;
92 struct work_struct work;
95 #define FLAG_EXITING 0
98 u8 ctrl[DS1305_CONTROL_LEN];
102 /*----------------------------------------------------------------------*/
105 * Utilities ... tolerate 12-hour AM/PM notation in case of non-Linux
106 * software (like a bootloader) which may require it.
109 static unsigned bcd2hour(u8 bcd)
111 if (bcd & DS1305_HR_12) {
114 bcd &= ~DS1305_HR_12;
115 if (bcd & DS1305_HR_PM) {
117 bcd &= ~DS1305_HR_PM;
119 hour += bcd2bin(bcd);
125 static u8 hour2bcd(bool hr12, int hour)
130 return DS1305_HR_12 | bin2bcd(hour);
132 return DS1305_HR_12 | DS1305_HR_PM | bin2bcd(hour);
134 return bin2bcd(hour);
137 /*----------------------------------------------------------------------*/
140 * Interface to RTC framework
143 static int ds1305_alarm_irq_enable(struct device *dev, unsigned int enabled)
145 struct ds1305 *ds1305 = dev_get_drvdata(dev);
149 buf[0] = DS1305_WRITE | DS1305_CONTROL;
150 buf[1] = ds1305->ctrl[0];
153 if (ds1305->ctrl[0] & DS1305_AEI0)
155 buf[1] |= DS1305_AEI0;
157 if (!(buf[1] & DS1305_AEI0))
159 buf[1] &= ~DS1305_AEI0;
161 err = spi_write_then_read(ds1305->spi, buf, sizeof(buf), NULL, 0);
163 ds1305->ctrl[0] = buf[1];
171 * Get/set of date and time is pretty normal.
174 static int ds1305_get_time(struct device *dev, struct rtc_time *time)
176 struct ds1305 *ds1305 = dev_get_drvdata(dev);
177 u8 addr = DS1305_SEC;
178 u8 buf[DS1305_RTC_LEN];
181 /* Use write-then-read to get all the date/time registers
182 * since dma from stack is nonportable
184 status = spi_write_then_read(ds1305->spi, &addr, sizeof(addr),
189 dev_vdbg(dev, "%s: %3ph, %4ph\n", "read", &buf[0], &buf[3]);
191 /* Decode the registers */
192 time->tm_sec = bcd2bin(buf[DS1305_SEC]);
193 time->tm_min = bcd2bin(buf[DS1305_MIN]);
194 time->tm_hour = bcd2hour(buf[DS1305_HOUR]);
195 time->tm_wday = buf[DS1305_WDAY] - 1;
196 time->tm_mday = bcd2bin(buf[DS1305_MDAY]);
197 time->tm_mon = bcd2bin(buf[DS1305_MON]) - 1;
198 time->tm_year = bcd2bin(buf[DS1305_YEAR]) + 100;
200 dev_vdbg(dev, "%s secs=%d, mins=%d, "
201 "hours=%d, mday=%d, mon=%d, year=%d, wday=%d\n",
202 "read", time->tm_sec, time->tm_min,
203 time->tm_hour, time->tm_mday,
204 time->tm_mon, time->tm_year, time->tm_wday);
206 /* Time may not be set */
207 return rtc_valid_tm(time);
210 static int ds1305_set_time(struct device *dev, struct rtc_time *time)
212 struct ds1305 *ds1305 = dev_get_drvdata(dev);
213 u8 buf[1 + DS1305_RTC_LEN];
216 dev_vdbg(dev, "%s secs=%d, mins=%d, "
217 "hours=%d, mday=%d, mon=%d, year=%d, wday=%d\n",
218 "write", time->tm_sec, time->tm_min,
219 time->tm_hour, time->tm_mday,
220 time->tm_mon, time->tm_year, time->tm_wday);
222 /* Write registers starting at the first time/date address. */
223 *bp++ = DS1305_WRITE | DS1305_SEC;
225 *bp++ = bin2bcd(time->tm_sec);
226 *bp++ = bin2bcd(time->tm_min);
227 *bp++ = hour2bcd(ds1305->hr12, time->tm_hour);
228 *bp++ = (time->tm_wday < 7) ? (time->tm_wday + 1) : 1;
229 *bp++ = bin2bcd(time->tm_mday);
230 *bp++ = bin2bcd(time->tm_mon + 1);
231 *bp++ = bin2bcd(time->tm_year - 100);
233 dev_dbg(dev, "%s: %3ph, %4ph\n", "write", &buf[1], &buf[4]);
235 /* use write-then-read since dma from stack is nonportable */
236 return spi_write_then_read(ds1305->spi, buf, sizeof(buf),
241 * Get/set of alarm is a bit funky:
243 * - First there's the inherent raciness of getting the (partitioned)
244 * status of an alarm that could trigger while we're reading parts
247 * - Second there's its limited range (we could increase it a bit by
248 * relying on WDAY), which means it will easily roll over.
250 * - Third there's the choice of two alarms and alarm signals.
251 * Here we use ALM0 and expect that nINT0 (open drain) is used;
252 * that's the only real option for DS1306 runtime alarms, and is
255 * - Fourth, there's also ALM1, and a second interrupt signal:
256 * + On DS1305 ALM1 uses nINT1 (when INTCN=1) else nINT0;
257 * + On DS1306 ALM1 only uses INT1 (an active high pulse)
258 * and it won't work when VCC1 is active.
260 * So to be most general, we should probably set both alarms to the
261 * same value, letting ALM1 be the wakeup event source on DS1306
262 * and handling several wiring options on DS1305.
264 * - Fifth, we support the polled mode (as well as possible; why not?)
265 * even when no interrupt line is wired to an IRQ.
269 * Context: caller holds rtc->ops_lock (to protect ds1305->ctrl)
271 static int ds1305_get_alarm(struct device *dev, struct rtc_wkalrm *alm)
273 struct ds1305 *ds1305 = dev_get_drvdata(dev);
274 struct spi_device *spi = ds1305->spi;
277 u8 buf[DS1305_ALM_LEN];
279 /* Refresh control register cache BEFORE reading ALM0 registers,
280 * since reading alarm registers acks any pending IRQ. That
281 * makes returning "pending" status a bit of a lie, but that bit
282 * of EFI status is at best fragile anyway (given IRQ handlers).
284 addr = DS1305_CONTROL;
285 status = spi_write_then_read(spi, &addr, sizeof(addr),
286 ds1305->ctrl, sizeof(ds1305->ctrl));
290 alm->enabled = !!(ds1305->ctrl[0] & DS1305_AEI0);
291 alm->pending = !!(ds1305->ctrl[1] & DS1305_AEI0);
293 /* get and check ALM0 registers */
294 addr = DS1305_ALM0(DS1305_SEC);
295 status = spi_write_then_read(spi, &addr, sizeof(addr),
300 dev_vdbg(dev, "%s: %02x %02x %02x %02x\n",
301 "alm0 read", buf[DS1305_SEC], buf[DS1305_MIN],
302 buf[DS1305_HOUR], buf[DS1305_WDAY]);
304 if ((DS1305_ALM_DISABLE & buf[DS1305_SEC])
305 || (DS1305_ALM_DISABLE & buf[DS1305_MIN])
306 || (DS1305_ALM_DISABLE & buf[DS1305_HOUR]))
309 /* Stuff these values into alm->time and let RTC framework code
310 * fill in the rest ... and also handle rollover to tomorrow when
313 alm->time.tm_sec = bcd2bin(buf[DS1305_SEC]);
314 alm->time.tm_min = bcd2bin(buf[DS1305_MIN]);
315 alm->time.tm_hour = bcd2hour(buf[DS1305_HOUR]);
321 * Context: caller holds rtc->ops_lock (to protect ds1305->ctrl)
323 static int ds1305_set_alarm(struct device *dev, struct rtc_wkalrm *alm)
325 struct ds1305 *ds1305 = dev_get_drvdata(dev);
326 struct spi_device *spi = ds1305->spi;
327 unsigned long now, later;
330 u8 buf[1 + DS1305_ALM_LEN];
332 /* convert desired alarm to time_t */
333 status = rtc_tm_to_time(&alm->time, &later);
337 /* Read current time as time_t */
338 status = ds1305_get_time(dev, &tm);
341 status = rtc_tm_to_time(&tm, &now);
345 /* make sure alarm fires within the next 24 hours */
348 if ((later - now) > 24 * 60 * 60)
351 /* disable alarm if needed */
352 if (ds1305->ctrl[0] & DS1305_AEI0) {
353 ds1305->ctrl[0] &= ~DS1305_AEI0;
355 buf[0] = DS1305_WRITE | DS1305_CONTROL;
356 buf[1] = ds1305->ctrl[0];
357 status = spi_write_then_read(ds1305->spi, buf, 2, NULL, 0);
363 buf[0] = DS1305_WRITE | DS1305_ALM0(DS1305_SEC);
364 buf[1 + DS1305_SEC] = bin2bcd(alm->time.tm_sec);
365 buf[1 + DS1305_MIN] = bin2bcd(alm->time.tm_min);
366 buf[1 + DS1305_HOUR] = hour2bcd(ds1305->hr12, alm->time.tm_hour);
367 buf[1 + DS1305_WDAY] = DS1305_ALM_DISABLE;
369 dev_dbg(dev, "%s: %02x %02x %02x %02x\n",
370 "alm0 write", buf[1 + DS1305_SEC], buf[1 + DS1305_MIN],
371 buf[1 + DS1305_HOUR], buf[1 + DS1305_WDAY]);
373 status = spi_write_then_read(spi, buf, sizeof(buf), NULL, 0);
377 /* enable alarm if requested */
379 ds1305->ctrl[0] |= DS1305_AEI0;
381 buf[0] = DS1305_WRITE | DS1305_CONTROL;
382 buf[1] = ds1305->ctrl[0];
383 status = spi_write_then_read(ds1305->spi, buf, 2, NULL, 0);
389 #ifdef CONFIG_PROC_FS
391 static int ds1305_proc(struct device *dev, struct seq_file *seq)
393 struct ds1305 *ds1305 = dev_get_drvdata(dev);
395 char *resistors = "";
397 /* ctrl[2] is treated as read-only; no locking needed */
398 if ((ds1305->ctrl[2] & 0xf0) == DS1305_TRICKLE_MAGIC) {
399 switch (ds1305->ctrl[2] & 0x0c) {
400 case DS1305_TRICKLE_DS2:
401 diodes = "2 diodes, ";
403 case DS1305_TRICKLE_DS1:
404 diodes = "1 diode, ";
409 switch (ds1305->ctrl[2] & 0x03) {
410 case DS1305_TRICKLE_2K:
411 resistors = "2k Ohm";
413 case DS1305_TRICKLE_4K:
414 resistors = "4k Ohm";
416 case DS1305_TRICKLE_8K:
417 resistors = "8k Ohm";
426 seq_printf(seq, "trickle_charge\t: %s%s\n", diodes, resistors);
432 #define ds1305_proc NULL
435 static const struct rtc_class_ops ds1305_ops = {
436 .read_time = ds1305_get_time,
437 .set_time = ds1305_set_time,
438 .read_alarm = ds1305_get_alarm,
439 .set_alarm = ds1305_set_alarm,
441 .alarm_irq_enable = ds1305_alarm_irq_enable,
444 static void ds1305_work(struct work_struct *work)
446 struct ds1305 *ds1305 = container_of(work, struct ds1305, work);
447 struct mutex *lock = &ds1305->rtc->ops_lock;
448 struct spi_device *spi = ds1305->spi;
452 /* lock to protect ds1305->ctrl */
455 /* Disable the IRQ, and clear its status ... for now, we "know"
456 * that if more than one alarm is active, they're in sync.
457 * Note that reading ALM data registers also clears IRQ status.
459 ds1305->ctrl[0] &= ~(DS1305_AEI1 | DS1305_AEI0);
462 buf[0] = DS1305_WRITE | DS1305_CONTROL;
463 buf[1] = ds1305->ctrl[0];
466 status = spi_write_then_read(spi, buf, sizeof(buf),
469 dev_dbg(&spi->dev, "clear irq --> %d\n", status);
473 if (!test_bit(FLAG_EXITING, &ds1305->flags))
474 enable_irq(spi->irq);
476 rtc_update_irq(ds1305->rtc, 1, RTC_AF | RTC_IRQF);
480 * This "real" IRQ handler hands off to a workqueue mostly to allow
481 * mutex locking for ds1305->ctrl ... unlike I2C, we could issue async
482 * I/O requests in IRQ context (to clear the IRQ status).
484 static irqreturn_t ds1305_irq(int irq, void *p)
486 struct ds1305 *ds1305 = p;
489 schedule_work(&ds1305->work);
493 /*----------------------------------------------------------------------*/
496 * Interface for NVRAM
499 static void msg_init(struct spi_message *m, struct spi_transfer *x,
500 u8 *addr, size_t count, char *tx, char *rx)
503 memset(x, 0, 2 * sizeof(*x));
507 spi_message_add_tail(x, m);
514 spi_message_add_tail(x, m);
517 static int ds1305_nvram_read(void *priv, unsigned int off, void *buf,
520 struct ds1305 *ds1305 = priv;
521 struct spi_device *spi = ds1305->spi;
523 struct spi_message m;
524 struct spi_transfer x[2];
526 addr = DS1305_NVRAM + off;
527 msg_init(&m, x, &addr, count, NULL, buf);
529 return spi_sync(spi, &m);
532 static int ds1305_nvram_write(void *priv, unsigned int off, void *buf,
535 struct ds1305 *ds1305 = priv;
536 struct spi_device *spi = ds1305->spi;
538 struct spi_message m;
539 struct spi_transfer x[2];
541 addr = (DS1305_WRITE | DS1305_NVRAM) + off;
542 msg_init(&m, x, &addr, count, buf, NULL);
544 return spi_sync(spi, &m);
547 static struct nvmem_config ds1305_nvmem_cfg = {
548 .name = "ds1305_nvram",
551 .size = DS1305_NVRAM_LEN,
552 .reg_read = ds1305_nvram_read,
553 .reg_write = ds1305_nvram_write,
556 /*----------------------------------------------------------------------*/
559 * Interface to SPI stack
562 static int ds1305_probe(struct spi_device *spi)
564 struct ds1305 *ds1305;
567 struct ds1305_platform_data *pdata = dev_get_platdata(&spi->dev);
568 bool write_ctrl = false;
570 /* Sanity check board setup data. This may be hooked up
571 * in 3wire mode, but we don't care. Note that unless
572 * there's an inverter in place, this needs SPI_CS_HIGH!
574 if ((spi->bits_per_word && spi->bits_per_word != 8)
575 || (spi->max_speed_hz > 2000000)
576 || !(spi->mode & SPI_CPHA))
579 /* set up driver data */
580 ds1305 = devm_kzalloc(&spi->dev, sizeof(*ds1305), GFP_KERNEL);
584 spi_set_drvdata(spi, ds1305);
586 /* read and cache control registers */
587 addr = DS1305_CONTROL;
588 status = spi_write_then_read(spi, &addr, sizeof(addr),
589 ds1305->ctrl, sizeof(ds1305->ctrl));
591 dev_dbg(&spi->dev, "can't %s, %d\n",
596 dev_dbg(&spi->dev, "ctrl %s: %3ph\n", "read", ds1305->ctrl);
598 /* Sanity check register values ... partially compensating for the
599 * fact that SPI has no device handshake. A pullup on MISO would
600 * make these tests fail; but not all systems will have one. If
601 * some register is neither 0x00 nor 0xff, a chip is likely there.
603 if ((ds1305->ctrl[0] & 0x38) != 0 || (ds1305->ctrl[1] & 0xfc) != 0) {
604 dev_dbg(&spi->dev, "RTC chip is not present\n");
607 if (ds1305->ctrl[2] == 0)
608 dev_dbg(&spi->dev, "chip may not be present\n");
610 /* enable writes if needed ... if we were paranoid it would
611 * make sense to enable them only when absolutely necessary.
613 if (ds1305->ctrl[0] & DS1305_WP) {
616 ds1305->ctrl[0] &= ~DS1305_WP;
618 buf[0] = DS1305_WRITE | DS1305_CONTROL;
619 buf[1] = ds1305->ctrl[0];
620 status = spi_write_then_read(spi, buf, sizeof(buf), NULL, 0);
622 dev_dbg(&spi->dev, "clear WP --> %d\n", status);
627 /* on DS1305, maybe start oscillator; like most low power
628 * oscillators, it may take a second to stabilize
630 if (ds1305->ctrl[0] & DS1305_nEOSC) {
631 ds1305->ctrl[0] &= ~DS1305_nEOSC;
633 dev_warn(&spi->dev, "SET TIME!\n");
636 /* ack any pending IRQs */
637 if (ds1305->ctrl[1]) {
642 /* this may need one-time (re)init */
644 /* maybe enable trickle charge */
645 if (((ds1305->ctrl[2] & 0xf0) != DS1305_TRICKLE_MAGIC)) {
646 ds1305->ctrl[2] = DS1305_TRICKLE_MAGIC
651 /* on DS1306, configure 1 Hz signal */
652 if (pdata->is_ds1306) {
654 if (!(ds1305->ctrl[0] & DS1306_1HZ)) {
655 ds1305->ctrl[0] |= DS1306_1HZ;
659 if (ds1305->ctrl[0] & DS1306_1HZ) {
660 ds1305->ctrl[0] &= ~DS1306_1HZ;
670 buf[0] = DS1305_WRITE | DS1305_CONTROL;
671 buf[1] = ds1305->ctrl[0];
672 buf[2] = ds1305->ctrl[1];
673 buf[3] = ds1305->ctrl[2];
674 status = spi_write_then_read(spi, buf, sizeof(buf), NULL, 0);
676 dev_dbg(&spi->dev, "can't %s, %d\n",
681 dev_dbg(&spi->dev, "ctrl %s: %3ph\n", "write", ds1305->ctrl);
684 /* see if non-Linux software set up AM/PM mode */
686 status = spi_write_then_read(spi, &addr, sizeof(addr),
687 &value, sizeof(value));
689 dev_dbg(&spi->dev, "read HOUR --> %d\n", status);
693 ds1305->hr12 = (DS1305_HR_12 & value) != 0;
695 dev_dbg(&spi->dev, "AM/PM\n");
697 /* register RTC ... from here on, ds1305->ctrl needs locking */
698 ds1305->rtc = devm_rtc_allocate_device(&spi->dev);
699 if (IS_ERR(ds1305->rtc)) {
700 return PTR_ERR(ds1305->rtc);
703 ds1305->rtc->ops = &ds1305_ops;
705 ds1305_nvmem_cfg.priv = ds1305;
706 ds1305->rtc->nvmem_config = &ds1305_nvmem_cfg;
707 ds1305->rtc->nvram_old_abi = true;
709 status = rtc_register_device(ds1305->rtc);
711 dev_dbg(&spi->dev, "register rtc --> %d\n", status);
715 /* Maybe set up alarm IRQ; be ready to handle it triggering right
716 * away. NOTE that we don't share this. The signal is active low,
717 * and we can't ack it before a SPI message delay. We temporarily
718 * disable the IRQ until it's acked, which lets us work with more
719 * IRQ trigger modes (not all IRQ controllers can do falling edge).
722 INIT_WORK(&ds1305->work, ds1305_work);
723 status = devm_request_irq(&spi->dev, spi->irq, ds1305_irq,
724 0, dev_name(&ds1305->rtc->dev), ds1305);
726 dev_err(&spi->dev, "request_irq %d --> %d\n",
729 device_set_wakeup_capable(&spi->dev, 1);
736 static int ds1305_remove(struct spi_device *spi)
738 struct ds1305 *ds1305 = spi_get_drvdata(spi);
740 /* carefully shut down irq and workqueue, if present */
742 set_bit(FLAG_EXITING, &ds1305->flags);
743 devm_free_irq(&spi->dev, spi->irq, ds1305);
744 cancel_work_sync(&ds1305->work);
750 static struct spi_driver ds1305_driver = {
751 .driver.name = "rtc-ds1305",
752 .probe = ds1305_probe,
753 .remove = ds1305_remove,
754 /* REVISIT add suspend/resume */
757 module_spi_driver(ds1305_driver);
759 MODULE_DESCRIPTION("RTC driver for DS1305 and DS1306 chips");
760 MODULE_LICENSE("GPL");
761 MODULE_ALIAS("spi:rtc-ds1305");