1 files changed, 282 insertions, 0 deletions
diff --git a/Documentation/rtc.txt b/Documentation/rtc.txt
new file mode 100644
index 000000000000..95d17b3e2eee
--- /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 */