|
|
Real Time Clock Driver for Linux
|
Real Time Clock Driver for Linux
|
================================
|
================================
|
|
|
All PCs (even Alpha machines) have a Real Time Clock built into them.
|
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
|
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
|
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.
|
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
|
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
|
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
|
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
|
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
|
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
|
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.
|
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
|
The clock can also be set to generate an interrupt upon every clock
|
update, thus generating a 1Hz signal.
|
update, thus generating a 1Hz signal.
|
|
|
The interrupts are reported via /dev/rtc (major 10, minor 135, read only
|
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
|
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
|
the type of interrupt (update-done, alarm-rang, or periodic) that was
|
raised, and the remaining bytes contain the number of interrupts since
|
raised, and the remaining bytes contain the number of interrupts since
|
the last read. Status information is reported through the pseudo-file
|
the last read. Status information is reported through the pseudo-file
|
/proc/rtc if the /proc filesystem was enabled. The driver has built in
|
/proc/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
|
locking so that only one process is allowed to have the /dev/rtc
|
interface open at a time.
|
interface open at a time.
|
|
|
A user process can monitor these interrupts by doing a read(2) or a
|
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
|
select(2) on /dev/rtc -- either will block/stop the user process until
|
the next interrupt is received. This is useful for things like
|
the next interrupt is received. This is useful for things like
|
reasonably high frequency data acquisition where one doesn't want to
|
reasonably high frequency data acquisition where one doesn't want to
|
burn up 100% CPU by polling gettimeofday etc. etc.
|
burn up 100% CPU by polling gettimeofday etc. etc.
|
|
|
At high frequencies, or under high loads, the user process should check
|
At high frequencies, or under high loads, the user process should check
|
the number of interrupts received since the last read to determine if
|
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
|
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
|
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
|
occasional interrupt pileup (i.e. > 1 IRQ event since last read) for
|
frequencies above 1024Hz. So you really should check the high bytes
|
frequencies above 1024Hz. So you really should check the high bytes
|
of the value you read, especially at frequencies above that of the
|
of the value you read, especially at frequencies above that of the
|
normal timer interrupt, which is 100Hz.
|
normal timer interrupt, which is 100Hz.
|
|
|
Programming and/or enabling interrupt frequencies greater than 64Hz is
|
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
|
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
|
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 negative impact on performance. Note that the interrupt handler is only
|
a few lines of code to minimize any possibility of this effect.
|
a few lines of code to minimize any possibility of this effect.
|
|
|
Also, if the kernel time is synchronized with an external source, the
|
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
|
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
|
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
|
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
|
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
|
whatever) then the kernel will keep its hands off the RTC, allowing you
|
exclusive access to the device for your applications.
|
exclusive access to the device for your applications.
|
|
|
The alarm and/or interrupt frequency are programmed into the RTC via
|
The alarm and/or interrupt frequency are programmed into the RTC via
|
various ioctl(2) calls as listed in ./include/linux/mc146818rtc.h
|
various ioctl(2) calls as listed in ./include/linux/mc146818rtc.h
|
Rather than write 50 pages describing the ioctl() and so on, it is
|
Rather than write 50 pages describing the ioctl() and so on, it is
|
perhaps more useful to include a small test program that demonstrates
|
perhaps more useful to include a small test program that demonstrates
|
how to use them, and demonstrates the features of the driver. This is
|
how to use them, and demonstrates the features of the driver. This is
|
probably a lot more useful to people interested in writing applications
|
probably a lot more useful to people interested in writing applications
|
that will be using this driver.
|
that will be using this driver.
|
|
|
Paul Gortmaker
|
Paul Gortmaker
|
|
|
Update in version 1.09
|
Update in version 1.09
|
======================
|
======================
|
|
|
Epoch handling is added. Epoch is the number which should be added to the
|
Epoch handling is added. Epoch is the number which should be added to the
|
value of the clock's year register to get the actual year. The default
|
value of the clock's year register to get the actual year. The default
|
Linux epoch is therefore 1900.
|
Linux epoch is therefore 1900.
|
|
|
Epochs are especially useful on Alphas where different operating systems
|
Epochs are especially useful on Alphas where different operating systems
|
use different epochs, and Linux wants to be compatible with all of them.
|
use different epochs, and Linux wants to be compatible with all of them.
|
They may eventually be helpful on Intel architecture as well, where a
|
They may eventually be helpful on Intel architecture as well, where a
|
value of an RTC register cannot exceed 99 due to BCD tradition originated
|
value of an RTC register cannot exceed 99 due to BCD tradition originated
|
from DOS.
|
from DOS.
|
|
|
When the epoch is set to 1900, the new code behaves exactly like the old
|
When the epoch is set to 1900, the new code behaves exactly like the old
|
one with respect to the BCD wrapping: values 00 - 69 are treated as if
|
one with respect to the BCD wrapping: values 00 - 69 are treated as if
|
they were 100 - 169. That means that after the 2000th year epoch 1900
|
they were 100 - 169. That means that after the 2000th year epoch 1900
|
will be the same as epoch 2000.
|
will be the same as epoch 2000.
|
|
|
Two new ioctls are introduced to read and set the epoch, RTC_EPOCH_READ
|
Two new ioctls are introduced to read and set the epoch, RTC_EPOCH_READ
|
and RTC_EPOCH_SET. They can be used in exactly the same manner as
|
and RTC_EPOCH_SET. They can be used in exactly the same manner as
|
RTC_IRQP_READ and RTC_IRQP_SET, so they are not included in the example
|
RTC_IRQP_READ and RTC_IRQP_SET, so they are not included in the example
|
program below.
|
program below.
|
|
|
On Alphas an epoch autodetection is performed. Currently 3 epochs
|
On Alphas an epoch autodetection is performed. Currently 3 epochs
|
are recognised: Linux (1900), Digital UNIX (1952) and Windows NT (1980).
|
are recognised: Linux (1900), Digital UNIX (1952) and Windows NT (1980).
|
|
|
Nikita Schmidt
|
Nikita Schmidt
|
|
|
|
|
-------------------- 8< ---------------- 8< -----------------------------
|
-------------------- 8< ---------------- 8< -----------------------------
|
|
|
/*
|
/*
|
* Real Time Clock Driver Test/Example Program
|
* Real Time Clock Driver Test/Example Program
|
*
|
*
|
* Compile with:
|
* Compile with:
|
* gcc -s -Wall -Wstrict-prototypes rtctest.c -o rtctest
|
* gcc -s -Wall -Wstrict-prototypes rtctest.c -o rtctest
|
*
|
*
|
* Copyright (C) 1996, Paul Gortmaker.
|
* Copyright (C) 1996, Paul Gortmaker.
|
*
|
*
|
* Released under the GNU General Public License, version 2,
|
* Released under the GNU General Public License, version 2,
|
* included herein by reference.
|
* included herein by reference.
|
*
|
*
|
*/
|
*/
|
|
|
#include
|
#include
|
#include
|
#include
|
#include
|
#include
|
#include
|
#include
|
#include
|
#include
|
#include
|
#include
|
#include
|
#include
|
#include
|
#include
|
|
|
void main(void) {
|
void main(void) {
|
|
|
int i, fd, retval, irqcount = 0;
|
int i, fd, retval, irqcount = 0;
|
unsigned long tmp, data;
|
unsigned long tmp, data;
|
struct rtc_time rtc_tm;
|
struct rtc_time rtc_tm;
|
|
|
fd = open ("/dev/rtc", O_RDONLY);
|
fd = open ("/dev/rtc", O_RDONLY);
|
|
|
if (fd == -1) {
|
if (fd == -1) {
|
perror("/dev/rtc");
|
perror("/dev/rtc");
|
exit(errno);
|
exit(errno);
|
}
|
}
|
|
|
fprintf(stderr, "\n\t\t\tRTC Driver Test Example.\n\n");
|
fprintf(stderr, "\n\t\t\tRTC Driver Test Example.\n\n");
|
|
|
/* Turn on update interrupts (one per second) */
|
/* Turn on update interrupts (one per second) */
|
retval = ioctl(fd, RTC_UIE_ON, 0);
|
retval = ioctl(fd, RTC_UIE_ON, 0);
|
if (retval == -1) {
|
if (retval == -1) {
|
perror("ioctl");
|
perror("ioctl");
|
exit(errno);
|
exit(errno);
|
}
|
}
|
|
|
fprintf(stderr, "Counting 5 update (1/sec) interrupts from reading /dev/rtc:");
|
fprintf(stderr, "Counting 5 update (1/sec) interrupts from reading /dev/rtc:");
|
fflush(stderr);
|
fflush(stderr);
|
for (i=1; i<6; i++) {
|
for (i=1; i<6; i++) {
|
/* This read will block */
|
/* This read will block */
|
retval = read(fd, &data, sizeof(unsigned long));
|
retval = read(fd, &data, sizeof(unsigned long));
|
if (retval == -1) {
|
if (retval == -1) {
|
perror("read");
|
perror("read");
|
exit(errno);
|
exit(errno);
|
}
|
}
|
fprintf(stderr, " %d",i);
|
fprintf(stderr, " %d",i);
|
fflush(stderr);
|
fflush(stderr);
|
irqcount++;
|
irqcount++;
|
}
|
}
|
|
|
fprintf(stderr, "\nAgain, from using select(2) on /dev/rtc:");
|
fprintf(stderr, "\nAgain, from using select(2) on /dev/rtc:");
|
fflush(stderr);
|
fflush(stderr);
|
for (i=1; i<6; i++) {
|
for (i=1; i<6; i++) {
|
struct timeval tv = {5, 0}; /* 5 second timeout on select */
|
struct timeval tv = {5, 0}; /* 5 second timeout on select */
|
fd_set readfds;
|
fd_set readfds;
|
|
|
FD_ZERO(&readfds);
|
FD_ZERO(&readfds);
|
FD_SET(fd, &readfds);
|
FD_SET(fd, &readfds);
|
/* The select will wait until an RTC interrupt happens. */
|
/* The select will wait until an RTC interrupt happens. */
|
retval = select(fd+1, &readfds, NULL, NULL, &tv);
|
retval = select(fd+1, &readfds, NULL, NULL, &tv);
|
if (retval == -1) {
|
if (retval == -1) {
|
perror("select");
|
perror("select");
|
exit(errno);
|
exit(errno);
|
}
|
}
|
/* This read won't block unlike the select-less case above. */
|
/* This read won't block unlike the select-less case above. */
|
retval = read(fd, &data, sizeof(unsigned long));
|
retval = read(fd, &data, sizeof(unsigned long));
|
if (retval == -1) {
|
if (retval == -1) {
|
perror("read");
|
perror("read");
|
exit(errno);
|
exit(errno);
|
}
|
}
|
fprintf(stderr, " %d",i);
|
fprintf(stderr, " %d",i);
|
fflush(stderr);
|
fflush(stderr);
|
irqcount++;
|
irqcount++;
|
}
|
}
|
|
|
/* Turn off update interrupts */
|
/* Turn off update interrupts */
|
retval = ioctl(fd, RTC_UIE_OFF, 0);
|
retval = ioctl(fd, RTC_UIE_OFF, 0);
|
if (retval == -1) {
|
if (retval == -1) {
|
perror("ioctl");
|
perror("ioctl");
|
exit(errno);
|
exit(errno);
|
}
|
}
|
|
|
/* Read the RTC time/date */
|
/* Read the RTC time/date */
|
retval = ioctl(fd, RTC_RD_TIME, &rtc_tm);
|
retval = ioctl(fd, RTC_RD_TIME, &rtc_tm);
|
if (retval == -1) {
|
if (retval == -1) {
|
perror("ioctl");
|
perror("ioctl");
|
exit(errno);
|
exit(errno);
|
}
|
}
|
|
|
fprintf(stderr, "\n\nCurrent RTC date/time is %d-%d-%d, %02d:%02d:%02d.\n",
|
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_mday, rtc_tm.tm_mon + 1, rtc_tm.tm_year + 1900,
|
rtc_tm.tm_hour, rtc_tm.tm_min, rtc_tm.tm_sec);
|
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 */
|
/* Set the alarm to 5 sec in the future, and check for rollover */
|
rtc_tm.tm_sec += 5;
|
rtc_tm.tm_sec += 5;
|
if (rtc_tm.tm_sec >= 60) {
|
if (rtc_tm.tm_sec >= 60) {
|
rtc_tm.tm_sec %= 60;
|
rtc_tm.tm_sec %= 60;
|
rtc_tm.tm_min++;
|
rtc_tm.tm_min++;
|
}
|
}
|
if (rtc_tm.tm_min == 60) {
|
if (rtc_tm.tm_min == 60) {
|
rtc_tm.tm_min = 0;
|
rtc_tm.tm_min = 0;
|
rtc_tm.tm_hour++;
|
rtc_tm.tm_hour++;
|
}
|
}
|
if (rtc_tm.tm_hour == 24)
|
if (rtc_tm.tm_hour == 24)
|
rtc_tm.tm_hour = 0;
|
rtc_tm.tm_hour = 0;
|
|
|
retval = ioctl(fd, RTC_ALM_SET, &rtc_tm);
|
retval = ioctl(fd, RTC_ALM_SET, &rtc_tm);
|
if (retval == -1) {
|
if (retval == -1) {
|
perror("ioctl");
|
perror("ioctl");
|
exit(errno);
|
exit(errno);
|
}
|
}
|
|
|
/* Read the current alarm settings */
|
/* Read the current alarm settings */
|
retval = ioctl(fd, RTC_ALM_READ, &rtc_tm);
|
retval = ioctl(fd, RTC_ALM_READ, &rtc_tm);
|
if (retval == -1) {
|
if (retval == -1) {
|
perror("ioctl");
|
perror("ioctl");
|
exit(errno);
|
exit(errno);
|
}
|
}
|
|
|
fprintf(stderr, "Alarm time now set to %02d:%02d:%02d.\n",
|
fprintf(stderr, "Alarm time now set to %02d:%02d:%02d.\n",
|
rtc_tm.tm_hour, rtc_tm.tm_min, rtc_tm.tm_sec);
|
rtc_tm.tm_hour, rtc_tm.tm_min, rtc_tm.tm_sec);
|
|
|
/* Enable alarm interrupts */
|
/* Enable alarm interrupts */
|
retval = ioctl(fd, RTC_AIE_ON, 0);
|
retval = ioctl(fd, RTC_AIE_ON, 0);
|
if (retval == -1) {
|
if (retval == -1) {
|
perror("ioctl");
|
perror("ioctl");
|
exit(errno);
|
exit(errno);
|
}
|
}
|
|
|
fprintf(stderr, "Waiting 5 seconds for alarm...");
|
fprintf(stderr, "Waiting 5 seconds for alarm...");
|
fflush(stderr);
|
fflush(stderr);
|
/* This blocks until the alarm ring causes an interrupt */
|
/* This blocks until the alarm ring causes an interrupt */
|
retval = read(fd, &data, sizeof(unsigned long));
|
retval = read(fd, &data, sizeof(unsigned long));
|
if (retval == -1) {
|
if (retval == -1) {
|
perror("read");
|
perror("read");
|
exit(errno);
|
exit(errno);
|
}
|
}
|
irqcount++;
|
irqcount++;
|
fprintf(stderr, " okay. Alarm rang.\n");
|
fprintf(stderr, " okay. Alarm rang.\n");
|
|
|
/* Disable alarm interrupts */
|
/* Disable alarm interrupts */
|
retval = ioctl(fd, RTC_AIE_OFF, 0);
|
retval = ioctl(fd, RTC_AIE_OFF, 0);
|
if (retval == -1) {
|
if (retval == -1) {
|
perror("ioctl");
|
perror("ioctl");
|
exit(errno);
|
exit(errno);
|
}
|
}
|
|
|
/* Read periodic IRQ rate */
|
/* Read periodic IRQ rate */
|
retval = ioctl(fd, RTC_IRQP_READ, &tmp);
|
retval = ioctl(fd, RTC_IRQP_READ, &tmp);
|
if (retval == -1) {
|
if (retval == -1) {
|
perror("ioctl");
|
perror("ioctl");
|
exit(errno);
|
exit(errno);
|
}
|
}
|
fprintf(stderr, "\nPeriodic IRQ rate was %ldHz.\n", tmp);
|
fprintf(stderr, "\nPeriodic IRQ rate was %ldHz.\n", tmp);
|
|
|
fprintf(stderr, "Counting 20 interrupts at:");
|
fprintf(stderr, "Counting 20 interrupts at:");
|
fflush(stderr);
|
fflush(stderr);
|
|
|
/* The frequencies 128Hz, 256Hz, ... 8192Hz are only allowed for root. */
|
/* The frequencies 128Hz, 256Hz, ... 8192Hz are only allowed for root. */
|
for (tmp=2; tmp<=64; tmp*=2) {
|
for (tmp=2; tmp<=64; tmp*=2) {
|
|
|
retval = ioctl(fd, RTC_IRQP_SET, tmp);
|
retval = ioctl(fd, RTC_IRQP_SET, tmp);
|
if (retval == -1) {
|
if (retval == -1) {
|
perror("ioctl");
|
perror("ioctl");
|
exit(errno);
|
exit(errno);
|
}
|
}
|
|
|
fprintf(stderr, "\n%ldHz:\t", tmp);
|
fprintf(stderr, "\n%ldHz:\t", tmp);
|
fflush(stderr);
|
fflush(stderr);
|
|
|
/* Enable periodic interrupts */
|
/* Enable periodic interrupts */
|
retval = ioctl(fd, RTC_PIE_ON, 0);
|
retval = ioctl(fd, RTC_PIE_ON, 0);
|
if (retval == -1) {
|
if (retval == -1) {
|
perror("ioctl");
|
perror("ioctl");
|
exit(errno);
|
exit(errno);
|
}
|
}
|
|
|
for (i=1; i<21; i++) {
|
for (i=1; i<21; i++) {
|
/* This blocks */
|
/* This blocks */
|
retval = read(fd, &data, sizeof(unsigned long));
|
retval = read(fd, &data, sizeof(unsigned long));
|
if (retval == -1) {
|
if (retval == -1) {
|
perror("read");
|
perror("read");
|
exit(errno);
|
exit(errno);
|
}
|
}
|
fprintf(stderr, " %d",i);
|
fprintf(stderr, " %d",i);
|
fflush(stderr);
|
fflush(stderr);
|
irqcount++;
|
irqcount++;
|
}
|
}
|
|
|
/* Disable periodic interrupts */
|
/* Disable periodic interrupts */
|
retval = ioctl(fd, RTC_PIE_OFF, 0);
|
retval = ioctl(fd, RTC_PIE_OFF, 0);
|
if (retval == -1) {
|
if (retval == -1) {
|
perror("ioctl");
|
perror("ioctl");
|
exit(errno);
|
exit(errno);
|
}
|
}
|
}
|
}
|
|
|
fprintf(stderr, "\n\n\t\t\t *** Test complete ***\n");
|
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",
|
fprintf(stderr, "\nTyping \"cat /proc/interrupts\" will show %d more events on IRQ 8.\n\n",
|
irqcount);
|
irqcount);
|
|
|
close(fd);
|
close(fd);
|
|
|
} /* end main */
|
} /* end main */
|
|
|
