Documentation updates for v4.21/v5.0
Subsystems (2)
cover Documentation updates for v4.21/v5.0
Hello!
This series provides documentation updates:
1. Set down forward-progress requirements.
2. Clarify RCU data-structure comment about rcu_tree fanout,
courtesy of Joel Fernandes.
3. Remove rcu_preempt_state reference in stallwarn, courtesy of
Joel Fernandes.
4. Update information about resched_cpu, courtesy of Joel Fernandes.
5. Remove rcu_dynticks from Data-Structures, courtesy of Joel
Fernandes.
6. Update Data-Structures for RCU flavor consolidation, courtesy of
Joel Fernandes.
7. Better clarify the rcu_segcblist ->len field, courtesy of Joel
Fernandes.
8. Update description of gp_seq fields in rcu_data, courtesy of
Joel Fernandes.
9. Document rcutorture forward-progress test kernel parameters.
10. Update core and full API in whatisRCU, courtesy of Joel Fernandes.
11. Add more rationale for using rcu_read_lock_sched() in checklist,
courtesy of Joel Fernandes.
12. Remove obsolete suggestion from checklist, courtesy of Joel
Fernandes.
13. Remove obsolete checklist item about synchronize_rcu() usage,
courtesy of Joel Fernandes.
14. Encourage use of rcu_barrier in checklist, courtesy of Joel
Fernandes.
15. Make reader aware of rcu_dereference_protected(), courtesy of
Joel Fernandes.
16. Remove obsolete (non-)requirement about disabling preemption,
courtesy of Joel Fernandes.
17. Make listing in RCU perf/scale requirements use rcu_assign_pointer(),
courtesy of Joel Fernandes.
18. RCU scheduler spinlock rcu_read_unlock() restriction remains.
19. Correct the parameter in stallwarn, courtesy of Joel Fernandes.
20. Fix "struction" typo in RCU memory-ordering documentation,
courtesy of Joel Fernandes.
Thanx, Paul
------------------------------------------------------------------------
Documentation/RCU/Design/Data-Structures/BigTreeClassicRCUBH.svg | 499 ----- Documentation/RCU/Design/Data-Structures/BigTreeClassicRCUBHdyntick.svg | 695 -------- Documentation/RCU/Design/Data-Structures/BigTreePreemptRCUBHdyntick.svg | 741 -------- b/Documentation/RCU/Design/Data-Structures/BigTreePreemptRCUBHdyntickCB.svg | 834 +++------- b/Documentation/RCU/Design/Data-Structures/Data-Structures.html | 177 -- b/Documentation/RCU/Design/Data-Structures/blkd_task.svg | 676 ++------ b/Documentation/RCU/Design/Expedited-Grace-Periods/Expedited-Grace-Periods.html | 6 b/Documentation/RCU/Design/Memory-Ordering/Tree-RCU-Memory-Ordering.html | 2 b/Documentation/RCU/Design/Requirements/Requirements.html | 206 +- b/Documentation/RCU/checklist.txt | 49 b/Documentation/RCU/stallwarn.txt | 7 b/Documentation/RCU/whatisRCU.txt | 70 b/Documentation/admin-guide/kernel-parameters.txt | 17 13 files changed, 823 insertions(+), 3156 deletions(-)
PATCH 1/20 doc: Set down forward-progress requirements
From: "Paul E. McKenney" <[email protected]>
This commit adds a section to the requirements documentation setting down requirements for grace-period and callback-invocation forward progress.
Signed-off-by Paul E. McKenney <[email protected]>
--- .../RCU/Design/Requirements/Requirements.html | 110 +++++++++++++++++- 1 file changed, 108 insertions(+), 2 deletions(-)
Documentation/RCU/Design/Requirements/Requirements.html +108 -2
@@ -1381,6 +1381,7 @@ Classes of quality-of-implementation requirements are as follows: <ol> <li> <a href="#Specialization">Specialization</a> <li> <a href="#Performance and Scalability">Performance and Scalability</a> +<li> <a href="#Forward Progress">Forward Progress</a> <li> <a href="#Composability">Composability</a> <li> <a href="#Corner Cases">Corner Cases</a> </ol>
@@ -1822,6 +1823,106 @@ so it is too early to tell whether they will stand the test of time. RCU thus provides a range of tools to allow updaters to strike the required tradeoff between latency, flexibility and CPU overhead. +<h3><a name="Forward Progress">Forward Progress</a></h3> + +<p> +In theory, delaying grace-period completion and callback invocation +is harmless. +In practice, not only are memory sizes finite but also callbacks sometimes +do wakeups, and sufficiently deferred wakeups can be difficult +to distinguish from system hangs. +Therefore, RCU must provide a number of mechanisms to promote forward +progress. + +<p> +These mechanisms are not foolproof, nor can they be. +For one simple example, an infinite loop in an RCU read-side critical +section must by definition prevent later grace periods from ever completing. +For a more involved example, consider a 64-CPU system built with +<tt>CONFIG_RCU_NOCB_CPU=y</tt> and booted with <tt>rcu_nocbs=1-63</tt>, +where CPUs 1 through 63 spin in tight loops that invoke +<tt>call_rcu()</tt>. +Even if these tight loops also contain calls to <tt>cond_resched()</tt> +(thus allowing grace periods to complete), CPU 0 simply will +not be able to invoke callbacks as fast as the other 63 CPUs can +register them, at least not until the system runs out of memory. +In both of these examples, the Spiderman principle applies: With great +power comes great responsibility. +However, short of this level of abuse, RCU is required to +ensure timely completion of grace periods and timely invocation of +callbacks. + +<p> +RCU takes the following steps to encourage timely completion of +grace periods: + +<ol> +<li> If a grace period fails to complete within 100 milliseconds, + RCU causes future invocations of <tt>cond_resched()</tt> on + the holdout CPUs to provide an RCU quiescent state. + RCU also causes those CPUs' <tt>need_resched()</tt> invocations + to return <tt>true</tt>, but only after the corresponding CPU's + next scheduling-clock. +<li> CPUs mentioned in the <tt>nohz_full</tt> kernel boot parameter + can run indefinitely in the kernel without scheduling-clock + interrupts, which defeats the above <tt>need_resched()</tt> + strategem. + RCU will therefore invoke <tt>resched_cpu()</tt> on any + <tt>nohz_full</tt> CPUs still holding out after + 109 milliseconds. +<li> In kernels built with <tt>CONFIG_RCU_BOOST=y</tt>, if a given + task that has been preempted within an RCU read-side critical + section is holding out for more than 500 milliseconds, + RCU will resort to priority boosting. +<li> If a CPU is still holding out 10 seconds into the grace + period, RCU will invoke <tt>resched_cpu()</tt> on it regardless + of its <tt>nohz_full</tt> state. +</ol> + +<p> +The above values are defaults for systems running with <tt>HZ=1000</tt>. +They will vary as the value of <tt>HZ</tt> varies, and can also be +changed using the relevant Kconfig options and kernel boot parameters. +RCU currently does not do much sanity checking of these +parameters, so please use caution when changing them. +Note that these forward-progress measures are provided only for RCU, +not for +<a href="#Sleepable RCU">SRCU</a> or +<a href="#Tasks RCU">Tasks RCU</a>. + +<p> +RCU takes the following steps in <tt>call_rcu()</tt> to encourage timely +invocation of callbacks when any given non-<tt>rcu_nocbs</tt> CPU has +10,000 callbacks, or has 10,000 more callbacks than it had the last time +encouragement was provided: + +<ol> +<li> Starts a grace period, if one is not already in progress. +<li> Forces immediate checking for quiescent states, rather than + waiting for three milliseconds to have elapsed since the + beginning of the grace period. +<li> Immediately tags the CPU's callbacks with their grace period + completion numbers, rather than waiting for the <tt>RCU_SOFTIRQ</tt> + handler to get around to it. +<li> Lifts callback-execution batch limits, which speeds up callback + invocation at the expense of degrading realtime response. +</ol> + +<p> +Again, these are default values when running at <tt>HZ=1000</tt>, +and can be overridden. +Again, these forward-progress measures are provided only for RCU, +not for +<a href="#Sleepable RCU">SRCU</a> or +<a href="#Tasks RCU">Tasks RCU</a>. +Even for RCU, callback-invocation forward progress for <tt>rcu_nocbs</tt> +CPUs is much less well-developed, in part because workloads benefiting +from <tt>rcu_nocbs</tt> CPUs tend to invoke <tt>call_rcu()</tt> +relatively infrequently. +If workloads emerge that need both <tt>rcu_nocbs</tt> CPUs and high +<tt>call_rcu()</tt> invocation rates, then additional forward-progress +work will be required. + <h3><a name="Composability">Composability</a></h3> <p>
@@ -2272,7 +2373,7 @@ that meets this requirement. Furthermore, NMI handlers can be interrupted by what appear to RCU to be normal interrupts. One way that this can happen is for code that directly invokes -<tt>rcu_irq_enter()</tt> and </tt>rcu_irq_exit()</tt> to be called +<tt>rcu_irq_enter()</tt> and <tt>rcu_irq_exit()</tt> to be called from an NMI handler. This astonishing fact of life prompted the current code structure, which has <tt>rcu_irq_enter()</tt> invoking <tt>rcu_nmi_enter()</tt>
@@ -2294,7 +2395,7 @@ via <tt>del_timer_sync()</tt> or similar. <p> Unfortunately, there is no way to cancel an RCU callback; once you invoke <tt>call_rcu()</tt>, the callback function is -going to eventually be invoked, unless the system goes down first. +eventually going to be invoked, unless the system goes down first. Because it is normally considered socially irresponsible to crash the system in response to a module unload request, we need some other way to deal with in-flight RCU callbacks.
@@ -3233,6 +3334,11 @@ For example, RCU callback overhead might be charged back to the originating <tt>call_rcu()</tt> instance, though probably not in production kernels. +<p> +Additional work may be required to provide reasonable forward-progress +guarantees under heavy load for grace periods and for callback +invocation. + <h2><a name="Summary">Summary</a></h2> <p>
Signature · 1 line
2.17.1
PATCH 15/20 doc: Make reader aware of rcu_dereference_protected
In reply to Paul E. McKenneyFrom: "Joel Fernandes (Google)" <[email protected]>
The whatisRCU.txt document says rcu_dereference() cannot be used outside of rcu_read_lock() protected sections. The commit adds a mention of rcu_dereference_protected(), so that the new reader knows that this API can be used to avoid update-side use of rcu_read_lock() and rcu_read_unlock().
Suggested-by [email protected]
Signed-off-by Joel Fernandes (Google) <[email protected]>
[ paulmck: Update wording, including further feedback from Joel. ]
Signed-off-by Paul E. McKenney <[email protected]>
--- Documentation/RCU/whatisRCU.txt | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-)
Documentation/RCU/whatisRCU.txt +14 -1
@@ -266,7 +266,7 @@ rcu_dereference() unnecessary overhead on Alpha CPUs. Note that the value returned by rcu_dereference() is valid - only within the enclosing RCU read-side critical section. + only within the enclosing RCU read-side critical section [1]. For example, the following is -not- legal: rcu_read_lock();
@@ -292,6 +292,19 @@ rcu_dereference() typically used indirectly, via the _rcu list-manipulation primitives, such as list_for_each_entry_rcu(). + [1] The variant rcu_dereference_protected() can be used outside + of an RCU read-side critical section as long as the usage is + protected by locks acquired by the update-side code. This variant + avoids the lockdep warning that would happen when using (for + example) rcu_dereference() without rcu_read_lock() protection. + Using rcu_dereference_protected() also has the advantage + of permitting compiler optimizations that 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 + and the API's code comments for more details and example usage. + The following diagram shows how each API communicates among the reader, updater, and reclaimer.
Signature · 1 line
2.17.1
PATCH 11/20 doc: rcu: Add more rationale for using rcu_read_lock_sched in checklist
In reply to Paul E. McKenneyFrom: "Joel Fernandes (Google)" <[email protected]>
This commit explains why rcu_read_lock_sched is better than using preempt_disable.
Signed-off-by Joel Fernandes (Google) <[email protected]>
Signed-off-by Paul E. McKenney <[email protected]>
--- Documentation/RCU/checklist.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/RCU/checklist.txt +1 -1
@@ -63,7 +63,7 @@ over a rather long period of time, but improvements are always welcome! pointer must be covered by rcu_read_lock(), rcu_read_lock_bh(), rcu_read_lock_sched(), or by the appropriate update-side lock. Disabling of preemption can serve as rcu_read_lock_sched(), but - is less readable. + is less readable and prevents lockdep from detecting locking issues. Letting RCU-protected pointers "leak" out of an RCU read-side critical section is every bid as bad as letting them leak out
Signature · 1 line
2.17.1
PATCH 17/20 doc: Make listing in RCU perf/scale requirements use rcu_assign_pointer()
In reply to Paul E. McKenneyFrom: "Joel Fernandes (Google)" <[email protected]>
The code listing under this section has a quick quiz that says line 19 uses rcu_access_pointer, but the code listing itself instead uses rcu_dereference(). This commit therefore makes the code listing match the quick quiz.
Signed-off-by Joel Fernandes (Google) <[email protected]>
Signed-off-by Paul E. McKenney <[email protected]>
--- Documentation/RCU/Design/Requirements/Requirements.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/RCU/Design/Requirements/Requirements.html +1 -1
@@ -1596,7 +1596,7 @@ used in place of <tt>synchronize_rcu()</tt> as follows: 16 struct foo *p; 17 18 spin_lock(&gp_lock); -19 p = rcu_dereference(gp); +19 p = rcu_access_pointer(gp); 20 if (!p) { 21 spin_unlock(&gp_lock); 22 return false;
Signature · 1 line
2.17.1
PATCH 6/20 doc: rcu: Update Data-Structures for RCU flavor consolidation
In reply to Paul E. McKenneyFrom: "Joel Fernandes (Google)" <[email protected]>
This patch updates all Data-Structures document figures and text and removes some unwanted figures, to reflect the recent work Paul has been doing with consolidating all flavors of RCU.
Signed-off-by Joel Fernandes (Google) <[email protected]>
Cc <[email protected]>
Signed-off-by Paul E. McKenney <[email protected]>
--- .../Data-Structures/BigTreeClassicRCUBH.svg | 499 ----------- .../BigTreePreemptRCUBHdyntick.svg | 741 ---------------- .../BigTreePreemptRCUBHdyntickCB.svg | 834 +++++++----------- .../Data-Structures/Data-Structures.html | 49 +- .../RCU/Design/Data-Structures/blkd_task.svg | 676 +++++--------- 5 files changed, 559 insertions(+), 2240 deletions(-) delete mode 100644 Documentation/RCU/Design/Data-Structures/BigTreeClassicRCUBH.svg delete mode 100644 Documentation/RCU/Design/Data-Structures/BigTreePreemptRCUBHdyntick.svg
Documentation/RCU/Design/Data-Structures/BigTreeClassicRCUBH.svg deleted +0 -499
@@ -1,499 +0,0 @@ -<?xml version="1.0" encoding="UTF-8" standalone="no"?> -<!-- Creator: fig2dev Version 3.2 Patchlevel 5e --> - -<!-- CreationDate: Wed Dec 9 17:26:09 2015 --> - -<!-- Magnification: 2.000 --> - -<svg - xmlns:dc="http://purl.org/dc/elements/1.1/" - xmlns:cc="http://creativecommons.org/ns#" - xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" - xmlns:svg="http://www.w3.org/2000/svg" - xmlns="http://www.w3.org/2000/svg" - xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" - xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" - width="5.7in" - height="6.6in" - viewBox="-44 -44 6838 7888" - id="svg2" - version="1.1" - inkscape:version="0.48.4 r9939" - sodipodi:docname="BigTreeClassicRCUBH.fig"> - <metadata - id="metadata110"> - <rdf:RDF> - <cc:Work - rdf:about=""> - <dc:format>image/svg+xml</dc:format> - <dc:type - rdf:resource="http://purl.org/dc/dcmitype/StillImage" /> - <dc:title></dc:title> - </cc:Work> - </rdf:RDF> - </metadata> - <defs - id="defs108"> - <marker - inkscape:stockid="Arrow1Mend" - orient="auto" - refY="0.0" - refX="0.0" - id="Arrow1Mend" - style="overflow:visible;"> - <path - id="path3868" - d="M 0.0,0.0 L 5.0,-5.0 L -12.5,0.0 L 5.0,5.0 L 0.0,0.0 z " - style="fill-rule:evenodd;stroke:#000000;stroke-width:1.0pt;" - transform="scale(0.4) rotate(180) translate(10,0)" /> - </marker> - <marker - inkscape:stockid="Arrow2Mend" - orient="auto" - refY="0.0" - refX="0.0" - id="Arrow2Mend" - style="overflow:visible;"> - <path - id="path3886" - style="fill-rule:evenodd;stroke-width:0.62500000;stroke-linejoin:round;" - d="M 8.7185878,4.0337352 L -2.2072895,0.016013256 L 8.7185884,-4.0017078 C 6.9730900,-1.6296469 6.9831476,1.6157441 8.7185878,4.0337352 z " - transform="scale(0.6) rotate(180) translate(0,0)" /> - </marker> - </defs> - <sodipodi:namedview - pagecolor="#ffffff" - bordercolor="#666666" - borderopacity="1" - objecttolerance="10" - gridtolerance="10" - guidetolerance="10" - inkscape:pageopacity="0" - inkscape:pageshadow="2" - inkscape:window-width="878" - inkscape:window-height="1148" - id="namedview106" - showgrid="false" - inkscape:zoom="1.3547758" - inkscape:cx="256.5" - inkscape:cy="297" - inkscape:window-x="45" - inkscape:window-y="24" - inkscape:window-maximized="0" - inkscape:current-layer="g4" /> - <g - style="stroke-width:.025in; fill:none" - id="g4"> - <!-- Line: box --> - <rect - x="450" - y="0" - width="6300" - height="7350" - rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffffff; " - id="rect6" /> - <!-- Line: box --> - <rect - x="4950" - y="4950" - width="1500" - height="900" - rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#87cfff; " - id="rect8" /> - <!-- Line: box --> - <rect - x="750" - y="600" - width="5700" - height="3750" - rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffff00; " - id="rect10" /> - <!-- Line: box --> - <rect - x="0" - y="450" - width="6300" - height="7350" - rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffffff; " - id="rect12" /> - <!-- Line: box --> - <rect - x="300" - y="1050" - width="5700" - height="3750" - rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffff00; " - id="rect14" /> - <!-- Circle --> - <circle - cx="2850" - cy="3900" - r="76" - style="fill:#000000;stroke:#000000;stroke-width:14;" - id="circle16" /> - <!-- Circle --> - <circle - cx="3150" - cy="3900" - r="76" - style="fill:#000000;stroke:#000000;stroke-width:14;" - id="circle18" /> - <!-- Circle --> - <circle - cx="3450" - cy="3900" - r="76" - style="fill:#000000;stroke:#000000;stroke-width:14;" - id="circle20" /> - <!-- Circle --> - <circle - cx="1350" - cy="5100" - r="76" - style="fill:#000000;stroke:#000000;stroke-width:14;" - id="circle22" /> - <!-- Circle --> - <circle - cx="1650" - cy="5100" - r="76" - style="fill:#000000;stroke:#000000;stroke-width:14;" - id="circle24" /> - <!-- Circle --> - <circle - cx="1950" - cy="5100" - r="76" - style="fill:#000000;stroke:#000000;stroke-width:14;" - id="circle26" /> - <!-- Circle --> - <circle - cx="4350" - cy="5100" - r="76" - style="fill:#000000;stroke:#000000;stroke-width:14;" - id="circle28" /> - <!-- Circle --> - <circle - cx="4650" - cy="5100" - r="76" - style="fill:#000000;stroke:#000000;stroke-width:14;" - id="circle30" /> - <!-- Circle --> - <circle - cx="4950" - cy="5100" - r="76" - style="fill:#000000;stroke:#000000;stroke-width:14;" - id="circle32" /> - <!-- Line --> - <polyline - points="1350,3450 2350,2590 " - style="stroke:#00d1d1;stroke-width:30.0045575;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" - id="polyline34" /> - <!-- Arrowhead on XXXpoint 1350 3450 - 2444 2510--> - <!-- Line --> - <polyline - points="4950,3450 3948,2590 " - style="stroke:#00d1d1;stroke-width:30.0045575;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" - id="polyline38" /> - <!-- Arrowhead on XXXpoint 4950 3450 - 3854 2510--> - <!-- Line: box --> - <rect - x="750" - y="3450" - width="1800" - height="900" - rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffbfbf; " - id="rect42" /> - <!-- Line --> - <polyline - points="2250,5400 2250,4414 " - style="stroke:#00d1d1;stroke-width:30.0045575;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" - id="polyline44" /> - <!-- Arrowhead on XXXpoint 2250 5400 - 2250 4290--> - <!-- Line: box --> - <rect - x="1500" - y="5400" - width="1500" - height="900" - rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#87cfff; " - id="rect48" /> - <!-- Line: box --> - <rect - x="300" - y="6600" - width="1500" - height="900" - rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#87cfff; " - id="rect50" /> - <!-- Line: box --> - <rect - x="3750" - y="3450" - width="1800" - height="900" - rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffbfbf; " - id="rect52" /> - <!-- Line: box --> - <rect - x="4500" - y="5400" - width="1500" - height="900" - rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#87cfff; " - id="rect54" /> - <!-- Line: box --> - <rect - x="3300" - y="6600" - width="1500" - height="900" - rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#87cfff; " - id="rect56" /> - <!-- Line: box --> - <rect - x="2250" - y="1650" - width="1800" - height="900" - rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffbfbf; " - id="rect58" /> - <!-- Text --> - <text - xml:space="preserve" - x="6450" - y="300" - fill="#000000" - font-family="Helvetica" - font-style="normal" - font-weight="normal" - font-size="192" - text-anchor="end" - id="text60">rcu_bh</text> - <!-- Text --> - <text - xml:space="preserve" - x="3150" - y="1950" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="middle" - id="text62">struct</text> - <!-- Text --> - <text - xml:space="preserve" - x="3150" - y="2250" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="middle" - id="text64">rcu_node</text> - <!-- Text --> - <text - xml:space="preserve" - x="1650" - y="3750" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="middle" - id="text66">struct</text> - <!-- Text --> - <text - xml:space="preserve" - x="1650" - y="4050" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="middle" - id="text68">rcu_node</text> - <!-- Text --> - <text - xml:space="preserve" - x="4650" - y="4050" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="middle" - id="text70">rcu_node</text> - <!-- Text --> - <text - xml:space="preserve" - x="4650" - y="3750" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="middle" - id="text72">struct</text> - <!-- Text --> - <text - xml:space="preserve" - x="2250" - y="5700" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="middle" - id="text74">struct</text> - <!-- Text --> - <text - xml:space="preserve" - x="2250" - y="6000" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="middle" - id="text76">rcu_data</text> - <!-- Text --> - <text - xml:space="preserve" - x="1050" - y="6900" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="middle" - id="text78">struct</text> - <!-- Text --> - <text - xml:space="preserve" - x="1050" - y="7200" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="middle" - id="text80">rcu_data</text> - <!-- Text --> - <text - xml:space="preserve" - x="5250" - y="5700" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="middle" - id="text82">struct</text> - <!-- Text --> - <text - xml:space="preserve" - x="5250" - y="6000" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="middle" - id="text84">rcu_data</text> - <!-- Text --> - <text - xml:space="preserve" - x="4050" - y="6900" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="middle" - id="text86">struct</text> - <!-- Text --> - <text - xml:space="preserve" - x="4050" - y="7200" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="middle" - id="text88">rcu_data</text> - <!-- Text --> - <text - xml:space="preserve" - x="450" - y="1350" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="start" - id="text90">struct rcu_state</text> - <!-- Text --> - <text - xml:space="preserve" - x="6000" - y="750" - fill="#000000" - font-family="Helvetica" - font-style="normal" - font-weight="normal" - font-size="192" - text-anchor="end" - id="text92">rcu_sched</text> - <!-- Line --> - <polyline - points="5250,5400 5250,4414 " - style="stroke:#00d1d1;stroke-width:30.0045575;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" - id="polyline94" /> - <!-- Arrowhead on XXXpoint 5250 5400 - 5250 4290--> - <!-- Line --> - <polyline - points="4050,6600 4050,4414 " - style="stroke:#00d1d1;stroke-width:30.0045575;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" - id="polyline98" /> - <!-- Arrowhead on XXXpoint 4050 6600 - 4050 4290--> - <!-- Line --> - <polyline - points="1050,6600 1050,4414 " - style="stroke:#00d1d1;stroke-width:30.0045575;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" - id="polyline102" /> - <!-- Arrowhead on XXXpoint 1050 6600 - 1050 4290--> - </g> -</svg>
Documentation/RCU/Design/Data-Structures/BigTreePreemptRCUBHdyntick.svg deleted +0 -741
741 lines not on this page · raw message
Documentation/RCU/Design/Data-Structures/BigTreePreemptRCUBHdyntickCB.svg +319 -515
1,148 lines not on this page · raw message
Documentation/RCU/Design/Data-Structures/Data-Structures.html +8 -41
100 lines not on this page · raw message
Documentation/RCU/Design/Data-Structures/blkd_task.svg +232 -444
512 lines not on this page · raw message
The rest of this diff is not shown. View the raw message.
Signature · 1 line
2.17.1
Part of the diff is not shown here. View the raw message.
PATCH 7/20 doc: rcu: Better clarify the rcu_segcblist ->len field
In reply to Paul E. McKenneyFrom: "Joel Fernandes (Google)" <[email protected]>
An important note under the rcu_segcblist description could use a more detailed description. Especially explanation of the scenario where the ->head field may be temporarily NULL making it not wise to rely on it to determine if callbacks are associated with the rcu_segcblist.
Signed-off-by Joel Fernandes (Google) <[email protected]>
Cc <[email protected]>
Signed-off-by Paul E. McKenney <[email protected]>
--- .../Data-Structures/Data-Structures.html | 23 ++++++++++++------- 1 file changed, 15 insertions(+), 8 deletions(-)
Documentation/RCU/Design/Data-Structures/Data-Structures.html +15 -8
@@ -928,17 +928,24 @@ this <tt>rcu_segcblist</tt> structure, <i>not</i> the <tt>->head</tt> pointer. The reason for this is that all the ready-to-invoke callbacks (that is, those in the <tt>RCU_DONE_TAIL</tt> segment) are extracted -all at once at callback-invocation time. +all at once at callback-invocation time (<tt>rcu_do_batch</tt>), due +to which <tt>->head</tt> may be set to NULL if there are no not-done +callbacks remaining in the <tt>rcu_segcblist</tt>. If callback invocation must be postponed, for example, because a high-priority process just woke up on this CPU, then the remaining -callbacks are placed back on the <tt>RCU_DONE_TAIL</tt> segment. -Either way, the <tt>->len</tt> and <tt>->len_lazy</tt> counts -are adjusted after the corresponding callbacks have been invoked, and so -again it is the <tt>->len</tt> count that accurately reflects whether -or not there are callbacks associated with this <tt>rcu_segcblist</tt> -structure. +callbacks are placed back on the <tt>RCU_DONE_TAIL</tt> segment and +<tt>->head</tt> once again points to the start of the segment. +In short, the head field can briefly be <tt>NULL</tt> even though the +CPU has callbacks present the entire time. +Therefore, it is not appropriate to test the <tt>->head</tt> pointer +for <tt>NULL</tt>. + +<p>In contrast, the <tt>->len</tt> and <tt>->len_lazy</tt> counts +are adjusted only after the corresponding callbacks have been invoked. +This means that the <tt>->len</tt> count is zero only if +the <tt>rcu_segcblist</tt> structure really is devoid of callbacks. Of course, off-CPU sampling of the <tt>->len</tt> count requires -the use of appropriate synchronization, for example, memory barriers. +careful use of appropriate synchronization, for example, memory barriers. This synchronization can be a bit subtle, particularly in the case of <tt>rcu_barrier()</tt>.
Signature · 1 line
2.17.1
PATCH 13/20 doc: rcu: Remove obsolete checklist item about synchronize_rcu usage
In reply to Paul E. McKenneyFrom: "Joel Fernandes (Google)" <[email protected]>
Since the RCU mechanisms have been consolidated, the checklist item warning that synchronize_rcu() waits only for RCU readers is obsolete. This commit therefore removes this checklist item.
Signed-off-by Joel Fernandes (Google) <[email protected]>
Signed-off-by Paul E. McKenney <[email protected]>
--- Documentation/RCU/checklist.txt | 37 +++++++-------------------------- 1 file changed, 7 insertions(+), 30 deletions(-)
Documentation/RCU/checklist.txt +7 -30
@@ -320,37 +320,14 @@ over a rather long period of time, but improvements are always welcome! will break Alpha, cause aggressive compilers to generate bad code, and confuse people trying to read your code. -11. Note that synchronize_rcu() -only- guarantees to wait until - all currently executing rcu_read_lock()-protected RCU read-side - critical sections complete. It does -not- necessarily guarantee - that all currently running interrupts, NMIs, preempt_disable() - code, or idle loops will complete. Therefore, if your - read-side critical sections are protected by something other - than rcu_read_lock(), do -not- use synchronize_rcu(). - - Similarly, disabling preemption is not an acceptable substitute - for rcu_read_lock(). Code that attempts to use preemption - disabling where it should be using rcu_read_lock() will break - in CONFIG_PREEMPT=y kernel builds. - - If you want to wait for interrupt handlers, NMI handlers, and - code under the influence of preempt_disable(), you instead - need to use synchronize_irq() or synchronize_sched(). - - This same limitation also applies to synchronize_rcu_bh() - and synchronize_srcu(), as well as to the asynchronous and - expedited forms of the three primitives, namely call_rcu(), - call_rcu_bh(), call_srcu(), synchronize_rcu_expedited(), - synchronize_rcu_bh_expedited(), and synchronize_srcu_expedited(). - -12. Any lock acquired by an RCU callback must be acquired elsewhere +11. Any lock acquired by an RCU callback must be acquired elsewhere with softirq disabled, e.g., via spin_lock_irqsave(), spin_lock_bh(), etc. Failing to disable irq on a given acquisition of that lock will result in deadlock as soon as the RCU softirq handler happens to run your RCU callback while interrupting that acquisition's critical section. -13. RCU callbacks can be and are executed in parallel. In many cases, +12. RCU callbacks can be and are executed in parallel. In many cases, the callback code simply wrappers around kfree(), so that this is not an issue (or, more accurately, to the extent that it is an issue, the memory-allocator locking handles it). However,
@@ -366,7 +343,7 @@ over a rather long period of time, but improvements are always welcome! not the case, a self-spawning RCU callback would prevent the victim CPU from ever going offline.) -14. Unlike other forms of RCU, it -is- permissible to block in an +13. Unlike other forms of RCU, it -is- permissible to block in an SRCU read-side critical section (demarked by srcu_read_lock() and srcu_read_unlock()), hence the "SRCU": "sleepable RCU". Please note that if you don't need to sleep in read-side critical
@@ -410,7 +387,7 @@ over a rather long period of time, but improvements are always welcome! Note that rcu_dereference() and rcu_assign_pointer() relate to SRCU just as they do to other forms of RCU. -15. The whole point of call_rcu(), synchronize_rcu(), and friends +14. The whole point of call_rcu(), synchronize_rcu(), and friends is to wait until all pre-existing readers have finished before carrying out some otherwise-destructive operation. It is therefore critically important to -first- remove any path
@@ -422,13 +399,13 @@ over a rather long period of time, but improvements are always welcome! is the caller's responsibility to guarantee that any subsequent readers will execute safely. -16. The various RCU read-side primitives do -not- necessarily contain +15. The various RCU read-side primitives do -not- necessarily contain memory barriers. You should therefore plan for the CPU and the compiler to freely reorder code into and out of RCU read-side critical sections. It is the responsibility of the RCU update-side primitives to deal with this. -17. Use CONFIG_PROVE_LOCKING, CONFIG_DEBUG_OBJECTS_RCU_HEAD, and the +16. Use CONFIG_PROVE_LOCKING, CONFIG_DEBUG_OBJECTS_RCU_HEAD, and the __rcu sparse checks to validate your RCU code. These can help find problems as follows:
@@ -451,7 +428,7 @@ over a rather long period of time, but improvements are always welcome! These debugging aids can help you find problems that are otherwise extremely difficult to spot. -18. If you register a callback using call_rcu(), call_rcu_bh(), +17. If you register a callback using call_rcu(), call_rcu_bh(), call_rcu_sched(), or call_srcu(), and pass in a function defined within a loadable module, then it in necessary to wait for all pending callbacks to be invoked after the last invocation
Signature · 1 line
2.17.1
PATCH 16/20 doc: Remove obsolete (non-)requirement about disabling preemption
In reply to Paul E. McKenneyFrom: "Joel Fernandes (Google)" <[email protected]>
The Requirements.html document says "Disabling Preemption Does Not Block Grace Periods". However this is no longer true with the RCU consolidation. This commit therefore removes the obsolete (non-)requirement entirely.
Signed-off-by Joel Fernandes (Google) <[email protected]>
Signed-off-by Paul E. McKenney <[email protected]>
--- .../RCU/Design/Requirements/Requirements.html | 50 ------------------- 1 file changed, 50 deletions(-)
Documentation/RCU/Design/Requirements/Requirements.html +0 -50
@@ -900,8 +900,6 @@ Except where otherwise noted, these non-guarantees were premeditated. Grace Periods Don't Partition Read-Side Critical Sections</a> <li> <a href="#Read-Side Critical Sections Don't Partition Grace Periods"> Read-Side Critical Sections Don't Partition Grace Periods</a> -<li> <a href="#Disabling Preemption Does Not Block Grace Periods"> - Disabling Preemption Does Not Block Grace Periods</a> </ol> <h3><a name="Readers Impose Minimal Ordering">Readers Impose Minimal Ordering</a></h3>
@@ -1259,54 +1257,6 @@ of RCU grace periods. <tr><td> </td></tr> </table> -<h3><a name="Disabling Preemption Does Not Block Grace Periods"> -Disabling Preemption Does Not Block Grace Periods</a></h3> - -<p> -There was a time when disabling preemption on any given CPU would block -subsequent grace periods. -However, this was an accident of implementation and is not a requirement. -And in the current Linux-kernel implementation, disabling preemption -on a given CPU in fact does not block grace periods, as Oleg Nesterov -<a href="https://lkml.kernel.org/g/[email protected]">demonstrated</a>. - -<p> -If you need a preempt-disable region to block grace periods, you need to add -<tt>rcu_read_lock()</tt> and <tt>rcu_read_unlock()</tt>, for example -as follows: - -<blockquote> -<pre> - 1 preempt_disable(); - 2 rcu_read_lock(); - 3 do_something(); - 4 rcu_read_unlock(); - 5 preempt_enable(); - 6 - 7 /* Spinlocks implicitly disable preemption. */ - 8 spin_lock(&mylock); - 9 rcu_read_lock(); -10 do_something(); -11 rcu_read_unlock(); -12 spin_unlock(&mylock); -</pre> -</blockquote> - -<p> -In theory, you could enter the RCU read-side critical section first, -but it is more efficient to keep the entire RCU read-side critical -section contained in the preempt-disable region as shown above. -Of course, RCU read-side critical sections that extend outside of -preempt-disable regions will work correctly, but such critical sections -can be preempted, which forces <tt>rcu_read_unlock()</tt> to do -more work. -And no, this is <i>not</i> an invitation to enclose all of your RCU -read-side critical sections within preempt-disable regions, because -doing so would degrade real-time response. - -<p> -This non-requirement appeared with preemptible RCU. - <h2><a name="Parallelism Facts of Life">Parallelism Facts of Life</a></h2> <p>
Signature · 1 line
2.17.1
PATCH 9/20 doc: Document rcutorture forward-progress test kernel parameters
In reply to Paul E. McKenneySigned-off-by Paul E. McKenney <[email protected]>
--- Documentation/admin-guide/kernel-parameters.txt | 17 +++++++++++++++++ 1 file changed, 17 insertions(+)
Documentation/admin-guide/kernel-parameters.txt +17 -0
@@ -3773,6 +3773,23 @@ Set wait time between force_quiescent_state bursts in seconds. + rcutorture.fwd_progress= [KNL] + Enable RCU grace-period forward-progress testing + for the types of RCU supporting this notion. + + rcutorture.fwd_progress_div= [KNL] + Specify the fraction of a CPU-stall-warning + period to do tight-loop forward-progress testing. + + rcutorture.fwd_progress_holdoff= [KNL] + Number of seconds to wait between successive + forward-progress tests. + + rcutorture.fwd_progress_need_resched= [KNL] + Enclose cond_resched() calls within checks for + need_resched() during tight-loop forward-progress + testing. + rcutorture.gp_cond= [KNL] Use conditional/asynchronous update-side primitives, if available.
Signature · 1 line
2.17.1
PATCH 20/20 doc: Fix "struction" typo in RCU memory-ordering documentation
In reply to Paul E. McKenneyFrom: "Joel Fernandes (Google)" <[email protected]>
This commit replaces "struction" with the correct "structure".
Signed-off-by Joel Fernandes (Google) <[email protected]>
Signed-off-by Paul E. McKenney <[email protected]>
--- .../RCU/Design/Memory-Ordering/Tree-RCU-Memory-Ordering.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/RCU/Design/Memory-Ordering/Tree-RCU-Memory-Ordering.html +1 -1
@@ -77,7 +77,7 @@ The key point is that the lock-acquisition functions, including <tt>smp_mb__after_unlock_lock()</tt> immediately after successful acquisition of the lock. -<p>Therefore, for any given <tt>rcu_node</tt> struction, any access +<p>Therefore, for any given <tt>rcu_node</tt> structure, any access happening before one of the above lock-release functions will be seen by all CPUs as happening before any access happening after a later one of the above lock-acquisition functions.
Signature · 1 line
2.17.1
PATCH 18/20 doc: RCU scheduler spinlock rcu_read_unlock() restriction remains
In reply to Paul E. McKenneyGiven RCU flavor consolidation, when rcu_read_unlock() is invoked with interrupts disabled, the reporting of the corresponding quiescent state is deferred until interrupts are re-enabled. There was therefore some hope that this would allow dropping the restriction against holding scheduler spinlocks across an rcu_read_unlock() without disabling interrupts across the entire corresponding RCU read-side critical section. Unfortunately, the need to quickly provide a quiescent state to expedited grace periods sometimes requires a call to raise_softirq() during rcu_read_unlock() execution. Because raise_softirq() can sometimes acquire the scheduler spinlocks, the restriction must remain in effect. This commit therefore updates the RCU requirements documentation accordingly.
Signed-off-by Paul E. McKenney <[email protected]>
--- .../RCU/Design/Requirements/Requirements.html | 44 ++++++++++++------- 1 file changed, 29 insertions(+), 15 deletions(-)
Documentation/RCU/Design/Requirements/Requirements.html +29 -15
@@ -2475,23 +2475,37 @@ for context-switch-heavy <tt>CONFIG_NO_HZ_FULL=y</tt> workloads, but there is room for further improvement. <p> -In the past, it was forbidden to disable interrupts across an -<tt>rcu_read_unlock()</tt> unless that interrupt-disabled region -of code also included the matching <tt>rcu_read_lock()</tt>. -Violating this restriction could result in deadlocks involving the -scheduler's runqueue and priority-inheritance spinlocks. -This restriction was lifted when interrupt-disabled calls to -<tt>rcu_read_unlock()</tt> started deferring the reporting of -the resulting RCU-preempt quiescent state until the end of that +It is forbidden to hold any of scheduler's runqueue or priority-inheritance +spinlocks across an <tt>rcu_read_unlock()</tt> unless interrupts have been +disabled across the entire RCU read-side critical section, that is, +up to and including the matching <tt>rcu_read_lock()</tt>. +Violating this restriction can result in deadlocks involving these +scheduler spinlocks. +There was hope that this restriction might be lifted when interrupt-disabled +calls to <tt>rcu_read_unlock()</tt> started deferring the reporting of +the resulting RCU-preempt quiescent state until the end of the corresponding interrupts-disabled region. -This deferred reporting means that the scheduler's runqueue and -priority-inheritance locks cannot be held while reporting an RCU-preempt -quiescent state, which lifts the earlier restriction, at least from -a deadlock perspective. -Unfortunately, real-time systems using RCU priority boosting may +Unfortunately, timely reporting of the corresponding quiescent state +to expedited grace periods requires a call to <tt>raise_softirq()</tt>, +which can acquire these scheduler spinlocks. +In addition, real-time systems using RCU priority boosting need this restriction to remain in effect because deferred -quiescent-state reporting also defers deboosting, which in turn -degrades real-time latencies. +quiescent-state reporting would also defer deboosting, which in turn +would degrade real-time latencies. + +<p> +In theory, if a given RCU read-side critical section could be +guaranteed to be less than one second in duration, holding a scheduler +spinlock across that critical section's <tt>rcu_read_unlock()</tt> +would require only that preemption be disabled across the entire +RCU read-side critical section, not interrupts. +Unfortunately, given the possibility of vCPU preemption, long-running +interrupts, and so on, it is not possible in practice to guarantee +that a given RCU read-side critical section will complete in less than +one second. +Therefore, as noted above, if scheduler spinlocks are held across +a given call to <tt>rcu_read_unlock()</tt>, interrupts must be +disabled across the entire RCU read-side critical section. <h3><a name="Tracing and RCU">Tracing and RCU</a></h3>
Signature · 1 line
2.17.1
PATCH 2/20 doc: Clarify RCU data-structure comment about rcu_tree fanout
In reply to Paul E. McKenneyFrom: "Joel Fernandes (Google)" <[email protected]>
RCU Data-Structures document describes a trick to test RCU with small number of CPUs but with a taller tree. It wasn't immediately clear how the document arrived at 16 CPUs which also requires setting the FANOUT_LEAF to 2 instead of the default of 16. This commit therefore provides the needed clarification.
Signed-off-by Joel Fernandes (Google) <[email protected]>
Cc <[email protected]>
Signed-off-by Paul E. McKenney <[email protected]>
--- .../RCU/Design/Data-Structures/Data-Structures.html | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-)
Documentation/RCU/Design/Data-Structures/Data-Structures.html +5 -3
@@ -127,9 +127,11 @@ CPUs, RCU would configure the <tt>rcu_node</tt> tree as follows: </p><p>RCU currently permits up to a four-level tree, which on a 64-bit system accommodates up to 4,194,304 CPUs, though only a mere 524,288 CPUs for 32-bit systems. -On the other hand, you can set <tt>CONFIG_RCU_FANOUT</tt> to be -as small as 2 if you wish, which would permit only 16 CPUs, which -is useful for testing. +On the other hand, you can set both <tt>CONFIG_RCU_FANOUT</tt> and +<tt>CONFIG_RCU_FANOUT_LEAF</tt> to be as small as 2, which would result +in a 16-CPU test using a 4-level tree. +This can be useful for testing large-system capabilities on small test +machines. </p><p>This multi-level combining tree allows us to get most of the performance and scalability
Signature · 1 line
2.17.1
PATCH 19/20 doc: Correct parameter in stallwarn
In reply to Paul E. McKenneyFrom: "Joel Fernandes (Google)" <[email protected]>
The stallwarn document incorrectly mentions 'fps=' instead of 'fqs='. This commit orrects that.
Signed-off-by Joel Fernandes (Google) <[email protected]>
Signed-off-by Paul E. McKenney <[email protected]>
--- Documentation/RCU/stallwarn.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/RCU/stallwarn.txt +1 -1
@@ -205,7 +205,7 @@ handlers are no longer able to execute on this CPU. This can happen if the stalled CPU is spinning with interrupts are disabled, or, in -rt kernels, if a high-priority process is starving RCU's softirq handler. -The "fps=" shows the number of force-quiescent-state idle/offline +The "fqs=" shows the number of force-quiescent-state idle/offline detection passes that the grace-period kthread has made across this CPU since the last time that this CPU noted the beginning of a grace period.
Signature · 1 line
2.17.1
PATCH 5/20 doc: rcu: Remove rcu_dynticks from Data-Structures
In reply to Paul E. McKenneyFrom: "Joel Fernandes (Google)" <[email protected]>
rcu_dynticks was folded into rcu_data structure. Update the data structures RCU document accordingly.
Signed-off-by Joel Fernandes (Google) <[email protected]>
Cc <[email protected]>
Signed-off-by Paul E. McKenney <[email protected]>
--- .../BigTreeClassicRCUBHdyntick.svg | 695 ------------------ .../Data-Structures/Data-Structures.html | 90 +-- 2 files changed, 25 insertions(+), 760 deletions(-) delete mode 100644 Documentation/RCU/Design/Data-Structures/BigTreeClassicRCUBHdyntick.svg
Documentation/RCU/Design/Data-Structures/BigTreeClassicRCUBHdyntick.svg deleted +0 -695
@@ -1,695 +0,0 @@ -<?xml version="1.0" encoding="UTF-8" standalone="no"?> -<!-- Creator: fig2dev Version 3.2 Patchlevel 5e --> - -<!-- CreationDate: Wed Dec 9 17:20:02 2015 --> - -<!-- Magnification: 2.000 --> - -<svg - xmlns:dc="http://purl.org/dc/elements/1.1/" - xmlns:cc="http://creativecommons.org/ns#" - xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" - xmlns:svg="http://www.w3.org/2000/svg" - xmlns="http://www.w3.org/2000/svg" - xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" - xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" - width="5.7in" - height="8.6in" - viewBox="-44 -44 6838 10288" - id="svg2" - version="1.1" - inkscape:version="0.48.4 r9939" - sodipodi:docname="BigTreeClassicRCUBHdyntick.fig"> - <metadata - id="metadata166"> - <rdf:RDF> - <cc:Work - rdf:about=""> - <dc:format>image/svg+xml</dc:format> - <dc:type - rdf:resource="http://purl.org/dc/dcmitype/StillImage" /> - <dc:title></dc:title> - </cc:Work> - </rdf:RDF> - </metadata> - <defs - id="defs164"> - <marker - inkscape:stockid="Arrow1Mend" - orient="auto" - refY="0.0" - refX="0.0" - id="Arrow1Mend" - style="overflow:visible;"> - <path - id="path3924" - d="M 0.0,0.0 L 5.0,-5.0 L -12.5,0.0 L 5.0,5.0 L 0.0,0.0 z " - style="fill-rule:evenodd;stroke:#000000;stroke-width:1.0pt;" - transform="scale(0.4) rotate(180) translate(10,0)" /> - </marker> - <marker - inkscape:stockid="Arrow2Lend" - orient="auto" - refY="0.0" - refX="0.0" - id="Arrow2Lend" - style="overflow:visible;"> - <path - id="path3936" - style="fill-rule:evenodd;stroke-width:0.62500000;stroke-linejoin:round;" - d="M 8.7185878,4.0337352 L -2.2072895,0.016013256 L 8.7185884,-4.0017078 C 6.9730900,-1.6296469 6.9831476,1.6157441 8.7185878,4.0337352 z " - transform="scale(1.1) rotate(180) translate(1,0)" /> - </marker> - </defs> - <sodipodi:namedview - pagecolor="#ffffff" - bordercolor="#666666" - borderopacity="1" - objecttolerance="10" - gridtolerance="10" - guidetolerance="10" - inkscape:pageopacity="0" - inkscape:pageshadow="2" - inkscape:window-width="845" - inkscape:window-height="988" - id="namedview162" - showgrid="false" - inkscape:zoom="1.0452196" - inkscape:cx="256.5" - inkscape:cy="387.00003" - inkscape:window-x="356" - inkscape:window-y="61" - inkscape:window-maximized="0" - inkscape:current-layer="g4" /> - <g - style="stroke-width:.025in; fill:none" - id="g4"> - <!-- Line: box --> - <rect - x="450" - y="0" - width="6300" - height="7350" - rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffffff; " - id="rect6" /> - <!-- Line: box --> - <rect - x="4950" - y="4950" - width="1500" - height="900" - rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#87cfff; " - id="rect8" /> - <!-- Line: box --> - <rect - x="750" - y="600" - width="5700" - height="3750" - rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffff00; " - id="rect10" /> - <!-- Line --> - <polyline - points="5250,8100 5688,5912 " - style="stroke:#00ff00;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; " - id="polyline12" /> - <!-- Arrowhead on XXXpoint 5250 8100 - 5710 5790--> - <polyline - points="5714 6068 5704 5822 5598 6044 " - style="stroke:#00ff00;stroke-width:14;stroke-miterlimit:8; " - id="polyline14" /> - <!-- Line --> - <polyline - points="4050,9300 4486,7262 " - style="stroke:#00ff00;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; " - id="polyline16" /> - <!-- Arrowhead on XXXpoint 4050 9300 - 4512 7140--> - <polyline - points="4514 7418 4506 7172 4396 7394 " - style="stroke:#00ff00;stroke-width:14;stroke-miterlimit:8; " - id="polyline18" /> - <!-- Line --> - <polyline - points="1040,9300 1476,7262 " - style="stroke:#00ff00;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; " - id="polyline20" /> - <!-- Arrowhead on XXXpoint 1040 9300 - 1502 7140--> - <polyline - points="1504 7418 1496 7172 1386 7394 " - style="stroke:#00ff00;stroke-width:14;stroke-miterlimit:8; " - id="polyline22" /> - <!-- Line --> - <polyline - points="2240,8100 2676,6062 " - style="stroke:#00ff00;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; " - id="polyline24" /> - <!-- Arrowhead on XXXpoint 2240 8100 - 2702 5940--> - <polyline - points="2704 6218 2696 5972 2586 6194 " - style="stroke:#00ff00;stroke-width:14;stroke-miterlimit:8; " - id="polyline26" /> - <!-- Line: box --> - <rect - x="0" - y="450" - width="6300" - height="7350" - rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffffff; " - id="rect28" /> - <!-- Line: box --> - <rect - x="300" - y="1050" - width="5700" - height="3750" - rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffff00; " - id="rect30" /> - <!-- Line --> - <polyline - points="1350,3450 2350,2590 " - style="stroke:#00d1d1;stroke-width:30.0045575;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" - id="polyline32" /> - <!-- Arrowhead on XXXpoint 1350 3450 - 2444 2510--> - <!-- Line --> - <polyline - points="4950,3450 3948,2590 " - style="stroke:#00d1d1;stroke-width:30.0045575;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" - id="polyline36" /> - <!-- Arrowhead on XXXpoint 4950 3450 - 3854 2510--> - <!-- Line --> - <polyline - points="4050,6600 4050,4414 " - style="stroke:#00d1d1;stroke-width:30.00455750000000066;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" - id="polyline40" /> - <!-- Arrowhead on XXXpoint 4050 6600 - 4050 4290--> - <!-- Line --> - <polyline - points="1050,6600 1050,4414 " - style="stroke:#00d1d1;stroke-width:30.00455750000000066;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" - id="polyline44" /> - <!-- Arrowhead on XXXpoint 1050 6600 - 1050 4290--> - <!-- Line --> - <polyline - points="2250,5400 2250,4414 " - style="stroke:#00d1d1;stroke-width:30.00455750000000066;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" - id="polyline48" /> - <!-- Arrowhead on XXXpoint 2250 5400 - 2250 4290--> - <!-- Line --> - <polyline - points="2250,8100 2250,6364 " - style="stroke:#00ff00;stroke-width:30;stroke-linejoin:miter;stroke-linecap:butt;marker-end:url(#Arrow1Mend)" - id="polyline52" /> - <!-- Arrowhead on XXXpoint 2250 8100 - 2250 6240--> - <!-- Line --> - <polyline - points="1050,9300 1050,7564 " - style="stroke:#00ff00;stroke-width:30;stroke-linejoin:miter;stroke-linecap:butt;marker-end:url(#Arrow1Mend)" - id="polyline56" /> - <!-- Arrowhead on XXXpoint 1050 9300 - 1050 7440--> - <!-- Line --> - <polyline - points="4050,9300 4050,7564 " - style="stroke:#00ff00;stroke-width:30;stroke-linejoin:miter;stroke-linecap:butt;marker-end:url(#Arrow1Mend)" - id="polyline60" /> - <!-- Arrowhead on XXXpoint 4050 9300 - 4050 7440--> - <!-- Line --> - <polyline - points="5250,8100 5250,6364 " - style="stroke:#00ff00;stroke-width:30;stroke-linejoin:miter;stroke-linecap:butt;marker-end:url(#Arrow1Mend)" - id="polyline64" /> - <!-- Arrowhead on XXXpoint 5250 8100 - 5250 6240--> - <!-- Circle --> - <circle - cx="2850" - cy="3900" - r="76" - style="fill:#000000;stroke:#000000;stroke-width:14;" - id="circle68" /> - <!-- Circle --> - <circle - cx="3150" - cy="3900" - r="76" - style="fill:#000000;stroke:#000000;stroke-width:14;" - id="circle70" /> - <!-- Circle --> - <circle - cx="3450" - cy="3900" - r="76" - style="fill:#000000;stroke:#000000;stroke-width:14;" - id="circle72" /> - <!-- Circle --> - <circle - cx="1350" - cy="5100" - r="76" - style="fill:#000000;stroke:#000000;stroke-width:14;" - id="circle74" /> - <!-- Circle --> - <circle - cx="1650" - cy="5100" - r="76" - style="fill:#000000;stroke:#000000;stroke-width:14;" - id="circle76" /> - <!-- Circle --> - <circle - cx="1950" - cy="5100" - r="76" - style="fill:#000000;stroke:#000000;stroke-width:14;" - id="circle78" /> - <!-- Circle --> - <circle - cx="4350" - cy="5100" - r="76" - style="fill:#000000;stroke:#000000;stroke-width:14;" - id="circle80" /> - <!-- Circle --> - <circle - cx="4650" - cy="5100" - r="76" - style="fill:#000000;stroke:#000000;stroke-width:14;" - id="circle82" /> - <!-- Circle --> - <circle - cx="4950" - cy="5100" - r="76" - style="fill:#000000;stroke:#000000;stroke-width:14;" - id="circle84" /> - <!-- Line: box --> - <rect - x="750" - y="3450" - width="1800" - height="900" - rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffbfbf; " - id="rect86" /> - <!-- Line: box --> - <rect - x="300" - y="6600" - width="1500" - height="900" - rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#87cfff; " - id="rect88" /> - <!-- Line: box --> - <rect - x="3750" - y="3450" - width="1800" - height="900" - rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffbfbf; " - id="rect90" /> - <!-- Line: box --> - <rect - x="4500" - y="5400" - width="1500" - height="900" - rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#87cfff; " - id="rect92" /> - <!-- Line: box --> - <rect - x="3300" - y="6600" - width="1500" - height="900" - rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#87cfff; " - id="rect94" /> - <!-- Line: box --> - <rect - x="2250" - y="1650" - width="1800" - height="900" - rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffbfbf; " - id="rect96" /> - <!-- Line: box --> - <rect - x="0" - y="9300" - width="2100" - height="900" - rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#00ff00; " - id="rect98" /> - <!-- Line: box --> - <rect - x="1350" - y="8100" - width="2100" - height="900" - rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#00ff00; " - id="rect100" /> - <!-- Line: box --> - <rect - x="3000" - y="9300" - width="2100" - height="900" - rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#00ff00; " - id="rect102" /> - <!-- Line: box --> - <rect - x="4350" - y="8100" - width="2100" - height="900" - rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#00ff00; " - id="rect104" /> - <!-- Line: box --> - <rect - x="1500" - y="5400" - width="1500" - height="900" - rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#87cfff; " - id="rect106" /> - <!-- Text --> - <text - xml:space="preserve" - x="6450" - y="300" - fill="#000000" - font-family="Helvetica" - font-style="normal" - font-weight="normal" - font-size="192" - text-anchor="end" - id="text108">rcu_bh</text> - <!-- Text --> - <text - xml:space="preserve" - x="3150" - y="1950" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="middle" - id="text110">struct</text> - <!-- Text --> - <text - xml:space="preserve" - x="3150" - y="2250" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="middle" - id="text112">rcu_node</text> - <!-- Text --> - <text - xml:space="preserve" - x="1650" - y="3750" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="middle" - id="text114">struct</text> - <!-- Text --> - <text - xml:space="preserve" - x="1650" - y="4050" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="middle" - id="text116">rcu_node</text> - <!-- Text --> - <text - xml:space="preserve" - x="4650" - y="4050" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="middle" - id="text118">rcu_node</text> - <!-- Text --> - <text - xml:space="preserve" - x="4650" - y="3750" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="middle" - id="text120">struct</text> - <!-- Text --> - <text - xml:space="preserve" - x="2250" - y="5700" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="middle" - id="text122">struct</text> - <!-- Text --> - <text - xml:space="preserve" - x="2250" - y="6000" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="middle" - id="text124">rcu_data</text> - <!-- Text --> - <text - xml:space="preserve" - x="1050" - y="6900" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="middle" - id="text126">struct</text> - <!-- Text --> - <text - xml:space="preserve" - x="1050" - y="7200" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="middle" - id="text128">rcu_data</text> - <!-- Text --> - <text - xml:space="preserve" - x="5250" - y="5700" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="middle" - id="text130">struct</text> - <!-- Text --> - <text - xml:space="preserve" - x="5250" - y="6000" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="middle" - id="text132">rcu_data</text> - <!-- Text --> - <text - xml:space="preserve" - x="4050" - y="6900" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="middle" - id="text134">struct</text> - <!-- Text --> - <text - xml:space="preserve" - x="4050" - y="7200" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="middle" - id="text136">rcu_data</text> - <!-- Text --> - <text - xml:space="preserve" - x="450" - y="1350" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="start" - id="text138">struct rcu_state</text> - <!-- Text --> - <text - xml:space="preserve" - x="1050" - y="9600" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="middle" - id="text140">struct</text> - <!-- Text --> - <text - xml:space="preserve" - x="1050" - y="9900" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="middle" - id="text142">rcu_dynticks</text> - <!-- Text --> - <text - xml:space="preserve" - x="4050" - y="9600" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="middle" - id="text144">struct</text> - <!-- Text --> - <text - xml:space="preserve" - x="4050" - y="9900" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="middle" - id="text146">rcu_dynticks</text> - <!-- Text --> - <text - xml:space="preserve" - x="2400" - y="8400" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="middle" - id="text148">struct</text> - <!-- Text --> - <text - xml:space="preserve" - x="2400" - y="8700" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="middle" - id="text150">rcu_dynticks</text> - <!-- Text --> - <text - xml:space="preserve" - x="5400" - y="8400" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="middle" - id="text152">struct</text> - <!-- Text --> - <text - xml:space="preserve" - x="5400" - y="8700" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="middle" - id="text154">rcu_dynticks</text> - <!-- Text --> - <text - xml:space="preserve" - x="6000" - y="750" - fill="#000000" - font-family="Helvetica" - font-style="normal" - font-weight="normal" - font-size="192" - text-anchor="end" - id="text156">rcu_sched</text> - <!-- Line --> - <polyline - points="5250,5400 5250,4414 " - style="stroke:#00d1d1;stroke-width:30.00455750000000066;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" - id="polyline158" /> - <!-- Arrowhead on XXXpoint 5250 5400 - 5250 4290--> - </g> -</svg>
Documentation/RCU/Design/Data-Structures/Data-Structures.html +25 -65
159 lines not on this page · raw message
Signature · 1 line
2.17.1
PATCH 14/20 doc: rcu: Encourage use of rcu_barrier in checklist
In reply to Paul E. McKenneyFrom: "Joel Fernandes (Google)" <[email protected]>
The checklist suggests rcu_barrier_bh() for RCU-bh and similarly for sched, however these APIs are now implemented as rcu_barrier() itself due to the RCU consolidation. This commit therefore corrects checklist.txt to encourage use of the underlying rcu_barrier() API.
Signed-off-by Joel Fernandes (Google) <[email protected]>
Signed-off-by Paul E. McKenney <[email protected]>
--- Documentation/RCU/checklist.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-)
Documentation/RCU/checklist.txt +2 -2
@@ -442,8 +442,8 @@ over a rather long period of time, but improvements are always welcome! You instead need to use one of the barrier functions: o call_rcu() -> rcu_barrier() - o call_rcu_bh() -> rcu_barrier_bh() - o call_rcu_sched() -> rcu_barrier_sched() + o call_rcu_bh() -> rcu_barrier() + o call_rcu_sched() -> rcu_barrier() o call_srcu() -> srcu_barrier() However, these barrier functions are absolutely -not- guaranteed
Signature · 1 line
2.17.1
PATCH 8/20 doc: rcu: Update description of gp_seq fields in rcu_data
In reply to Paul E. McKenneyFrom: "Joel Fernandes (Google)" <[email protected]>
The rcu_state structure doesn't have a gp_seq_needed field. Update the description under rcu_data accordingly, to reflect this.
Signed-off-by Joel Fernandes (Google) <[email protected]>
Cc <[email protected]>
Signed-off-by Paul E. McKenney <[email protected]>
--- .../RCU/Design/Data-Structures/Data-Structures.html | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-)
Documentation/RCU/Design/Data-Structures/Data-Structures.html +4 -3
@@ -1011,9 +1011,10 @@ as follows: 5 bool gpwrap; </pre> -<p>The <tt>->gp_seq</tt> and <tt>->gp_seq_needed</tt> -fields are the counterparts of the fields of the same name -in the <tt>rcu_state</tt> and <tt>rcu_node</tt> structures. +<p>The <tt>->gp_seq</tt> field is the counterpart of the field of the same +name in the <tt>rcu_state</tt> and <tt>rcu_node</tt> structures. The +<tt>->gp_seq_needed</tt> field is the counterpart of the field of the same +name in the rcu_node</tt> structure. They may each lag up to one behind their <tt>rcu_node</tt> counterparts, but in <tt>CONFIG_NO_HZ_IDLE</tt> and <tt>CONFIG_NO_HZ_FULL</tt> kernels can lag
Signature · 1 line
2.17.1
PATCH 10/20 doc: rcu: Update core and full API in whatisRCU
In reply to Paul E. McKenneyFrom: "Joel Fernandes (Google)" <[email protected]>
RCU consolidation effort causes the update side of the RCU API to be consistent across all the 3 RCU flavors (normal, sched, bh). This commit therefore updates the full API in the whatisRCU document, thus encouraging people to use the consolidated RCU update API instead of the old RCU-bh and RCU-sched update APIs.
Also rcu_dereference is documented to be the same for all 3 mechanisms (even before the consolidation), however its actually different - as using the right rcu_dereference primitive (such as rcu_dereference_bh for bh) is needed to make lock debugging work correctly. This update also corrects that.
Also, add local_bh_disable() and local_bh_enable() as softirq protection primitives and correct a grammar error in a quiz answer.
Signed-off-by Joel Fernandes (Google) <[email protected]>
Signed-off-by Paul E. McKenney <[email protected]>
--- Documentation/RCU/whatisRCU.txt | 55 +++++++++++++++++---------------- 1 file changed, 28 insertions(+), 27 deletions(-)
Documentation/RCU/whatisRCU.txt +28 -27
@@ -322,28 +322,27 @@ to their callers and (2) call_rcu() callbacks may be invoked. Efficient implementations of the RCU infrastructure make heavy use of batching in order to amortize their overhead over many uses of the corresponding APIs. -There are no fewer than three RCU mechanisms in the Linux kernel; the -diagram above shows the first one, which is by far the most commonly used. -The rcu_dereference() and rcu_assign_pointer() primitives are used for -all three mechanisms, but different defer and protect primitives are -used as follows: +There are at least three flavors of RCU usage in the Linux kernel. The diagram +above shows the most common one. On the updater side, the rcu_assign_pointer(), +sychronize_rcu() and call_rcu() primitives used are the same for all three +flavors. However for protection (on the reader side), the primitives used vary +depending on the flavor: - Defer Protect +a. rcu_read_lock() / rcu_read_unlock() + rcu_dereference() -a. synchronize_rcu() rcu_read_lock() / rcu_read_unlock() - call_rcu() rcu_dereference() +b. rcu_read_lock_bh() / rcu_read_unlock_bh() + local_bh_disable() / local_bh_enable() + rcu_dereference_bh() -b. synchronize_rcu_bh() rcu_read_lock_bh() / rcu_read_unlock_bh() - call_rcu_bh() rcu_dereference_bh() +c. rcu_read_lock_sched() / rcu_read_unlock_sched() + preempt_disable() / preempt_enable() + local_irq_save() / local_irq_restore() + hardirq enter / hardirq exit + NMI enter / NMI exit + rcu_dereference_sched() -c. synchronize_sched() rcu_read_lock_sched() / rcu_read_unlock_sched() - call_rcu_sched() preempt_disable() / preempt_enable() - local_irq_save() / local_irq_restore() - hardirq enter / hardirq exit - NMI enter / NMI exit - rcu_dereference_sched() - -These three mechanisms are used as follows: +These three flavors are used as follows: a. RCU applied to normal data structures.
@@ -867,18 +866,20 @@ RCU: Critical sections Grace period Barrier bh: Critical sections Grace period Barrier - rcu_read_lock_bh call_rcu_bh rcu_barrier_bh - rcu_read_unlock_bh synchronize_rcu_bh - rcu_dereference_bh synchronize_rcu_bh_expedited + rcu_read_lock_bh call_rcu rcu_barrier + rcu_read_unlock_bh synchronize_rcu + [local_bh_disable] synchronize_rcu_expedited + [and friends] + rcu_dereference_bh rcu_dereference_bh_check rcu_dereference_bh_protected rcu_read_lock_bh_held sched: Critical sections Grace period Barrier - rcu_read_lock_sched synchronize_sched rcu_barrier_sched - rcu_read_unlock_sched call_rcu_sched - [preempt_disable] synchronize_sched_expedited + rcu_read_lock_sched call_rcu rcu_barrier + rcu_read_unlock_sched synchronize_rcu + [preempt_disable] synchronize_rcu_expedited [and friends] rcu_read_lock_sched_notrace rcu_read_unlock_sched_notrace
@@ -890,8 +891,8 @@ sched: Critical sections Grace period Barrier SRCU: Critical sections Grace period Barrier - srcu_read_lock synchronize_srcu srcu_barrier - srcu_read_unlock call_srcu + srcu_read_lock call_srcu srcu_barrier + srcu_read_unlock synchronize_srcu srcu_dereference synchronize_srcu_expedited srcu_dereference_check srcu_read_lock_held
@@ -1034,7 +1035,7 @@ Answer: Just as PREEMPT_RT permits preemption of spinlock spinlocks blocking while in RCU read-side critical sections. - Why the apparent inconsistency? Because it is it + Why the apparent inconsistency? Because it is possible to use priority boosting to keep the RCU grace periods short if need be (for example, if running short of memory). In contrast, if blocking waiting
Signature · 1 line
2.17.1
PATCH 12/20 doc: rcu: Remove obsolete suggestion from checklist
In reply to Paul E. McKenneyFrom: "Joel Fernandes (Google)" <[email protected]>
call_rcu_bh is now implemented in terms of call_rcu, so the suggestion to use a different API for speed benefits is not accurate anymore. This commit updates the document accordingly.
Signed-off-by Joel Fernandes (Google) <[email protected]>
Signed-off-by Paul E. McKenney <[email protected]>
--- Documentation/RCU/checklist.txt | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-)
Documentation/RCU/checklist.txt +1 -5
@@ -285,11 +285,7 @@ over a rather long period of time, but improvements are always welcome! here is that superuser already has lots of ways to crash the machine. - d. Use call_rcu_bh() rather than call_rcu(), in order to take - advantage of call_rcu_bh()'s faster grace periods. (This - is only a partial solution, though.) - - e. Periodically invoke synchronize_rcu(), permitting a limited + d. Periodically invoke synchronize_rcu(), permitting a limited number of updates per grace period. The same cautions apply to call_rcu_bh(), call_rcu_sched(),
Signature · 1 line
2.17.1
PATCH 4/20 doc: rcu: Update information about resched_cpu
In reply to Paul E. McKenneyFrom: "Joel Fernandes (Google)" <[email protected]>
Since commit fced9c8cfe6b ("rcu: Avoid resched_cpu() when rescheduling the current CPU"), resched_cpu is not directly called from sync_sched_exp_handler. Update the documentation about the same.
Signed-off-by Joel Fernandes (Google) <[email protected]>
Cc <[email protected]>
Signed-off-by Paul E. McKenney <[email protected]>
--- .../Expedited-Grace-Periods/Expedited-Grace-Periods.html | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-)
Documentation/RCU/Design/Expedited-Grace-Periods/Expedited-Grace-Periods.html +3 -3
@@ -160,9 +160,9 @@ was in flight. If the CPU is idle, then <tt>sync_sched_exp_handler()</tt> reports the quiescent state. -<p> -Otherwise, the handler invokes <tt>resched_cpu()</tt>, which forces -a future context switch. +<p> Otherwise, the handler forces a future context switch by setting the +NEED_RESCHED flag of the current task's thread flag and the CPU preempt +counter. At the time of the context switch, the CPU reports the quiescent state. Should the CPU go offline first, it will report the quiescent state at that time.
Signature · 1 line
2.17.1
PATCH 3/20 doc: Remove rcu_preempt_state reference in stallwarn
In reply to Paul E. McKenneyFrom: "Joel Fernandes (Google)" <[email protected]>
Consolidation of RCU-bh, RCU-preempt, and RCU-sched into one RCU flavor to rule them all resulted in the removal of rcu_preempt_state. However, stallwarn.txt still mentions rcu_preempt_state. This commit therefore Updates stallwarn documentation accordingly.
Signed-off-by Joel Fernandes (Google) <[email protected]>
Cc <[email protected]>
Signed-off-by Paul E. McKenney <[email protected]>
--- Documentation/RCU/stallwarn.txt | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-)
Documentation/RCU/stallwarn.txt +2 -3
@@ -176,9 +176,8 @@ causing stalls, and that the stall was affecting RCU-sched. This message will normally be followed by stack dumps for each CPU. Please note that PREEMPT_RCU builds can be stalled by tasks as well as by CPUs, and that the tasks will be indicated by PID, for example, "P3421". It is even -possible for a rcu_preempt_state stall to be caused by both CPUs -and- -tasks, in which case the offending CPUs and tasks will all be called -out in the list. +possible for an rcu_state stall to be caused by both CPUs -and- tasks, +in which case the offending CPUs and tasks will all be called out in the list. CPU 2's "(3 GPs behind)" indicates that this CPU has not interacted with the RCU core for the past three grace periods. In contrast, CPU 16's "(0
Signature · 1 line
2.17.1