Skip to contentSkip to conversation

Documentation/RCU: Update documents

PATCH Applied Junchang Wang 2 participants 7 messages Jan 1, 2019 – Jan 2, 2019

Subsystems (2)
lore
Share & tools
lore
#0 lore raw

cover Documentation/RCU: Update documents

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(-)
Signature · 1 line
2.7.4
#1 lore raw

PATCH 1/2 whatisRCU.txt: fix outdated links

Fix outdated links in whatisRCU.txt.

---
 Documentation/RCU/whatisRCU.txt | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)
Documentation/RCU/whatisRCU.txt +2 -2
index 4a68543..1ace208 100644
@@ -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
Signature · 1 line
2.7.4
#2 lore raw

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

Quoted 3 lines · Junchang Wang

Fix outdated links in whatisRCU.txt.

Queued and pushed, thank you!

Thanx, Paul

Quoted 29 lines
---
 Documentation/RCU/whatisRCU.txt | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)
Documentation/RCU/whatisRCU.txt +2 -2
index 4a68543..1ace208 100644
@@ -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
Signature · 1 line
2.7.4
#3 lore raw

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

In reply to 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.

---
 Documentation/RCU/torture.txt | 15 +++++++--------
 1 file changed, 7 insertions(+), 8 deletions(-)
Documentation/RCU/torture.txt +7 -8
index 55918b5..6395f0b 100644
@@ -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.
Signature · 1 line
2.7.4
#4 lore raw

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

Quoted 7 lines · 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.

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

Quoted 39 lines
---
 Documentation/RCU/torture.txt | 15 +++++++--------
 1 file changed, 7 insertions(+), 8 deletions(-)
Documentation/RCU/torture.txt +7 -8
index 55918b5..6395f0b 100644
@@ -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.
Signature · 1 line
2.7.4
#5 lore raw

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

Quoted 10 lines · Paul E. McKenney
Quoted 7 lines · 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.

Quoted 7 lines

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

Quoted 43 lines

Thanx, Paul

Quoted 39 lines
---
 Documentation/RCU/torture.txt | 15 +++++++--------
 1 file changed, 7 insertions(+), 8 deletions(-)
Documentation/RCU/torture.txt +7 -9
index 55918b5..6395f0b 100644
@@ -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

#6 lore raw

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

Quoted 21 lines · Junchang Wang
Quoted 10 lines · Paul E. McKenney
Quoted 7 lines · 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.

Quoted 7 lines

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,

Quoted 7 lines

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

Quoted 47 lines

Thanks,
--Junchang

Quoted 43 lines

Thanx, Paul

Quoted 39 lines
---
 Documentation/RCU/torture.txt | 15 +++++++--------
 1 file changed, 7 insertions(+), 8 deletions(-)
Documentation/RCU/torture.txt +7 -9
index 55918b5..6395f0b 100644
@@ -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