Documentation updates for 4.2
cover Documentation updates for 4.2
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(-)
PATCH 1/3 documentation: memory-barriers: Fix smp_mb__before_spinlock() semantics
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(-)
Documentation/memory-barriers.txt +3 -4
@@ -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:
include/linux/spinlock.h +1 -1
@@ -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
Signature · 1 line
1.8.1.5
PATCH 2/3 documentation: Update rcu_dereference.txt based on WG21 discussions
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(+)
Documentation/RCU/rcu_dereference.txt +5 -0
@@ -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
Signature · 1 line
1.8.1.5
Re: [PATCH tip/core/rcu 2/3] documentation: Update rcu_dereference.txt based on WG21 discussions
----- Original Message -----
Quoted 7 lines
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.Signed-off-by Paul E. McKenney <[email protected]>
BTW, reading through rcu_dereference.txt, I found a nit:
operatiors -> operators
Very interesting reading :)
Thanks!
Mathieu
Quoted 25 lines
--- Documentation/RCU/rcu_dereference.txt | 5 +++++ 1 file changed, 5 insertions(+)Documentation/RCU/rcu_dereference.txt +5
-1@@ -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
Signature · 3 lines
Mathieu Desnoyers EfficiOS Inc. http://www.efficios.com
Paul E. McKenney
AppliedRe: [PATCH tip/core/rcu 2/3] documentation: Update rcu_dereference.txt based on WG21 discussions
Quoted 10 lines · Mathieu Desnoyers
----- Original Message -----
Quoted 7 lines
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.Signed-off-by Paul E. McKenney <[email protected]>Reviewed-by Mathieu Desnoyers <[email protected]>
Thank you, applied.
Quoted 3 lines
BTW, reading through rcu_dereference.txt, I found a nit:
operatiors -> operators
Hmmm... Almost like I was trying (and spectacularly failing) to write the document in French. ;-)
Quoted 1 line
Very interesting reading :)
Glad you liked it!
Thanx, Paul
Quoted 35 lines
Thanks!
Mathieu
Quoted 25 lines
--- Documentation/RCU/rcu_dereference.txt | 5 +++++ 1 file changed, 5 insertions(+)Documentation/RCU/rcu_dereference.txt +5
-1@@ -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
Signature · 3 lines
Mathieu Desnoyers EfficiOS Inc. http://www.efficios.com
PATCH 3/3 documentation: State that rcu_dereference() reloads pointer
In reply to Paul E. McKenneyFrom: 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(-)
Documentation/RCU/whatisRCU.txt +3 -1
@@ -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.
Signature · 1 line
1.8.1.5