[PATCH tip/core/rcu 0/2] Documenmtation update for 4.10

[PATCH tip/core/rcu 0/2] Documenmtation update for 4.10

[Paul E. McKenney]

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 tip/core/rcu 1/2] documentation: Present updated RCU guarantee

[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 <paulmck@linux.vnet.ibm.com>
---
 .../RCU/Design/Requirements/Requirements.html      | 25 +++++++++++++++++++++-
 1 file changed, 24 insertions(+), 1 deletion(-)

diff --git a/Documentation/RCU/Design/Requirements/Requirements.html b/Documentation/RCU/Design/Requirements/Requirements.html
index a4d3838130e4..81b40cb83435 100644
--- a/Documentation/RCU/Design/Requirements/Requirements.html
+++ b/Documentation/RCU/Design/Requirements/Requirements.html
@@ -547,7 +547,7 @@ The <tt>rcu_access_pointer()</tt> on line&nbsp;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 &ldquo;When <tt>rcu_read_lock()</tt>
+	doesn't generate any code, why does it matter how it relates
+	to a grace period?&rdquo;
+	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&nbsp;62 and&nbsp;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>&nbsp;</td></tr>
 </table>
-- 
2.5.2

Re: [PATCH tip/core/rcu 1/2] documentation: Present updated RCU guarantee

[Pranith Kumar]

Hi Paul,

On Mon, Nov 14, 2016 at 11:47 AM, Paul E. McKenney
<paulmck@linux.vnet.ibm.com> wrote:
> 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 <paulmck@linux.vnet.ibm.com>
> ---
>  .../RCU/Design/Requirements/Requirements.html      | 25 +++++++++++++++++++++-
>  1 file changed, 24 insertions(+), 1 deletion(-)
>
> diff --git a/Documentation/RCU/Design/Requirements/Requirements.html b/Documentation/RCU/Design/Requirements/Requirements.html
> index a4d3838130e4..81b40cb83435 100644
> --- a/Documentation/RCU/Design/Requirements/Requirements.html
> +++ b/Documentation/RCU/Design/Requirements/Requirements.html
> @@ -547,7 +547,7 @@ The <tt>rcu_access_pointer()</tt> on line&nbsp;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 &ldquo;When <tt>rcu_read_lock()</tt>
> +       doesn't generate any code, why does it matter how it relates
> +       to a grace period?&rdquo;
> +       The answer if that it is not the relationship of

s/if/is?

> +       <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&nbsp;62 and&nbsp;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>&nbsp;</td></tr>
>  </table>
> --
> 2.5.2
>



-- 
Pranith

Re: [PATCH tip/core/rcu 1/2] documentation: Present updated RCU guarantee

[Paul E. McKenney]

On Mon, Nov 14, 2016 at 11:57:46AM -0500, Pranith Kumar wrote:
> Hi Paul,
> 
> On Mon, Nov 14, 2016 at 11:47 AM, Paul E. McKenney
> <paulmck@linux.vnet.ibm.com> wrote:
> > 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 <paulmck@linux.vnet.ibm.com>
> > ---
> >  .../RCU/Design/Requirements/Requirements.html      | 25 +++++++++++++++++++++-
> >  1 file changed, 24 insertions(+), 1 deletion(-)
> >
> > diff --git a/Documentation/RCU/Design/Requirements/Requirements.html b/Documentation/RCU/Design/Requirements/Requirements.html
> > index a4d3838130e4..81b40cb83435 100644
> > --- a/Documentation/RCU/Design/Requirements/Requirements.html
> > +++ b/Documentation/RCU/Design/Requirements/Requirements.html
> > @@ -547,7 +547,7 @@ The <tt>rcu_access_pointer()</tt> on line&nbsp;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 &ldquo;When <tt>rcu_read_lock()</tt>
> > +       doesn't generate any code, why does it matter how it relates
> > +       to a grace period?&rdquo;
> > +       The answer if that it is not the relationship of
> 
> s/if/is?

Good catch, fixed!

							Thanx, Paul

> > +       <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&nbsp;62 and&nbsp;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>&nbsp;</td></tr>
> >  </table>
> > --
> > 2.5.2
> >
> 
> 
> 
> -- 
> Pranith
> 

[PATCH tip/core/rcu 2/2] Documentation/RCU: Fix minor typo

[Paul E. McKenney]

From: Pranith Kumar <bobby.prani@gmail.com>

deference should actually be dereference.

Signed-off-by: Pranith Kumar <bobby.prani@gmail.com>
Reviewed-by: Josh Triplett <josh@joshtriplett.org>
Signed-off-by: Paul E. McKenney <paulmck@linux.vnet.ibm.com>
---
 Documentation/RCU/whatisRCU.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/RCU/whatisRCU.txt b/Documentation/RCU/whatisRCU.txt
index 204422719197..5cbd8b2395b8 100644
--- a/Documentation/RCU/whatisRCU.txt
+++ b/Documentation/RCU/whatisRCU.txt
@@ -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
-- 
2.5.2