[PATCH 0/2] Documentation/RCU: Update documents

[PATCH 0/2] Documentation/RCU: Update documents

[Junchang Wang]

Hi list,

This patch set updates a few outdated links/sections in the documents of RCU.
Please take a look.

--
Junchang Wang (2):
  whatisRCU.txt: correct outdated links
  torture.txt: update the list of supported torture types

 Documentation/RCU/torture.txt   | 15 +++++++--------
 Documentation/RCU/whatisRCU.txt |  4 ++--
 2 files changed, 9 insertions(+), 10 deletions(-)

-- 
2.7.4

[PATCH 1/2] whatisRCU.txt: fix outdated links

[Junchang Wang]

Fix outdated links in whatisRCU.txt.

Signed-off-by: Junchang Wang <junchangwang@gmail.com>
---
 Documentation/RCU/whatisRCU.txt | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/RCU/whatisRCU.txt b/Documentation/RCU/whatisRCU.txt
index 4a68543..1ace208 100644
--- a/Documentation/RCU/whatisRCU.txt
+++ b/Documentation/RCU/whatisRCU.txt
@@ -302,7 +302,7 @@ rcu_dereference()
 	must prohibit.	The rcu_dereference_protected() variant takes
 	a lockdep expression to indicate which locks must be acquired
 	by the caller. If the indicated protection is not provided,
-	a lockdep splat is emitted.  See RCU/Design/Requirements.html
+	a lockdep splat is emitted.  See RCU/Design/Requirements/Requirements.html
 	and the API's code comments for more details and example usage.
 
 The following diagram shows how each API communicates among the
@@ -560,7 +560,7 @@ presents two such "toy" implementations of RCU, one that is implemented
 in terms of familiar locking primitives, and another that more closely
 resembles "classic" RCU.  Both are way too simple for real-world use,
 lacking both functionality and performance.  However, they are useful
-in getting a feel for how RCU works.  See kernel/rcupdate.c for a
+in getting a feel for how RCU works.  See kernel/rcu/update.c for a
 production-quality implementation, and see:
 
 	http://www.rdrop.com/users/paulmck/RCU
-- 
2.7.4

[PATCH 2/2] torture.txt: update the list of supported torture types

[Junchang Wang]

Torture types "rcu_bh" and "sched" were removed in commit "c770c82a23".
The name of torture type "rcu_busted" was changed to "busted" in commit
"b3c983142d". Two other types, "srcud" and "busted_srcud" were added in
commits "ca1d51ed98" and "2397d072f7", respectively. This patch updates
torture.txt accordingly.

Signed-off-by: Junchang Wang <junchangwang@gmail.com>
---
 Documentation/RCU/torture.txt | 15 +++++++--------
 1 file changed, 7 insertions(+), 8 deletions(-)

diff --git a/Documentation/RCU/torture.txt b/Documentation/RCU/torture.txt
index 55918b5..6395f0b 100644
--- a/Documentation/RCU/torture.txt
+++ b/Documentation/RCU/torture.txt
@@ -155,20 +155,19 @@ torture_type	The type of RCU to test, with string values as follows:
 			along with expedited, synchronous, and polling
 			variants.
 
-		"rcu_bh": rcu_read_lock_bh(), rcu_read_unlock_bh(), and
-			call_rcu_bh(), along with expedited and synchronous
-			variants.
-
-		"rcu_busted": This tests an intentionally incorrect version
+		"busted": This tests an intentionally incorrect version
 			of RCU in order to help test rcutorture itself.
 
 		"srcu": srcu_read_lock(), srcu_read_unlock() and
 			call_srcu(), along with expedited and
 			synchronous variants.
 
-		"sched": preempt_disable(), preempt_enable(), and
-			call_rcu_sched(), along with expedited,
-			synchronous, and polling variants.
+		"srcud": A second form of srcu that dynamically allocates
+			and frees srcu_struct to test srcu cleanup code path.
+
+		"busted_srcud": This torture type verifies rcutorture's ability
+			to detect extensions of RCU read-side critical sections
+			that are not handled.
 
 		"tasks": voluntary context switch and call_rcu_tasks(),
 			along with expedited and synchronous variants.
-- 
2.7.4

Re: [PATCH 1/2] whatisRCU.txt: fix outdated links

[Paul E. McKenney]

On Tue, Jan 01, 2019 at 10:03:19PM +0800, Junchang Wang wrote:
> Fix outdated links in whatisRCU.txt.
> 
> Signed-off-by: Junchang Wang <junchangwang@gmail.com>

Queued and pushed, thank you!

							Thanx, Paul

> ---
>  Documentation/RCU/whatisRCU.txt | 4 ++--
>  1 file changed, 2 insertions(+), 2 deletions(-)
> 
> diff --git a/Documentation/RCU/whatisRCU.txt b/Documentation/RCU/whatisRCU.txt
> index 4a68543..1ace208 100644
> --- a/Documentation/RCU/whatisRCU.txt
> +++ b/Documentation/RCU/whatisRCU.txt
> @@ -302,7 +302,7 @@ rcu_dereference()
>  	must prohibit.	The rcu_dereference_protected() variant takes
>  	a lockdep expression to indicate which locks must be acquired
>  	by the caller. If the indicated protection is not provided,
> -	a lockdep splat is emitted.  See RCU/Design/Requirements.html
> +	a lockdep splat is emitted.  See RCU/Design/Requirements/Requirements.html
>  	and the API's code comments for more details and example usage.
>  
>  The following diagram shows how each API communicates among the
> @@ -560,7 +560,7 @@ presents two such "toy" implementations of RCU, one that is implemented
>  in terms of familiar locking primitives, and another that more closely
>  resembles "classic" RCU.  Both are way too simple for real-world use,
>  lacking both functionality and performance.  However, they are useful
> -in getting a feel for how RCU works.  See kernel/rcupdate.c for a
> +in getting a feel for how RCU works.  See kernel/rcu/update.c for a
>  production-quality implementation, and see:
>  
>  	http://www.rdrop.com/users/paulmck/RCU
> -- 
> 2.7.4
> 

Re: [PATCH 2/2] torture.txt: update the list of supported torture types

[Paul E. McKenney]

On Tue, Jan 01, 2019 at 10:03:20PM +0800, Junchang Wang wrote:
> Torture types "rcu_bh" and "sched" were removed in commit "c770c82a23".
> The name of torture type "rcu_busted" was changed to "busted" in commit
> "b3c983142d". Two other types, "srcud" and "busted_srcud" were added in
> commits "ca1d51ed98" and "2397d072f7", respectively. This patch updates
> torture.txt accordingly.
> 
> Signed-off-by: Junchang Wang <junchangwang@gmail.com>

Given that this section of this file duplicates the rcutorture kernel boot
parameters called out in Documentation/admin-guide/kernel-parameters.txt,
perhaps the best way forward is to instead remove this information from
Documentation/RCU/torture.txt in favor of a reference to the information
(with search string) in Documentation/admin-guide/kernel-parameters.txt.

Thoughts?

							Thanx, Paul

> ---
>  Documentation/RCU/torture.txt | 15 +++++++--------
>  1 file changed, 7 insertions(+), 8 deletions(-)
> 
> diff --git a/Documentation/RCU/torture.txt b/Documentation/RCU/torture.txt
> index 55918b5..6395f0b 100644
> --- a/Documentation/RCU/torture.txt
> +++ b/Documentation/RCU/torture.txt
> @@ -155,20 +155,19 @@ torture_type	The type of RCU to test, with string values as follows:
>  			along with expedited, synchronous, and polling
>  			variants.
>  
> -		"rcu_bh": rcu_read_lock_bh(), rcu_read_unlock_bh(), and
> -			call_rcu_bh(), along with expedited and synchronous
> -			variants.
> -
> -		"rcu_busted": This tests an intentionally incorrect version
> +		"busted": This tests an intentionally incorrect version
>  			of RCU in order to help test rcutorture itself.
>  
>  		"srcu": srcu_read_lock(), srcu_read_unlock() and
>  			call_srcu(), along with expedited and
>  			synchronous variants.
>  
> -		"sched": preempt_disable(), preempt_enable(), and
> -			call_rcu_sched(), along with expedited,
> -			synchronous, and polling variants.
> +		"srcud": A second form of srcu that dynamically allocates
> +			and frees srcu_struct to test srcu cleanup code path.
> +
> +		"busted_srcud": This torture type verifies rcutorture's ability
> +			to detect extensions of RCU read-side critical sections
> +			that are not handled.
>  
>  		"tasks": voluntary context switch and call_rcu_tasks(),
>  			along with expedited and synchronous variants.
> -- 
> 2.7.4
> 

Re: [PATCH 2/2] torture.txt: update the list of supported torture types

[Junchang Wang]

On Wed, Jan 2, 2019 at 1:54 AM Paul E. McKenney <paulmck@linux.ibm.com> wrote:
>
> On Tue, Jan 01, 2019 at 10:03:20PM +0800, Junchang Wang wrote:
> > Torture types "rcu_bh" and "sched" were removed in commit "c770c82a23".
> > The name of torture type "rcu_busted" was changed to "busted" in commit
> > "b3c983142d". Two other types, "srcud" and "busted_srcud" were added in
> > commits "ca1d51ed98" and "2397d072f7", respectively. This patch updates
> > torture.txt accordingly.
> >
> > Signed-off-by: Junchang Wang <junchangwang@gmail.com>
>
> Given that this section of this file duplicates the rcutorture kernel boot
> parameters called out in Documentation/admin-guide/kernel-parameters.txt,
> perhaps the best way forward is to instead remove this information from
> Documentation/RCU/torture.txt in favor of a reference to the information
> (with search string) in Documentation/admin-guide/kernel-parameters.txt.
>
> Thoughts?

Hi Paul,

Thanks for the comment; indeed the section "MODULE PARAMETERS" in
torture.txt duplicates the corresponding sections in
kernel-parameters.txt. I can resubmit a patch that (1) removes the
section "MODULE PARAMETERS" in torture.txt, and (2) add a single
sentence saying "Module parameters are detailed in
Documentation/admin-guide/kernel-parameters.txt". Does that sound
good?

Thanks,
--Junchang

>
>                                                         Thanx, Paul
>
> > ---
> >  Documentation/RCU/torture.txt | 15 +++++++--------
> >  1 file changed, 7 insertions(+), 8 deletions(-)
> >
> > diff --git a/Documentation/RCU/torture.txt b/Documentation/RCU/torture.txt
> > index 55918b5..6395f0b 100644
> > --- a/Documentation/RCU/torture.txt
> > +++ b/Documentation/RCU/torture.txt
> > @@ -155,20 +155,19 @@ torture_type    The type of RCU to test, with string values as follows:
> >                       along with expedited, synchronous, and polling
> >                       variants.
> >
> > -             "rcu_bh": rcu_read_lock_bh(), rcu_read_unlock_bh(), and
> > -                     call_rcu_bh(), along with expedited and synchronous
> > -                     variants.
> > -
> > -             "rcu_busted": This tests an intentionally incorrect version
> > +             "busted": This tests an intentionally incorrect version
> >                       of RCU in order to help test rcutorture itself.
> >
> >               "srcu": srcu_read_lock(), srcu_read_unlock() and
> >                       call_srcu(), along with expedited and
> >                       synchronous variants.
> >
> > -             "sched": preempt_disable(), preempt_enable(), and
> > -                     call_rcu_sched(), along with expedited,
> > -                     synchronous, and polling variants.
> > +             "srcud": A second form of srcu that dynamically allocates
> > +                     and frees srcu_struct to test srcu cleanup code path.
> > +
> > +             "busted_srcud": This torture type verifies rcutorture's ability
> > +                     to detect extensions of RCU read-side critical sections
> > +                     that are not handled.
> >
> >               "tasks": voluntary context switch and call_rcu_tasks(),
> >                       along with expedited and synchronous variants.
> > --
> > 2.7.4
> >
>

Re: [PATCH 2/2] torture.txt: update the list of supported torture types

[Paul E. McKenney]

On Wed, Jan 02, 2019 at 11:48:00AM +0800, Junchang Wang wrote:
> On Wed, Jan 2, 2019 at 1:54 AM Paul E. McKenney <paulmck@linux.ibm.com> wrote:
> >
> > On Tue, Jan 01, 2019 at 10:03:20PM +0800, Junchang Wang wrote:
> > > Torture types "rcu_bh" and "sched" were removed in commit "c770c82a23".
> > > The name of torture type "rcu_busted" was changed to "busted" in commit
> > > "b3c983142d". Two other types, "srcud" and "busted_srcud" were added in
> > > commits "ca1d51ed98" and "2397d072f7", respectively. This patch updates
> > > torture.txt accordingly.
> > >
> > > Signed-off-by: Junchang Wang <junchangwang@gmail.com>
> >
> > Given that this section of this file duplicates the rcutorture kernel boot
> > parameters called out in Documentation/admin-guide/kernel-parameters.txt,
> > perhaps the best way forward is to instead remove this information from
> > Documentation/RCU/torture.txt in favor of a reference to the information
> > (with search string) in Documentation/admin-guide/kernel-parameters.txt.
> >
> > Thoughts?
> 
> Hi Paul,
> 
> Thanks for the comment; indeed the section "MODULE PARAMETERS" in
> torture.txt duplicates the corresponding sections in
> kernel-parameters.txt. I can resubmit a patch that (1) removes the
> section "MODULE PARAMETERS" in torture.txt, and (2) add a single
> sentence saying "Module parameters are detailed in
> Documentation/admin-guide/kernel-parameters.txt". Does that sound
> good?

A patch that did that would be quite welcome!

							Thanx, Paul

> Thanks,
> --Junchang
> 
> >
> >                                                         Thanx, Paul
> >
> > > ---
> > >  Documentation/RCU/torture.txt | 15 +++++++--------
> > >  1 file changed, 7 insertions(+), 8 deletions(-)
> > >
> > > diff --git a/Documentation/RCU/torture.txt b/Documentation/RCU/torture.txt
> > > index 55918b5..6395f0b 100644
> > > --- a/Documentation/RCU/torture.txt
> > > +++ b/Documentation/RCU/torture.txt
> > > @@ -155,20 +155,19 @@ torture_type    The type of RCU to test, with string values as follows:
> > >                       along with expedited, synchronous, and polling
> > >                       variants.
> > >
> > > -             "rcu_bh": rcu_read_lock_bh(), rcu_read_unlock_bh(), and
> > > -                     call_rcu_bh(), along with expedited and synchronous
> > > -                     variants.
> > > -
> > > -             "rcu_busted": This tests an intentionally incorrect version
> > > +             "busted": This tests an intentionally incorrect version
> > >                       of RCU in order to help test rcutorture itself.
> > >
> > >               "srcu": srcu_read_lock(), srcu_read_unlock() and
> > >                       call_srcu(), along with expedited and
> > >                       synchronous variants.
> > >
> > > -             "sched": preempt_disable(), preempt_enable(), and
> > > -                     call_rcu_sched(), along with expedited,
> > > -                     synchronous, and polling variants.
> > > +             "srcud": A second form of srcu that dynamically allocates
> > > +                     and frees srcu_struct to test srcu cleanup code path.
> > > +
> > > +             "busted_srcud": This torture type verifies rcutorture's ability
> > > +                     to detect extensions of RCU read-side critical sections
> > > +                     that are not handled.
> > >
> > >               "tasks": voluntary context switch and call_rcu_tasks(),
> > >                       along with expedited and synchronous variants.
> > > --
> > > 2.7.4
> > >
> >
>