rcu: Documentation update

	whether the increased speed is worth it.

8.	Although synchronize_rcu() is slower than is call_rcu(), it

	usually results in simpler code.  So, unless update performance

	is critically important or the updaters cannot block,

	synchronize_rcu() should be used in preference to call_rcu().

	usually results in simpler code.  So, unless update performance is

	critically important, the updaters cannot block, or the latency of

	synchronize_rcu() is visible from userspace, synchronize_rcu()

	should be used in preference to call_rcu().  Furthermore,

	kfree_rcu() usually results in even simpler code than does

	synchronize_rcu() without synchronize_rcu()'s multi-millisecond

	latency.  So please take advantage of kfree_rcu()'s "fire and

	forget" memory-freeing capabilities where it applies.

	An especially important property of the synchronize_rcu()

	primitive is that it automatically self-limits: if grace periods

	e.	Periodically invoke synchronize_rcu(), permitting a limited

		number of updates per grace period.

	The same cautions apply to call_rcu_bh() and call_rcu_sched().

	The same cautions apply to call_rcu_bh(), call_rcu_sched(),

	call_srcu(), and kfree_rcu().

9.	All RCU list-traversal primitives, which include

	rcu_dereference(), list_for_each_entry_rcu(), and

	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 you do not have

	rcu_read_lock()-protected read-side critical sections, do -not-

	use synchronize_rcu().

	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

	read-side critical sections.  It is the responsibility of the

	RCU update-side primitives to deal with this.

17.	Use CONFIG_PROVE_RCU, CONFIG_DEBUG_OBJECTS_RCU_HEAD, and

	the __rcu sparse checks to validate your RCU code.  These

	can help find problems as follows:

17.	Use CONFIG_PROVE_RCU, CONFIG_DEBUG_OBJECTS_RCU_HEAD, and the

	__rcu sparse checks (enabled by CONFIG_SPARSE_RCU_POINTER) to

	validate your RCU code.  These can help find problems as follows:

	CONFIG_PROVE_RCU: check that accesses to RCU-protected data

		structures are carried out under the proper RCU

		but retain the compiler constraints that prevent duplicating

		or coalescsing.  This is useful when when testing the

		value of the pointer itself, for example, against NULL.

	rcu_access_index(idx):

		Return the value of the index and omit all barriers, but

		retain the compiler constraints that prevent duplicating

		or coalescsing.  This is useful when when testing the

		value of the index itself, for example, against -1.

The rcu_dereference_check() check expression can be any boolean

expression, but would normally include a lockdep expression.  However,

   2. Execute rcu_barrier().

   3. Allow the module to be unloaded.

The rcutorture module makes use of rcu_barrier in its exit function

There are also rcu_barrier_bh(), rcu_barrier_sched(), and srcu_barrier()

functions for the other flavors of RCU, and you of course must match

the flavor of rcu_barrier() with that of call_rcu().  If your module

uses multiple flavors of call_rcu(), then it must also use multiple

flavors of rcu_barrier() when unloading that module.  For example, if

it uses call_rcu_bh(), call_srcu() on srcu_struct_1, and call_srcu() on

srcu_struct_2(), then the following three lines of code will be required

when unloading:

 1 rcu_barrier_bh();

 2 srcu_barrier(&srcu_struct_1);

 3 srcu_barrier(&srcu_struct_2);

The rcutorture module makes use of rcu_barrier() in its exit function

as follows:

 1 static void