[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>

[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>
Mike Frysinger · Linus Torvalds
1 parent 1efc5da3cf
Showing 1 changed file with 34 additions and 12 deletions Side-by-side Diff
Documentation/rtc.txt
@@ -149,7 +149,7 @@
 	is connected to an IRQ line, it can often issue an alarm IRQ up to
 	24 hours in the future.
  
-    *	RTC_WKALM_SET, RTC_WKALM_READ ... RTCs that can issue alarms beyond
+    *	RTC_WKALM_SET, RTC_WKALM_RD ... RTCs that can issue alarms beyond
 	the next 24 hours use a slightly more powerful API, which supports
 	setting the longer alarm time and enabling its IRQ using a single
 	request (using the same model as EFI firmware).
  
@@ -167,7 +167,29 @@
 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:
  
+    *	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.  To differentiate
+	between the ALM and WKALM, check the larger fields of the rtc_wkalrm
+	struct (like tm_year).  These will be set to -1 when using ALM and
+	will be set to proper values when using WKALM.
+
+    *	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.
+
+If all else fails, check out the rtc-test.c driver!
+
+
 -------------------- 8< ---------------- 8< -----------------------------
  
 /*
@@ -237,7 +259,7 @@
 				"\n...Update IRQs not supported.\n");
 			goto test_READ;
 		}
-		perror("ioctl");
+		perror("RTC_UIE_ON ioctl");
 		exit(errno);
 	}
  
@@ -284,7 +306,7 @@
 	/* Turn off update interrupts */
 	retval = ioctl(fd, RTC_UIE_OFF, 0);
 	if (retval == -1) {
-		perror("ioctl");
+		perror("RTC_UIE_OFF ioctl");
 		exit(errno);
 	}
  
@@ -292,7 +314,7 @@
 	/* Read the RTC time/date */
 	retval = ioctl(fd, RTC_RD_TIME, &rtc_tm);
 	if (retval == -1) {
-		perror("ioctl");
+		perror("RTC_RD_TIME ioctl");
 		exit(errno);
 	}
  
  
@@ -320,14 +342,14 @@
 				"\n...Alarm IRQs not supported.\n");
 			goto test_PIE;
 		}
-		perror("ioctl");
+		perror("RTC_ALM_SET ioctl");
 		exit(errno);
 	}
  
 	/* Read the current alarm settings */
 	retval = ioctl(fd, RTC_ALM_READ, &rtc_tm);
 	if (retval == -1) {
-		perror("ioctl");
+		perror("RTC_ALM_READ ioctl");
 		exit(errno);
 	}
  
@@ -337,7 +359,7 @@
 	/* Enable alarm interrupts */
 	retval = ioctl(fd, RTC_AIE_ON, 0);
 	if (retval == -1) {
-		perror("ioctl");
+		perror("RTC_AIE_ON ioctl");
 		exit(errno);
 	}
  
@@ -355,7 +377,7 @@
 	/* Disable alarm interrupts */
 	retval = ioctl(fd, RTC_AIE_OFF, 0);
 	if (retval == -1) {
-		perror("ioctl");
+		perror("RTC_AIE_OFF ioctl");
 		exit(errno);
 	}
  
@@ -368,7 +390,7 @@
 			fprintf(stderr, "\nNo periodic IRQ support\n");
 			return 0;
 		}
-		perror("ioctl");
+		perror("RTC_IRQP_READ ioctl");
 		exit(errno);
 	}
 	fprintf(stderr, "\nPeriodic IRQ rate is %ldHz.\n", tmp);
@@ -387,7 +409,7 @@
 					"\n...Periodic IRQ rate is fixed\n");
 				goto done;
 			}
-		        perror("ioctl");
+		        perror("RTC_IRQP_SET ioctl");
 		        exit(errno);
 		}
  
@@ -397,7 +419,7 @@
 		/* Enable periodic interrupts */
 		retval = ioctl(fd, RTC_PIE_ON, 0);
 		if (retval == -1) {
-		        perror("ioctl");
+		        perror("RTC_PIE_ON ioctl");
 		        exit(errno);
 		}
  
@@ -416,7 +438,7 @@
 		/* Disable periodic interrupts */
 		retval = ioctl(fd, RTC_PIE_OFF, 0);
 		if (retval == -1) {
-		        perror("ioctl");
+		        perror("RTC_PIE_OFF ioctl");
 		        exit(errno);
 		}
 	}
...	...	@@ -149,7 +149,7 @@
149	149	is connected to an IRQ line, it can often issue an alarm IRQ up to
150	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	153	the next 24 hours use a slightly more powerful API, which supports
154	154	setting the longer alarm time and enabling its IRQ using a single
155	155	request (using the same model as EFI firmware).
156	156
...	...	@@ -167,7 +167,29 @@
167	167	operational state. For example, a system could enter a deep power saving
168	168	state until it's time to execute some scheduled tasks.
169	169
	170	+Note that many of these ioctls need not actually be implemented by your
	171	+driver. The common rtc-dev interface handles many of these nicely if your
	172	+driver returns ENOIOCTLCMD. Some common examples:
170	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	+
	190	+If all else fails, check out the rtc-test.c driver!
	191	+
	192	+
171	193	-------------------- 8< ---------------- 8< -----------------------------
172	194
173	195	/*
...	...	@@ -237,7 +259,7 @@
237	259	"\n...Update IRQs not supported.\n");
238	260	goto test_READ;
239	261	}
240		- perror("ioctl");
	262	+ perror("RTC_UIE_ON ioctl");
241	263	exit(errno);
242	264	}
243	265
...	...	@@ -284,7 +306,7 @@
284	306	/* Turn off update interrupts */
285	307	retval = ioctl(fd, RTC_UIE_OFF, 0);
286	308	if (retval == -1) {
287		- perror("ioctl");
	309	+ perror("RTC_UIE_OFF ioctl");
288	310	exit(errno);
289	311	}
290	312
...	...	@@ -292,7 +314,7 @@
292	314	/* Read the RTC time/date */
293	315	retval = ioctl(fd, RTC_RD_TIME, &rtc_tm);
294	316	if (retval == -1) {
295		- perror("ioctl");
	317	+ perror("RTC_RD_TIME ioctl");
296	318	exit(errno);
297	319	}
298	320
299	321
...	...	@@ -320,14 +342,14 @@
320	342	"\n...Alarm IRQs not supported.\n");
321	343	goto test_PIE;
322	344	}
323		- perror("ioctl");
	345	+ perror("RTC_ALM_SET ioctl");
324	346	exit(errno);
325	347	}
326	348
327	349	/* Read the current alarm settings */
328	350	retval = ioctl(fd, RTC_ALM_READ, &rtc_tm);
329	351	if (retval == -1) {
330		- perror("ioctl");
	352	+ perror("RTC_ALM_READ ioctl");
331	353	exit(errno);
332	354	}
333	355
...	...	@@ -337,7 +359,7 @@
337	359	/* Enable alarm interrupts */
338	360	retval = ioctl(fd, RTC_AIE_ON, 0);
339	361	if (retval == -1) {
340		- perror("ioctl");
	362	+ perror("RTC_AIE_ON ioctl");
341	363	exit(errno);
342	364	}
343	365
...	...	@@ -355,7 +377,7 @@
355	377	/* Disable alarm interrupts */
356	378	retval = ioctl(fd, RTC_AIE_OFF, 0);
357	379	if (retval == -1) {
358		- perror("ioctl");
	380	+ perror("RTC_AIE_OFF ioctl");
359	381	exit(errno);
360	382	}
361	383
...	...	@@ -368,7 +390,7 @@
368	390	fprintf(stderr, "\nNo periodic IRQ support\n");
369	391	return 0;
370	392	}
371		- perror("ioctl");
	393	+ perror("RTC_IRQP_READ ioctl");
372	394	exit(errno);
373	395	}
374	396	fprintf(stderr, "\nPeriodic IRQ rate is %ldHz.\n", tmp);
...	...	@@ -387,7 +409,7 @@
387	409	"\n...Periodic IRQ rate is fixed\n");
388	410	goto done;
389	411	}
390		- perror("ioctl");
	412	+ perror("RTC_IRQP_SET ioctl");
391	413	exit(errno);
392	414	}
393	415
...	...	@@ -397,7 +419,7 @@
397	419	/* Enable periodic interrupts */
398	420	retval = ioctl(fd, RTC_PIE_ON, 0);
399	421	if (retval == -1) {
400		- perror("ioctl");
	422	+ perror("RTC_PIE_ON ioctl");
401	423	exit(errno);
402	424	}
403	425
...	...	@@ -416,7 +438,7 @@
416	438	/* Disable periodic interrupts */
417	439	retval = ioctl(fd, RTC_PIE_OFF, 0);
418	440	if (retval == -1) {
419		- perror("ioctl");
	441	+ perror("RTC_PIE_OFF ioctl");
420	442	exit(errno);
421	443	}
422	444	}