Documenmtation update for 4.10
Subsystems (2)
cover Documenmtation update for 4.10
Hello!
This series provides a couple of documentation updates:
1. Provide an updated description of RCU's grace-period guarantee
based on recent memory-model work. This does not change the way that RCU behaves, but rather presents a more accurate view of how it works. The difference is subtle, so most people won't need to care.
2. Fix a "deference" -> "dereference" typo, courtesy of Pranith
Kumar.
Thanx, Paul
------------------------------------------------------------------------
Design/Requirements/Requirements.html | 25 ++++++++++++++++++++++++- whatisRCU.txt | 2 +- 2 files changed, 25 insertions(+), 2 deletions(-)
PATCH 1/2 documentation: Present updated RCU guarantee
Recent memory-model work deduces the relationships of RCU read-side critical sections and grace periods based on the relationships of accesses within a critical section and accesses preceding and following the grace period. This commit therefore adds this viewpoint.
Signed-off-by Paul E. McKenney <[email protected]>
--- .../RCU/Design/Requirements/Requirements.html | 25 +++++++++++++++++++++- 1 file changed, 24 insertions(+), 1 deletion(-)
Documentation/RCU/Design/Requirements/Requirements.html +24 -1
@@ -547,7 +547,7 @@ The <tt>rcu_access_pointer()</tt> on line 6 is similar to It could reuse a value formerly fetched from this same pointer. It could also fetch the pointer from <tt>gp</tt> in a byte-at-a-time manner, resulting in <i>load tearing</i>, in turn resulting a bytewise - mash-up of two distince pointer values. + mash-up of two distinct pointer values. It might even use value-speculation optimizations, where it makes a wrong guess, but by the time it gets around to checking the value, an update has changed the pointer to match the wrong guess.
@@ -659,6 +659,29 @@ systems with more than one CPU: In other words, a given instance of <tt>synchronize_rcu()</tt> can avoid waiting on a given RCU read-side critical section only if it can prove that <tt>synchronize_rcu()</tt> started first. + + <p> + A related question is “When <tt>rcu_read_lock()</tt> + doesn't generate any code, why does it matter how it relates + to a grace period?” + The answer if that it is not the relationship of + <tt>rcu_read_lock()</tt> itself that is important, but rather + the relationship of the code within the enclosed RCU read-side + critical section to the code preceding and following the + grace period. + If we take this viewpoint, then a given RCU read-side critical + section begins before a given grace period when some access + preceding the grace period observes the effect of some access + within the critical section, in which case none of the accesses + within the critical section may observe the effects of any + access following the grace period. + + <p> + As of late 2016, mathematical models of RCU take this + viewpoint, for example, see slides 62 and 63 + of the + <a href="http://www2.rdrop.com/users/paulmck/scalability/paper/LinuxMM.2016.10.04c.LCE.pdf">2016 LinuxCon EU</a> + presentation. </font></td></tr> <tr><td> </td></tr> </table>
Signature · 1 line
2.5.2
Re: [PATCH tip/core/rcu 1/2] documentation: Present updated RCU guarantee
Hi Paul,
Quoted 24 lines · Paul E. McKenney
Recent memory-model work deduces the relationships of RCU read-side critical sections and grace periods based on the relationships of accesses within a critical section and accesses preceding and following the grace period. This commit therefore adds this viewpoint.
Signed-off-by Paul E. McKenney <[email protected]>--- .../RCU/Design/Requirements/Requirements.html | 25 +++++++++++++++++++++- 1 file changed, 24 insertions(+), 1 deletion(-)Documentation/RCU/Design/Requirements/Requirements.html +1
-1@@ -547,7 +547,7 @@ The <tt>rcu_access_pointer()</tt> on line 6 is similar to It could reuse a value formerly fetched from this same pointer. It could also fetch the pointer from <tt>gp</tt> in a byte-at-a-time manner, resulting in <i>load tearing</i>, in turn resulting a bytewise - mash-up of two distince pointer values. + mash-up of two distinct pointer values. It might even use value-speculation optimizations, where it makes a wrong guess, but by the time it gets around to checking the value, an update has changed the pointer to match the wrong guess.
Documentation/RCU/Design/Requirements/Requirements.html systems with more than one CPU: · line 667
Quoted 9 lines
Documentation/RCU/Design/Requirements/Requirements.html +6
-0@@ -659,6 +659,29 @@ systems with more than one CPU: In other words, a given instance of <tt>synchronize_rcu()</tt> can avoid waiting on a given RCU read-side critical section only if it can prove that <tt>synchronize_rcu()</tt> started first. + + <p> + A related question is “When <tt>rcu_read_lock()</tt> + doesn't generate any code, why does it matter how it relates + to a grace period?” + The answer if that it is not the relationship of
s/if/is?
Quoted 23 lines
Documentation/RCU/Design/Requirements/Requirements.html +17
-1+ <tt>rcu_read_lock()</tt> itself that is important, but rather + the relationship of the code within the enclosed RCU read-side + critical section to the code preceding and following the + grace period. + If we take this viewpoint, then a given RCU read-side critical + section begins before a given grace period when some access + preceding the grace period observes the effect of some access + within the critical section, in which case none of the accesses + within the critical section may observe the effects of any + access following the grace period. + + <p> + As of late 2016, mathematical models of RCU take this + viewpoint, for example, see slides 62 and 63 + of the + <a href="http://www2.rdrop.com/users/paulmck/scalability/paper/LinuxMM.2016.10.04c.LCE.pdf">2016 LinuxCon EU</a> + presentation. </font></td></tr> <tr><td> </td></tr> </table> --2.5.2
Signature · 1 line
Pranith
Re: [PATCH tip/core/rcu 1/2] documentation: Present updated RCU guarantee
Quoted 31 lines · Pranith Kumar
Hi Paul,
Quoted 27 lines · Paul E. McKenney
Recent memory-model work deduces the relationships of RCU read-side critical sections and grace periods based on the relationships of accesses within a critical section and accesses preceding and following the grace period. This commit therefore adds this viewpoint.
Signed-off-by Paul E. McKenney <[email protected]>--- .../RCU/Design/Requirements/Requirements.html | 25 +++++++++++++++++++++- 1 file changed, 24 insertions(+), 1 deletion(-)Documentation/RCU/Design/Requirements/Requirements.html +1
-1@@ -547,7 +547,7 @@ The <tt>rcu_access_pointer()</tt> on line 6 is similar to It could reuse a value formerly fetched from this same pointer. It could also fetch the pointer from <tt>gp</tt> in a byte-at-a-time manner, resulting in <i>load tearing</i>, in turn resulting a bytewise - mash-up of two distince pointer values. + mash-up of two distinct pointer values. It might even use value-speculation optimizations, where it makes a wrong guess, but by the time it gets around to checking the value, an update has changed the pointer to match the wrong guess.@@ -659,6 +659,29 @@ systems with more than one CPU: In other words, a given instance of <tt>synchronize_rcu()</tt> can avoid waiting on a given RCU read-side critical section only if it can prove that <tt>synchronize_rcu()</tt> started first.
Quoted 8 lines
Documentation/RCU/Design/Requirements/Requirements.html systems with more than one CPU: · line 667
Quoted 6 lines
Documentation/RCU/Design/Requirements/Requirements.html +6
-0+ + <p> + A related question is “When <tt>rcu_read_lock()</tt> + doesn't generate any code, why does it matter how it relates + to a grace period?” + The answer if that it is not the relationship ofs/if/is?
Good catch, fixed!
Thanx, Paul
Quoted 29 lines
Quoted 23 lines
Documentation/RCU/Design/Requirements/Requirements.html +17
-1+ <tt>rcu_read_lock()</tt> itself that is important, but rather + the relationship of the code within the enclosed RCU read-side + critical section to the code preceding and following the + grace period. + If we take this viewpoint, then a given RCU read-side critical + section begins before a given grace period when some access + preceding the grace period observes the effect of some access + within the critical section, in which case none of the accesses + within the critical section may observe the effects of any + access following the grace period. + + <p> + As of late 2016, mathematical models of RCU take this + viewpoint, for example, see slides 62 and 63 + of the + <a href="http://www2.rdrop.com/users/paulmck/scalability/paper/LinuxMM.2016.10.04c.LCE.pdf">2016 LinuxCon EU</a> + presentation. </font></td></tr> <tr><td> </td></tr> </table> --2.5.2
Signature · 1 line
Pranith
PATCH 2/2 Documentation/RCU: Fix minor typo
In reply to Paul E. McKenneyFrom: Pranith Kumar <[email protected]>
deference should actually be dereference.
Signed-off-by Pranith Kumar <[email protected]>
Reviewed-by Josh Triplett <[email protected]>
Signed-off-by Paul E. McKenney <[email protected]>
--- Documentation/RCU/whatisRCU.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/RCU/whatisRCU.txt +1 -1
@@ -237,7 +237,7 @@ rcu_dereference() The reader uses rcu_dereference() to fetch an RCU-protected pointer, which returns a value that may then be safely - dereferenced. Note that rcu_deference() does not actually + dereferenced. Note that rcu_dereference() does not actually dereference the pointer, instead, it protects the pointer for later dereferencing. It also executes any needed memory-barrier instructions for a given CPU architecture. Currently, only Alpha
Signature · 1 line
2.5.2