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

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

[Paul E. McKenney]

Hello!

This series provides a few documentation updates:

1.	Update stall-warning documentation to catch up with recent updates.

2.	Add a reference to the new vmstat-avoidance patch to the
	file describing how to quiet per-CPU kthreads.

3.	Fix a typo in Documentation/RCU/checklist.txt, courtesy of
	Michael Opdenacker.

							Thanx, Paul


 b/Documentation/RCU/checklist.txt           |    2 +-
 b/Documentation/RCU/stallwarn.txt           |   22 +++++++++++++++-------
 b/Documentation/kernel-per-CPU-kthreads.txt |   17 +++++++++++------
 3 files changed, 27 insertions(+), 14 deletions(-)

[PATCH tip/core/rcu 1/3] rcu: Update stall-warning documentation

[Paul E. McKenney]

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

Signed-off-by: Paul E. McKenney <paulmck@linux.vnet.ibm.com>
---
 Documentation/RCU/stallwarn.txt | 22 +++++++++++++++-------
 1 file changed, 15 insertions(+), 7 deletions(-)

diff --git a/Documentation/RCU/stallwarn.txt b/Documentation/RCU/stallwarn.txt
index 8e9359d..6f3a005 100644
--- a/Documentation/RCU/stallwarn.txt
+++ b/Documentation/RCU/stallwarn.txt
@@ -12,12 +12,12 @@ CONFIG_RCU_CPU_STALL_TIMEOUT
 	This kernel configuration parameter defines the period of time
 	that RCU will wait from the beginning of a grace period until it
 	issues an RCU CPU stall warning.  This time period is normally
-	sixty seconds.
+	21 seconds.
 
 	This configuration parameter may be changed at runtime via the
 	/sys/module/rcutree/parameters/rcu_cpu_stall_timeout, however
 	this parameter is checked only at the beginning of a cycle.
-	So if you are 30 seconds into a 70-second stall, setting this
+	So if you are 10 seconds into a 40-second stall, setting this
 	sysfs parameter to (say) five will shorten the timeout for the
 	-next- stall, or the following warning for the current stall
 	(assuming the stall lasts long enough).  It will not affect the
@@ -32,7 +32,7 @@ CONFIG_RCU_CPU_STALL_VERBOSE
 	also dump the stacks of any tasks that are blocking the current
 	RCU-preempt grace period.
 
-RCU_CPU_STALL_INFO
+CONFIG_RCU_CPU_STALL_INFO
 
 	This kernel configuration parameter causes the stall warning to
 	print out additional per-CPU diagnostic information, including
@@ -43,7 +43,8 @@ RCU_STALL_DELAY_DELTA
 	Although the lockdep facility is extremely useful, it does add
 	some overhead.  Therefore, under CONFIG_PROVE_RCU, the
 	RCU_STALL_DELAY_DELTA macro allows five extra seconds before
-	giving an RCU CPU stall warning message.
+	giving an RCU CPU stall warning message.  (This is a cpp
+	macro, not a kernel configuration parameter.)
 
 RCU_STALL_RAT_DELAY
 
@@ -52,7 +53,8 @@ RCU_STALL_RAT_DELAY
 	However, if the offending CPU does not detect its own stall in
 	the number of jiffies specified by RCU_STALL_RAT_DELAY, then
 	some other CPU will complain.  This delay is normally set to
-	two jiffies.
+	two jiffies.  (This is a cpp macro, not a kernel configuration
+	parameter.)
 
 When a CPU detects that it is stalling, it will print a message similar
 to the following:
@@ -86,7 +88,12 @@ printing, there will be a spurious stall-warning message:
 
 INFO: rcu_bh_state detected stalls on CPUs/tasks: { } (detected by 4, 2502 jiffies)
 
-This is rare, but does happen from time to time in real life.
+This is rare, but does happen from time to time in real life.  It is also
+possible for a zero-jiffy stall to be flagged in this case, depending
+on how the stall warning and the grace-period initialization happen to
+interact.  Please note that it is not possible to entirely eliminate this
+sort of false positive without resorting to things like stop_machine(),
+which is overkill for this sort of problem.
 
 If the CONFIG_RCU_CPU_STALL_INFO kernel configuration parameter is set,
 more information is printed with the stall-warning message, for example:
@@ -216,4 +223,5 @@ that portion of the stack which remains the same from trace to trace.
 If you can reliably trigger the stall, ftrace can be quite helpful.
 
 RCU bugs can often be debugged with the help of CONFIG_RCU_TRACE
-and with RCU's event tracing.
+and with RCU's event tracing.  For information on RCU's event tracing,
+see include/trace/events/rcu.h.
-- 
1.8.1.5

[PATCH tip/core/rcu 2/3] kthread: Add pointer to vmstat-avoidance patch

[Paul E. McKenney]

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

Signed-off-by: Paul E. McKenney <paulmck@linux.vnet.ibm.com>
---
 Documentation/kernel-per-CPU-kthreads.txt | 17 +++++++++++------
 1 file changed, 11 insertions(+), 6 deletions(-)

diff --git a/Documentation/kernel-per-CPU-kthreads.txt b/Documentation/kernel-per-CPU-kthreads.txt
index 32351bf..827104f 100644
--- a/Documentation/kernel-per-CPU-kthreads.txt
+++ b/Documentation/kernel-per-CPU-kthreads.txt
@@ -181,12 +181,17 @@ To reduce its OS jitter, do any of the following:
 		make sure that this is safe on your particular system.
 	d.	It is not possible to entirely get rid of OS jitter
 		from vmstat_update() on CONFIG_SMP=y systems, but you
-		can decrease its frequency by writing a large value to
-		/proc/sys/vm/stat_interval.  The default value is HZ,
-		for an interval of one second.  Of course, larger values
-		will make your virtual-memory statistics update more
-		slowly.  Of course, you can also run your workload at
-		a real-time priority, thus preempting vmstat_update().
+		can decrease its frequency by writing a large value
+		to /proc/sys/vm/stat_interval.	The default value is
+		HZ, for an interval of one second.  Of course, larger
+		values will make your virtual-memory statistics update
+		more slowly.  Of course, you can also run your workload
+		at a real-time priority, thus preempting vmstat_update(),
+		but if your workload is CPU-bound, this is a bad idea.
+		However, there is an RFC patch from Christoph Lameter
+		(based on an earlier one from Gilad Ben-Yossef) that
+		reduces or even eliminates vmstat overhead for some
+		workloads at https://lkml.org/lkml/2013/9/4/379.
 	e.	If running on high-end powerpc servers, build with
 		CONFIG_PPC_RTAS_DAEMON=n.  This prevents the RTAS
 		daemon from running on each CPU every second or so.
-- 
1.8.1.5

[PATCH tip/core/rcu 3/3] rcu: Fix occurrence of "the the" in checklist.txt

[Paul E. McKenney]

From: Michael Opdenacker <michael.opdenacker@free-electrons.com>

Signed-off-by: Michael Opdenacker <michael.opdenacker@free-electrons.com>
Signed-off-by: Paul E. McKenney <paulmck@linux.vnet.ibm.com>
---
 Documentation/RCU/checklist.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/RCU/checklist.txt b/Documentation/RCU/checklist.txt
index 7703ec7..ad6cba4 100644
--- a/Documentation/RCU/checklist.txt
+++ b/Documentation/RCU/checklist.txt
@@ -203,7 +203,7 @@ over a rather long period of time, but improvements are always welcome!
 	the corresponding readers must disable preemption, possibly
 	by calling rcu_read_lock_sched() and rcu_read_unlock_sched().
 	If the updater uses synchronize_srcu() or call_srcu(),
-	the the corresponding readers must use srcu_read_lock() and
+	the corresponding readers must use srcu_read_lock() and
 	srcu_read_unlock(), and with the same srcu_struct.  The rules for
 	the expedited primitives are the same as for their non-expedited
 	counterparts.  Mixing things up will result in confusion and
-- 
1.8.1.5

Re: [PATCH tip/core/rcu 3/3] rcu: Fix occurrence of "the the" in checklist.txt

[Josh Triplett]

On Tue, Sep 24, 2013 at 06:17:23PM -0700, Paul E. McKenney wrote:
> From: Michael Opdenacker <michael.opdenacker@free-electrons.com>
> 
> Signed-off-by: Michael Opdenacker <michael.opdenacker@free-electrons.com>
> Signed-off-by: Paul E. McKenney <paulmck@linux.vnet.ibm.com>
> ---

See comment below.

>  Documentation/RCU/checklist.txt | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/Documentation/RCU/checklist.txt b/Documentation/RCU/checklist.txt
> index 7703ec7..ad6cba4 100644
> --- a/Documentation/RCU/checklist.txt
> +++ b/Documentation/RCU/checklist.txt
> @@ -203,7 +203,7 @@ over a rather long period of time, but improvements are always welcome!
>  	the corresponding readers must disable preemption, possibly
>  	by calling rcu_read_lock_sched() and rcu_read_unlock_sched().
>  	If the updater uses synchronize_srcu() or call_srcu(),
> -	the the corresponding readers must use srcu_read_lock() and
> +	the corresponding readers must use srcu_read_lock() and

I think this may have actually been a typo for "then", as in "If the
updater uses ..., then the corresponding readers must use ...".

>  	srcu_read_unlock(), and with the same srcu_struct.  The rules for
>  	the expedited primitives are the same as for their non-expedited
>  	counterparts.  Mixing things up will result in confusion and
> -- 
> 1.8.1.5
> 

Re: [PATCH tip/core/rcu 0/3] Documentation updates for 3.13

[Josh Triplett]

On Tue, Sep 24, 2013 at 06:16:57PM -0700, Paul E. McKenney wrote:
> Hello!
> 
> This series provides a few documentation updates:
> 
> 1.	Update stall-warning documentation to catch up with recent updates.
> 
> 2.	Add a reference to the new vmstat-avoidance patch to the
> 	file describing how to quiet per-CPU kthreads.
> 
> 3.	Fix a typo in Documentation/RCU/checklist.txt, courtesy of
> 	Michael Opdenacker.

I replied to 3 with a comment; for 1 and 2:
Reviewed-by: Josh Triplett <josh@joshtriplett.org>

Re: [PATCH tip/core/rcu 3/3] rcu: Fix occurrence of "the the" in checklist.txt

[Paul E. McKenney]

On Tue, Sep 24, 2013 at 08:47:39PM -0700, Josh Triplett wrote:
> On Tue, Sep 24, 2013 at 06:17:23PM -0700, Paul E. McKenney wrote:
> > From: Michael Opdenacker <michael.opdenacker@free-electrons.com>
> > 
> > Signed-off-by: Michael Opdenacker <michael.opdenacker@free-electrons.com>
> > Signed-off-by: Paul E. McKenney <paulmck@linux.vnet.ibm.com>
> > ---
> 
> See comment below.
> 
> >  Documentation/RCU/checklist.txt | 2 +-
> >  1 file changed, 1 insertion(+), 1 deletion(-)
> > 
> > diff --git a/Documentation/RCU/checklist.txt b/Documentation/RCU/checklist.txt
> > index 7703ec7..ad6cba4 100644
> > --- a/Documentation/RCU/checklist.txt
> > +++ b/Documentation/RCU/checklist.txt
> > @@ -203,7 +203,7 @@ over a rather long period of time, but improvements are always welcome!
> >  	the corresponding readers must disable preemption, possibly
> >  	by calling rcu_read_lock_sched() and rcu_read_unlock_sched().
> >  	If the updater uses synchronize_srcu() or call_srcu(),
> > -	the the corresponding readers must use srcu_read_lock() and
> > +	the corresponding readers must use srcu_read_lock() and
> 
> I think this may have actually been a typo for "then", as in "If the
> updater uses ..., then the corresponding readers must use ...".

Good point -- that would make the sentence construction parallel with
the surrounding sentences.  Updated patch below.

							Thanx, Paul

> >  	srcu_read_unlock(), and with the same srcu_struct.  The rules for
> >  	the expedited primitives are the same as for their non-expedited
> >  	counterparts.  Mixing things up will result in confusion and
> > -- 
> > 1.8.1.5

rcu: Fix occurrence of "the the" in checklist.txt

Signed-off-by: Michael Opdenacker <michael.opdenacker@free-electrons.com>
Signed-off-by: Paul E. McKenney <paulmck@linux.vnet.ibm.com>
[ paulmck: Add "then" as suggested by Josh Triplett. ]

diff --git a/Documentation/RCU/checklist.txt b/Documentation/RCU/checklist.txt
index 7703ec7..9126619 100644
--- a/Documentation/RCU/checklist.txt
+++ b/Documentation/RCU/checklist.txt
@@ -202,8 +202,8 @@ over a rather long period of time, but improvements are always welcome!
 	updater uses call_rcu_sched() or synchronize_sched(), then
 	the corresponding readers must disable preemption, possibly
 	by calling rcu_read_lock_sched() and rcu_read_unlock_sched().
-	If the updater uses synchronize_srcu() or call_srcu(),
-	the the corresponding readers must use srcu_read_lock() and
+	If the updater uses synchronize_srcu() or call_srcu(), then
+	the corresponding readers must use srcu_read_lock() and
 	srcu_read_unlock(), and with the same srcu_struct.  The rules for
 	the expedited primitives are the same as for their non-expedited
 	counterparts.  Mixing things up will result in confusion and

Re: [PATCH tip/core/rcu 0/3] Documentation updates for 3.13

[Paul E. McKenney]

On Tue, Sep 24, 2013 at 08:48:18PM -0700, Josh Triplett wrote:
> On Tue, Sep 24, 2013 at 06:16:57PM -0700, Paul E. McKenney wrote:
> > Hello!
> > 
> > This series provides a few documentation updates:
> > 
> > 1.	Update stall-warning documentation to catch up with recent updates.
> > 
> > 2.	Add a reference to the new vmstat-avoidance patch to the
> > 	file describing how to quiet per-CPU kthreads.
> > 
> > 3.	Fix a typo in Documentation/RCU/checklist.txt, courtesy of
> > 	Michael Opdenacker.
> 
> I replied to 3 with a comment; for 1 and 2:
> Reviewed-by: Josh Triplett <josh@joshtriplett.org>

Thank you for the review, applied to 1 and 2.

							Thanx, Paul

Re: [PATCH tip/core/rcu 3/3] rcu: Fix occurrence of "the the" in checklist.txt

[Josh Triplett]

On Wed, Sep 25, 2013 at 06:55:27AM -0700, Paul E. McKenney wrote:
> On Tue, Sep 24, 2013 at 08:47:39PM -0700, Josh Triplett wrote:
> > On Tue, Sep 24, 2013 at 06:17:23PM -0700, Paul E. McKenney wrote:
> > > From: Michael Opdenacker <michael.opdenacker@free-electrons.com>
> > > 
> > > Signed-off-by: Michael Opdenacker <michael.opdenacker@free-electrons.com>
> > > Signed-off-by: Paul E. McKenney <paulmck@linux.vnet.ibm.com>
> > > ---
> > 
> > See comment below.
> > 
> > >  Documentation/RCU/checklist.txt | 2 +-
> > >  1 file changed, 1 insertion(+), 1 deletion(-)
> > > 
> > > diff --git a/Documentation/RCU/checklist.txt b/Documentation/RCU/checklist.txt
> > > index 7703ec7..ad6cba4 100644
> > > --- a/Documentation/RCU/checklist.txt
> > > +++ b/Documentation/RCU/checklist.txt
> > > @@ -203,7 +203,7 @@ over a rather long period of time, but improvements are always welcome!
> > >  	the corresponding readers must disable preemption, possibly
> > >  	by calling rcu_read_lock_sched() and rcu_read_unlock_sched().
> > >  	If the updater uses synchronize_srcu() or call_srcu(),
> > > -	the the corresponding readers must use srcu_read_lock() and
> > > +	the corresponding readers must use srcu_read_lock() and
> > 
> > I think this may have actually been a typo for "then", as in "If the
> > updater uses ..., then the corresponding readers must use ...".
> 
> Good point -- that would make the sentence construction parallel with
> the surrounding sentences.  Updated patch below.
> 
> 							Thanx, Paul
> 
> rcu: Fix occurrence of "the the" in checklist.txt
> 
> Signed-off-by: Michael Opdenacker <michael.opdenacker@free-electrons.com>
> Signed-off-by: Paul E. McKenney <paulmck@linux.vnet.ibm.com>
> [ paulmck: Add "then" as suggested by Josh Triplett. ]

Reviewed-by: Josh Triplett <josh@joshtriplett.org>

> diff --git a/Documentation/RCU/checklist.txt b/Documentation/RCU/checklist.txt
> index 7703ec7..9126619 100644
> --- a/Documentation/RCU/checklist.txt
> +++ b/Documentation/RCU/checklist.txt
> @@ -202,8 +202,8 @@ over a rather long period of time, but improvements are always welcome!
>  	updater uses call_rcu_sched() or synchronize_sched(), then
>  	the corresponding readers must disable preemption, possibly
>  	by calling rcu_read_lock_sched() and rcu_read_unlock_sched().
> -	If the updater uses synchronize_srcu() or call_srcu(),
> -	the the corresponding readers must use srcu_read_lock() and
> +	If the updater uses synchronize_srcu() or call_srcu(), then
> +	the corresponding readers must use srcu_read_lock() and
>  	srcu_read_unlock(), and with the same srcu_struct.  The rules for
>  	the expedited primitives are the same as for their non-expedited
>  	counterparts.  Mixing things up will result in confusion and
> 

Re: [PATCH tip/core/rcu 3/3] rcu: Fix occurrence of "the the" in checklist.txt

[Paul E. McKenney]

On Wed, Sep 25, 2013 at 08:33:21AM -0700, Josh Triplett wrote:
> On Wed, Sep 25, 2013 at 06:55:27AM -0700, Paul E. McKenney wrote:
> > On Tue, Sep 24, 2013 at 08:47:39PM -0700, Josh Triplett wrote:
> > > On Tue, Sep 24, 2013 at 06:17:23PM -0700, Paul E. McKenney wrote:
> > > > From: Michael Opdenacker <michael.opdenacker@free-electrons.com>
> > > > 
> > > > Signed-off-by: Michael Opdenacker <michael.opdenacker@free-electrons.com>
> > > > Signed-off-by: Paul E. McKenney <paulmck@linux.vnet.ibm.com>
> > > > ---
> > > 
> > > See comment below.
> > > 
> > > >  Documentation/RCU/checklist.txt | 2 +-
> > > >  1 file changed, 1 insertion(+), 1 deletion(-)
> > > > 
> > > > diff --git a/Documentation/RCU/checklist.txt b/Documentation/RCU/checklist.txt
> > > > index 7703ec7..ad6cba4 100644
> > > > --- a/Documentation/RCU/checklist.txt
> > > > +++ b/Documentation/RCU/checklist.txt
> > > > @@ -203,7 +203,7 @@ over a rather long period of time, but improvements are always welcome!
> > > >  	the corresponding readers must disable preemption, possibly
> > > >  	by calling rcu_read_lock_sched() and rcu_read_unlock_sched().
> > > >  	If the updater uses synchronize_srcu() or call_srcu(),
> > > > -	the the corresponding readers must use srcu_read_lock() and
> > > > +	the corresponding readers must use srcu_read_lock() and
> > > 
> > > I think this may have actually been a typo for "then", as in "If the
> > > updater uses ..., then the corresponding readers must use ...".
> > 
> > Good point -- that would make the sentence construction parallel with
> > the surrounding sentences.  Updated patch below.
> > 
> > 							Thanx, Paul
> > 
> > rcu: Fix occurrence of "the the" in checklist.txt
> > 
> > Signed-off-by: Michael Opdenacker <michael.opdenacker@free-electrons.com>
> > Signed-off-by: Paul E. McKenney <paulmck@linux.vnet.ibm.com>
> > [ paulmck: Add "then" as suggested by Josh Triplett. ]
> 
> Reviewed-by: Josh Triplett <josh@joshtriplett.org>

Got it, thank you again!

							Thanx, Paul

> > diff --git a/Documentation/RCU/checklist.txt b/Documentation/RCU/checklist.txt
> > index 7703ec7..9126619 100644
> > --- a/Documentation/RCU/checklist.txt
> > +++ b/Documentation/RCU/checklist.txt
> > @@ -202,8 +202,8 @@ over a rather long period of time, but improvements are always welcome!
> >  	updater uses call_rcu_sched() or synchronize_sched(), then
> >  	the corresponding readers must disable preemption, possibly
> >  	by calling rcu_read_lock_sched() and rcu_read_unlock_sched().
> > -	If the updater uses synchronize_srcu() or call_srcu(),
> > -	the the corresponding readers must use srcu_read_lock() and
> > +	If the updater uses synchronize_srcu() or call_srcu(), then
> > +	the corresponding readers must use srcu_read_lock() and
> >  	srcu_read_unlock(), and with the same srcu_struct.  The rules for
> >  	the expedited primitives are the same as for their non-expedited
> >  	counterparts.  Mixing things up will result in confusion and
> > 
> 

Re: [PATCH tip/core/rcu 3/3] rcu: Fix occurrence of "the the" in checklist.txt

[Michael Opdenacker]

On 09/25/2013 05:33 PM, Josh Triplett wrote:
> On Wed, Sep 25, 2013 at 06:55:27AM -0700, Paul E. McKenney wrote:
>> On Tue, Sep 24, 2013 at 08:47:39PM -0700, Josh Triplett wrote:
>>> On Tue, Sep 24, 2013 at 06:17:23PM -0700, Paul E. McKenney wrote:
>>>> From: Michael Opdenacker <michael.opdenacker@free-electrons.com>
>>>>
>>>> Signed-off-by: Michael Opdenacker <michael.opdenacker@free-electrons.com>
>>>> Signed-off-by: Paul E. McKenney <paulmck@linux.vnet.ibm.com>
>>>> ---
>>> See comment below.
>>>
>>>>  Documentation/RCU/checklist.txt | 2 +-
>>>>  1 file changed, 1 insertion(+), 1 deletion(-)
>>>>
>>>> diff --git a/Documentation/RCU/checklist.txt b/Documentation/RCU/checklist.txt
>>>> index 7703ec7..ad6cba4 100644
>>>> --- a/Documentation/RCU/checklist.txt
>>>> +++ b/Documentation/RCU/checklist.txt
>>>> @@ -203,7 +203,7 @@ over a rather long period of time, but improvements are always welcome!
>>>>  	the corresponding readers must disable preemption, possibly
>>>>  	by calling rcu_read_lock_sched() and rcu_read_unlock_sched().
>>>>  	If the updater uses synchronize_srcu() or call_srcu(),
>>>> -	the the corresponding readers must use srcu_read_lock() and
>>>> +	the corresponding readers must use srcu_read_lock() and
>>> I think this may have actually been a typo for "then", as in "If the
>>> updater uses ..., then the corresponding readers must use ...".
>> Good point -- that would make the sentence construction parallel with
>> the surrounding sentences.  Updated patch below.
>>
>> 							Thanx, Paul
Good catch! Thanks!

Michael.

-- 
Michael Opdenacker, Free Electrons
Embedded Linux, Kernel and Android engineering
http://free-electrons.com
+33 484 258 098