Commit | Line | Data |
---|---|---|
1da177e4 LT |
1 | |
2 | Real Time Clock Driver for Linux | |
3 | ================================ | |
4 | ||
5 | All PCs (even Alpha machines) have a Real Time Clock built into them. | |
6 | Usually they are built into the chipset of the computer, but some may | |
7 | actually have a Motorola MC146818 (or clone) on the board. This is the | |
8 | clock that keeps the date and time while your computer is turned off. | |
9 | ||
10 | However it can also be used to generate signals from a slow 2Hz to a | |
11 | relatively fast 8192Hz, in increments of powers of two. These signals | |
12 | are reported by interrupt number 8. (Oh! So *that* is what IRQ 8 is | |
13 | for...) It can also function as a 24hr alarm, raising IRQ 8 when the | |
14 | alarm goes off. The alarm can also be programmed to only check any | |
15 | subset of the three programmable values, meaning that it could be set to | |
16 | ring on the 30th second of the 30th minute of every hour, for example. | |
17 | The clock can also be set to generate an interrupt upon every clock | |
18 | update, thus generating a 1Hz signal. | |
19 | ||
20 | The interrupts are reported via /dev/rtc (major 10, minor 135, read only | |
21 | character device) in the form of an unsigned long. The low byte contains | |
22 | the type of interrupt (update-done, alarm-rang, or periodic) that was | |
23 | raised, and the remaining bytes contain the number of interrupts since | |
24 | the last read. Status information is reported through the pseudo-file | |
25 | /proc/driver/rtc if the /proc filesystem was enabled. The driver has | |
26 | built in locking so that only one process is allowed to have the /dev/rtc | |
27 | interface open at a time. | |
28 | ||
29 | A user process can monitor these interrupts by doing a read(2) or a | |
30 | select(2) on /dev/rtc -- either will block/stop the user process until | |
31 | the next interrupt is received. This is useful for things like | |
32 | reasonably high frequency data acquisition where one doesn't want to | |
33 | burn up 100% CPU by polling gettimeofday etc. etc. | |
34 | ||
35 | At high frequencies, or under high loads, the user process should check | |
36 | the number of interrupts received since the last read to determine if | |
37 | there has been any interrupt "pileup" so to speak. Just for reference, a | |
38 | typical 486-33 running a tight read loop on /dev/rtc will start to suffer | |
39 | occasional interrupt pileup (i.e. > 1 IRQ event since last read) for | |
40 | frequencies above 1024Hz. So you really should check the high bytes | |
41 | of the value you read, especially at frequencies above that of the | |
42 | normal timer interrupt, which is 100Hz. | |
43 | ||
44 | Programming and/or enabling interrupt frequencies greater than 64Hz is | |
45 | only allowed by root. This is perhaps a bit conservative, but we don't want | |
46 | an evil user generating lots of IRQs on a slow 386sx-16, where it might have | |
9be05b57 JD |
47 | a negative impact on performance. This 64Hz limit can be changed by writing |
48 | a different value to /proc/sys/dev/rtc/max-user-freq. Note that the | |
49 | interrupt handler is only a few lines of code to minimize any possibility | |
50 | of this effect. | |
1da177e4 LT |
51 | |
52 | Also, if the kernel time is synchronized with an external source, the | |
53 | kernel will write the time back to the CMOS clock every 11 minutes. In | |
54 | the process of doing this, the kernel briefly turns off RTC periodic | |
55 | interrupts, so be aware of this if you are doing serious work. If you | |
56 | don't synchronize the kernel time with an external source (via ntp or | |
57 | whatever) then the kernel will keep its hands off the RTC, allowing you | |
58 | exclusive access to the device for your applications. | |
59 | ||
60 | The alarm and/or interrupt frequency are programmed into the RTC via | |
61 | various ioctl(2) calls as listed in ./include/linux/rtc.h | |
62 | Rather than write 50 pages describing the ioctl() and so on, it is | |
63 | perhaps more useful to include a small test program that demonstrates | |
64 | how to use them, and demonstrates the features of the driver. This is | |
65 | probably a lot more useful to people interested in writing applications | |
66 | that will be using this driver. | |
67 | ||
68 | Paul Gortmaker | |
69 | ||
70 | -------------------- 8< ---------------- 8< ----------------------------- | |
71 | ||
72 | /* | |
73 | * Real Time Clock Driver Test/Example Program | |
74 | * | |
75 | * Compile with: | |
76 | * gcc -s -Wall -Wstrict-prototypes rtctest.c -o rtctest | |
77 | * | |
78 | * Copyright (C) 1996, Paul Gortmaker. | |
79 | * | |
80 | * Released under the GNU General Public License, version 2, | |
81 | * included herein by reference. | |
82 | * | |
83 | */ | |
84 | ||
85 | #include <stdio.h> | |
9be05b57 | 86 | #include <stdlib.h> |
1da177e4 LT |
87 | #include <linux/rtc.h> |
88 | #include <sys/ioctl.h> | |
89 | #include <sys/time.h> | |
90 | #include <sys/types.h> | |
91 | #include <fcntl.h> | |
92 | #include <unistd.h> | |
93 | #include <errno.h> | |
94 | ||
95 | int main(void) { | |
96 | ||
97 | int i, fd, retval, irqcount = 0; | |
98 | unsigned long tmp, data; | |
99 | struct rtc_time rtc_tm; | |
100 | ||
101 | fd = open ("/dev/rtc", O_RDONLY); | |
102 | ||
103 | if (fd == -1) { | |
104 | perror("/dev/rtc"); | |
105 | exit(errno); | |
106 | } | |
107 | ||
108 | fprintf(stderr, "\n\t\t\tRTC Driver Test Example.\n\n"); | |
109 | ||
110 | /* Turn on update interrupts (one per second) */ | |
111 | retval = ioctl(fd, RTC_UIE_ON, 0); | |
112 | if (retval == -1) { | |
113 | perror("ioctl"); | |
114 | exit(errno); | |
115 | } | |
116 | ||
117 | fprintf(stderr, "Counting 5 update (1/sec) interrupts from reading /dev/rtc:"); | |
118 | fflush(stderr); | |
119 | for (i=1; i<6; i++) { | |
120 | /* This read will block */ | |
121 | retval = read(fd, &data, sizeof(unsigned long)); | |
122 | if (retval == -1) { | |
123 | perror("read"); | |
124 | exit(errno); | |
125 | } | |
126 | fprintf(stderr, " %d",i); | |
127 | fflush(stderr); | |
128 | irqcount++; | |
129 | } | |
130 | ||
131 | fprintf(stderr, "\nAgain, from using select(2) on /dev/rtc:"); | |
132 | fflush(stderr); | |
133 | for (i=1; i<6; i++) { | |
134 | struct timeval tv = {5, 0}; /* 5 second timeout on select */ | |
135 | fd_set readfds; | |
136 | ||
137 | FD_ZERO(&readfds); | |
138 | FD_SET(fd, &readfds); | |
139 | /* The select will wait until an RTC interrupt happens. */ | |
140 | retval = select(fd+1, &readfds, NULL, NULL, &tv); | |
141 | if (retval == -1) { | |
142 | perror("select"); | |
143 | exit(errno); | |
144 | } | |
145 | /* This read won't block unlike the select-less case above. */ | |
146 | retval = read(fd, &data, sizeof(unsigned long)); | |
147 | if (retval == -1) { | |
148 | perror("read"); | |
149 | exit(errno); | |
150 | } | |
151 | fprintf(stderr, " %d",i); | |
152 | fflush(stderr); | |
153 | irqcount++; | |
154 | } | |
155 | ||
156 | /* Turn off update interrupts */ | |
157 | retval = ioctl(fd, RTC_UIE_OFF, 0); | |
158 | if (retval == -1) { | |
159 | perror("ioctl"); | |
160 | exit(errno); | |
161 | } | |
162 | ||
163 | /* Read the RTC time/date */ | |
164 | retval = ioctl(fd, RTC_RD_TIME, &rtc_tm); | |
165 | if (retval == -1) { | |
166 | perror("ioctl"); | |
167 | exit(errno); | |
168 | } | |
169 | ||
170 | fprintf(stderr, "\n\nCurrent RTC date/time is %d-%d-%d, %02d:%02d:%02d.\n", | |
171 | rtc_tm.tm_mday, rtc_tm.tm_mon + 1, rtc_tm.tm_year + 1900, | |
172 | rtc_tm.tm_hour, rtc_tm.tm_min, rtc_tm.tm_sec); | |
173 | ||
174 | /* Set the alarm to 5 sec in the future, and check for rollover */ | |
175 | rtc_tm.tm_sec += 5; | |
176 | if (rtc_tm.tm_sec >= 60) { | |
177 | rtc_tm.tm_sec %= 60; | |
178 | rtc_tm.tm_min++; | |
179 | } | |
180 | if (rtc_tm.tm_min == 60) { | |
181 | rtc_tm.tm_min = 0; | |
182 | rtc_tm.tm_hour++; | |
183 | } | |
184 | if (rtc_tm.tm_hour == 24) | |
185 | rtc_tm.tm_hour = 0; | |
186 | ||
187 | retval = ioctl(fd, RTC_ALM_SET, &rtc_tm); | |
188 | if (retval == -1) { | |
189 | perror("ioctl"); | |
190 | exit(errno); | |
191 | } | |
192 | ||
193 | /* Read the current alarm settings */ | |
194 | retval = ioctl(fd, RTC_ALM_READ, &rtc_tm); | |
195 | if (retval == -1) { | |
196 | perror("ioctl"); | |
197 | exit(errno); | |
198 | } | |
199 | ||
200 | fprintf(stderr, "Alarm time now set to %02d:%02d:%02d.\n", | |
201 | rtc_tm.tm_hour, rtc_tm.tm_min, rtc_tm.tm_sec); | |
202 | ||
203 | /* Enable alarm interrupts */ | |
204 | retval = ioctl(fd, RTC_AIE_ON, 0); | |
205 | if (retval == -1) { | |
206 | perror("ioctl"); | |
207 | exit(errno); | |
208 | } | |
209 | ||
210 | fprintf(stderr, "Waiting 5 seconds for alarm..."); | |
211 | fflush(stderr); | |
212 | /* This blocks until the alarm ring causes an interrupt */ | |
213 | retval = read(fd, &data, sizeof(unsigned long)); | |
214 | if (retval == -1) { | |
215 | perror("read"); | |
216 | exit(errno); | |
217 | } | |
218 | irqcount++; | |
219 | fprintf(stderr, " okay. Alarm rang.\n"); | |
220 | ||
221 | /* Disable alarm interrupts */ | |
222 | retval = ioctl(fd, RTC_AIE_OFF, 0); | |
223 | if (retval == -1) { | |
224 | perror("ioctl"); | |
225 | exit(errno); | |
226 | } | |
227 | ||
228 | /* Read periodic IRQ rate */ | |
229 | retval = ioctl(fd, RTC_IRQP_READ, &tmp); | |
230 | if (retval == -1) { | |
231 | perror("ioctl"); | |
232 | exit(errno); | |
233 | } | |
234 | fprintf(stderr, "\nPeriodic IRQ rate was %ldHz.\n", tmp); | |
235 | ||
236 | fprintf(stderr, "Counting 20 interrupts at:"); | |
237 | fflush(stderr); | |
238 | ||
239 | /* The frequencies 128Hz, 256Hz, ... 8192Hz are only allowed for root. */ | |
240 | for (tmp=2; tmp<=64; tmp*=2) { | |
241 | ||
242 | retval = ioctl(fd, RTC_IRQP_SET, tmp); | |
243 | if (retval == -1) { | |
244 | perror("ioctl"); | |
245 | exit(errno); | |
246 | } | |
247 | ||
248 | fprintf(stderr, "\n%ldHz:\t", tmp); | |
249 | fflush(stderr); | |
250 | ||
251 | /* Enable periodic interrupts */ | |
252 | retval = ioctl(fd, RTC_PIE_ON, 0); | |
253 | if (retval == -1) { | |
254 | perror("ioctl"); | |
255 | exit(errno); | |
256 | } | |
257 | ||
258 | for (i=1; i<21; i++) { | |
259 | /* This blocks */ | |
260 | retval = read(fd, &data, sizeof(unsigned long)); | |
261 | if (retval == -1) { | |
262 | perror("read"); | |
263 | exit(errno); | |
264 | } | |
265 | fprintf(stderr, " %d",i); | |
266 | fflush(stderr); | |
267 | irqcount++; | |
268 | } | |
269 | ||
270 | /* Disable periodic interrupts */ | |
271 | retval = ioctl(fd, RTC_PIE_OFF, 0); | |
272 | if (retval == -1) { | |
273 | perror("ioctl"); | |
274 | exit(errno); | |
275 | } | |
276 | } | |
277 | ||
278 | fprintf(stderr, "\n\n\t\t\t *** Test complete ***\n"); | |
279 | fprintf(stderr, "\nTyping \"cat /proc/interrupts\" will show %d more events on IRQ 8.\n\n", | |
280 | irqcount); | |
281 | ||
282 | close(fd); | |
283 | return 0; | |
284 | ||
285 | } /* end main */ |