Merge branches 'array.2015.05.27a', 'doc.2015.05.27a', 'fixes.2015.05.27a',...

		pointer.  Note that the volatile cast in rcu_dereference()

		will normally prevent the compiler from knowing too much.

		However, please note that if the compiler knows that the

		pointer takes on only one of two values, a not-equal

		comparison will provide exactly the information that the

		compiler needs to deduce the value of the pointer.

o	Disable any value-speculation optimizations that your compiler

	might provide, especially if you are making use of feedback-based

	optimizations that take data collected from prior runs.  Such

	If you are going to be fetching multiple fields from the

	RCU-protected structure, using the local variable is of

	course preferred.  Repeated rcu_dereference() calls look

	ugly and incur unnecessary overhead on Alpha CPUs.

	ugly, do not guarantee that the same pointer will be returned

	if an update happened while in the critical section, and incur

	unnecessary overhead on Alpha CPUs.

	Note that the value returned by rcu_dereference() is valid

	only within the enclosing RCU read-side critical section.

			Set maximum number of finished RCU callbacks to

			process in one batch.

	rcutree.dump_tree=	[KNL]

			Dump the structure of the rcu_node combining tree

			out at early boot.  This is used for diagnostic

			purposes, to verify correct tree setup.

	rcutree.gp_cleanup_delay=	[KNL]

			Set the number of jiffies to delay each step of

			RCU grace-period cleanup.  This only has effect

			when CONFIG_RCU_TORTURE_TEST_SLOW_CLEANUP is set.

	rcutree.gp_init_delay=	[KNL]

			Set the number of jiffies to delay each step of

			RCU grace-period initialization.  This only has

			effect when CONFIG_RCU_TORTURE_TEST_SLOW_INIT is

			set.

			effect when CONFIG_RCU_TORTURE_TEST_SLOW_INIT

			is set.

	rcutree.gp_preinit_delay=	[KNL]

			Set the number of jiffies to delay each step of

			RCU grace-period pre-initialization, that is,

			the propagation of recent CPU-hotplug changes up

			the rcu_node combining tree.  This only has effect

			when CONFIG_RCU_TORTURE_TEST_SLOW_PREINIT is set.

	rcutree.rcu_fanout_exact= [KNL]

			Disable autobalancing of the rcu_node combining

			tree.  This is used by rcutorture, and might

			possibly be useful for architectures having high

			cache-to-cache transfer latencies.

	rcutree.rcu_fanout_leaf= [KNL]

			Increase the number of CPUs assigned to each

			test, hence the "fake".

	rcutorture.nreaders= [KNL]

			Set number of RCU readers.

			Set number of RCU readers.  The value -1 selects

			N-1, where N is the number of CPUs.  A value

			"n" less than -1 selects N-n-2, where N is again

			the number of CPUs.  For example, -2 selects N

			(the number of CPUs), -3 selects N+1, and so on.

	rcutorture.object_debug= [KNL]

			Enable debug-object double-call_rcu() testing.

However, stores are not speculated.  This means that ordering -is- provided

for load-store control dependencies, as in the following example:

	q = ACCESS_ONCE(a);

	q = READ_ONCE_CTRL(a);

	if (q) {

		ACCESS_ONCE(b) = p;

	}

Control dependencies pair normally with other types of barriers.

That said, please note that ACCESS_ONCE() is not optional!  Without the

ACCESS_ONCE(), might combine the load from 'a' with other loads from

'a', and the store to 'b' with other stores to 'b', with possible highly

counterintuitive effects on ordering.

Control dependencies pair normally with other types of barriers.  That

said, please note that READ_ONCE_CTRL() is not optional!  Without the

READ_ONCE_CTRL(), the compiler might combine the load from 'a' with

other loads from 'a', and the store to 'b' with other stores to 'b',

with possible highly counterintuitive effects on ordering.

Worse yet, if the compiler is able to prove (say) that the value of

variable 'a' is always non-zero, it would be well within its rights

	q = a;

	b = p;  /* BUG: Compiler and CPU can both reorder!!! */

So don't leave out the ACCESS_ONCE().

Finally, the READ_ONCE_CTRL() includes an smp_read_barrier_depends()

that DEC Alpha needs in order to respect control depedencies.

So don't leave out the READ_ONCE_CTRL().

It is tempting to try to enforce ordering on identical stores on both

branches of the "if" statement as follows:

	q = ACCESS_ONCE(a);

	q = READ_ONCE_CTRL(a);

	if (q) {

		barrier();

		ACCESS_ONCE(b) = p;

Unfortunately, current compilers will transform this as follows at high

optimization levels:

	q = ACCESS_ONCE(a);

	q = READ_ONCE_CTRL(a);

	barrier();

	ACCESS_ONCE(b) = p;  /* BUG: No ordering vs. load from a!!! */

	if (q) {

In contrast, without explicit memory barriers, two-legged-if control

ordering is guaranteed only when the stores differ, for example:

	q = ACCESS_ONCE(a);

	q = READ_ONCE_CTRL(a);

	if (q) {

		ACCESS_ONCE(b) = p;

		do_something();

		do_something_else();

	}

The initial ACCESS_ONCE() is still required to prevent the compiler from

proving the value of 'a'.

The initial READ_ONCE_CTRL() is still required to prevent the compiler

from proving the value of 'a'.

In addition, you need to be careful what you do with the local variable 'q',

otherwise the compiler might be able to guess the value and again remove

the needed conditional.  For example:

	q = ACCESS_ONCE(a);

	q = READ_ONCE_CTRL(a);

	if (q % MAX) {

		ACCESS_ONCE(b) = p;

		do_something();

equal to zero, in which case the compiler is within its rights to

transform the above code into the following:

	q = ACCESS_ONCE(a);

	q = READ_ONCE_CTRL(a);

	ACCESS_ONCE(b) = p;

	do_something_else();

relying on this ordering, you should make sure that MAX is greater than

one, perhaps as follows:

	q = ACCESS_ONCE(a);

	q = READ_ONCE_CTRL(a);

	BUILD_BUG_ON(MAX <= 1); /* Order load from a with store to b. */

	if (q % MAX) {

		ACCESS_ONCE(b) = p;

You must also be careful not to rely too much on boolean short-circuit

evaluation.  Consider this example:

	q = ACCESS_ONCE(a);

	q = READ_ONCE_CTRL(a);

	if (a || 1 > 0)

		ACCESS_ONCE(b) = 1;

Because the second condition is always true, the compiler can transform

this example as following, defeating control dependency:

Because the first condition cannot fault and the second condition is

always true, the compiler can transform this example as following,

defeating control dependency:

	q = ACCESS_ONCE(a);

	q = READ_ONCE_CTRL(a);

	ACCESS_ONCE(b) = 1;

This example underscores the need to ensure that the compiler cannot

x and y both being zero:

	CPU 0                     CPU 1

	=====================     =====================

	r1 = ACCESS_ONCE(x);      r2 = ACCESS_ONCE(y);

	=======================   =======================

	r1 = READ_ONCE_CTRL(x);   r2 = READ_ONCE_CTRL(y);

	if (r1 > 0)               if (r2 > 0)

	  ACCESS_ONCE(y) = 1;       ACCESS_ONCE(x) = 1;

assertion can fail after the combined three-CPU example completes.  If you

need the three-CPU example to provide ordering, you will need smp_mb()

between the loads and stores in the CPU 0 and CPU 1 code fragments,

that is, just before or just after the "if" statements.

that is, just before or just after the "if" statements.  Furthermore,

the original two-CPU example is very fragile and should be avoided.

These two examples are the LB and WWC litmus tests from this paper:

http://www.cl.cam.ac.uk/users/pes20/ppc-supplemental/test6.pdf and this

In summary:

  (*) Control dependencies must be headed by READ_ONCE_CTRL().

      Or, as a much less preferable alternative, interpose

      be headed by READ_ONCE() or an ACCESS_ONCE() read and must

      have smp_read_barrier_depends() between this read and the

      control-dependent write.

  (*) Control dependencies can order prior loads against later stores.

      However, they do -not- guarantee any other sort of ordering:

      Not prior loads against later loads, nor prior stores against

     Memory operations issued before the ACQUIRE may be completed after

     the ACQUIRE operation has completed.  An smp_mb__before_spinlock(),

     combined with a following ACQUIRE, orders prior loads against

     subsequent loads and stores and also orders prior stores against

     subsequent stores.  Note that this is weaker than smp_mb()!  The

     smp_mb__before_spinlock() primitive is free on many architectures.

     combined with a following ACQUIRE, orders prior stores against

     subsequent loads and stores. Note that this is weaker than smp_mb()!

     The smp_mb__before_spinlock() primitive is free on many architectures.

 (2) RELEASE operation implication:

#define smp_mb__before_atomic()     smp_mb()

#define smp_mb__after_atomic()      smp_mb()

#define smp_mb__before_spinlock()   smp_mb()

#endif /* _ASM_POWERPC_BARRIER_H */