Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 9ceae0e2 authored by Paul E. McKenney's avatar Paul E. McKenney
Browse files

rcu: Add documentation for raw SRCU read-side primitives 



Update various files in Documentation/RCU to reflect srcu_read_lock_raw()
and srcu_read_unlock_raw().  Credit to Peter Zijlstra for suggesting
use of the existing _raw suffix instead of the earlier bulkref names.

Signed-off-by: default avatarPaul E. McKenney <paulmck@linux.vnet.ibm.com>
parent 0c53dd8b

Documentation/RCU/checklist.txt

+6 −0
Original line number Diff line number Diff line
@@ -328,6 +328,12 @@ over a rather long period of time, but improvements are always welcome! 
	RCU rather than SRCU, because RCU is almost always faster and

	easier to use than is SRCU.



	If you need to enter your read-side critical section in a

	hardirq or exception handler, and then exit that same read-side

	critical section in the task that was interrupted, then you need

	to srcu_read_lock_raw() and srcu_read_unlock_raw(), which avoid

	the lockdep checking that would otherwise this practice illegal.



	Also unlike other forms of RCU, explicit initialization

	and cleanup is required via init_srcu_struct() and

	cleanup_srcu_struct().	These are passed a "struct srcu_struct"

Documentation/RCU/rcu.txt

+5 −5
Original line number Diff line number Diff line
@@ -38,11 +38,11 @@ o How can the updater tell when a grace period has completed 


	Preemptible variants of RCU (CONFIG_TREE_PREEMPT_RCU) get the

	same effect, but require that the readers manipulate CPU-local

	counters.  These counters allow limited types of blocking

	within RCU read-side critical sections.  SRCU also uses

	CPU-local counters, and permits general blocking within

	RCU read-side critical sections.  These two variants of

	RCU detect grace periods by sampling these counters.

	counters.  These counters allow limited types of blocking within

	RCU read-side critical sections.  SRCU also uses CPU-local

	counters, and permits general blocking within RCU read-side

	critical sections.  These variants of RCU detect grace periods

	by sampling these counters.



o	If I am running on a uniprocessor kernel, which can only do one

	thing at a time, why should I wait for a grace period?

Documentation/RCU/stallwarn.txt

+5 −6
Original line number Diff line number Diff line
@@ -114,12 +114,11 @@ o A hardware failure. This is quite unlikely, but has occurred 
	This resulted in a series of RCU CPU stall warnings, eventually

	leading the realization that the CPU had failed.



The RCU, RCU-sched, and RCU-bh implementations have CPU stall

warning.  SRCU does not have its own CPU stall warnings, but its

calls to synchronize_sched() will result in RCU-sched detecting

RCU-sched-related CPU stalls.  Please note that RCU only detects

CPU stalls when there is a grace period in progress.  No grace period,

no CPU stall warnings.

The RCU, RCU-sched, and RCU-bh implementations have CPU stall warning.

SRCU does not have its own CPU stall warnings, but its calls to

synchronize_sched() will result in RCU-sched detecting RCU-sched-related

CPU stalls.  Please note that RCU only detects CPU stalls when there is

a grace period in progress.  No grace period, no CPU stall warnings.



To diagnose the cause of the stall, inspect the stack traces.

The offending function will usually be near the top of the stack.

Documentation/RCU/whatisRCU.txt

+13 −5
Original line number Diff line number Diff line
@@ -834,6 +834,8 @@ SRCU: Critical sections Grace period Barrier 


	srcu_read_lock		synchronize_srcu	N/A

	srcu_read_unlock	synchronize_srcu_expedited

	srcu_read_lock_raw

	srcu_read_unlock_raw

	srcu_dereference



SRCU:	Initialization/cleanup
@@ -855,27 +857,33 @@ list can be helpful: 


a.	Will readers need to block?  If so, you need SRCU.



b.	What about the -rt patchset?  If readers would need to block

b.	Is it necessary to start a read-side critical section in a

	hardirq handler or exception handler, and then to complete

	this read-side critical section in the task that was

	interrupted?  If so, you need SRCU's srcu_read_lock_raw() and

	srcu_read_unlock_raw() primitives.



c.	What about the -rt patchset?  If readers would need to block

	in an non-rt kernel, you need SRCU.  If readers would block

	in a -rt kernel, but not in a non-rt kernel, SRCU is not

	necessary.



c.	Do you need to treat NMI handlers, hardirq handlers,

d.	Do you need to treat NMI handlers, hardirq handlers,

	and code segments with preemption disabled (whether

	via preempt_disable(), local_irq_save(), local_bh_disable(),

	or some other mechanism) as if they were explicit RCU readers?

	If so, you need RCU-sched.



d.	Do you need RCU grace periods to complete even in the face

e.	Do you need RCU grace periods to complete even in the face

	of softirq monopolization of one or more of the CPUs?  For

	example, is your code subject to network-based denial-of-service

	attacks?  If so, you need RCU-bh.



e.	Is your workload too update-intensive for normal use of

f.	Is your workload too update-intensive for normal use of

	RCU, but inappropriate for other synchronization mechanisms?

	If so, consider SLAB_DESTROY_BY_RCU.  But please be careful!



f.	Otherwise, use RCU.

g.	Otherwise, use RCU.



Of course, this all assumes that you have determined that RCU is in fact

the right tool for your job.