From: Frank Mori Hess <fmhess@speakeasy.net>
Date: Mon, 29 Apr 2002 20:16:58 +0000 (+0000)
Subject: added comments describing scheme for reading/writing to comedi's buffer
X-Git-Tag: r0_7_65~73
X-Git-Url: http://git.tremily.us/?a=commitdiff_plain;h=635fd401420afb59e1ec71a22f813f05f9985bb6;p=comedi.git

added comments describing scheme for reading/writing to comedi's buffer
that should be race-free and reliably detect overruns.
---

diff --git a/include/linux/comedidev.h b/include/linux/comedidev.h
index 9d1989f1..c468d5d5 100644
--- a/include/linux/comedidev.h
+++ b/include/linux/comedidev.h
@@ -130,6 +130,18 @@ struct comedi_async_struct{
 	unsigned int	max_bufsize;		/* maximum buffer size, bytes */
 	unsigned int	mmap_count;	/* current number of mmaps of prealloc_buf */
 
+	/* To avoid races and provide reliable overrun detection, read / writes
+	 * to buffer should proceed as follows:
+	 * Writing:
+	 *   1) increment write count
+	 *   2) write data to buffer
+	 *   3) increment write ptr
+	 * Reading:
+	 *   1) read data from buffer, using 'ptr' members to determine how much
+	 *   2) update the read ptr, exactly when this occurs is not critical
+	 *   3) check for overrun, using 'count' members
+	 *   4) increment read count
+	 */
 	volatile unsigned int buf_int_ptr;	/* buffer marker for interrupt */
 	unsigned int buf_user_ptr;		/* buffer marker for read() and write() */
 	volatile unsigned int buf_int_count;	/* byte count for interrupt */