Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > linux.kernel > #1288023 > unrolled thread

[PATCH v2 tip/core/rcu 0/8] Documentation updates for 4.5

Back to article view | Back to linux.kernel

Contents

  [PATCH v2 tip/core/rcu 0/8] Documentation updates for 4.5 "Paul E. McKenney" <paulmck@linux.vnet.ibm.com> - 2015-12-10 00:20 +0100
    [PATCH v2 tip/core/rcu 6/8] documentation: Clarify RCU memory barriers and requirements "Paul E. McKenney" <paulmck@linux.vnet.ibm.com> - 2015-12-10 00:20 +0100
    [PATCH v2 tip/core/rcu 7/8] documentation: Update RCU requirements based on expedited changes "Paul E. McKenney" <paulmck@linux.vnet.ibm.com> - 2015-12-10 00:20 +0100

#1288023 — [PATCH v2 tip/core/rcu 0/8] Documentation updates for 4.5

Hello!

This series contains documentation updates, perhaps most notably a first
installment of RCU design documentation, which first appeared on LWN
(http://lwn.net/Articles/652156/, http://lwn.net/Articles/652677/, and
http://lwn.net/Articles/653326/).  The individual patches are as follows:

1.	Add RCU requirements design document.

2-7.	Updates to the RCU requirements.

8.	Fix memory-barrier.txt typo, courtesy of Chris Metcalf.

Changes since v1:

o	Apply review feedback from Josh Triplett.

							Thanx, Paul

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

 RCU/Design/Requirements/GPpartitionReaders1.svg |  374 +++
 RCU/Design/Requirements/RCUApplicability.svg    |  237 +
 RCU/Design/Requirements/ReadersPartitionGP1.svg |  639 +++++
 RCU/Design/Requirements/Requirements.html       | 2967 +++++++++++++++++++++++-
 RCU/Design/Requirements/Requirements.htmlx      | 2809 ++++++++++++++++++++++
 RCU/Design/htmlqqz.sh                           |  108 
 memory-barriers.txt                             |    8 
 7 files changed, 7069 insertions(+), 73 deletions(-)

--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/

[toc] | [next] | [standalone]

#1288025 — [PATCH v2 tip/core/rcu 6/8] documentation: Clarify RCU memory barriers and requirements

The RCU requirements do not make it absolutely clear that the
memory-barrier requirements are not intended to replace the fundamental
requirement that all pre-existing RCU readers complete before a grace
period completes.  This commit therefore pulls the memory-barrier
requirements into a separate section and explicitly calls out the
relationship between the memory-barrier requirements and the fundamental
requirement.

Signed-off-by: Paul E. McKenney <paulmck@linux.vnet.ibm.com>
---
 .../RCU/Design/Requirements/Requirements.html      | 66 +++++++++++++---------
 .../RCU/Design/Requirements/Requirements.htmlx     | 66 +++++++++++++---------
 2 files changed, 78 insertions(+), 54 deletions(-)

diff --git a/Documentation/RCU/Design/Requirements/Requirements.html b/Documentation/RCU/Design/Requirements/Requirements.html
index ab513ed229d7..96cdcf7195d5 100644
--- a/Documentation/RCU/Design/Requirements/Requirements.html
+++ b/Documentation/RCU/Design/Requirements/Requirements.html
@@ -80,6 +80,8 @@ These are:
 	Grace-Period Guarantee</a>
 <li>	<a href="#Publish-Subscribe Guarantee">
 	Publish-Subscribe Guarantee</a>
+<li>	<a href="#Memory-Barrier Guarantees">
+	Memory-Barrier Guarantees</a>
 <li>	<a href="#RCU Primitives Guaranteed to Execute Unconditionally">
 	RCU Primitives Guaranteed to Execute Unconditionally</a>
 <li>	<a href="#Guaranteed Read-to-Write Upgrade">
@@ -499,9 +501,37 @@ might the compiler make use of?
 <br><a href="#qq4answer">Answer</a>
 
 <p>
-This simple linked-data-structure scenario clearly demonstrates the need
-for RCU's stringent memory-ordering guarantees on systems with more than
-one CPU:
+In short, RCU's publish-subscribe guarantee is provided by the combination
+of <tt>rcu_assign_pointer()</tt> and <tt>rcu_dereference()</tt>.
+This guarantee allows data elements to be safely added to RCU-protected
+linked data structures without disrupting RCU readers.
+This guarantee can be used in combination with the grace-period
+guarantee to also allow data elements to be removed from RCU-protected
+linked data structures, again without disrupting RCU readers.
+
+<p>
+This guarantee was only partially premeditated.
+DYNIX/ptx used an explicit memory barrier for publication, but had nothing
+resembling <tt>rcu_dereference()</tt> for subscription, nor did it
+have anything resembling the <tt>smp_read_barrier_depends()</tt>
+that was later subsumed into <tt>rcu_dereference()</tt>.
+The need for these operations made itself known quite suddenly at a
+late-1990s meeting with the DEC Alpha architects, back in the days when
+DEC was still a free-standing company.
+It took the Alpha architects a good hour to convince me that any sort
+of barrier would ever be needed, and it then took me a good <i>two</i> hours
+to convince them that their documentation did not make this point clear.
+More recent work with the C and C++ standards committees have provided
+much education on tricks and traps from the compiler.
+In short, compilers were much less tricky in the early 1990s, but in
+2015, don't even think about omitting <tt>rcu_dereference()</tt>!
+
+<h3><a name="Memory-Barrier Guarantees">Memory-Barrier Guarantees</a></h3>
+
+<p>
+The previous section's simple linked-data-structure scenario clearly
+demonstrates the need for RCU's stringent memory-ordering guarantees on
+systems with more than one CPU:
 
 <ol>
 <li>	Each CPU that has an RCU read-side critical section that
@@ -554,30 +584,12 @@ Are all these memory barriers <i> really</i> required?
 <br><a href="#qq6answer">Answer</a>
 
 <p>
-In short, RCU's publish-subscribe guarantee is provided by the combination
-of <tt>rcu_assign_pointer()</tt> and <tt>rcu_dereference()</tt>.
-This guarantee allows data elements to be safely added to RCU-protected
-linked data structures without disrupting RCU readers.
-This guarantee can be used in combination with the grace-period
-guarantee to also allow data elements to be removed from RCU-protected
-linked data structures, again without disrupting RCU readers.
-
-<p>
-This guarantee was only partially premeditated.
-DYNIX/ptx used an explicit memory barrier for publication, but had nothing
-resembling <tt>rcu_dereference()</tt> for subscription, nor did it
-have anything resembling the <tt>smp_read_barrier_depends()</tt>
-that was later subsumed into <tt>rcu_dereference()</tt>.
-The need for these operations made itself known quite suddenly at a
-late-1990s meeting with the DEC Alpha architects, back in the days when
-DEC was still a free-standing company.
-It took the Alpha architects a good hour to convince me that any sort
-of barrier would ever be needed, and it then took me a good <i>two</i> hours
-to convince them that their documentation did not make this point clear.
-More recent work with the C and C++ standards committees have provided
-much education on tricks and traps from the compiler.
-In short, compilers were much less tricky in the early 1990s, but in
-2015, don't even think about omitting <tt>rcu_dereference()</tt>!
+Note that these memory-barrier requirements do not replace the fundamental
+RCU requirement that a grace period wait for all pre-existing readers.
+On the contrary, the memory barriers called out in this section must operate in
+such a way as to <i>enforce</i> this fundamental requirement.
+Of course, different implementations enforce this requirement in different
+ways, but enforce it they must.
 
 <h3><a name="RCU Primitives Guaranteed to Execute Unconditionally">RCU Primitives Guaranteed to Execute Unconditionally</a></h3>
 
diff --git a/Documentation/RCU/Design/Requirements/Requirements.htmlx b/Documentation/RCU/Design/Requirements/Requirements.htmlx
index f7c817f235e0..2d0cd90987f6 100644
--- a/Documentation/RCU/Design/Requirements/Requirements.htmlx
+++ b/Documentation/RCU/Design/Requirements/Requirements.htmlx
@@ -78,6 +78,8 @@ These are:
 	Grace-Period Guarantee</a>
 <li>	<a href="#Publish-Subscribe Guarantee">
 	Publish-Subscribe Guarantee</a>
+<li>	<a href="#Memory-Barrier Guarantees">
+	Memory-Barrier Guarantees</a>
 <li>	<a href="#RCU Primitives Guaranteed to Execute Unconditionally">
 	RCU Primitives Guaranteed to Execute Unconditionally</a>
 <li>	<a href="#Guaranteed Read-to-Write Upgrade">
@@ -539,9 +541,37 @@ either <tt>rcu_access_pointer()</tt> or <tt>rcu_dereference()</tt>.
 <p>@@QQE@@
 
 <p>
-This simple linked-data-structure scenario clearly demonstrates the need
-for RCU's stringent memory-ordering guarantees on systems with more than
-one CPU:
+In short, RCU's publish-subscribe guarantee is provided by the combination
+of <tt>rcu_assign_pointer()</tt> and <tt>rcu_dereference()</tt>.
+This guarantee allows data elements to be safely added to RCU-protected
+linked data structures without disrupting RCU readers.
+This guarantee can be used in combination with the grace-period
+guarantee to also allow data elements to be removed from RCU-protected
+linked data structures, again without disrupting RCU readers.
+
+<p>
+This guarantee was only partially premeditated.
+DYNIX/ptx used an explicit memory barrier for publication, but had nothing
+resembling <tt>rcu_dereference()</tt> for subscription, nor did it
+have anything resembling the <tt>smp_read_barrier_depends()</tt>
+that was later subsumed into <tt>rcu_dereference()</tt>.
+The need for these operations made itself known quite suddenly at a
+late-1990s meeting with the DEC Alpha architects, back in the days when
+DEC was still a free-standing company.
+It took the Alpha architects a good hour to convince me that any sort
+of barrier would ever be needed, and it then took me a good <i>two</i> hours
+to convince them that their documentation did not make this point clear.
+More recent work with the C and C++ standards committees have provided
+much education on tricks and traps from the compiler.
+In short, compilers were much less tricky in the early 1990s, but in
+2015, don't even think about omitting <tt>rcu_dereference()</tt>!
+
+<h3><a name="Memory-Barrier Guarantees">Memory-Barrier Guarantees</a></h3>
+
+<p>
+The previous section's simple linked-data-structure scenario clearly
+demonstrates the need for RCU's stringent memory-ordering guarantees on
+systems with more than one CPU:
 
 <ol>
 <li>	Each CPU that has an RCU read-side critical section that
@@ -653,30 +683,12 @@ adhered to the as-if rule than it is to actually adhere to it!
 <p>@@QQE@@
 
 <p>
-In short, RCU's publish-subscribe guarantee is provided by the combination
-of <tt>rcu_assign_pointer()</tt> and <tt>rcu_dereference()</tt>.
-This guarantee allows data elements to be safely added to RCU-protected
-linked data structures without disrupting RCU readers.
-This guarantee can be used in combination with the grace-period
-guarantee to also allow data elements to be removed from RCU-protected
-linked data structures, again without disrupting RCU readers.
-
-<p>
-This guarantee was only partially premeditated.
-DYNIX/ptx used an explicit memory barrier for publication, but had nothing
-resembling <tt>rcu_dereference()</tt> for subscription, nor did it
-have anything resembling the <tt>smp_read_barrier_depends()</tt>
-that was later subsumed into <tt>rcu_dereference()</tt>.
-The need for these operations made itself known quite suddenly at a
-late-1990s meeting with the DEC Alpha architects, back in the days when
-DEC was still a free-standing company.
-It took the Alpha architects a good hour to convince me that any sort
-of barrier would ever be needed, and it then took me a good <i>two</i> hours
-to convince them that their documentation did not make this point clear.
-More recent work with the C and C++ standards committees have provided
-much education on tricks and traps from the compiler.
-In short, compilers were much less tricky in the early 1990s, but in
-2015, don't even think about omitting <tt>rcu_dereference()</tt>!
+Note that these memory-barrier requirements do not replace the fundamental
+RCU requirement that a grace period wait for all pre-existing readers.
+On the contrary, the memory barriers called out in this section must operate in
+such a way as to <i>enforce</i> this fundamental requirement.
+Of course, different implementations enforce this requirement in different
+ways, but enforce it they must.
 
 <h3><a name="RCU Primitives Guaranteed to Execute Unconditionally">RCU Primitives Guaranteed to Execute Unconditionally</a></h3>
 
-- 
2.5.2

--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/

[toc] | [prev] | [next] | [standalone]

#1288027 — [PATCH v2 tip/core/rcu 7/8] documentation: Update RCU requirements based on expedited changes

Because RCU-sched expedited grace periods now use IPIs and interact
with rcu_read_unlock(), it is no longer sufficient to disable preemption
across RCU read-side critical sections that acquire and hold scheduler
locks.  It is now necessary to instead disable interrupts.  This commit
documents this change.

Signed-off-by: Paul E. McKenney <paulmck@linux.vnet.ibm.com>
---
 Documentation/RCU/Design/Requirements/Requirements.html  | 12 ++++++++++--
 Documentation/RCU/Design/Requirements/Requirements.htmlx | 10 +++++++++-
 2 files changed, 19 insertions(+), 3 deletions(-)

diff --git a/Documentation/RCU/Design/Requirements/Requirements.html b/Documentation/RCU/Design/Requirements/Requirements.html
index 96cdcf7195d5..a725f9900ec8 100644
--- a/Documentation/RCU/Design/Requirements/Requirements.html
+++ b/Documentation/RCU/Design/Requirements/Requirements.html
@@ -1,5 +1,5 @@
 <!-- DO NOT HAND EDIT. -->
-<!-- Instead, edit Requirements.htmlx and run 'sh htmlqqz.sh Requirements' -->
+<!-- Instead, edit Documentation/RCU/Design/Requirements/Requirements.htmlx and run 'sh htmlqqz.sh Documentation/RCU/Design/Requirements/Requirements' -->
 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
         "http://www.w3.org/TR/html4/loose.dtd">
         <html>
@@ -1957,7 +1957,7 @@ the runqueue locks and the priority-inheritance locks
 in the middle of an outermost RCU read-side critical section unless either
 (1)&nbsp;it releases them before exiting that same
 RCU read-side critical section, or
-(2)&nbsp;preemption is disabled across
+(2)&nbsp;interrupts are disabled across
 that entire RCU read-side critical section.
 This same prohibition also applies (recursively!) to any lock that is acquired
 while holding any lock to which this prohibition applies.
@@ -1966,6 +1966,14 @@ Adhering to this rule prevents preemptible RCU from invoking
 priority-inheritance locks are held, thus avoiding deadlock.
 
 <p>
+Prior to v4.4, it was only necessary to disable preemption across
+RCU read-side critical sections that acquired scheduler locks.
+In v4.4, expedited grace periods started using IPIs, and these
+IPIs could force a <tt>rcu_read_unlock()</tt> to take the slowpath.
+Therefore, this expedited-grace-period change required disabling of
+interrupts, not just preemption.
+
+<p>
 For RCU's part, the preemptible-RCU <tt>rcu_read_unlock()</tt>
 implementation must be written carefully to avoid similar deadlocks.
 In particular, <tt>rcu_read_unlock()</tt> must tolerate an
diff --git a/Documentation/RCU/Design/Requirements/Requirements.htmlx b/Documentation/RCU/Design/Requirements/Requirements.htmlx
index 2d0cd90987f6..3a97ba490c42 100644
--- a/Documentation/RCU/Design/Requirements/Requirements.htmlx
+++ b/Documentation/RCU/Design/Requirements/Requirements.htmlx
@@ -2124,7 +2124,7 @@ the runqueue locks and the priority-inheritance locks
 in the middle of an outermost RCU read-side critical section unless either
 (1)&nbsp;it releases them before exiting that same
 RCU read-side critical section, or
-(2)&nbsp;preemption is disabled across
+(2)&nbsp;interrupts are disabled across
 that entire RCU read-side critical section.
 This same prohibition also applies (recursively!) to any lock that is acquired
 while holding any lock to which this prohibition applies.
@@ -2133,6 +2133,14 @@ Adhering to this rule prevents preemptible RCU from invoking
 priority-inheritance locks are held, thus avoiding deadlock.
 
 <p>
+Prior to v4.4, it was only necessary to disable preemption across
+RCU read-side critical sections that acquired scheduler locks.
+In v4.4, expedited grace periods started using IPIs, and these
+IPIs could force a <tt>rcu_read_unlock()</tt> to take the slowpath.
+Therefore, this expedited-grace-period change required disabling of
+interrupts, not just preemption.
+
+<p>
 For RCU's part, the preemptible-RCU <tt>rcu_read_unlock()</tt>
 implementation must be written carefully to avoid similar deadlocks.
 In particular, <tt>rcu_read_unlock()</tt> must tolerate an
-- 
2.5.2

--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/

[toc] | [prev] | [standalone]

Back to top | Article view | linux.kernel

csiph-web