| 1 | =======================================
|
| 2 | Real Time Clock (RTC) Drivers for Linux
|
| 3 | =======================================
|
| 4 |
|
| 5 | When Linux developers talk about a "Real Time Clock", they usually mean
|
| 6 | something that tracks wall clock time and is battery backed so that it
|
| 7 | works even with system power off. Such clocks will normally not track
|
| 8 | the local time zone or daylight savings time -- unless they dual boot
|
| 9 | with MS-Windows -- but will instead be set to Coordinated Universal Time
|
| 10 | (UTC, formerly "Greenwich Mean Time").
|
| 11 |
|
| 12 | The newest non-PC hardware tends to just count seconds, like the time(2)
|
| 13 | system call reports, but RTCs also very commonly represent time using
|
| 14 | the Gregorian calendar and 24 hour time, as reported by gmtime(3).
|
| 15 |
|
| 16 | Linux has two largely-compatible userspace RTC API families you may
|
| 17 | need to know about:
|
| 18 |
|
| 19 | * /dev/rtc ... is the RTC provided by PC compatible systems,
|
| 20 | so it's not very portable to non-x86 systems.
|
| 21 |
|
| 22 | * /dev/rtc0, /dev/rtc1 ... are part of a framework that's
|
| 23 | supported by a wide variety of RTC chips on all systems.
|
| 24 |
|
| 25 | Programmers need to understand that the PC/AT functionality is not
|
| 26 | always available, and some systems can do much more. That is, the
|
| 27 | RTCs use the same API to make requests in both RTC frameworks (using
|
| 28 | different filenames of course), but the hardware may not offer the
|
| 29 | same functionality. For example, not every RTC is hooked up to an
|
| 30 | IRQ, so they can't all issue alarms; and where standard PC RTCs can
|
| 31 | only issue an alarm up to 24 hours in the future, other hardware may
|
| 32 | be able to schedule one any time in the upcoming century.
|
| 33 |
|
| 34 |
|
| 35 | Old PC/AT-Compatible driver: /dev/rtc
|
| 36 | --------------------------------------
|
| 37 |
|
| 38 | All PCs (even Alpha machines) have a Real Time Clock built into them.
|
| 39 | Usually they are built into the chipset of the computer, but some may
|
| 40 | actually have a Motorola MC146818 (or clone) on the board. This is the
|
| 41 | clock that keeps the date and time while your computer is turned off.
|
| 42 |
|
| 43 | ACPI has standardized that MC146818 functionality, and extended it in
|
| 44 | a few ways (enabling longer alarm periods, and wake-from-hibernate).
|
| 45 | That functionality is NOT exposed in the old driver.
|
| 46 |
|
| 47 | However it can also be used to generate signals from a slow 2Hz to a
|
| 48 | relatively fast 8192Hz, in increments of powers of two. These signals
|
| 49 | are reported by interrupt number 8. (Oh! So *that* is what IRQ 8 is
|
| 50 | for...) It can also function as a 24hr alarm, raising IRQ 8 when the
|
| 51 | alarm goes off. The alarm can also be programmed to only check any
|
| 52 | subset of the three programmable values, meaning that it could be set to
|
| 53 | ring on the 30th second of the 30th minute of every hour, for example.
|
| 54 | The clock can also be set to generate an interrupt upon every clock
|
| 55 | update, thus generating a 1Hz signal.
|
| 56 |
|
| 57 | The interrupts are reported via /dev/rtc (major 10, minor 135, read only
|
| 58 | character device) in the form of an unsigned long. The low byte contains
|
| 59 | the type of interrupt (update-done, alarm-rang, or periodic) that was
|
| 60 | raised, and the remaining bytes contain the number of interrupts since
|
| 61 | the last read. Status information is reported through the pseudo-file
|
| 62 | /proc/driver/rtc if the /proc filesystem was enabled. The driver has
|
| 63 | built in locking so that only one process is allowed to have the /dev/rtc
|
| 64 | interface open at a time.
|
| 65 |
|
| 66 | A user process can monitor these interrupts by doing a read(2) or a
|
| 67 | select(2) on /dev/rtc -- either will block/stop the user process until
|
| 68 | the next interrupt is received. This is useful for things like
|
| 69 | reasonably high frequency data acquisition where one doesn't want to
|
| 70 | burn up 100% CPU by polling gettimeofday etc. etc.
|
| 71 |
|
| 72 | At high frequencies, or under high loads, the user process should check
|
| 73 | the number of interrupts received since the last read to determine if
|
| 74 | there has been any interrupt "pileup" so to speak. Just for reference, a
|
| 75 | typical 486-33 running a tight read loop on /dev/rtc will start to suffer
|
| 76 | occasional interrupt pileup (i.e. > 1 IRQ event since last read) for
|
| 77 | frequencies above 1024Hz. So you really should check the high bytes
|
| 78 | of the value you read, especially at frequencies above that of the
|
| 79 | normal timer interrupt, which is 100Hz.
|
| 80 |
|
| 81 | Programming and/or enabling interrupt frequencies greater than 64Hz is
|
| 82 | only allowed by root. This is perhaps a bit conservative, but we don't want
|
| 83 | an evil user generating lots of IRQs on a slow 386sx-16, where it might have
|
| 84 | a negative impact on performance. This 64Hz limit can be changed by writing
|
| 85 | a different value to /proc/sys/dev/rtc/max-user-freq. Note that the
|
| 86 | interrupt handler is only a few lines of code to minimize any possibility
|
| 87 | of this effect.
|
| 88 |
|
| 89 | Also, if the kernel time is synchronized with an external source, the
|
| 90 | kernel will write the time back to the CMOS clock every 11 minutes. In
|
| 91 | the process of doing this, the kernel briefly turns off RTC periodic
|
| 92 | interrupts, so be aware of this if you are doing serious work. If you
|
| 93 | don't synchronize the kernel time with an external source (via ntp or
|
| 94 | whatever) then the kernel will keep its hands off the RTC, allowing you
|
| 95 | exclusive access to the device for your applications.
|
| 96 |
|
| 97 | The alarm and/or interrupt frequency are programmed into the RTC via
|
| 98 | various ioctl(2) calls as listed in ./include/linux/rtc.h
|
| 99 | Rather than write 50 pages describing the ioctl() and so on, it is
|
| 100 | perhaps more useful to include a small test program that demonstrates
|
| 101 | how to use them, and demonstrates the features of the driver. This is
|
| 102 | probably a lot more useful to people interested in writing applications
|
| 103 | that will be using this driver. See the code at the end of this document.
|
| 104 |
|
| 105 | (The original /dev/rtc driver was written by Paul Gortmaker.)
|
| 106 |
|
| 107 |
|
| 108 | New portable "RTC Class" drivers: /dev/rtcN
|
| 109 | --------------------------------------------
|
| 110 |
|
| 111 | Because Linux supports many non-ACPI and non-PC platforms, some of which
|
| 112 | have more than one RTC style clock, it needed a more portable solution
|
| 113 | than expecting a single battery-backed MC146818 clone on every system.
|
| 114 | Accordingly, a new "RTC Class" framework has been defined. It offers
|
| 115 | three different userspace interfaces:
|
| 116 |
|
| 117 | * /dev/rtcN ... much the same as the older /dev/rtc interface
|
| 118 |
|
| 119 | * /sys/class/rtc/rtcN ... sysfs attributes support readonly
|
| 120 | access to some RTC attributes.
|
| 121 |
|
| 122 | * /proc/driver/rtc ... the system clock RTC may expose itself
|
| 123 | using a procfs interface. If there is no RTC for the system clock,
|
| 124 | rtc0 is used by default. More information is (currently) shown
|
| 125 | here than through sysfs.
|
| 126 |
|
| 127 | The RTC Class framework supports a wide variety of RTCs, ranging from those
|
| 128 | integrated into embeddable system-on-chip (SOC) processors to discrete chips
|
| 129 | using I2C, SPI, or some other bus to communicate with the host CPU. There's
|
| 130 | even support for PC-style RTCs ... including the features exposed on newer PCs
|
| 131 | through ACPI.
|
| 132 |
|
| 133 | The new framework also removes the "one RTC per system" restriction. For
|
| 134 | example, maybe the low-power battery-backed RTC is a discrete I2C chip, but
|
| 135 | a high functionality RTC is integrated into the SOC. That system might read
|
| 136 | the system clock from the discrete RTC, but use the integrated one for all
|
| 137 | other tasks, because of its greater functionality.
|
| 138 |
|
| 139 | Check out tools/testing/selftests/rtc/rtctest.c for an example usage of the
|
| 140 | ioctl interface.
|