[PATCH tip/core/rcu 0/3] Documentation updates for 4.2

[PATCH tip/core/rcu 0/3] Documentation updates for 4.2

[Paul E. McKenney]

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 tip/core/rcu 1/3] documentation: memory-barriers: Fix smp_mb__before_spinlock() semantics

[Paul E. McKenney]

From: Will Deacon <will.deacon@arm.com>

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.

Cc: Oleg Nesterov <oleg@redhat.com>
Cc: "Paul E. McKenney" <paulmck@linux.vnet.ibm.com>
Cc: Peter Zijlstra <peterz@infradead.org>
Signed-off-by: Will Deacon <will.deacon@arm.com>
Signed-off-by: Paul E. McKenney <paulmck@linux.vnet.ibm.com>
---
 Documentation/memory-barriers.txt | 7 +++----
 include/linux/spinlock.h          | 2 +-
 2 files changed, 4 insertions(+), 5 deletions(-)

diff --git a/Documentation/memory-barriers.txt b/Documentation/memory-barriers.txt
index f95746189b5d..1f362fd2ecb4 100644
--- a/Documentation/memory-barriers.txt
+++ b/Documentation/memory-barriers.txt
@@ -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:
 
diff --git a/include/linux/spinlock.h b/include/linux/spinlock.h
index 3e18379dfa6f..0063b24b4f36 100644
--- a/include/linux/spinlock.h
+++ b/include/linux/spinlock.h
@@ -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

[PATCH tip/core/rcu 2/3] documentation: Update rcu_dereference.txt based on WG21 discussions

[Paul E. McKenney]

From: "Paul E. McKenney" <paulmck@linux.vnet.ibm.com>

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 <paulmck@linux.vnet.ibm.com>
---
 Documentation/RCU/rcu_dereference.txt | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/Documentation/RCU/rcu_dereference.txt b/Documentation/RCU/rcu_dereference.txt
index ceb05da5a5ac..2d05c9241a33 100644
--- a/Documentation/RCU/rcu_dereference.txt
+++ b/Documentation/RCU/rcu_dereference.txt
@@ -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

[PATCH tip/core/rcu 3/3] documentation: State that rcu_dereference() reloads pointer

[Paul E. McKenney]

From: Milos Vyletel <milos@redhat.com>

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

Reported-by: Jeff Haran <jeff.haran@citrix.com>
Signed-off-by: Milos Vyletel <milos@redhat.com>
Reviewed-by: Steven Rostedt <rostedt@goodmis.org>
Signed-off-by: Paul E. McKenney <paulmck@linux.vnet.ibm.com>
---
 Documentation/RCU/whatisRCU.txt | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/Documentation/RCU/whatisRCU.txt b/Documentation/RCU/whatisRCU.txt
index 88dfce182f66..16622c9e86b5 100644
--- a/Documentation/RCU/whatisRCU.txt
+++ b/Documentation/RCU/whatisRCU.txt
@@ -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

Re: [PATCH tip/core/rcu 2/3] documentation: Update rcu_dereference.txt based on WG21 discussions

[Mathieu Desnoyers]

----- Original Message -----
> From: "Paul E. McKenney" <paulmck@linux.vnet.ibm.com>
> 
> 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 <paulmck@linux.vnet.ibm.com>

Reviewed-by: Mathieu Desnoyers <mathieu.desnoyers@efficios.com>

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

operatiors -> operators

Very interesting reading :)

Thanks!

Mathieu

> ---
>  Documentation/RCU/rcu_dereference.txt | 5 +++++
>  1 file changed, 5 insertions(+)
> 
> diff --git a/Documentation/RCU/rcu_dereference.txt
> b/Documentation/RCU/rcu_dereference.txt
> index ceb05da5a5ac..2d05c9241a33 100644
> --- a/Documentation/RCU/rcu_dereference.txt
> +++ b/Documentation/RCU/rcu_dereference.txt
> @@ -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
> 
> 

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

Re: [PATCH tip/core/rcu 2/3] documentation: Update rcu_dereference.txt based on WG21 discussions

[Paul E. McKenney]

On Wed, May 13, 2015 at 06:33:10PM +0000, Mathieu Desnoyers wrote:
> ----- Original Message -----
> > From: "Paul E. McKenney" <paulmck@linux.vnet.ibm.com>
> > 
> > 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 <paulmck@linux.vnet.ibm.com>
> 
> Reviewed-by: Mathieu Desnoyers <mathieu.desnoyers@efficios.com>

Thank you, applied.

> 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.  ;-)

> Very interesting reading :)

Glad you liked it!

							Thanx, Paul

> Thanks!
> 
> Mathieu
> 
> > ---
> >  Documentation/RCU/rcu_dereference.txt | 5 +++++
> >  1 file changed, 5 insertions(+)
> > 
> > diff --git a/Documentation/RCU/rcu_dereference.txt
> > b/Documentation/RCU/rcu_dereference.txt
> > index ceb05da5a5ac..2d05c9241a33 100644
> > --- a/Documentation/RCU/rcu_dereference.txt
> > +++ b/Documentation/RCU/rcu_dereference.txt
> > @@ -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
> > 
> > 
> 
> -- 
> Mathieu Desnoyers
> EfficiOS Inc.
> http://www.efficios.com
>