Skip to contentSkip to conversation

Documentation updates for v5.1

PATCH New Paul E. McKenney 1 participant 4 messages Jan 9, 2019

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

cover Documentation updates for v5.1

Hello!

This series contains RCU documentation updates:

1. Record the fact that jiffies_till_sched_qs solicits help from

	cond_resched().

2. Document that CPU-hotplug notifiers cannot invoke
synchronize_srcu() or srcu_barrier().

3. Fix outdated links, courtesy of Junchang Wang.

Thanx, Paul

------------------------------------------------------------------------

 RCU/Design/Requirements/Requirements.html |   20 +++++++++++++-------
 RCU/whatisRCU.txt                         |    4 ++--
 admin-guide/kernel-parameters.txt         |   27 ++++++++++++++-------------
 3 files changed, 29 insertions(+), 22 deletions(-)
#3 lore raw

PATCH 3/3 doc: Fix outdated links

From: Junchang Wang <[email protected]>

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 4a6854318b17..1ace20815bb1 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.17.1
#2 lore raw

PATCH 2/3 doc: CPU-hotplug notifiers cannot invoke synchronize_srcu() or srcu_barrier()

In reply to Paul E. McKenney

SRCU's synchronize_srcu() may not be invoked from CPU-hotplug notifiers, due to the fact that SRCU grace periods make use of timers and the possibility of timers being temporarily stranded on the outgoing CPU. This stranding of timers means that timers posted to the outgoing CPU will not fire until late in the CPU-hotplug process. The problem is that if a notifier is waiting on an SRCU grace period, that grace period is waiting on a timer, and that timer is stranded on the outgoing CPU, then the notifier will never be awakened, in other words, deadlock has occurred. This same situation of course also prohibits srcu_barrier() from being invoked from CPU-hotplug notifiers.

This commit therefore updates the requirements to include this restriction.

---
 .../RCU/Design/Requirements/Requirements.html | 20 ++++++++++++-------
 1 file changed, 13 insertions(+), 7 deletions(-)
Documentation/RCU/Design/Requirements/Requirements.html +13 -7
index 9fca73e03a98..5a9238a2883c 100644
@@ -3099,7 +3099,7 @@ If you block forever in one of a given domain's SRCU read-side critical
 sections, then that domain's grace periods will also be blocked forever.
 Of course, one good way to block forever is to deadlock, which can
 happen if any operation in a given domain's SRCU read-side critical
-section can block waiting, either directly or indirectly, for that domain's
+section can wait, either directly or indirectly, for that domain's
 grace period to elapse.
 For example, this results in a self-deadlock:
 
@@ -3139,12 +3139,18 @@ API, which, in combination with <tt>srcu_read_unlock()</tt>,
 guarantees a full memory barrier.
 
 <p>
-Also unlike other RCU flavors, SRCU's callbacks-wait function
-<tt>srcu_barrier()</tt> may be invoked from CPU-hotplug notifiers,
-though this is not necessarily a good idea.
-The reason that this is possible is that SRCU is insensitive
-to whether or not a CPU is online, which means that <tt>srcu_barrier()</tt>
-need not exclude CPU-hotplug operations.
+Also unlike other RCU flavors, <tt>synchronize_srcu()</tt> may <b>not</b>
+be invoked from CPU-hotplug notifiers, due to the fact that SRCU grace
+periods make use of timers and the possibility of timers being temporarily
+&ldquo;stranded&rdquo; on the outgoing CPU.
+This stranding of timers means that timers posted to the outgoing CPU
+will not fire until late in the CPU-hotplug process.
+The problem is that if a notifier is waiting on an SRCU grace period,
+that grace period is waiting on a timer, and that timer is stranded on the
+outgoing CPU, then the notifier will never be awakened, in other words,
+deadlock has occurred.
+This same situation of course also prohibits <tt>srcu_barrier()</tt>
+from being invoked from CPU-hotplug notifiers.
 
 <p>
 SRCU also differs from other RCU flavors in that SRCU's expedited and
Signature · 1 line
2.17.1
#1 lore raw

PATCH 1/3 doc: Now jiffies_till_sched_qs solicits help from cond_resched()

In reply to Paul E. McKenney

The rcutree.jiffies_till_sched_qs kernel boot parameter used to solicit help only from rcu_note_context_switch(), but now also solicits help from cond_resched(). This commit therefore updates kernel-parameters.txt accordingly.

---
 .../admin-guide/kernel-parameters.txt         | 27 ++++++++++---------
 1 file changed, 14 insertions(+), 13 deletions(-)
Documentation/admin-guide/kernel-parameters.txt +14 -13
index b799bcf67d7b..4974966451e2 100644
@@ -3654,19 +3654,6 @@
 			latencies, which will choose a value aligned
 			with the appropriate hardware boundaries.
 
-	rcutree.jiffies_till_sched_qs= [KNL]
-			Set required age in jiffies for a
-			given grace period before RCU starts
-			soliciting quiescent-state help from
-			rcu_note_context_switch().  If not specified, the
-			kernel will calculate a value based on the most
-			recent settings of rcutree.jiffies_till_first_fqs
-			and rcutree.jiffies_till_next_fqs.
-			This calculated value may be viewed in
-			rcutree.jiffies_to_sched_qs.  Any attempt to
-			set rcutree.jiffies_to_sched_qs will be
-			cheerfully overwritten.
-
 	rcutree.jiffies_till_first_fqs= [KNL]
 			Set delay from grace-period initialization to
 			first attempt to force quiescent states.
@@ -3678,6 +3665,20 @@
 			quiescent states.  Units are jiffies, minimum
 			value is one, and maximum value is HZ.
 
+	rcutree.jiffies_till_sched_qs= [KNL]
+			Set required age in jiffies for a
+			given grace period before RCU starts
+			soliciting quiescent-state help from
+			rcu_note_context_switch() and cond_resched().
+			If not specified, the kernel will calculate
+			a value based on the most recent settings
+			of rcutree.jiffies_till_first_fqs
+			and rcutree.jiffies_till_next_fqs.
+			This calculated value may be viewed in
+			rcutree.jiffies_to_sched_qs.  Any attempt to set
+			rcutree.jiffies_to_sched_qs will be cheerfully
+			overwritten.
+
 	rcutree.kthread_prio= 	 [KNL,BOOT]
 			Set the SCHED_FIFO priority of the RCU per-CPU
 			kthreads (rcuc/N). This value is also used for
Signature · 1 line
2.17.1