Documentation updates for 4.2

From: Milos Vyletel <[email protected]>

Make a note stating that repeated calls of rcu_dereference() may not return the same pointer if update happens while in critical section.

---
 Documentation/RCU/whatisRCU.txt | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

index 88dfce182f66..16622c9e86b5 100644
@@ -256,7 +256,9 @@ rcu_dereference()
 	If you are going to be fetching multiple fields from the
 	RCU-protected structure, using the local variable is of
 	course preferred.  Repeated rcu_dereference() calls look
-	ugly and incur unnecessary overhead on Alpha CPUs.
+	ugly, do not guarantee that the same pointer will be returned
+	if an update happened while in the critical section, and incur
+	unnecessary overhead on Alpha CPUs.
 
 	Note that the value returned by rcu_dereference() is valid
 	only within the enclosing RCU read-side critical section.

1.8.1.5

From: "Paul E. McKenney" <[email protected]>

This commit provides another caveat for the care and feeding of pointers returned by rcu_dereference() that was pointed out in discussions within the C++ standards committee.

---
 Documentation/RCU/rcu_dereference.txt | 5 +++++
 1 file changed, 5 insertions(+)

index ceb05da5a5ac..2d05c9241a33 100644
@@ -193,6 +193,11 @@ o	Be very careful about comparing pointers obtained from
 		pointer.  Note that the volatile cast in rcu_dereference()
 		will normally prevent the compiler from knowing too much.
 
+		However, please note that if the compiler knows that the
+		pointer takes on only one of two values, a not-equal
+		comparison will provide exactly the information that the
+		compiler needs to deduce the value of the pointer.
+
 o	Disable any value-speculation optimizations that your compiler
 	might provide, especially if you are making use of feedback-based
 	optimizations that take data collected from prior runs.  Such

1.8.1.5

From: Will Deacon <[email protected]>

Our current documentation claims that, when followed by an ACQUIRE, smp_mb__before_spinlock() orders prior loads against subsequent loads and stores, which isn't the intent. This commit therefore fixes the documentation to state that this sequence orders only prior stores against subsequent loads and stores.

In addition, the original intent of smp_mb__before_spinlock() was to only order prior loads against subsequent stores, however, people have started using it as if it ordered prior loads against subsequent loads and stores. This commit therefore also updates smp_mb__before_spinlock()'s header comment to reflect this new reality.

---
 Documentation/memory-barriers.txt | 7 +++----
 include/linux/spinlock.h          | 2 +-
 2 files changed, 4 insertions(+), 5 deletions(-)

index f95746189b5d..1f362fd2ecb4 100644
@@ -1784,10 +1784,9 @@ for each construct.  These operations all imply certain barriers:
 
      Memory operations issued before the ACQUIRE may be completed after
      the ACQUIRE operation has completed.  An smp_mb__before_spinlock(),
-     combined with a following ACQUIRE, orders prior loads against
-     subsequent loads and stores and also orders prior stores against
-     subsequent stores.  Note that this is weaker than smp_mb()!  The
-     smp_mb__before_spinlock() primitive is free on many architectures.
+     combined with a following ACQUIRE, orders prior stores against
+     subsequent loads and stores. Note that this is weaker than smp_mb()!
+     The smp_mb__before_spinlock() primitive is free on many architectures.
 
  (2) RELEASE operation implication:
 

index 3e18379dfa6f..0063b24b4f36 100644
@@ -120,7 +120,7 @@ do {								\
 /*
  * Despite its name it doesn't necessarily has to be a full barrier.
  * It should only guarantee that a STORE before the critical section
- * can not be reordered with a LOAD inside this section.
+ * can not be reordered with LOADs and STOREs inside this section.
  * spin_lock() is the one-way barrier, this LOAD can not escape out
  * of the region. So the default implementation simply ensures that
  * a STORE can not move into the critical section, smp_wmb() should

1.8.1.5

Hello!

This series provides a few documentation updates:

1. Fix description of smp_mb__before_spinlock() semantics, courtesy
of Will Deacon.

2. Add another caveat to the list regarding the care and feeding
of pointers returned by rcu_derefence(). You cannot let the compiler know too much.

3. Explicitly state that each instance of rcu_dereference() will
reload the pointer, courtesy of Milos Vyletel.

Thanx, Paul

------------------------------------------------------------------------

 b/Documentation/RCU/rcu_dereference.txt |    5 +++++
 b/Documentation/RCU/whatisRCU.txt       |    4 +++-
 b/Documentation/memory-barriers.txt     |    7 +++----
 b/include/linux/spinlock.h              |    2 +-
 4 files changed, 12 insertions(+), 6 deletions(-)

----- Original Message -----

BTW, reading through rcu_dereference.txt, I found a nit:

operatiors -> operators

Very interesting reading :)

Thanks!

Mathieu

Mathieu Desnoyers
EfficiOS Inc.
http://www.efficios.com

Thank you, applied.

Hmmm... Almost like I was trying (and spectacularly failing) to write the document in French. ;-)

Glad you liked it!

Thanx, Paul