diff options
Diffstat (limited to 'Documentation/rtc.txt')
| -rw-r--r-- | Documentation/rtc.txt | 282 |
1 files changed, 282 insertions, 0 deletions
diff --git a/Documentation/rtc.txt b/Documentation/rtc.txt new file mode 100644 index 00000000000..95d17b3e2ee --- /dev/null +++ b/Documentation/rtc.txt @@ -0,0 +1,282 @@ + + 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 */ |