oom: make deprecated use of oom_adj more verbose
[linux-2.6.git] / Documentation / rtc.txt
index c931d61..2501604 100644 (file)
@@ -135,6 +135,30 @@ a high functionality RTC is integrated into the SOC.  That system might read
 the system clock from the discrete RTC, but use the integrated one for all
 other tasks, because of its greater functionality.
 
+SYSFS INTERFACE
+---------------
+
+The sysfs interface under /sys/class/rtc/rtcN provides access to various
+rtc attributes without requiring the use of ioctls. All dates and times
+are in the RTC's timezone, rather than in system time.
+
+date:                   RTC-provided date
+hctosys:        1 if the RTC provided the system time at boot via the
+                CONFIG_RTC_HCTOSYS kernel option, 0 otherwise
+max_user_freq:  The maximum interrupt rate an unprivileged user may request
+                from this RTC.
+name:           The name of the RTC corresponding to this sysfs directory
+since_epoch:    The number of seconds since the epoch according to the RTC
+time:           RTC-provided time
+wakealarm:      The time at which the clock will generate a system wakeup
+                event. This is a one shot wakeup event, so must be reset
+                after wake if a daily wakeup is required. Format is either
+                seconds since the epoch or, if there's a leading +, seconds
+                in the future.
+
+IOCTL INTERFACE
+---------------
+
 The ioctl() calls supported by /dev/rtc are also supported by the RTC class
 framework.  However, because the chips and systems are not standardized,
 some PC/AT functionality might not be provided.  And in the same way, some
@@ -154,35 +178,29 @@ RTC class framework, but can't be supported by the older driver.
        setting the longer alarm time and enabling its IRQ using a single
        request (using the same model as EFI firmware).
 
-    *  RTC_UIE_ON, RTC_UIE_OFF ... if the RTC offers IRQs, it probably
-       also offers update IRQs whenever the "seconds" counter changes.
-       If needed, the RTC framework can emulate this mechanism.
+    *  RTC_UIE_ON, RTC_UIE_OFF ... if the RTC offers IRQs, the RTC framework
+       will emulate this mechanism.
 
-    *  RTC_PIE_ON, RTC_PIE_OFF, RTC_IRQP_SET, RTC_IRQP_READ ... another
-       feature often accessible with an IRQ line is a periodic IRQ, issued
-       at settable frequencies (usually 2^N Hz).
+    *  RTC_PIE_ON, RTC_PIE_OFF, RTC_IRQP_SET, RTC_IRQP_READ ... these icotls
+       are emulated via a kernel hrtimer.
 
 In many cases, the RTC alarm can be a system wake event, used to force
 Linux out of a low power sleep state (or hibernation) back to a fully
 operational state.  For example, a system could enter a deep power saving
 state until it's time to execute some scheduled tasks.
 
-Note that many of these ioctls need not actually be implemented by your
-driver.  The common rtc-dev interface handles many of these nicely if your
-driver returns ENOIOCTLCMD.  Some common examples:
+Note that many of these ioctls are handled by the common rtc-dev interface.
+Some common examples:
 
     *  RTC_RD_TIME, RTC_SET_TIME: the read_time/set_time functions will be
        called with appropriate values.
 
-    *  RTC_ALM_SET, RTC_ALM_READ, RTC_WKALM_SET, RTC_WKALM_RD: the
-       set_alarm/read_alarm functions will be called.
+    *  RTC_ALM_SET, RTC_ALM_READ, RTC_WKALM_SET, RTC_WKALM_RD: gets or sets
+       the alarm rtc_timer. May call the set_alarm driver function.
+
+    *  RTC_IRQP_SET, RTC_IRQP_READ: These are emulated by the generic code.
 
-    *  RTC_IRQP_SET, RTC_IRQP_READ: the irq_set_freq function will be called
-       to set the frequency while the framework will handle the read for you
-       since the frequency is stored in the irq_freq member of the rtc_device
-       structure.  Also make sure you set the max_user_freq member in your
-       initialization routines so the framework can sanity check the user
-       input for you.
+    *  RTC_PIE_ON, RTC_PIE_OFF: These are also emulated by the generic code.
 
 If all else fails, check out the rtc-test.c driver!
 
@@ -267,8 +285,8 @@ int main(int argc, char **argv)
                /* This read will block */
                retval = read(fd, &data, sizeof(unsigned long));
                if (retval == -1) {
-                       perror("read");
-                       exit(errno);
+                       perror("read");
+                       exit(errno);
                }
                fprintf(stderr, " %d",i);
                fflush(stderr);
@@ -325,11 +343,11 @@ test_READ:
                rtc_tm.tm_sec %= 60;
                rtc_tm.tm_min++;
        }
-       if  (rtc_tm.tm_min == 60) {
+       if (rtc_tm.tm_min == 60) {
                rtc_tm.tm_min = 0;
                rtc_tm.tm_hour++;
        }
-       if  (rtc_tm.tm_hour == 24)
+       if (rtc_tm.tm_hour == 24)
                rtc_tm.tm_hour = 0;
 
        retval = ioctl(fd, RTC_ALM_SET, &rtc_tm);
@@ -406,8 +424,8 @@ test_PIE:
                                        "\n...Periodic IRQ rate is fixed\n");
                                goto done;
                        }
-                       perror("RTC_IRQP_SET ioctl");
-                       exit(errno);
+                       perror("RTC_IRQP_SET ioctl");
+                       exit(errno);
                }
 
                fprintf(stderr, "\n%ldHz:\t", tmp);
@@ -416,27 +434,27 @@ test_PIE:
                /* Enable periodic interrupts */
                retval = ioctl(fd, RTC_PIE_ON, 0);
                if (retval == -1) {
-                       perror("RTC_PIE_ON ioctl");
-                       exit(errno);
+                       perror("RTC_PIE_ON 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++;
+                       /* 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("RTC_PIE_OFF ioctl");
-                       exit(errno);
+                       perror("RTC_PIE_OFF ioctl");
+                       exit(errno);
                }
        }