Commit | Line | Data |
---|---|---|
1da177e4 | 1 | |
7531d8fa DB |
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 | -------------------------------------- | |
1da177e4 LT |
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 | ||
7531d8fa DB |
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 | ||
1da177e4 LT |
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 | |
9be05b57 JD |
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. | |
1da177e4 LT |
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 | |
7531d8fa DB |
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 first RTC (rtc0) may expose itself | |
123 | using a procfs interface. More information is (currently) shown | |
124 | here than through sysfs. | |
125 | ||
126 | The RTC Class framework supports a wide variety of RTCs, ranging from those | |
127 | integrated into embeddable system-on-chip (SOC) processors to discrete chips | |
128 | using I2C, SPI, or some other bus to communicate with the host CPU. There's | |
129 | even support for PC-style RTCs ... including the features exposed on newer PCs | |
130 | through ACPI. | |
131 | ||
132 | The new framework also removes the "one RTC per system" restriction. For | |
133 | example, maybe the low-power battery-backed RTC is a discrete I2C chip, but | |
134 | a high functionality RTC is integrated into the SOC. That system might read | |
135 | the system clock from the discrete RTC, but use the integrated one for all | |
136 | other tasks, because of its greater functionality. | |
137 | ||
138 | The ioctl() calls supported by /dev/rtc are also supported by the RTC class | |
139 | framework. However, because the chips and systems are not standardized, | |
140 | some PC/AT functionality might not be provided. And in the same way, some | |
141 | newer features -- including those enabled by ACPI -- are exposed by the | |
142 | RTC class framework, but can't be supported by the older driver. | |
143 | ||
144 | * RTC_RD_TIME, RTC_SET_TIME ... every RTC supports at least reading | |
145 | time, returning the result as a Gregorian calendar date and 24 hour | |
146 | wall clock time. To be most useful, this time may also be updated. | |
147 | ||
148 | * RTC_AIE_ON, RTC_AIE_OFF, RTC_ALM_SET, RTC_ALM_READ ... when the RTC | |
149 | is connected to an IRQ line, it can often issue an alarm IRQ up to | |
f8245c26 | 150 | 24 hours in the future. (Use RTC_WKALM_* by preference.) |
7531d8fa | 151 | |
2b1cd4c4 | 152 | * RTC_WKALM_SET, RTC_WKALM_RD ... RTCs that can issue alarms beyond |
7531d8fa DB |
153 | the next 24 hours use a slightly more powerful API, which supports |
154 | setting the longer alarm time and enabling its IRQ using a single | |
155 | request (using the same model as EFI firmware). | |
156 | ||
157 | * RTC_UIE_ON, RTC_UIE_OFF ... if the RTC offers IRQs, it probably | |
158 | also offers update IRQs whenever the "seconds" counter changes. | |
159 | If needed, the RTC framework can emulate this mechanism. | |
160 | ||
161 | * RTC_PIE_ON, RTC_PIE_OFF, RTC_IRQP_SET, RTC_IRQP_READ ... another | |
162 | feature often accessible with an IRQ line is a periodic IRQ, issued | |
163 | at settable frequencies (usually 2^N Hz). | |
164 | ||
165 | In many cases, the RTC alarm can be a system wake event, used to force | |
166 | Linux out of a low power sleep state (or hibernation) back to a fully | |
167 | operational state. For example, a system could enter a deep power saving | |
168 | state until it's time to execute some scheduled tasks. | |
1da177e4 | 169 | |
2b1cd4c4 MF |
170 | Note that many of these ioctls need not actually be implemented by your |
171 | driver. The common rtc-dev interface handles many of these nicely if your | |
172 | driver returns ENOIOCTLCMD. Some common examples: | |
173 | ||
174 | * RTC_RD_TIME, RTC_SET_TIME: the read_time/set_time functions will be | |
175 | called with appropriate values. | |
176 | ||
177 | * RTC_ALM_SET, RTC_ALM_READ, RTC_WKALM_SET, RTC_WKALM_RD: the | |
f8245c26 | 178 | set_alarm/read_alarm functions will be called. |
2b1cd4c4 MF |
179 | |
180 | * RTC_IRQP_SET, RTC_IRQP_READ: the irq_set_freq function will be called | |
181 | to set the frequency while the framework will handle the read for you | |
182 | since the frequency is stored in the irq_freq member of the rtc_device | |
108b4c36 MF |
183 | structure. Your driver needs to initialize the irq_freq member during |
184 | init. Make sure you check the requested frequency is in range of your | |
8a0ba4e0 MF |
185 | hardware in the irq_set_freq function. If it isn't, return -EINVAL. If |
186 | you cannot actually change the frequency, do not define irq_set_freq. | |
2b1cd4c4 MF |
187 | |
188 | If all else fails, check out the rtc-test.c driver! | |
189 | ||
1da177e4 LT |
190 | |
191 | -------------------- 8< ---------------- 8< ----------------------------- | |
192 | ||
193 | /* | |
7531d8fa | 194 | * Real Time Clock Driver Test/Example Program |
1da177e4 | 195 | * |
7531d8fa DB |
196 | * Compile with: |
197 | * gcc -s -Wall -Wstrict-prototypes rtctest.c -o rtctest | |
1da177e4 | 198 | * |
7531d8fa | 199 | * Copyright (C) 1996, Paul Gortmaker. |
1da177e4 | 200 | * |
7531d8fa DB |
201 | * Released under the GNU General Public License, version 2, |
202 | * included herein by reference. | |
1da177e4 LT |
203 | * |
204 | */ | |
205 | ||
206 | #include <stdio.h> | |
207 | #include <linux/rtc.h> | |
208 | #include <sys/ioctl.h> | |
209 | #include <sys/time.h> | |
210 | #include <sys/types.h> | |
211 | #include <fcntl.h> | |
212 | #include <unistd.h> | |
7531d8fa | 213 | #include <stdlib.h> |
1da177e4 LT |
214 | #include <errno.h> |
215 | ||
1da177e4 | 216 | |
7531d8fa DB |
217 | /* |
218 | * This expects the new RTC class driver framework, working with | |
219 | * clocks that will often not be clones of what the PC-AT had. | |
220 | * Use the command line to specify another RTC if you need one. | |
221 | */ | |
222 | static const char default_rtc[] = "/dev/rtc0"; | |
223 | ||
224 | ||
225 | int main(int argc, char **argv) | |
226 | { | |
227 | int i, fd, retval, irqcount = 0; | |
228 | unsigned long tmp, data; | |
229 | struct rtc_time rtc_tm; | |
230 | const char *rtc = default_rtc; | |
231 | ||
232 | switch (argc) { | |
233 | case 2: | |
234 | rtc = argv[1]; | |
235 | /* FALLTHROUGH */ | |
236 | case 1: | |
237 | break; | |
238 | default: | |
239 | fprintf(stderr, "usage: rtctest [rtcdev]\n"); | |
240 | return 1; | |
241 | } | |
1da177e4 | 242 | |
7531d8fa | 243 | fd = open(rtc, O_RDONLY); |
1da177e4 | 244 | |
7531d8fa DB |
245 | if (fd == -1) { |
246 | perror(rtc); | |
247 | exit(errno); | |
248 | } | |
1da177e4 | 249 | |
7531d8fa | 250 | fprintf(stderr, "\n\t\t\tRTC Driver Test Example.\n\n"); |
1da177e4 | 251 | |
7531d8fa DB |
252 | /* Turn on update interrupts (one per second) */ |
253 | retval = ioctl(fd, RTC_UIE_ON, 0); | |
1da177e4 | 254 | if (retval == -1) { |
7531d8fa DB |
255 | if (errno == ENOTTY) { |
256 | fprintf(stderr, | |
257 | "\n...Update IRQs not supported.\n"); | |
258 | goto test_READ; | |
259 | } | |
2b1cd4c4 | 260 | perror("RTC_UIE_ON ioctl"); |
1da177e4 LT |
261 | exit(errno); |
262 | } | |
7531d8fa DB |
263 | |
264 | fprintf(stderr, "Counting 5 update (1/sec) interrupts from reading %s:", | |
265 | rtc); | |
1da177e4 | 266 | fflush(stderr); |
7531d8fa DB |
267 | for (i=1; i<6; i++) { |
268 | /* This read will block */ | |
269 | retval = read(fd, &data, sizeof(unsigned long)); | |
270 | if (retval == -1) { | |
8696e702 MF |
271 | perror("read"); |
272 | exit(errno); | |
7531d8fa DB |
273 | } |
274 | fprintf(stderr, " %d",i); | |
275 | fflush(stderr); | |
276 | irqcount++; | |
277 | } | |
1da177e4 | 278 | |
7531d8fa DB |
279 | fprintf(stderr, "\nAgain, from using select(2) on /dev/rtc:"); |
280 | fflush(stderr); | |
281 | for (i=1; i<6; i++) { | |
282 | struct timeval tv = {5, 0}; /* 5 second timeout on select */ | |
283 | fd_set readfds; | |
284 | ||
285 | FD_ZERO(&readfds); | |
286 | FD_SET(fd, &readfds); | |
287 | /* The select will wait until an RTC interrupt happens. */ | |
288 | retval = select(fd+1, &readfds, NULL, NULL, &tv); | |
289 | if (retval == -1) { | |
290 | perror("select"); | |
291 | exit(errno); | |
292 | } | |
293 | /* This read won't block unlike the select-less case above. */ | |
294 | retval = read(fd, &data, sizeof(unsigned long)); | |
295 | if (retval == -1) { | |
296 | perror("read"); | |
297 | exit(errno); | |
298 | } | |
299 | fprintf(stderr, " %d",i); | |
300 | fflush(stderr); | |
301 | irqcount++; | |
302 | } | |
1da177e4 | 303 | |
7531d8fa DB |
304 | /* Turn off update interrupts */ |
305 | retval = ioctl(fd, RTC_UIE_OFF, 0); | |
1da177e4 | 306 | if (retval == -1) { |
2b1cd4c4 | 307 | perror("RTC_UIE_OFF ioctl"); |
1da177e4 LT |
308 | exit(errno); |
309 | } | |
7531d8fa DB |
310 | |
311 | test_READ: | |
312 | /* Read the RTC time/date */ | |
313 | retval = ioctl(fd, RTC_RD_TIME, &rtc_tm); | |
1da177e4 | 314 | if (retval == -1) { |
2b1cd4c4 | 315 | perror("RTC_RD_TIME ioctl"); |
1da177e4 LT |
316 | exit(errno); |
317 | } | |
1da177e4 | 318 | |
7531d8fa DB |
319 | fprintf(stderr, "\n\nCurrent RTC date/time is %d-%d-%d, %02d:%02d:%02d.\n", |
320 | rtc_tm.tm_mday, rtc_tm.tm_mon + 1, rtc_tm.tm_year + 1900, | |
321 | rtc_tm.tm_hour, rtc_tm.tm_min, rtc_tm.tm_sec); | |
1da177e4 | 322 | |
7531d8fa DB |
323 | /* Set the alarm to 5 sec in the future, and check for rollover */ |
324 | rtc_tm.tm_sec += 5; | |
325 | if (rtc_tm.tm_sec >= 60) { | |
326 | rtc_tm.tm_sec %= 60; | |
327 | rtc_tm.tm_min++; | |
328 | } | |
8696e702 | 329 | if (rtc_tm.tm_min == 60) { |
7531d8fa DB |
330 | rtc_tm.tm_min = 0; |
331 | rtc_tm.tm_hour++; | |
332 | } | |
8696e702 | 333 | if (rtc_tm.tm_hour == 24) |
7531d8fa | 334 | rtc_tm.tm_hour = 0; |
1da177e4 | 335 | |
7531d8fa DB |
336 | retval = ioctl(fd, RTC_ALM_SET, &rtc_tm); |
337 | if (retval == -1) { | |
338 | if (errno == ENOTTY) { | |
339 | fprintf(stderr, | |
340 | "\n...Alarm IRQs not supported.\n"); | |
341 | goto test_PIE; | |
342 | } | |
2b1cd4c4 | 343 | perror("RTC_ALM_SET ioctl"); |
7531d8fa DB |
344 | exit(errno); |
345 | } | |
1da177e4 | 346 | |
7531d8fa DB |
347 | /* Read the current alarm settings */ |
348 | retval = ioctl(fd, RTC_ALM_READ, &rtc_tm); | |
349 | if (retval == -1) { | |
2b1cd4c4 | 350 | perror("RTC_ALM_READ ioctl"); |
7531d8fa DB |
351 | exit(errno); |
352 | } | |
1da177e4 | 353 | |
7531d8fa DB |
354 | fprintf(stderr, "Alarm time now set to %02d:%02d:%02d.\n", |
355 | rtc_tm.tm_hour, rtc_tm.tm_min, rtc_tm.tm_sec); | |
1da177e4 | 356 | |
7531d8fa DB |
357 | /* Enable alarm interrupts */ |
358 | retval = ioctl(fd, RTC_AIE_ON, 0); | |
1da177e4 | 359 | if (retval == -1) { |
2b1cd4c4 | 360 | perror("RTC_AIE_ON ioctl"); |
1da177e4 LT |
361 | exit(errno); |
362 | } | |
363 | ||
7531d8fa | 364 | fprintf(stderr, "Waiting 5 seconds for alarm..."); |
1da177e4 | 365 | fflush(stderr); |
7531d8fa DB |
366 | /* This blocks until the alarm ring causes an interrupt */ |
367 | retval = read(fd, &data, sizeof(unsigned long)); | |
368 | if (retval == -1) { | |
369 | perror("read"); | |
370 | exit(errno); | |
371 | } | |
372 | irqcount++; | |
373 | fprintf(stderr, " okay. Alarm rang.\n"); | |
1da177e4 | 374 | |
7531d8fa DB |
375 | /* Disable alarm interrupts */ |
376 | retval = ioctl(fd, RTC_AIE_OFF, 0); | |
1da177e4 | 377 | if (retval == -1) { |
2b1cd4c4 | 378 | perror("RTC_AIE_OFF ioctl"); |
1da177e4 LT |
379 | exit(errno); |
380 | } | |
381 | ||
7531d8fa DB |
382 | test_PIE: |
383 | /* Read periodic IRQ rate */ | |
384 | retval = ioctl(fd, RTC_IRQP_READ, &tmp); | |
385 | if (retval == -1) { | |
386 | /* not all RTCs support periodic IRQs */ | |
387 | if (errno == ENOTTY) { | |
388 | fprintf(stderr, "\nNo periodic IRQ support\n"); | |
7a39a49c | 389 | goto done; |
7531d8fa | 390 | } |
2b1cd4c4 | 391 | perror("RTC_IRQP_READ ioctl"); |
7531d8fa DB |
392 | exit(errno); |
393 | } | |
394 | fprintf(stderr, "\nPeriodic IRQ rate is %ldHz.\n", tmp); | |
395 | ||
396 | fprintf(stderr, "Counting 20 interrupts at:"); | |
397 | fflush(stderr); | |
398 | ||
399 | /* The frequencies 128Hz, 256Hz, ... 8192Hz are only allowed for root. */ | |
400 | for (tmp=2; tmp<=64; tmp*=2) { | |
401 | ||
402 | retval = ioctl(fd, RTC_IRQP_SET, tmp); | |
1da177e4 | 403 | if (retval == -1) { |
7531d8fa DB |
404 | /* not all RTCs can change their periodic IRQ rate */ |
405 | if (errno == ENOTTY) { | |
406 | fprintf(stderr, | |
407 | "\n...Periodic IRQ rate is fixed\n"); | |
408 | goto done; | |
409 | } | |
8696e702 MF |
410 | perror("RTC_IRQP_SET ioctl"); |
411 | exit(errno); | |
1da177e4 | 412 | } |
7531d8fa DB |
413 | |
414 | fprintf(stderr, "\n%ldHz:\t", tmp); | |
1da177e4 | 415 | fflush(stderr); |
1da177e4 | 416 | |
7531d8fa DB |
417 | /* Enable periodic interrupts */ |
418 | retval = ioctl(fd, RTC_PIE_ON, 0); | |
419 | if (retval == -1) { | |
8696e702 MF |
420 | perror("RTC_PIE_ON ioctl"); |
421 | exit(errno); | |
7531d8fa DB |
422 | } |
423 | ||
424 | for (i=1; i<21; i++) { | |
8696e702 MF |
425 | /* This blocks */ |
426 | retval = read(fd, &data, sizeof(unsigned long)); | |
427 | if (retval == -1) { | |
428 | perror("read"); | |
429 | exit(errno); | |
430 | } | |
431 | fprintf(stderr, " %d",i); | |
432 | fflush(stderr); | |
433 | irqcount++; | |
7531d8fa DB |
434 | } |
435 | ||
436 | /* Disable periodic interrupts */ | |
437 | retval = ioctl(fd, RTC_PIE_OFF, 0); | |
438 | if (retval == -1) { | |
8696e702 MF |
439 | perror("RTC_PIE_OFF ioctl"); |
440 | exit(errno); | |
7531d8fa | 441 | } |
1da177e4 | 442 | } |
1da177e4 | 443 | |
7531d8fa DB |
444 | done: |
445 | fprintf(stderr, "\n\n\t\t\t *** Test complete ***\n"); | |
1da177e4 | 446 | |
7531d8fa | 447 | close(fd); |
1da177e4 | 448 | |
7531d8fa DB |
449 | return 0; |
450 | } |