|Real Time Clock (RTC) Drivers for Linux
|When Linux developers talk about a "Real Time Clock", they usually mean
|something that tracks wall clock time and is battery backed so that it
|works even with system power off. Such clocks will normally not track
|the local time zone or daylight savings time -- unless they dual boot
|with MS-Windows -- but will instead be set to Coordinated Universal Time
|(UTC, formerly "Greenwich Mean Time").
|The newest non-PC hardware tends to just count seconds, like the time(2)
|system call reports, but RTCs also very commonly represent time using
|the Gregorian calendar and 24 hour time, as reported by gmtime(3).
|Linux has two largely-compatible userspace RTC API families you may
|need to know about:
| * /dev/rtc ... is the RTC provided by PC compatible systems,
| so it's not very portable to non-x86 systems.
| * /dev/rtc0, /dev/rtc1 ... are part of a framework that's
| supported by a wide variety of RTC chips on all systems.
|Programmers need to understand that the PC/AT functionality is not
|always available, and some systems can do much more. That is, the
|RTCs use the same API to make requests in both RTC frameworks (using
|different filenames of course), but the hardware may not offer the
|same functionality. For example, not every RTC is hooked up to an
|IRQ, so they can't all issue alarms; and where standard PC RTCs can
|only issue an alarm up to 24 hours in the future, other hardware may
|be able to schedule one any time in the upcoming century.
|Old PC/AT-Compatible driver: /dev/rtc
|All PCs (even Alpha machines) have a Real Time Clock built into them.
|Usually they are built into the chipset of the computer, but some may
|actually have a Motorola MC146818 (or clone) on the board. This is the
|clock that keeps the date and time while your computer is turned off.
|ACPI has standardized that MC146818 functionality, and extended it in
|a few ways (enabling longer alarm periods, and wake-from-hibernate).
|That functionality is NOT exposed in the old driver.
|However it can also be used to generate signals from a slow 2Hz to a
|relatively fast 8192Hz, in increments of powers of two. These signals
|are reported by interrupt number 8. (Oh! So *that* is what IRQ 8 is
|for...) It can also function as a 24hr alarm, raising IRQ 8 when the
|alarm goes off. The alarm can also be programmed to only check any
|subset of the three programmable values, meaning that it could be set to
|ring on the 30th second of the 30th minute of every hour, for example.
|The clock can also be set to generate an interrupt upon every clock
|update, thus generating a 1Hz signal.
|The interrupts are reported via /dev/rtc (major 10, minor 135, read only
|character device) in the form of an unsigned long. The low byte contains
|the type of interrupt (update-done, alarm-rang, or periodic) that was
|raised, and the remaining bytes contain the number of interrupts since
|the last read. Status information is reported through the pseudo-file
|/proc/driver/rtc if the /proc filesystem was enabled. The driver has
|built in locking so that only one process is allowed to have the /dev/rtc
|interface open at a time.
|A user process can monitor these interrupts by doing a read(2) or a
|select(2) on /dev/rtc -- either will block/stop the user process until
|the next interrupt is received. This is useful for things like
|reasonably high frequency data acquisition where one doesn't want to
|burn up 100% CPU by polling gettimeofday etc. etc.
|At high frequencies, or under high loads, the user process should check
|the number of interrupts received since the last read to determine if
|there has been any interrupt "pileup" so to speak. Just for reference, a
|typical 486-33 running a tight read loop on /dev/rtc will start to suffer
|occasional interrupt pileup (i.e. > 1 IRQ event since last read) for
|frequencies above 1024Hz. So you really should check the high bytes
|of the value you read, especially at frequencies above that of the
|normal timer interrupt, which is 100Hz.
|Programming and/or enabling interrupt frequencies greater than 64Hz is
|only allowed by root. This is perhaps a bit conservative, but we don't want
|an evil user generating lots of IRQs on a slow 386sx-16, where it might have
|a negative impact on performance. This 64Hz limit can be changed by writing
|a different value to /proc/sys/dev/rtc/max-user-freq. Note that the
|interrupt handler is only a few lines of code to minimize any possibility
|of this effect.
|Also, if the kernel time is synchronized with an external source, the
|kernel will write the time back to the CMOS clock every 11 minutes. In
|the process of doing this, the kernel briefly turns off RTC periodic
|interrupts, so be aware of this if you are doing serious work. If you
|don't synchronize the kernel time with an external source (via ntp or
|whatever) then the kernel will keep its hands off the RTC, allowing you
|exclusive access to the device for your applications.
|The alarm and/or interrupt frequency are programmed into the RTC via
|various ioctl(2) calls as listed in ./include/linux/rtc.h
|Rather than write 50 pages describing the ioctl() and so on, it is
|perhaps more useful to include a small test program that demonstrates
|how to use them, and demonstrates the features of the driver. This is
|probably a lot more useful to people interested in writing applications
|that will be using this driver. See the code at the end of this document.
|(The original /dev/rtc driver was written by Paul Gortmaker.)
|New portable "RTC Class" drivers: /dev/rtcN
|Because Linux supports many non-ACPI and non-PC platforms, some of which
|have more than one RTC style clock, it needed a more portable solution
|than expecting a single battery-backed MC146818 clone on every system.
|Accordingly, a new "RTC Class" framework has been defined. It offers
|three different userspace interfaces:
| * /dev/rtcN ... much the same as the older /dev/rtc interface
| * /sys/class/rtc/rtcN ... sysfs attributes support readonly
| access to some RTC attributes.
| * /proc/driver/rtc ... the system clock RTC may expose itself
| using a procfs interface. If there is no RTC for the system clock,
| rtc0 is used by default. More information is (currently) shown
| here than through sysfs.
|The RTC Class framework supports a wide variety of RTCs, ranging from those
|integrated into embeddable system-on-chip (SOC) processors to discrete chips
|using I2C, SPI, or some other bus to communicate with the host CPU. There's
|even support for PC-style RTCs ... including the features exposed on newer PCs
|The new framework also removes the "one RTC per system" restriction. For
|example, maybe the low-power battery-backed RTC is a discrete I2C chip, but
|a high functionality RTC is integrated into the SOC. That system might read
|the system clock from the discrete RTC, but use the integrated one for all
|other tasks, because of its greater functionality.
|The sysfs interface under /sys/class/rtc/rtcN provides access to various
|rtc attributes without requiring the use of ioctls. All dates and times
|are in the RTC's timezone, rather than in system time.
|date RTC-provided date
|hctosys 1 if the RTC provided the system time at boot via the
| CONFIG_RTC_HCTOSYS kernel option, 0 otherwise
|max_user_freq The maximum interrupt rate an unprivileged user may request
| from this RTC.
|name The name of the RTC corresponding to this sysfs directory
|since_epoch The number of seconds since the epoch according to the RTC
|time RTC-provided time
|wakealarm The time at which the clock will generate a system wakeup
| event. This is a one shot wakeup event, so must be reset
| after wake if a daily wakeup is required. Format is seconds
| since the epoch by default, or if there's a leading +, seconds
| in the future, or if there is a leading +=, seconds ahead of
| the current alarm.
|offset The amount which the rtc clock has been adjusted in firmware.
| Visible only if the driver supports clock offset adjustment.
| The unit is parts per billion, i.e. The number of clock ticks
| which are added to or removed from the rtc's base clock per
| billion ticks. A positive value makes a day pass more slowly,
| longer, and a negative value makes a day pass more quickly.
|*/nvmem The non volatile storage exported as a raw file, as described
| in Documentation/nvmem/nvmem.txt
|The ioctl() calls supported by /dev/rtc are also supported by the RTC class
|framework. However, because the chips and systems are not standardized,
|some PC/AT functionality might not be provided. And in the same way, some
|newer features -- including those enabled by ACPI -- are exposed by the
|RTC class framework, but can't be supported by the older driver.
| * RTC_RD_TIME, RTC_SET_TIME ... every RTC supports at least reading
| time, returning the result as a Gregorian calendar date and 24 hour
| wall clock time. To be most useful, this time may also be updated.
| * RTC_AIE_ON, RTC_AIE_OFF, RTC_ALM_SET, RTC_ALM_READ ... when the RTC
| is connected to an IRQ line, it can often issue an alarm IRQ up to
| 24 hours in the future. (Use RTC_WKALM_* by preference.)
| * RTC_WKALM_SET, RTC_WKALM_RD ... RTCs that can issue alarms beyond
| the next 24 hours use a slightly more powerful API, which supports
| setting the longer alarm time and enabling its IRQ using a single
| request (using the same model as EFI firmware).
| * RTC_UIE_ON, RTC_UIE_OFF ... if the RTC offers IRQs, the RTC framework
| will emulate this mechanism.
| * RTC_PIE_ON, RTC_PIE_OFF, RTC_IRQP_SET, RTC_IRQP_READ ... these icotls
| are emulated via a kernel hrtimer.
|In many cases, the RTC alarm can be a system wake event, used to force
|Linux out of a low power sleep state (or hibernation) back to a fully
|operational state. For example, a system could enter a deep power saving
|state until it's time to execute some scheduled tasks.
|Note that many of these ioctls are handled by the common rtc-dev interface.
|Some common examples:
| * RTC_RD_TIME, RTC_SET_TIME: the read_time/set_time functions will be
| called with appropriate values.
| * RTC_ALM_SET, RTC_ALM_READ, RTC_WKALM_SET, RTC_WKALM_RD: gets or sets
| the alarm rtc_timer. May call the set_alarm driver function.
| * RTC_IRQP_SET, RTC_IRQP_READ: These are emulated by the generic code.
| * RTC_PIE_ON, RTC_PIE_OFF: These are also emulated by the generic code.
|If all else fails, check out the tools/testing/selftests/timers/rtctest.c test!