Commit 1893afd6 authored by Paul E. McKenney's avatar Paul E. McKenney
Browse files

rcu: Improve comments describing RCU read-side critical sections 



There are a number of places that call out the fact that preempt-disable
regions of code now act as RCU read-side critical sections, where
preempt-disable regions of code include irq-disable regions of code,
bh-disable regions of code, hardirq handlers, and NMI handlers.  However,
someone relying solely on (for example) the call_rcu() header comment
might well have no idea that preempt-disable regions of code have RCU
semantics.

This commit therefore updates the header comments for
call_rcu(), synchronize_rcu(), rcu_dereference_bh_check(), and
rcu_dereference_sched_check() to call out these new(ish) forms of RCU
readers.

Reported-by: default avatarMichel Lespinasse <michel@lespinasse.org>
[ paulmck: Apply Matthew Wilcox and Michel Lespinasse feedback. ]
Signed-off-by: default avatarPaul E. McKenney <paulmck@kernel.org>
parent 76c8eaaf

include/linux/rcupdate.h

+28 −7
Original line number Diff line number Diff line
@@ -532,7 +532,12 @@ do { \ 
 * @p: The pointer to read, prior to dereferencing

 * @c: The conditions under which the dereference will take place

 *

 * This is the RCU-bh counterpart to rcu_dereference_check().

 * This is the RCU-bh counterpart to rcu_dereference_check().  However,

 * please note that starting in v5.0 kernels, vanilla RCU grace periods

 * wait for local_bh_disable() regions of code in addition to regions of

 * code demarked by rcu_read_lock() and rcu_read_unlock().  This means

 * that synchronize_rcu(), call_rcu, and friends all take not only

 * rcu_read_lock() but also rcu_read_lock_bh() into account.

 */

#define rcu_dereference_bh_check(p, c) \

	__rcu_dereference_check((p), (c) || rcu_read_lock_bh_held(), __rcu)
@@ -543,6 +548,11 @@ do { \ 
 * @c: The conditions under which the dereference will take place

 *

 * This is the RCU-sched counterpart to rcu_dereference_check().

 * However, please note that starting in v5.0 kernels, vanilla RCU grace

 * periods wait for preempt_disable() regions of code in addition to

 * regions of code demarked by rcu_read_lock() and rcu_read_unlock().

 * This means that synchronize_rcu(), call_rcu, and friends all take not

 * only rcu_read_lock() but also rcu_read_lock_sched() into account.

 */

#define rcu_dereference_sched_check(p, c) \

	__rcu_dereference_check((p), (c) || rcu_read_lock_sched_held(), \
@@ -634,6 +644,12 @@ do { \ 
 * sections, invocation of the corresponding RCU callback is deferred

 * until after the all the other CPUs exit their critical sections.

 *

 * In v5.0 and later kernels, synchronize_rcu() and call_rcu() also

 * wait for regions of code with preemption disabled, including regions of

 * code with interrupts or softirqs disabled.  In pre-v5.0 kernels, which

 * define synchronize_sched(), only code enclosed within rcu_read_lock()

 * and rcu_read_unlock() are guaranteed to be waited for.

 *

 * Note, however, that RCU callbacks are permitted to run concurrently

 * with new RCU read-side critical sections.  One way that this can happen

 * is via the following sequence of events: (1) CPU 0 enters an RCU
@@ -728,9 +744,11 @@ static inline void rcu_read_unlock(void) 
/**

 * rcu_read_lock_bh() - mark the beginning of an RCU-bh critical section

 *

 * This is equivalent of rcu_read_lock(), but also disables softirqs.

 * Note that anything else that disables softirqs can also serve as

 * an RCU read-side critical section.

 * This is equivalent to rcu_read_lock(), but also disables softirqs.

 * Note that anything else that disables softirqs can also serve as an RCU

 * read-side critical section.  However, please note that this equivalence

 * applies only to v5.0 and later.  Before v5.0, rcu_read_lock() and

 * rcu_read_lock_bh() were unrelated.

 *

 * Note that rcu_read_lock_bh() and the matching rcu_read_unlock_bh()

 * must occur in the same context, for example, it is illegal to invoke
@@ -763,9 +781,12 @@ static inline void rcu_read_unlock_bh(void) 
/**

 * rcu_read_lock_sched() - mark the beginning of a RCU-sched critical section

 *

 * This is equivalent of rcu_read_lock(), but disables preemption.

 * Read-side critical sections can also be introduced by anything else

 * that disables preemption, including local_irq_disable() and friends.

 * This is equivalent to rcu_read_lock(), but also disables preemption.

 * Read-side critical sections can also be introduced by anything else that

 * disables preemption, including local_irq_disable() and friends.  However,

 * please note that the equivalence to rcu_read_lock() applies only to

 * v5.0 and later.  Before v5.0, rcu_read_lock() and rcu_read_lock_sched()

 * were unrelated.

 *

 * Note that rcu_read_lock_sched() and the matching rcu_read_unlock_sched()

 * must occur in the same context, for example, it is illegal to invoke

kernel/rcu/tree.c

+14 −10
Original line number Diff line number Diff line
@@ -3059,12 +3059,14 @@ __call_rcu(struct rcu_head *head, rcu_callback_t func) 
 * period elapses, in other words after all pre-existing RCU read-side

 * critical sections have completed.  However, the callback function

 * might well execute concurrently with RCU read-side critical sections

 * that started after call_rcu() was invoked.  RCU read-side critical

 * sections are delimited by rcu_read_lock() and rcu_read_unlock(), and

 * may be nested.  In addition, regions of code across which interrupts,

 * preemption, or softirqs have been disabled also serve as RCU read-side

 * critical sections.  This includes hardware interrupt handlers, softirq

 * handlers, and NMI handlers.

 * that started after call_rcu() was invoked.

 *

 * RCU read-side critical sections are delimited by rcu_read_lock()

 * and rcu_read_unlock(), and may be nested.  In addition, but only in

 * v5.0 and later, regions of code across which interrupts, preemption,

 * or softirqs have been disabled also serve as RCU read-side critical

 * sections.  This includes hardware interrupt handlers, softirq handlers,

 * and NMI handlers.

 *

 * Note that all CPUs must agree that the grace period extended beyond

 * all pre-existing RCU read-side critical section.  On systems with more
@@ -3730,10 +3732,12 @@ static int rcu_blocking_is_gp(void) 
 * read-side critical sections have completed.  Note, however, that

 * upon return from synchronize_rcu(), the caller might well be executing

 * concurrently with new RCU read-side critical sections that began while

 * synchronize_rcu() was waiting.  RCU read-side critical sections are

 * delimited by rcu_read_lock() and rcu_read_unlock(), and may be nested.

 * In addition, regions of code across which interrupts, preemption, or

 * softirqs have been disabled also serve as RCU read-side critical

 * synchronize_rcu() was waiting.

 *

 * RCU read-side critical sections are delimited by rcu_read_lock()

 * and rcu_read_unlock(), and may be nested.  In addition, but only in

 * v5.0 and later, regions of code across which interrupts, preemption,

 * or softirqs have been disabled also serve as RCU read-side critical

 * sections.  This includes hardware interrupt handlers, softirq handlers,

 * and NMI handlers.

 *