[PATCH] Document Linux's memory barriers [try #4]

[David Howells]

Eric W. Biederman <ebiederm at xmission.com> wrote:

> A small nit.  You are not documenting the most subtle memory barrier:
> smp_read_barrier_depends();  Which is a deep requirement of the RCU
> code.

How about this the attached adjustment?

David

diff --git a/Documentation/memory-barriers.txt b/Documentation/memory-barriers.txt
index 3ec9ff4..0c38bea 100644
--- a/Documentation/memory-barriers.txt
+++ b/Documentation/memory-barriers.txt
@@ -457,13 +457,14 @@ except in small and specific cases.  In 
 EXPLICIT KERNEL MEMORY BARRIERS
 ===============================
 
-The Linux kernel has six basic CPU memory barriers:
+The Linux kernel has eight basic CPU memory barriers:
 
-		MANDATORY	SMP CONDITIONAL
-		===============	===============
-	GENERAL	mb()		smp_mb()
-	READ	rmb()		smp_rmb()
-	WRITE	wmb()		smp_wmb()
+	TYPE		MANDATORY		SMP CONDITIONAL
+	===============	=======================	===========================
+	GENERAL		mb()			smp_mb()
+	WRITE		wmb()			smp_wmb()
+	READ		rmb()			smp_rmb()
+	DATA DEPENDENCY	read_barrier_depends()	smp_read_barrier_depends()
 
 General memory barriers give a guarantee that all memory accesses specified
 before the barrier will appear to happen before all memory accesses specified
@@ -472,6 +473,36 @@ after the barrier with respect to the ot
 Read and write memory barriers give similar guarantees, but only for memory
 reads versus memory reads and memory writes versus memory writes respectively.
 
+Data dependency memory barriers ensure that if two reads are issued that
+depend on each other, that the first read is completed _before_ the dependency
+comes into effect.  For instance, consider a case where the address used in
+the second read is calculated from the result of the first read:
+
+	CPU 1		CPU 2		COMMENT
+	===============	===============	=======================================
+					a == 0, b == 1 and p == &a, q == &a
+	b = 2;
+	smp_wmb();			Make sure b is changed before p
+	p = &b;		q = p;
+			d = *q;
+
+then old data values may be used in the address calculation for the second
+value, potentially resulting in q == &b and d == 0 being seen, which is never
+correct.  What is required is a data dependency memory barrier:
+
+	CPU 1		CPU 2		COMMENT
+	===============	===============	=======================================
+					a == 0, b == 1 and p == &a, q == &a
+	b = 2;
+	smp_wmb();			Make sure b is changed before p
+	p = &b;		q = p;
+			smp_read_barrier_depends();
+					Make sure q is changed before d is read
+			d = *q;
+
+This forces the result to be either q == &a and d == 0 or q == &b and d == 2.
+The result of q == &b and d == 0 will never be seen.
+
 All memory barriers imply compiler barriers.
 
 SMP memory barriers are only compiler barriers on uniprocessor compiled systems