From: "Paul E. McKenney" <paulmck@linux.ibm.com>
To: linux-kernel@vger.kernel.org
Cc: mingo@kernel.org, jiangshanlai@gmail.com, dipankar@in.ibm.com,
akpm@linux-foundation.org, mathieu.desnoyers@efficios.com,
josh@joshtriplett.org, tglx@linutronix.de, peterz@infradead.org,
rostedt@goodmis.org, dhowells@redhat.com, edumazet@google.com,
fweisbec@gmail.com, oleg@redhat.com, joel@joelfernandes.org,
"Paul E . McKenney" <paulmck@linux.ibm.com>
Subject: [PATCH tip/core/rcu 10/20] doc: rcu: Update core and full API in whatisRCU
Date: Sun, 11 Nov 2018 11:56:35 -0800 [thread overview]
Message-ID: <20181111195645.9205-10-paulmck@linux.ibm.com> (raw)
In-Reply-To: <20181111195619.GA6958@linux.ibm.com>
From: "Joel Fernandes (Google)" <joel@joelfernandes.org>
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) <joel@joelfernandes.org>
Signed-off-by: Paul E. McKenney <paulmck@linux.ibm.com>
---
Documentation/RCU/whatisRCU.txt | 55 +++++++++++++++++----------------
1 file changed, 28 insertions(+), 27 deletions(-)
diff --git a/Documentation/RCU/whatisRCU.txt b/Documentation/RCU/whatisRCU.txt
index 86d82f7f3500..7c33445fd0e5 100644
--- a/Documentation/RCU/whatisRCU.txt
+++ b/Documentation/RCU/whatisRCU.txt
@@ -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
--
2.17.1
next prev parent reply other threads:[~2018-11-11 19:58 UTC|newest]
Thread overview: 21+ messages / expand[flat|nested] mbox.gz Atom feed top
2018-11-11 19:56 [PATCH tip/core/rcu 0/20] Documentation updates for v4.21/v5.0 Paul E. McKenney
2018-11-11 19:56 ` [PATCH tip/core/rcu 01/20] doc: Set down forward-progress requirements Paul E. McKenney
2018-11-11 19:56 ` [PATCH tip/core/rcu 02/20] doc: Clarify RCU data-structure comment about rcu_tree fanout Paul E. McKenney
2018-11-11 19:56 ` [PATCH tip/core/rcu 03/20] doc: Remove rcu_preempt_state reference in stallwarn Paul E. McKenney
2018-11-11 19:56 ` [PATCH tip/core/rcu 04/20] doc: rcu: Update information about resched_cpu Paul E. McKenney
2018-11-11 19:56 ` [PATCH tip/core/rcu 05/20] doc: rcu: Remove rcu_dynticks from Data-Structures Paul E. McKenney
2018-11-11 19:56 ` [PATCH tip/core/rcu 06/20] doc: rcu: Update Data-Structures for RCU flavor consolidation Paul E. McKenney
2018-11-11 19:56 ` [PATCH tip/core/rcu 07/20] doc: rcu: Better clarify the rcu_segcblist ->len field Paul E. McKenney
2018-11-11 19:56 ` [PATCH tip/core/rcu 08/20] doc: rcu: Update description of gp_seq fields in rcu_data Paul E. McKenney
2018-11-11 19:56 ` [PATCH tip/core/rcu 09/20] doc: Document rcutorture forward-progress test kernel parameters Paul E. McKenney
2018-11-11 19:56 ` Paul E. McKenney [this message]
2018-11-11 19:56 ` [PATCH tip/core/rcu 11/20] doc: rcu: Add more rationale for using rcu_read_lock_sched in checklist Paul E. McKenney
2018-11-11 19:56 ` [PATCH tip/core/rcu 12/20] doc: rcu: Remove obsolete suggestion from checklist Paul E. McKenney
2018-11-11 19:56 ` [PATCH tip/core/rcu 13/20] doc: rcu: Remove obsolete checklist item about synchronize_rcu usage Paul E. McKenney
2018-11-11 19:56 ` [PATCH tip/core/rcu 14/20] doc: rcu: Encourage use of rcu_barrier in checklist Paul E. McKenney
2018-11-11 19:56 ` [PATCH tip/core/rcu 15/20] doc: Make reader aware of rcu_dereference_protected Paul E. McKenney
2018-11-11 19:56 ` [PATCH tip/core/rcu 16/20] doc: Remove obsolete (non-)requirement about disabling preemption Paul E. McKenney
2018-11-11 19:56 ` [PATCH tip/core/rcu 17/20] doc: Make listing in RCU perf/scale requirements use rcu_assign_pointer() Paul E. McKenney
2018-11-11 19:56 ` [PATCH tip/core/rcu 18/20] doc: RCU scheduler spinlock rcu_read_unlock() restriction remains Paul E. McKenney
2018-11-11 19:56 ` [PATCH tip/core/rcu 19/20] doc: Correct parameter in stallwarn Paul E. McKenney
2018-11-11 19:56 ` [PATCH tip/core/rcu 20/20] doc: Fix "struction" typo in RCU memory-ordering documentation Paul E. McKenney
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20181111195645.9205-10-paulmck@linux.ibm.com \
--to=paulmck@linux.ibm.com \
--cc=akpm@linux-foundation.org \
--cc=dhowells@redhat.com \
--cc=dipankar@in.ibm.com \
--cc=edumazet@google.com \
--cc=fweisbec@gmail.com \
--cc=jiangshanlai@gmail.com \
--cc=joel@joelfernandes.org \
--cc=josh@joshtriplett.org \
--cc=linux-kernel@vger.kernel.org \
--cc=mathieu.desnoyers@efficios.com \
--cc=mingo@kernel.org \
--cc=oleg@redhat.com \
--cc=peterz@infradead.org \
--cc=rostedt@goodmis.org \
--cc=tglx@linutronix.de \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).