Merge branch 'rcu/doc' of...

	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

more information is printed with the stall-warning message, for example:

	INFO: rcu_preempt detected stall on CPU

	0: (63959 ticks this GP) idle=241/3fffffffffffffff/0

	0: (63959 ticks this GP) idle=241/3fffffffffffffff/0 softirq=82/543

	   (t=65000 jiffies)

In kernels with CONFIG_RCU_FAST_NO_HZ, even more information is

printed:

	INFO: rcu_preempt detected stall on CPU

	0: (64628 ticks this GP) idle=dd5/3fffffffffffffff/0 drain=0 . timer not pending

	0: (64628 ticks this GP) idle=dd5/3fffffffffffffff/0 softirq=82/543 last_accelerate: a345/d342 nonlazy_posted: 25 .D

	   (t=65000 jiffies)

The "(64628 ticks this GP)" indicates that this CPU has taken more

be a small positive number if in the idle loop and a very large positive

number (as shown above) otherwise.

For CONFIG_RCU_FAST_NO_HZ kernels, the "drain=0" indicates that the CPU is

not in the process of trying to force itself into dyntick-idle state, the

"." indicates that the CPU has not given up forcing RCU into dyntick-idle

mode (it would be "H" otherwise), and the "timer not pending" indicates

that the CPU has not recently forced RCU into dyntick-idle mode (it

would otherwise indicate the number of microseconds remaining in this

forced state).

The "softirq=" portion of the message tracks the number of RCU softirq

handlers that the stalled CPU has executed.  The number before the "/"

is the number that had executed since boot at the time that this CPU

last noted the beginning of a grace period, which might be the current

(stalled) grace period, or it might be some earlier grace period (for

example, if the CPU might have been in dyntick-idle mode for an extended

time period.  The number after the "/" is the number that have executed

since boot until the current time.  If this latter number stays constant

across repeated stall-warning messages, it is possible that RCU's softirq

handlers are no longer able to execute on this CPU.  This can happen if

the stalled CPU is spinning with interrupts are disabled, or, in -rt

kernels, if a high-priority process is starving RCU's softirq handler.

For CONFIG_RCU_FAST_NO_HZ kernels, the "last_accelerate:" prints the

low-order 16 bits (in hex) of the jiffies counter when this CPU last

invoked rcu_try_advance_all_cbs() from rcu_needs_cpu() or last invoked

rcu_accelerate_cbs() from rcu_prepare_for_idle().  The "nonlazy_posted:"

prints the number of non-lazy callbacks posted since the last call to

rcu_needs_cpu().  Finally, an "L" indicates that there are currently

no non-lazy callbacks ("." is printed otherwise, as shown above) and

"D" indicates that dyntick-idle processing is enabled ("." is printed

otherwise, for example, if disabled via the "nohz=" kernel boot parameter).

Multiple Warnings From One Stall

		rcu_read_lock();

		p = rcu_dereference(head.next);

		rcu_read_unlock();

		x = p->address;

		x = p->address;	/* BUG!!! */

		rcu_read_lock();

		y = p->data;

		y = p->data;	/* BUG!!! */

		rcu_read_unlock();

	Holding a reference from one RCU read-side critical section