[v1,2/2] Documentation: RCU: Refer to ptr_eq()

Commit Message

Mathieu Desnoyers Sept. 29, 2024, 11:16 a.m. UTC

Refer to ptr_eq() in the rcu_dereference() documentation.

ptr_eq() is a mechanism that preserves address dependencies when
comparing pointers, and should be favored when comparing a pointer
obtained from rcu_dereference() against another pointer.

Signed-off-by: Mathieu Desnoyers <[e-mail]>
Cc: Greg Kroah-Hartman <[e-mail]>
Cc: Sebastian Andrzej Siewior <[e-mail]>
Cc: "Paul E. McKenney" <[e-mail]>
Cc: Will Deacon <[e-mail]>
Cc: Peter Zijlstra <[e-mail]>
Cc: Boqun Feng <[e-mail]>
Cc: Alan Stern <[e-mail]>
Cc: John Stultz <[e-mail]>
Cc: Neeraj Upadhyay <[e-mail]>
Cc: Linus Torvalds <[e-mail]>
Cc: Boqun Feng <[e-mail]>
Cc: Frederic Weisbecker <[e-mail]>
Cc: Joel Fernandes <[e-mail]>
Cc: Josh Triplett <[e-mail]>
Cc: Uladzislau Rezki <[e-mail]>
Cc: Steven Rostedt <[e-mail]>
Cc: Lai Jiangshan <[e-mail]>
Cc: Zqiang <[e-mail]>
Cc: Ingo Molnar <[e-mail]>
Cc: Waiman Long <[e-mail]>
Cc: Mark Rutland <[e-mail]>
Cc: Thomas Gleixner <[e-mail]>
Cc: Vlastimil Babka <[e-mail]>
Cc: [e-mail]
Cc: Mateusz Guzik <[e-mail]>
Cc: Gary Guo <[e-mail]>
Cc: Jonas Oberhauser <[e-mail]>
Cc: [e-mail]
Cc: [e-mail]
Cc: [e-mail]
Cc: Nikita Popov <[e-mail]>
Cc: [e-mail]
---
Changes since v0:
- Include feedback from Alan Stern.
---
 Documentation/RCU/rcu_dereference.rst | 32 ++++++++++++++++++++++-----
 1 file changed, 27 insertions(+), 5 deletions(-)

Comments

Paul E. McKenney Sept. 29, 2024, 3:51 p.m. UTC | #1

On Sun, Sep 29, 2024 at 07:16:08AM -0400, Mathieu Desnoyers wrote:
> Refer to ptr_eq() in the rcu_dereference() documentation.
> 
> ptr_eq() is a mechanism that preserves address dependencies when
> comparing pointers, and should be favored when comparing a pointer
> obtained from rcu_dereference() against another pointer.
> 
> Signed-off-by: Mathieu Desnoyers <[e-mail]>
> Cc: Greg Kroah-Hartman <[e-mail]>
> Cc: Sebastian Andrzej Siewior <[e-mail]>
> Cc: "Paul E. McKenney" <[e-mail]>
> Cc: Will Deacon <[e-mail]>
> Cc: Peter Zijlstra <[e-mail]>
> Cc: Boqun Feng <[e-mail]>
> Cc: Alan Stern <[e-mail]>
> Cc: John Stultz <[e-mail]>
> Cc: Neeraj Upadhyay <[e-mail]>
> Cc: Linus Torvalds <[e-mail]>
> Cc: Boqun Feng <[e-mail]>
> Cc: Frederic Weisbecker <[e-mail]>
> Cc: Joel Fernandes <[e-mail]>
> Cc: Josh Triplett <[e-mail]>
> Cc: Uladzislau Rezki <[e-mail]>
> Cc: Steven Rostedt <[e-mail]>
> Cc: Lai Jiangshan <[e-mail]>
> Cc: Zqiang <[e-mail]>
> Cc: Ingo Molnar <[e-mail]>
> Cc: Waiman Long <[e-mail]>
> Cc: Mark Rutland <[e-mail]>
> Cc: Thomas Gleixner <[e-mail]>
> Cc: Vlastimil Babka <[e-mail]>
> Cc: [e-mail]
> Cc: Mateusz Guzik <[e-mail]>
> Cc: Gary Guo <[e-mail]>
> Cc: Jonas Oberhauser <[e-mail]>
> Cc: [e-mail]
> Cc: [e-mail]
> Cc: [e-mail]
> Cc: Nikita Popov <[e-mail]>
> Cc: [e-mail]
> ---
> Changes since v0:
> - Include feedback from Alan Stern.
> ---
>  Documentation/RCU/rcu_dereference.rst | 32 ++++++++++++++++++++++-----
>  1 file changed, 27 insertions(+), 5 deletions(-)
> 
> diff --git a/Documentation/RCU/rcu_dereference.rst b/Documentation/RCU/rcu_dereference.rst
> index 2524dcdadde2..9ef97b7ca74d 100644
> --- a/Documentation/RCU/rcu_dereference.rst
> +++ b/Documentation/RCU/rcu_dereference.rst
> @@ -104,11 +104,12 @@ readers working properly:
>  	after such branches, but can speculate loads, which can again
>  	result in misordering bugs.
>  
> --	Be very careful about comparing pointers obtained from
> -	rcu_dereference() against non-NULL values.  As Linus Torvalds
> -	explained, if the two pointers are equal, the compiler could
> -	substitute the pointer you are comparing against for the pointer
> -	obtained from rcu_dereference().  For example::
> +-	Use operations that preserve address dependencies (such as
> +	"ptr_eq()") to compare pointers obtained from rcu_dereference()
> +	against non-NULL pointers. As Linus Torvalds explained, if the
> +	two pointers are equal, the compiler could substitute the
> +	pointer you are comparing against for the pointer obtained from
> +	rcu_dereference().  For example::
>  
>  		p = rcu_dereference(gp);
>  		if (p == &default_struct)
> @@ -125,6 +126,23 @@ readers working properly:
>  	On ARM and Power hardware, the load from "default_struct.a"
>  	can now be speculated, such that it might happen before the
>  	rcu_dereference().  This could result in bugs due to misordering.
> +	Performing the comparison with "ptr_eq()" ensures the compiler
> +	does not perform such transformation.
> +
> +	If the comparison is against another pointer, the compiler is
> +	allowed to use either pointer for the following accesses, which
> +	loses the address dependency and allows weakly-ordered
> +	architectures such as ARM and PowerPC to speculate the
> +	address-dependent load before rcu_dereference().  For example::
> +
> +		p1 = READ_ONCE(gp);
> +		p2 = rcu_dereference(gp);
> +		if (p1 == p2)
> +			do_default(p2->a);
> +
> +	The compiler can use p1->a rather than p2->a, destroying the
> +	address dependency.  Performing the comparison with "ptr_eq()"
> +	ensures the compiler preserves the address dependencies.

Bitter experience leads me to suggest a "// BUGGY" comment on the "if"
statement in the above example, and a corrected code snippet right here.  :-/

Other than that, loks good!

							Thanx, Paul

>  	However, comparisons are OK in the following cases:
>  
> @@ -204,6 +222,10 @@ readers working properly:
>  		comparison will provide exactly the information that the
>  		compiler needs to deduce the value of the pointer.
>  
> +	When in doubt, use operations that preserve address dependencies
> +	(such as "ptr_eq()") to compare pointers obtained from
> +	rcu_dereference() against non-NULL pointers.
> +
>  -	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
> -- 
> 2.39.2
>

Mathieu Desnoyers Sept. 29, 2024, 4:09 p.m. UTC | #2

On 2024-09-29 17:51, Paul E. McKenney wrote:
> On Sun, Sep 29, 2024 at 07:16:08AM -0400, Mathieu Desnoyers wrote:
>> Refer to ptr_eq() in the rcu_dereference() documentation.
>>
>> ptr_eq() is a mechanism that preserves address dependencies when
>> comparing pointers, and should be favored when comparing a pointer
>> obtained from rcu_dereference() against another pointer.
>>
>> Signed-off-by: Mathieu Desnoyers <[e-mail]>
>> Cc: Greg Kroah-Hartman <[e-mail]>
>> Cc: Sebastian Andrzej Siewior <[e-mail]>
>> Cc: "Paul E. McKenney" <[e-mail]>
>> Cc: Will Deacon <[e-mail]>
>> Cc: Peter Zijlstra <[e-mail]>
>> Cc: Boqun Feng <[e-mail]>
>> Cc: Alan Stern <[e-mail]>
>> Cc: John Stultz <[e-mail]>
>> Cc: Neeraj Upadhyay <[e-mail]>
>> Cc: Linus Torvalds <[e-mail]>
>> Cc: Boqun Feng <[e-mail]>
>> Cc: Frederic Weisbecker <[e-mail]>
>> Cc: Joel Fernandes <[e-mail]>
>> Cc: Josh Triplett <[e-mail]>
>> Cc: Uladzislau Rezki <[e-mail]>
>> Cc: Steven Rostedt <[e-mail]>
>> Cc: Lai Jiangshan <[e-mail]>
>> Cc: Zqiang <[e-mail]>
>> Cc: Ingo Molnar <[e-mail]>
>> Cc: Waiman Long <[e-mail]>
>> Cc: Mark Rutland <[e-mail]>
>> Cc: Thomas Gleixner <[e-mail]>
>> Cc: Vlastimil Babka <[e-mail]>
>> Cc: [e-mail]
>> Cc: Mateusz Guzik <[e-mail]>
>> Cc: Gary Guo <[e-mail]>
>> Cc: Jonas Oberhauser <[e-mail]>
>> Cc: [e-mail]
>> Cc: [e-mail]
>> Cc: [e-mail]
>> Cc: Nikita Popov <[e-mail]>
>> Cc: [e-mail]
>> ---
>> Changes since v0:
>> - Include feedback from Alan Stern.
>> ---
>>   Documentation/RCU/rcu_dereference.rst | 32 ++++++++++++++++++++++-----
>>   1 file changed, 27 insertions(+), 5 deletions(-)
>>
>> diff --git a/Documentation/RCU/rcu_dereference.rst b/Documentation/RCU/rcu_dereference.rst
>> index 2524dcdadde2..9ef97b7ca74d 100644
>> --- a/Documentation/RCU/rcu_dereference.rst
>> +++ b/Documentation/RCU/rcu_dereference.rst
>> @@ -104,11 +104,12 @@ readers working properly:
>>   	after such branches, but can speculate loads, which can again
>>   	result in misordering bugs.
>>   
>> --	Be very careful about comparing pointers obtained from
>> -	rcu_dereference() against non-NULL values.  As Linus Torvalds
>> -	explained, if the two pointers are equal, the compiler could
>> -	substitute the pointer you are comparing against for the pointer
>> -	obtained from rcu_dereference().  For example::
>> +-	Use operations that preserve address dependencies (such as
>> +	"ptr_eq()") to compare pointers obtained from rcu_dereference()
>> +	against non-NULL pointers. As Linus Torvalds explained, if the
>> +	two pointers are equal, the compiler could substitute the
>> +	pointer you are comparing against for the pointer obtained from
>> +	rcu_dereference().  For example::
>>   
>>   		p = rcu_dereference(gp);
>>   		if (p == &default_struct)
>> @@ -125,6 +126,23 @@ readers working properly:
>>   	On ARM and Power hardware, the load from "default_struct.a"
>>   	can now be speculated, such that it might happen before the
>>   	rcu_dereference().  This could result in bugs due to misordering.
>> +	Performing the comparison with "ptr_eq()" ensures the compiler
>> +	does not perform such transformation.
>> +
>> +	If the comparison is against another pointer, the compiler is
>> +	allowed to use either pointer for the following accesses, which
>> +	loses the address dependency and allows weakly-ordered
>> +	architectures such as ARM and PowerPC to speculate the
>> +	address-dependent load before rcu_dereference().  For example::
>> +
>> +		p1 = READ_ONCE(gp);
>> +		p2 = rcu_dereference(gp);
>> +		if (p1 == p2)
>> +			do_default(p2->a);
>> +
>> +	The compiler can use p1->a rather than p2->a, destroying the
>> +	address dependency.  Performing the comparison with "ptr_eq()"
>> +	ensures the compiler preserves the address dependencies.
> 
> Bitter experience leads me to suggest a "// BUGGY" comment on the "if"
> statement in the above example, and a corrected code snippet right here.  :-/

Changing for the following:

+               p1 = READ_ONCE(gp);
+               p2 = rcu_dereference(gp);
+               if (p1 == p2)  /* BUGGY!!! */
+                       do_default(p2->a);
+
+       The compiler can use p1->a rather than p2->a, destroying the
+       address dependency.  Performing the comparison with "ptr_eq()"
+       ensures the compiler preserves the address dependencies.
+       Corrected code::
+
+               p1 = READ_ONCE(gp);
+               p2 = rcu_dereference(gp);
+               if (ptr_eq(p1, p2))
+                       do_default(p2->a);

> 
> Other than that, loks good!

Let me know if I should add an acked-by from you on this
documentation patch as well.

Thanks,

Mathieu

> 
> 							Thanx, Paul
> 
>>   	However, comparisons are OK in the following cases:
>>   
>> @@ -204,6 +222,10 @@ readers working properly:
>>   		comparison will provide exactly the information that the
>>   		compiler needs to deduce the value of the pointer.
>>   
>> +	When in doubt, use operations that preserve address dependencies
>> +	(such as "ptr_eq()") to compare pointers obtained from
>> +	rcu_dereference() against non-NULL pointers.
>> +
>>   -	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
>> -- 
>> 2.39.2
>>

Paul E. McKenney Sept. 29, 2024, 5:07 p.m. UTC | #3

On Sun, Sep 29, 2024 at 12:09:54PM -0400, Mathieu Desnoyers wrote:
> On 2024-09-29 17:51, Paul E. McKenney wrote:
> > On Sun, Sep 29, 2024 at 07:16:08AM -0400, Mathieu Desnoyers wrote:
> > > Refer to ptr_eq() in the rcu_dereference() documentation.
> > > 
> > > ptr_eq() is a mechanism that preserves address dependencies when
> > > comparing pointers, and should be favored when comparing a pointer
> > > obtained from rcu_dereference() against another pointer.
> > > 
> > > Signed-off-by: Mathieu Desnoyers <[e-mail]>
> > > Cc: Greg Kroah-Hartman <[e-mail]>
> > > Cc: Sebastian Andrzej Siewior <[e-mail]>
> > > Cc: "Paul E. McKenney" <[e-mail]>
> > > Cc: Will Deacon <[e-mail]>
> > > Cc: Peter Zijlstra <[e-mail]>
> > > Cc: Boqun Feng <[e-mail]>
> > > Cc: Alan Stern <[e-mail]>
> > > Cc: John Stultz <[e-mail]>
> > > Cc: Neeraj Upadhyay <[e-mail]>
> > > Cc: Linus Torvalds <[e-mail]>
> > > Cc: Boqun Feng <[e-mail]>
> > > Cc: Frederic Weisbecker <[e-mail]>
> > > Cc: Joel Fernandes <[e-mail]>
> > > Cc: Josh Triplett <[e-mail]>
> > > Cc: Uladzislau Rezki <[e-mail]>
> > > Cc: Steven Rostedt <[e-mail]>
> > > Cc: Lai Jiangshan <[e-mail]>
> > > Cc: Zqiang <[e-mail]>
> > > Cc: Ingo Molnar <[e-mail]>
> > > Cc: Waiman Long <[e-mail]>
> > > Cc: Mark Rutland <[e-mail]>
> > > Cc: Thomas Gleixner <[e-mail]>
> > > Cc: Vlastimil Babka <[e-mail]>
> > > Cc: [e-mail]
> > > Cc: Mateusz Guzik <[e-mail]>
> > > Cc: Gary Guo <[e-mail]>
> > > Cc: Jonas Oberhauser <[e-mail]>
> > > Cc: [e-mail]
> > > Cc: [e-mail]
> > > Cc: [e-mail]
> > > Cc: Nikita Popov <[e-mail]>
> > > Cc: [e-mail]
> > > ---
> > > Changes since v0:
> > > - Include feedback from Alan Stern.
> > > ---
> > >   Documentation/RCU/rcu_dereference.rst | 32 ++++++++++++++++++++++-----
> > >   1 file changed, 27 insertions(+), 5 deletions(-)
> > > 
> > > diff --git a/Documentation/RCU/rcu_dereference.rst b/Documentation/RCU/rcu_dereference.rst
> > > index 2524dcdadde2..9ef97b7ca74d 100644
> > > --- a/Documentation/RCU/rcu_dereference.rst
> > > +++ b/Documentation/RCU/rcu_dereference.rst
> > > @@ -104,11 +104,12 @@ readers working properly:
> > >   	after such branches, but can speculate loads, which can again
> > >   	result in misordering bugs.
> > > --	Be very careful about comparing pointers obtained from
> > > -	rcu_dereference() against non-NULL values.  As Linus Torvalds
> > > -	explained, if the two pointers are equal, the compiler could
> > > -	substitute the pointer you are comparing against for the pointer
> > > -	obtained from rcu_dereference().  For example::
> > > +-	Use operations that preserve address dependencies (such as
> > > +	"ptr_eq()") to compare pointers obtained from rcu_dereference()
> > > +	against non-NULL pointers. As Linus Torvalds explained, if the
> > > +	two pointers are equal, the compiler could substitute the
> > > +	pointer you are comparing against for the pointer obtained from
> > > +	rcu_dereference().  For example::
> > >   		p = rcu_dereference(gp);
> > >   		if (p == &default_struct)
> > > @@ -125,6 +126,23 @@ readers working properly:
> > >   	On ARM and Power hardware, the load from "default_struct.a"
> > >   	can now be speculated, such that it might happen before the
> > >   	rcu_dereference().  This could result in bugs due to misordering.
> > > +	Performing the comparison with "ptr_eq()" ensures the compiler
> > > +	does not perform such transformation.
> > > +
> > > +	If the comparison is against another pointer, the compiler is
> > > +	allowed to use either pointer for the following accesses, which
> > > +	loses the address dependency and allows weakly-ordered
> > > +	architectures such as ARM and PowerPC to speculate the
> > > +	address-dependent load before rcu_dereference().  For example::
> > > +
> > > +		p1 = READ_ONCE(gp);
> > > +		p2 = rcu_dereference(gp);
> > > +		if (p1 == p2)
> > > +			do_default(p2->a);
> > > +
> > > +	The compiler can use p1->a rather than p2->a, destroying the
> > > +	address dependency.  Performing the comparison with "ptr_eq()"
> > > +	ensures the compiler preserves the address dependencies.
> > 
> > Bitter experience leads me to suggest a "// BUGGY" comment on the "if"
> > statement in the above example, and a corrected code snippet right here.  :-/
> 
> Changing for the following:
> 
> +               p1 = READ_ONCE(gp);
> +               p2 = rcu_dereference(gp);
> +               if (p1 == p2)  /* BUGGY!!! */
> +                       do_default(p2->a);
> +
> +       The compiler can use p1->a rather than p2->a, destroying the
> +       address dependency.  Performing the comparison with "ptr_eq()"
> +       ensures the compiler preserves the address dependencies.
> +       Corrected code::
> +
> +               p1 = READ_ONCE(gp);
> +               p2 = rcu_dereference(gp);
> +               if (ptr_eq(p1, p2))
> +                       do_default(p2->a);
> 
> > 
> > Other than that, loks good!
> 
> Let me know if I should add an acked-by from you on this
> documentation patch as well.

Much better!

Acked-by: Paul E. McKenney <[e-mail]>

> Thanks,
> 
> Mathieu
> 
> > 
> > 							Thanx, Paul
> > 
> > >   	However, comparisons are OK in the following cases:
> > > @@ -204,6 +222,10 @@ readers working properly:
> > >   		comparison will provide exactly the information that the
> > >   		compiler needs to deduce the value of the pointer.
> > > +	When in doubt, use operations that preserve address dependencies
> > > +	(such as "ptr_eq()") to compare pointers obtained from
> > > +	rcu_dereference() against non-NULL pointers.
> > > +
> > >   -	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
> > > -- 
> > > 2.39.2
> > > 
> 
> -- 
> Mathieu Desnoyers
> EfficiOS Inc.
> https://www.efficios.com
>

Patch

diff --git a/Documentation/RCU/rcu_dereference.rst b/Documentation/RCU/rcu_dereference.rst
index 2524dcdadde2..9ef97b7ca74d 100644
--- a/Documentation/RCU/rcu_dereference.rst
+++ b/Documentation/RCU/rcu_dereference.rst
@@ -104,11 +104,12 @@  readers working properly:
 	after such branches, but can speculate loads, which can again
 	result in misordering bugs.
 
--	Be very careful about comparing pointers obtained from
-	rcu_dereference() against non-NULL values.  As Linus Torvalds
-	explained, if the two pointers are equal, the compiler could
-	substitute the pointer you are comparing against for the pointer
-	obtained from rcu_dereference().  For example::
+-	Use operations that preserve address dependencies (such as
+	"ptr_eq()") to compare pointers obtained from rcu_dereference()
+	against non-NULL pointers. As Linus Torvalds explained, if the
+	two pointers are equal, the compiler could substitute the
+	pointer you are comparing against for the pointer obtained from
+	rcu_dereference().  For example::
 
 		p = rcu_dereference(gp);
 		if (p == &default_struct)
@@ -125,6 +126,23 @@  readers working properly:
 	On ARM and Power hardware, the load from "default_struct.a"
 	can now be speculated, such that it might happen before the
 	rcu_dereference().  This could result in bugs due to misordering.
+	Performing the comparison with "ptr_eq()" ensures the compiler
+	does not perform such transformation.
+
+	If the comparison is against another pointer, the compiler is
+	allowed to use either pointer for the following accesses, which
+	loses the address dependency and allows weakly-ordered
+	architectures such as ARM and PowerPC to speculate the
+	address-dependent load before rcu_dereference().  For example::
+
+		p1 = READ_ONCE(gp);
+		p2 = rcu_dereference(gp);
+		if (p1 == p2)
+			do_default(p2->a);
+
+	The compiler can use p1->a rather than p2->a, destroying the
+	address dependency.  Performing the comparison with "ptr_eq()"
+	ensures the compiler preserves the address dependencies.
 
 	However, comparisons are OK in the following cases:
 
@@ -204,6 +222,10 @@  readers working properly:
 		comparison will provide exactly the information that the
 		compiler needs to deduce the value of the pointer.
 
+	When in doubt, use operations that preserve address dependencies
+	(such as "ptr_eq()") to compare pointers obtained from
+	rcu_dereference() against non-NULL pointers.
+
 -	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