initial import
[patches.git] / linux-rtc-doc-update.patch
1 Fix typo when describing RTC_WKALM. Add some helpful pointers to people
2 developing their own RTC driver. Change a bunch of the error messages in the
3 test program to be a bit more helpful.
4
5 Signed-off-by: Mike Frysinger <vapier@gentoo.org>
6
7 diff --git a/Documentation/rtc.txt b/Documentation/rtc.txt
8 index 7cf1ec5..1ef6bb8 100644
9 --- a/Documentation/rtc.txt
10 +++ b/Documentation/rtc.txt
11 @@ -149,7 +149,7 @@ RTC class framework, but can't be supported by the older driver.
12 is connected to an IRQ line, it can often issue an alarm IRQ up to
13 24 hours in the future.
14
15 - * RTC_WKALM_SET, RTC_WKALM_READ ... RTCs that can issue alarms beyond
16 + * RTC_WKALM_SET, RTC_WKALM_RD ... RTCs that can issue alarms beyond
17 the next 24 hours use a slightly more powerful API, which supports
18 setting the longer alarm time and enabling its IRQ using a single
19 request (using the same model as EFI firmware).
20 @@ -167,6 +167,28 @@ Linux out of a low power sleep state (or hibernation) back to a fully
21 operational state. For example, a system could enter a deep power saving
22 state until it's time to execute some scheduled tasks.
23
24 +Note that many of these ioctls need not actually be implemented by your
25 +driver. The common rtc-dev interface handles many of these nicely if your
26 +driver returns ENOIOCTLCMD. Some common examples:
27 +
28 + * RTC_RD_TIME, RTC_SET_TIME: the read_time/set_time functions will be
29 + called with appropriate values.
30 +
31 + * RTC_ALM_SET, RTC_ALM_READ, RTC_WKALM_SET, RTC_WKALM_RD: the
32 + set_alarm/read_alarm functions will be called. To differentiate
33 + between the ALM and WKALM, check the larger fields of the rtc_wkalrm
34 + struct (like tm_year). These will be set to -1 when using ALM and
35 + will be set to proper values when using WKALM.
36 +
37 + * RTC_IRQP_SET, RTC_IRQP_READ: the irq_set_freq function will be called
38 + to set the frequency while the framework will handle the read for you
39 + since the frequency is stored in the irq_freq member of the rtc_device
40 + structure. Also make sure you set the max_user_freq member in your
41 + initialization routines so the framework can sanity check the user
42 + input for you.
43 +
44 +If all else fails, check out the rtc-test.c driver!
45 +
46
47 -------------------- 8< ---------------- 8< -----------------------------
48
49 @@ -237,7 +259,7 @@ int main(int argc, char **argv)
50 "\n...Update IRQs not supported.\n");
51 goto test_READ;
52 }
53 - perror("ioctl");
54 + perror("RTC_UIE_ON ioctl");
55 exit(errno);
56 }
57
58 @@ -284,7 +306,7 @@ int main(int argc, char **argv)
59 /* Turn off update interrupts */
60 retval = ioctl(fd, RTC_UIE_OFF, 0);
61 if (retval == -1) {
62 - perror("ioctl");
63 + perror("RTC_UIE_OFF ioctl");
64 exit(errno);
65 }
66
67 @@ -292,7 +314,7 @@ test_READ:
68 /* Read the RTC time/date */
69 retval = ioctl(fd, RTC_RD_TIME, &rtc_tm);
70 if (retval == -1) {
71 - perror("ioctl");
72 + perror("RTC_RD_TIME ioctl");
73 exit(errno);
74 }
75
76 @@ -320,14 +342,14 @@ test_READ:
77 "\n...Alarm IRQs not supported.\n");
78 goto test_PIE;
79 }
80 - perror("ioctl");
81 + perror("RTC_ALM_SET ioctl");
82 exit(errno);
83 }
84
85 /* Read the current alarm settings */
86 retval = ioctl(fd, RTC_ALM_READ, &rtc_tm);
87 if (retval == -1) {
88 - perror("ioctl");
89 + perror("RTC_ALM_READ ioctl");
90 exit(errno);
91 }
92
93 @@ -337,7 +359,7 @@ test_READ:
94 /* Enable alarm interrupts */
95 retval = ioctl(fd, RTC_AIE_ON, 0);
96 if (retval == -1) {
97 - perror("ioctl");
98 + perror("RTC_AIE_ON ioctl");
99 exit(errno);
100 }
101
102 @@ -355,7 +377,7 @@ test_READ:
103 /* Disable alarm interrupts */
104 retval = ioctl(fd, RTC_AIE_OFF, 0);
105 if (retval == -1) {
106 - perror("ioctl");
107 + perror("RTC_AIE_OFF ioctl");
108 exit(errno);
109 }
110
111 @@ -368,7 +390,7 @@ test_PIE:
112 fprintf(stderr, "\nNo periodic IRQ support\n");
113 return 0;
114 }
115 - perror("ioctl");
116 + perror("RTC_IRQP_READ ioctl");
117 exit(errno);
118 }
119 fprintf(stderr, "\nPeriodic IRQ rate is %ldHz.\n", tmp);
120 @@ -387,7 +409,7 @@ test_PIE:
121 "\n...Periodic IRQ rate is fixed\n");
122 goto done;
123 }
124 - perror("ioctl");
125 + perror("RTC_IRQP_SET ioctl");
126 exit(errno);
127 }
128
129 @@ -397,7 +419,7 @@ test_PIE:
130 /* Enable periodic interrupts */
131 retval = ioctl(fd, RTC_PIE_ON, 0);
132 if (retval == -1) {
133 - perror("ioctl");
134 + perror("RTC_PIE_ON ioctl");
135 exit(errno);
136 }
137
138 @@ -416,7 +438,7 @@ test_PIE:
139 /* Disable periodic interrupts */
140 retval = ioctl(fd, RTC_PIE_OFF, 0);
141 if (retval == -1) {
142 - perror("ioctl");
143 + perror("RTC_PIE_OFF ioctl");
144 exit(errno);
145 }
146 }