Root/
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 | SYSFS INTERFACE |
140 | --------------- |
141 | |
142 | The sysfs interface under /sys/class/rtc/rtcN provides access to various |
143 | rtc attributes without requiring the use of ioctls. All dates and times |
144 | are in the RTC's timezone, rather than in system time. |
145 | |
146 | date: RTC-provided date |
147 | hctosys: 1 if the RTC provided the system time at boot via the |
148 | CONFIG_RTC_HCTOSYS kernel option, 0 otherwise |
149 | max_user_freq: The maximum interrupt rate an unprivileged user may request |
150 | from this RTC. |
151 | name: The name of the RTC corresponding to this sysfs directory |
152 | since_epoch: The number of seconds since the epoch according to the RTC |
153 | time: RTC-provided time |
154 | wakealarm: The time at which the clock will generate a system wakeup |
155 | event. This is a one shot wakeup event, so must be reset |
156 | after wake if a daily wakeup is required. Format is seconds since |
157 | the epoch by default, or if there's a leading +, seconds in the |
158 | future, or if there is a leading +=, seconds ahead of the current |
159 | alarm. |
160 | |
161 | IOCTL INTERFACE |
162 | --------------- |
163 | |
164 | The ioctl() calls supported by /dev/rtc are also supported by the RTC class |
165 | framework. However, because the chips and systems are not standardized, |
166 | some PC/AT functionality might not be provided. And in the same way, some |
167 | newer features -- including those enabled by ACPI -- are exposed by the |
168 | RTC class framework, but can't be supported by the older driver. |
169 | |
170 | * RTC_RD_TIME, RTC_SET_TIME ... every RTC supports at least reading |
171 | time, returning the result as a Gregorian calendar date and 24 hour |
172 | wall clock time. To be most useful, this time may also be updated. |
173 | |
174 | * RTC_AIE_ON, RTC_AIE_OFF, RTC_ALM_SET, RTC_ALM_READ ... when the RTC |
175 | is connected to an IRQ line, it can often issue an alarm IRQ up to |
176 | 24 hours in the future. (Use RTC_WKALM_* by preference.) |
177 | |
178 | * RTC_WKALM_SET, RTC_WKALM_RD ... RTCs that can issue alarms beyond |
179 | the next 24 hours use a slightly more powerful API, which supports |
180 | setting the longer alarm time and enabling its IRQ using a single |
181 | request (using the same model as EFI firmware). |
182 | |
183 | * RTC_UIE_ON, RTC_UIE_OFF ... if the RTC offers IRQs, the RTC framework |
184 | will emulate this mechanism. |
185 | |
186 | * RTC_PIE_ON, RTC_PIE_OFF, RTC_IRQP_SET, RTC_IRQP_READ ... these icotls |
187 | are emulated via a kernel hrtimer. |
188 | |
189 | In many cases, the RTC alarm can be a system wake event, used to force |
190 | Linux out of a low power sleep state (or hibernation) back to a fully |
191 | operational state. For example, a system could enter a deep power saving |
192 | state until it's time to execute some scheduled tasks. |
193 | |
194 | Note that many of these ioctls are handled by the common rtc-dev interface. |
195 | Some common examples: |
196 | |
197 | * RTC_RD_TIME, RTC_SET_TIME: the read_time/set_time functions will be |
198 | called with appropriate values. |
199 | |
200 | * RTC_ALM_SET, RTC_ALM_READ, RTC_WKALM_SET, RTC_WKALM_RD: gets or sets |
201 | the alarm rtc_timer. May call the set_alarm driver function. |
202 | |
203 | * RTC_IRQP_SET, RTC_IRQP_READ: These are emulated by the generic code. |
204 | |
205 | * RTC_PIE_ON, RTC_PIE_OFF: These are also emulated by the generic code. |
206 | |
207 | If all else fails, check out the rtc-test.c driver! |
208 | |
209 | |
210 | -------------------- 8< ---------------- 8< ----------------------------- |
211 | |
212 | /* |
213 | * Real Time Clock Driver Test/Example Program |
214 | * |
215 | * Compile with: |
216 | * gcc -s -Wall -Wstrict-prototypes rtctest.c -o rtctest |
217 | * |
218 | * Copyright (C) 1996, Paul Gortmaker. |
219 | * |
220 | * Released under the GNU General Public License, version 2, |
221 | * included herein by reference. |
222 | * |
223 | */ |
224 | |
225 | #include <stdio.h> |
226 | #include <linux/rtc.h> |
227 | #include <sys/ioctl.h> |
228 | #include <sys/time.h> |
229 | #include <sys/types.h> |
230 | #include <fcntl.h> |
231 | #include <unistd.h> |
232 | #include <stdlib.h> |
233 | #include <errno.h> |
234 | |
235 | |
236 | /* |
237 | * This expects the new RTC class driver framework, working with |
238 | * clocks that will often not be clones of what the PC-AT had. |
239 | * Use the command line to specify another RTC if you need one. |
240 | */ |
241 | static const char default_rtc[] = "/dev/rtc0"; |
242 | |
243 | |
244 | int main(int argc, char **argv) |
245 | { |
246 | int i, fd, retval, irqcount = 0; |
247 | unsigned long tmp, data; |
248 | struct rtc_time rtc_tm; |
249 | const char *rtc = default_rtc; |
250 | |
251 | switch (argc) { |
252 | case 2: |
253 | rtc = argv[1]; |
254 | /* FALLTHROUGH */ |
255 | case 1: |
256 | break; |
257 | default: |
258 | fprintf(stderr, "usage: rtctest [rtcdev]\n"); |
259 | return 1; |
260 | } |
261 | |
262 | fd = open(rtc, O_RDONLY); |
263 | |
264 | if (fd == -1) { |
265 | perror(rtc); |
266 | exit(errno); |
267 | } |
268 | |
269 | fprintf(stderr, "\n\t\t\tRTC Driver Test Example.\n\n"); |
270 | |
271 | /* Turn on update interrupts (one per second) */ |
272 | retval = ioctl(fd, RTC_UIE_ON, 0); |
273 | if (retval == -1) { |
274 | if (errno == ENOTTY) { |
275 | fprintf(stderr, |
276 | "\n...Update IRQs not supported.\n"); |
277 | goto test_READ; |
278 | } |
279 | perror("RTC_UIE_ON ioctl"); |
280 | exit(errno); |
281 | } |
282 | |
283 | fprintf(stderr, "Counting 5 update (1/sec) interrupts from reading %s:", |
284 | rtc); |
285 | fflush(stderr); |
286 | for (i=1; i<6; i++) { |
287 | /* This read will block */ |
288 | retval = read(fd, &data, sizeof(unsigned long)); |
289 | if (retval == -1) { |
290 | perror("read"); |
291 | exit(errno); |
292 | } |
293 | fprintf(stderr, " %d",i); |
294 | fflush(stderr); |
295 | irqcount++; |
296 | } |
297 | |
298 | fprintf(stderr, "\nAgain, from using select(2) on /dev/rtc:"); |
299 | fflush(stderr); |
300 | for (i=1; i<6; i++) { |
301 | struct timeval tv = {5, 0}; /* 5 second timeout on select */ |
302 | fd_set readfds; |
303 | |
304 | FD_ZERO(&readfds); |
305 | FD_SET(fd, &readfds); |
306 | /* The select will wait until an RTC interrupt happens. */ |
307 | retval = select(fd+1, &readfds, NULL, NULL, &tv); |
308 | if (retval == -1) { |
309 | perror("select"); |
310 | exit(errno); |
311 | } |
312 | /* This read won't block unlike the select-less case above. */ |
313 | retval = read(fd, &data, sizeof(unsigned long)); |
314 | if (retval == -1) { |
315 | perror("read"); |
316 | exit(errno); |
317 | } |
318 | fprintf(stderr, " %d",i); |
319 | fflush(stderr); |
320 | irqcount++; |
321 | } |
322 | |
323 | /* Turn off update interrupts */ |
324 | retval = ioctl(fd, RTC_UIE_OFF, 0); |
325 | if (retval == -1) { |
326 | perror("RTC_UIE_OFF ioctl"); |
327 | exit(errno); |
328 | } |
329 | |
330 | test_READ: |
331 | /* Read the RTC time/date */ |
332 | retval = ioctl(fd, RTC_RD_TIME, &rtc_tm); |
333 | if (retval == -1) { |
334 | perror("RTC_RD_TIME ioctl"); |
335 | exit(errno); |
336 | } |
337 | |
338 | fprintf(stderr, "\n\nCurrent RTC date/time is %d-%d-%d, %02d:%02d:%02d.\n", |
339 | rtc_tm.tm_mday, rtc_tm.tm_mon + 1, rtc_tm.tm_year + 1900, |
340 | rtc_tm.tm_hour, rtc_tm.tm_min, rtc_tm.tm_sec); |
341 | |
342 | /* Set the alarm to 5 sec in the future, and check for rollover */ |
343 | rtc_tm.tm_sec += 5; |
344 | if (rtc_tm.tm_sec >= 60) { |
345 | rtc_tm.tm_sec %= 60; |
346 | rtc_tm.tm_min++; |
347 | } |
348 | if (rtc_tm.tm_min == 60) { |
349 | rtc_tm.tm_min = 0; |
350 | rtc_tm.tm_hour++; |
351 | } |
352 | if (rtc_tm.tm_hour == 24) |
353 | rtc_tm.tm_hour = 0; |
354 | |
355 | retval = ioctl(fd, RTC_ALM_SET, &rtc_tm); |
356 | if (retval == -1) { |
357 | if (errno == ENOTTY) { |
358 | fprintf(stderr, |
359 | "\n...Alarm IRQs not supported.\n"); |
360 | goto test_PIE; |
361 | } |
362 | perror("RTC_ALM_SET ioctl"); |
363 | exit(errno); |
364 | } |
365 | |
366 | /* Read the current alarm settings */ |
367 | retval = ioctl(fd, RTC_ALM_READ, &rtc_tm); |
368 | if (retval == -1) { |
369 | perror("RTC_ALM_READ ioctl"); |
370 | exit(errno); |
371 | } |
372 | |
373 | fprintf(stderr, "Alarm time now set to %02d:%02d:%02d.\n", |
374 | rtc_tm.tm_hour, rtc_tm.tm_min, rtc_tm.tm_sec); |
375 | |
376 | /* Enable alarm interrupts */ |
377 | retval = ioctl(fd, RTC_AIE_ON, 0); |
378 | if (retval == -1) { |
379 | perror("RTC_AIE_ON ioctl"); |
380 | exit(errno); |
381 | } |
382 | |
383 | fprintf(stderr, "Waiting 5 seconds for alarm..."); |
384 | fflush(stderr); |
385 | /* This blocks until the alarm ring causes an interrupt */ |
386 | retval = read(fd, &data, sizeof(unsigned long)); |
387 | if (retval == -1) { |
388 | perror("read"); |
389 | exit(errno); |
390 | } |
391 | irqcount++; |
392 | fprintf(stderr, " okay. Alarm rang.\n"); |
393 | |
394 | /* Disable alarm interrupts */ |
395 | retval = ioctl(fd, RTC_AIE_OFF, 0); |
396 | if (retval == -1) { |
397 | perror("RTC_AIE_OFF ioctl"); |
398 | exit(errno); |
399 | } |
400 | |
401 | test_PIE: |
402 | /* Read periodic IRQ rate */ |
403 | retval = ioctl(fd, RTC_IRQP_READ, &tmp); |
404 | if (retval == -1) { |
405 | /* not all RTCs support periodic IRQs */ |
406 | if (errno == ENOTTY) { |
407 | fprintf(stderr, "\nNo periodic IRQ support\n"); |
408 | goto done; |
409 | } |
410 | perror("RTC_IRQP_READ ioctl"); |
411 | exit(errno); |
412 | } |
413 | fprintf(stderr, "\nPeriodic IRQ rate is %ldHz.\n", tmp); |
414 | |
415 | fprintf(stderr, "Counting 20 interrupts at:"); |
416 | fflush(stderr); |
417 | |
418 | /* The frequencies 128Hz, 256Hz, ... 8192Hz are only allowed for root. */ |
419 | for (tmp=2; tmp<=64; tmp*=2) { |
420 | |
421 | retval = ioctl(fd, RTC_IRQP_SET, tmp); |
422 | if (retval == -1) { |
423 | /* not all RTCs can change their periodic IRQ rate */ |
424 | if (errno == ENOTTY) { |
425 | fprintf(stderr, |
426 | "\n...Periodic IRQ rate is fixed\n"); |
427 | goto done; |
428 | } |
429 | perror("RTC_IRQP_SET ioctl"); |
430 | exit(errno); |
431 | } |
432 | |
433 | fprintf(stderr, "\n%ldHz:\t", tmp); |
434 | fflush(stderr); |
435 | |
436 | /* Enable periodic interrupts */ |
437 | retval = ioctl(fd, RTC_PIE_ON, 0); |
438 | if (retval == -1) { |
439 | perror("RTC_PIE_ON ioctl"); |
440 | exit(errno); |
441 | } |
442 | |
443 | for (i=1; i<21; i++) { |
444 | /* This blocks */ |
445 | retval = read(fd, &data, sizeof(unsigned long)); |
446 | if (retval == -1) { |
447 | perror("read"); |
448 | exit(errno); |
449 | } |
450 | fprintf(stderr, " %d",i); |
451 | fflush(stderr); |
452 | irqcount++; |
453 | } |
454 | |
455 | /* Disable periodic interrupts */ |
456 | retval = ioctl(fd, RTC_PIE_OFF, 0); |
457 | if (retval == -1) { |
458 | perror("RTC_PIE_OFF ioctl"); |
459 | exit(errno); |
460 | } |
461 | } |
462 | |
463 | done: |
464 | fprintf(stderr, "\n\n\t\t\t *** Test complete ***\n"); |
465 | |
466 | close(fd); |
467 | |
468 | return 0; |
469 | } |
470 |
Branches:
ben-wpan
ben-wpan-stefan
javiroman/ks7010
jz-2.6.34
jz-2.6.34-rc5
jz-2.6.34-rc6
jz-2.6.34-rc7
jz-2.6.35
jz-2.6.36
jz-2.6.37
jz-2.6.38
jz-2.6.39
jz-3.0
jz-3.1
jz-3.11
jz-3.12
jz-3.13
jz-3.15
jz-3.16
jz-3.18-dt
jz-3.2
jz-3.3
jz-3.4
jz-3.5
jz-3.6
jz-3.6-rc2-pwm
jz-3.9
jz-3.9-clk
jz-3.9-rc8
jz47xx
jz47xx-2.6.38
master
Tags:
od-2011-09-04
od-2011-09-18
v2.6.34-rc5
v2.6.34-rc6
v2.6.34-rc7
v3.9