Document the circular buffering capabilities available in Linux.
Signed-off-by: David Howells <email@example.com>
Signed-off-by: Paul E. McKenney <firstname.lastname@example.org>
Reviewed-by: Randy Dunlap <email@example.com>
Reviewed-by: Stefan Richter <firstname.lastname@example.org>
Documentation/circular-buffers.txt | 234 ++++++++++++++++++++++++++++++++++++
Documentation/memory-barriers.txt | 20 +++
include/linux/circ_buf.h | 4 +
3 files changed, 258 insertions(+), 0 deletions(-)
create mode 100644 Documentation/circular-buffers.txt
diff --git a/Documentation/circular-buffers.txt b/Documentation/circular-buffers.txt
new file mode 100644
@@ -0,0 +1,234 @@
+ CIRCULAR BUFFERS
+By: David Howells <email@example.com>
+ Paul E. McKenney <firstname.lastname@example.org>
+Linux provides a number of features that can be used to implement circular
+buffering. There are two sets of such features:
+ (1) Convenience functions for determining information about power-of-2 sized
+ (2) Memory barriers for when the producer and the consumer of objects in the
+ buffer don't want to share a lock.
+To use these facilities, as discussed below, there needs to be just one
+producer and just one consumer. It is possible to handle multiple producers by
+serialising them, and to handle multiple consumers by serialising them.
+ (*) What is a circular buffer?
+ (*) Measuring power-of-2 buffers.
+ (*) Using memory barriers with circular buffers.
+ - The producer.
+ - The consumer.
+WHAT IS A CIRCULAR BUFFER?
+First of all, what is a circular buffer? A circular buffer is a buffer of
+fixed, finite size into which there are two indices:
+ (1) A 'head' index - the point at which the ...