Documentation updates for v5.1
Subsystems (2)
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(-)
PATCH 1/3 doc: Now jiffies_till_sched_qs solicits help from cond_resched()
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
@@ -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
PATCH 2/3 doc: CPU-hotplug notifiers cannot invoke synchronize_srcu() or srcu_barrier()
In reply to Paul E. McKenneySRCU'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
@@ -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 +“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 <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
PATCH 3/3 doc: Fix outdated links
In reply to Paul E. McKenneyFrom: 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
@@ -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