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

An IRC discussion uncovered many conflicting opinions on what types
of data may be atomically loaded and stored. This commit therefore
calls this out the official set: pointers, longs, ints, and chars (but
not shorts). This commit also gives some examples of compiler mischief
that can thwart atomicity.

Please note that this discussion is relevant to !SMP kernels if
CONFIG_PREEMPT=y: preemption can cause almost as much trouble as can SMP.

Signed-off-by: Paul E. McKenney <[e-mail]>
Cc: Richard Henderson <[e-mail]>
Cc: Ivan Kokshaysky <[e-mail]>
Cc: Matt Turner <[e-mail]>
Cc: Russell King <[e-mail]>
Cc: Haavard Skinnemoen <[e-mail]>
Cc: Hans-Christian Egtvedt <[e-mail]>
Cc: Mike Frysinger <[e-mail]>
Cc: Mikael Starvik <[e-mail]>
Cc: Jesper Nilsson <[e-mail]>
Cc: David Howells <[e-mail]>
Cc: Yoshinori Sato <[e-mail]>
Cc: Richard Kuo <[e-mail]>
Cc: Jes Sorensen <[e-mail]>
Cc: Hirokazu Takata <[e-mail]>
Cc: Geert Uytterhoeven <[e-mail]>
Cc: Michal Simek <[e-mail]>
Cc: Ralf Baechle <[e-mail]>
Cc: Koichi Yasutake <[e-mail]>
Cc: Jonas Bonn <[e-mail]>
Cc: Kyle McMartin <[e-mail]>
Cc: Helge Deller <[e-mail]>
Cc: "James E.J. Bottomley" <[e-mail]>
Cc: Benjamin Herrenschmidt <[e-mail]>
Cc: Paul Mackerras <[e-mail]>
Cc: Martin Schwidefsky <[e-mail]>
Cc: Heiko Carstens <[e-mail]>
Cc: Chen Liqin <[e-mail]>
Cc: Lennox Wu <[e-mail]>
Cc: Paul Mundt <[e-mail]>
Cc: "David S. Miller" <[e-mail]>
Cc: Chris Metcalf <[e-mail]>
Cc: Jeff Dike <[e-mail]>
Cc: Richard Weinberger <[e-mail]>
Cc: Guan Xuetao <[e-mail]>
Cc: Thomas Gleixner <[e-mail]>
Cc: Ingo Molnar <[e-mail]>
Cc: "H. Peter Anvin" <[e-mail]>
Cc: Chris Zankel <[e-mail]>

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.