| Real Time Clock Driver for Linux | |
| ================================ | |
| 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. | |
| 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. 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. | |
| Paul Gortmaker | |
| -------------------- 8< ---------------- 8< ----------------------------- | |
| /* | |
| * Real Time Clock Driver Test/Example Program | |
| * | |
| * Compile with: | |
| * gcc -s -Wall -Wstrict-prototypes rtctest.c -o rtctest | |
| * | |
| * Copyright (C) 1996, Paul Gortmaker. | |
| * | |
| * Released under the GNU General Public License, version 2, | |
| * included herein by reference. | |
| * | |
| */ | |
| #include <stdio.h> | |
| #include <linux/rtc.h> | |
| #include <sys/ioctl.h> | |
| #include <sys/time.h> | |
| #include <sys/types.h> | |
| #include <fcntl.h> | |
| #include <unistd.h> | |
| #include <errno.h> | |
| int main(void) { | |
| int i, fd, retval, irqcount = 0; | |
| unsigned long tmp, data; | |
| struct rtc_time rtc_tm; | |
| fd = open ("/dev/rtc", O_RDONLY); | |
| if (fd == -1) { | |
| perror("/dev/rtc"); | |
| exit(errno); | |
| } | |
| fprintf(stderr, "\n\t\t\tRTC Driver Test Example.\n\n"); | |
| /* Turn on update interrupts (one per second) */ | |
| retval = ioctl(fd, RTC_UIE_ON, 0); | |
| if (retval == -1) { | |
| perror("ioctl"); | |
| exit(errno); | |
| } | |
| fprintf(stderr, "Counting 5 update (1/sec) interrupts from reading /dev/rtc:"); | |
| fflush(stderr); | |
| for (i=1; i<6; i++) { | |
| /* This read will block */ | |
| retval = read(fd, &data, sizeof(unsigned long)); | |
| if (retval == -1) { | |
| perror("read"); | |
| exit(errno); | |
| } | |
| fprintf(stderr, " %d",i); | |
| fflush(stderr); | |
| irqcount++; | |
| } | |
| fprintf(stderr, "\nAgain, from using select(2) on /dev/rtc:"); | |
| fflush(stderr); | |
| for (i=1; i<6; i++) { | |
| struct timeval tv = {5, 0}; /* 5 second timeout on select */ | |
| fd_set readfds; | |
| FD_ZERO(&readfds); | |
| FD_SET(fd, &readfds); | |
| /* The select will wait until an RTC interrupt happens. */ | |
| retval = select(fd+1, &readfds, NULL, NULL, &tv); | |
| if (retval == -1) { | |
| perror("select"); | |
| exit(errno); | |
| } | |
| /* This read won't block unlike the select-less case above. */ | |
| retval = read(fd, &data, sizeof(unsigned long)); | |
| if (retval == -1) { | |
| perror("read"); | |
| exit(errno); | |
| } | |
| fprintf(stderr, " %d",i); | |
| fflush(stderr); | |
| irqcount++; | |
| } | |
| /* Turn off update interrupts */ | |
| retval = ioctl(fd, RTC_UIE_OFF, 0); | |
| if (retval == -1) { | |
| perror("ioctl"); | |
| exit(errno); | |
| } | |
| /* Read the RTC time/date */ | |
| retval = ioctl(fd, RTC_RD_TIME, &rtc_tm); | |
| if (retval == -1) { | |
| perror("ioctl"); | |
| exit(errno); | |
| } | |
| fprintf(stderr, "\n\nCurrent RTC date/time is %d-%d-%d, %02d:%02d:%02d.\n", | |
| rtc_tm.tm_mday, rtc_tm.tm_mon + 1, rtc_tm.tm_year + 1900, | |
| rtc_tm.tm_hour, rtc_tm.tm_min, rtc_tm.tm_sec); | |
| /* Set the alarm to 5 sec in the future, and check for rollover */ | |
| rtc_tm.tm_sec += 5; | |
| if (rtc_tm.tm_sec >= 60) { | |
| rtc_tm.tm_sec %= 60; | |
| rtc_tm.tm_min++; | |
| } | |
| if (rtc_tm.tm_min == 60) { | |
| rtc_tm.tm_min = 0; | |
| rtc_tm.tm_hour++; | |
| } | |
| if (rtc_tm.tm_hour == 24) | |
| rtc_tm.tm_hour = 0; | |
| retval = ioctl(fd, RTC_ALM_SET, &rtc_tm); | |
| if (retval == -1) { | |
| perror("ioctl"); | |
| exit(errno); | |
| } | |
| /* Read the current alarm settings */ | |
| retval = ioctl(fd, RTC_ALM_READ, &rtc_tm); | |
| if (retval == -1) { | |
| perror("ioctl"); | |
| exit(errno); | |
| } | |
| fprintf(stderr, "Alarm time now set to %02d:%02d:%02d.\n", | |
| rtc_tm.tm_hour, rtc_tm.tm_min, rtc_tm.tm_sec); | |
| /* Enable alarm interrupts */ | |
| retval = ioctl(fd, RTC_AIE_ON, 0); | |
| if (retval == -1) { | |
| perror("ioctl"); | |
| exit(errno); | |
| } | |
| fprintf(stderr, "Waiting 5 seconds for alarm..."); | |
| fflush(stderr); | |
| /* This blocks until the alarm ring causes an interrupt */ | |
| retval = read(fd, &data, sizeof(unsigned long)); | |
| if (retval == -1) { | |
| perror("read"); | |
| exit(errno); | |
| } | |
| irqcount++; | |
| fprintf(stderr, " okay. Alarm rang.\n"); | |
| /* Disable alarm interrupts */ | |
| retval = ioctl(fd, RTC_AIE_OFF, 0); | |
| if (retval == -1) { | |
| perror("ioctl"); | |
| exit(errno); | |
| } | |
| /* Read periodic IRQ rate */ | |
| retval = ioctl(fd, RTC_IRQP_READ, &tmp); | |
| if (retval == -1) { | |
| perror("ioctl"); | |
| exit(errno); | |
| } | |
| fprintf(stderr, "\nPeriodic IRQ rate was %ldHz.\n", tmp); | |
| fprintf(stderr, "Counting 20 interrupts at:"); | |
| fflush(stderr); | |
| /* The frequencies 128Hz, 256Hz, ... 8192Hz are only allowed for root. */ | |
| for (tmp=2; tmp<=64; tmp*=2) { | |
| retval = ioctl(fd, RTC_IRQP_SET, tmp); | |
| if (retval == -1) { | |
| perror("ioctl"); | |
| exit(errno); | |
| } | |
| fprintf(stderr, "\n%ldHz:\t", tmp); | |
| fflush(stderr); | |
| /* Enable periodic interrupts */ | |
| retval = ioctl(fd, RTC_PIE_ON, 0); | |
| if (retval == -1) { | |
| perror("ioctl"); | |
| exit(errno); | |
| } | |
| for (i=1; i<21; i++) { | |
| /* This blocks */ | |
| retval = read(fd, &data, sizeof(unsigned long)); | |
| if (retval == -1) { | |
| perror("read"); | |
| exit(errno); | |
| } | |
| fprintf(stderr, " %d",i); | |
| fflush(stderr); | |
| irqcount++; | |
| } | |
| /* Disable periodic interrupts */ | |
| retval = ioctl(fd, RTC_PIE_OFF, 0); | |
| if (retval == -1) { | |
| perror("ioctl"); | |
| exit(errno); | |
| } | |
| } | |
| fprintf(stderr, "\n\n\t\t\t *** Test complete ***\n"); | |
| fprintf(stderr, "\nTyping \"cat /proc/interrupts\" will show %d more events on IRQ 8.\n\n", | |
| irqcount); | |
| close(fd); | |
| return 0; | |
| } /* end main */ |