aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorMike Frysinger <vapier@gentoo.org>2007-02-10 04:46:30 -0500
committerLinus Torvalds <torvalds@woody.linux-foundation.org>2007-02-11 14:18:06 -0500
commit2b1cd4c43b90059b54baa8d9113365984113c631 (patch)
tree418dfe24b8be0b2df98530fcfe9544c1269fe7b0
parent1efc5da3cf567d2f6b795f9d2112ed97fec4ee7c (diff)
[PATCH] some rtc documentation updates
Fix typo when describing RTC_WKALM. Add some helpful pointers to people developing their own RTC driver. Change a bunch of the error messages in the test program to be a bit more helpful. Signed-off-by: Mike Frysinger <vapier@gentoo.org> Cc: Alessandro Zummo <a.zummo@towertech.it> Signed-off-by: Andrew Morton <akpm@linux-foundation.org> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
-rw-r--r--Documentation/rtc.txt46
1 files changed, 34 insertions, 12 deletions
diff --git a/Documentation/rtc.txt b/Documentation/rtc.txt
index 7cf1ec5bcdd3..1ef6bb88cd00 100644
--- a/Documentation/rtc.txt
+++ b/Documentation/rtc.txt
@@ -149,7 +149,7 @@ RTC class framework, but can't be supported by the older driver.
149 is connected to an IRQ line, it can often issue an alarm IRQ up to 149 is connected to an IRQ line, it can often issue an alarm IRQ up to
150 24 hours in the future. 150 24 hours in the future.
151 151
152 * RTC_WKALM_SET, RTC_WKALM_READ ... RTCs that can issue alarms beyond 152 * RTC_WKALM_SET, RTC_WKALM_RD ... RTCs that can issue alarms beyond
153 the next 24 hours use a slightly more powerful API, which supports 153 the next 24 hours use a slightly more powerful API, which supports
154 setting the longer alarm time and enabling its IRQ using a single 154 setting the longer alarm time and enabling its IRQ using a single
155 request (using the same model as EFI firmware). 155 request (using the same model as EFI firmware).
@@ -167,6 +167,28 @@ Linux out of a low power sleep state (or hibernation) back to a fully
167operational state. For example, a system could enter a deep power saving 167operational state. For example, a system could enter a deep power saving
168state until it's time to execute some scheduled tasks. 168state until it's time to execute some scheduled tasks.
169 169
170Note that many of these ioctls need not actually be implemented by your
171driver. The common rtc-dev interface handles many of these nicely if your
172driver returns ENOIOCTLCMD. Some common examples:
173
174 * RTC_RD_TIME, RTC_SET_TIME: the read_time/set_time functions will be
175 called with appropriate values.
176
177 * RTC_ALM_SET, RTC_ALM_READ, RTC_WKALM_SET, RTC_WKALM_RD: the
178 set_alarm/read_alarm functions will be called. To differentiate
179 between the ALM and WKALM, check the larger fields of the rtc_wkalrm
180 struct (like tm_year). These will be set to -1 when using ALM and
181 will be set to proper values when using WKALM.
182
183 * RTC_IRQP_SET, RTC_IRQP_READ: the irq_set_freq function will be called
184 to set the frequency while the framework will handle the read for you
185 since the frequency is stored in the irq_freq member of the rtc_device
186 structure. Also make sure you set the max_user_freq member in your
187 initialization routines so the framework can sanity check the user
188 input for you.
189
190If all else fails, check out the rtc-test.c driver!
191
170 192
171-------------------- 8< ---------------- 8< ----------------------------- 193-------------------- 8< ---------------- 8< -----------------------------
172 194
@@ -237,7 +259,7 @@ int main(int argc, char **argv)
237 "\n...Update IRQs not supported.\n"); 259 "\n...Update IRQs not supported.\n");
238 goto test_READ; 260 goto test_READ;
239 } 261 }
240 perror("ioctl"); 262 perror("RTC_UIE_ON ioctl");
241 exit(errno); 263 exit(errno);
242 } 264 }
243 265
@@ -284,7 +306,7 @@ int main(int argc, char **argv)
284 /* Turn off update interrupts */ 306 /* Turn off update interrupts */
285 retval = ioctl(fd, RTC_UIE_OFF, 0); 307 retval = ioctl(fd, RTC_UIE_OFF, 0);
286 if (retval == -1) { 308 if (retval == -1) {
287 perror("ioctl"); 309 perror("RTC_UIE_OFF ioctl");
288 exit(errno); 310 exit(errno);
289 } 311 }
290 312
@@ -292,7 +314,7 @@ test_READ:
292 /* Read the RTC time/date */ 314 /* Read the RTC time/date */
293 retval = ioctl(fd, RTC_RD_TIME, &rtc_tm); 315 retval = ioctl(fd, RTC_RD_TIME, &rtc_tm);
294 if (retval == -1) { 316 if (retval == -1) {
295 perror("ioctl"); 317 perror("RTC_RD_TIME ioctl");
296 exit(errno); 318 exit(errno);
297 } 319 }
298 320
@@ -320,14 +342,14 @@ test_READ:
320 "\n...Alarm IRQs not supported.\n"); 342 "\n...Alarm IRQs not supported.\n");
321 goto test_PIE; 343 goto test_PIE;
322 } 344 }
323 perror("ioctl"); 345 perror("RTC_ALM_SET ioctl");
324 exit(errno); 346 exit(errno);
325 } 347 }
326 348
327 /* Read the current alarm settings */ 349 /* Read the current alarm settings */
328 retval = ioctl(fd, RTC_ALM_READ, &rtc_tm); 350 retval = ioctl(fd, RTC_ALM_READ, &rtc_tm);
329 if (retval == -1) { 351 if (retval == -1) {
330 perror("ioctl"); 352 perror("RTC_ALM_READ ioctl");
331 exit(errno); 353 exit(errno);
332 } 354 }
333 355
@@ -337,7 +359,7 @@ test_READ:
337 /* Enable alarm interrupts */ 359 /* Enable alarm interrupts */
338 retval = ioctl(fd, RTC_AIE_ON, 0); 360 retval = ioctl(fd, RTC_AIE_ON, 0);
339 if (retval == -1) { 361 if (retval == -1) {
340 perror("ioctl"); 362 perror("RTC_AIE_ON ioctl");
341 exit(errno); 363 exit(errno);
342 } 364 }
343 365
@@ -355,7 +377,7 @@ test_READ:
355 /* Disable alarm interrupts */ 377 /* Disable alarm interrupts */
356 retval = ioctl(fd, RTC_AIE_OFF, 0); 378 retval = ioctl(fd, RTC_AIE_OFF, 0);
357 if (retval == -1) { 379 if (retval == -1) {
358 perror("ioctl"); 380 perror("RTC_AIE_OFF ioctl");
359 exit(errno); 381 exit(errno);
360 } 382 }
361 383
@@ -368,7 +390,7 @@ test_PIE:
368 fprintf(stderr, "\nNo periodic IRQ support\n"); 390 fprintf(stderr, "\nNo periodic IRQ support\n");
369 return 0; 391 return 0;
370 } 392 }
371 perror("ioctl"); 393 perror("RTC_IRQP_READ ioctl");
372 exit(errno); 394 exit(errno);
373 } 395 }
374 fprintf(stderr, "\nPeriodic IRQ rate is %ldHz.\n", tmp); 396 fprintf(stderr, "\nPeriodic IRQ rate is %ldHz.\n", tmp);
@@ -387,7 +409,7 @@ test_PIE:
387 "\n...Periodic IRQ rate is fixed\n"); 409 "\n...Periodic IRQ rate is fixed\n");
388 goto done; 410 goto done;
389 } 411 }
390 perror("ioctl"); 412 perror("RTC_IRQP_SET ioctl");
391 exit(errno); 413 exit(errno);
392 } 414 }
393 415
@@ -397,7 +419,7 @@ test_PIE:
397 /* Enable periodic interrupts */ 419 /* Enable periodic interrupts */
398 retval = ioctl(fd, RTC_PIE_ON, 0); 420 retval = ioctl(fd, RTC_PIE_ON, 0);
399 if (retval == -1) { 421 if (retval == -1) {
400 perror("ioctl"); 422 perror("RTC_PIE_ON ioctl");
401 exit(errno); 423 exit(errno);
402 } 424 }
403 425
@@ -416,7 +438,7 @@ test_PIE:
416 /* Disable periodic interrupts */ 438 /* Disable periodic interrupts */
417 retval = ioctl(fd, RTC_PIE_OFF, 0); 439 retval = ioctl(fd, RTC_PIE_OFF, 0);
418 if (retval == -1) { 440 if (retval == -1) {
419 perror("ioctl"); 441 perror("RTC_PIE_OFF ioctl");
420 exit(errno); 442 exit(errno);
421 } 443 }
422 } 444 }