doc: Add load/store guarantees to Documentation/atomic-ops.txt

*** YOU HAVE BEEN WARNED! ***

Properly aligned pointers, longs, ints, and chars (and unsigned

equivalents) may be atomically loaded from and stored to in the same

sense as described for atomic_read() and atomic_set().  The ACCESS_ONCE()

macro should be used to prevent the compiler from using optimizations

that might otherwise optimize accesses out of existence on the one hand,

or that might create unsolicited accesses on the other.

For example consider the following code:

	while (a > 0)

		do_something();

If the compiler can prove that do_something() does not store to the

variable a, then the compiler is within its rights transforming this to

the following:

	tmp = a;

	if (a > 0)

		for (;;)

			do_something();

If you don't want the compiler to do this (and you probably don't), then

you should use something like the following:

	while (ACCESS_ONCE(a) < 0)

		do_something();

Alternatively, you could place a barrier() call in the loop.

For another example, consider the following code:

	tmp_a = a;

	do_something_with(tmp_a);

	do_something_else_with(tmp_a);

If the compiler can prove that do_something_with() does not store to the

variable a, then the compiler is within its rights to manufacture an

additional load as follows:

	tmp_a = a;

	do_something_with(tmp_a);

	tmp_a = a;

	do_something_else_with(tmp_a);

This could fatally confuse your code if it expected the same value

to be passed to do_something_with() and do_something_else_with().

The compiler would be likely to manufacture this additional load if

do_something_with() was an inline function that made very heavy use

of registers: reloading from variable a could save a flush to the

stack and later reload.  To prevent the compiler from attacking your

code in this manner, write the following:

	tmp_a = ACCESS_ONCE(a);

	do_something_with(tmp_a);

	do_something_else_with(tmp_a);

For a final example, consider the following code, assuming that the

variable a is set at boot time before the second CPU is brought online

and never changed later, so that memory barriers are not needed:

	if (a)

		b = 9;

	else

		b = 42;

The compiler is within its rights to manufacture an additional store

by transforming the above code into the following:

	b = 42;

	if (a)

		b = 9;

This could come as a fatal surprise to other code running concurrently

that expected b to never have the value 42 if a was zero.  To prevent

the compiler from doing this, write something like:

	if (a)

		ACCESS_ONCE(b) = 9;

	else

		ACCESS_ONCE(b) = 42;

Don't even -think- about doing this without proper use of memory barriers,

locks, or atomic operations if variable a can change at runtime!

*** WARNING: ACCESS_ONCE() DOES NOT IMPLY A BARRIER! ***

Now, we move onto the atomic operation interfaces typically implemented with

the help of assembly code.