[PATCH]: powerpc documentation: Clarify why twi appears in the i/o macros.

[Linas Vepstas]

Paul, a revised patch below, please apply.

On Wed, Dec 06, 2006 at 09:39:00PM +0300, Sergei Shtylyov wrote:
> 
>    A minor type here -- double "the".

Dohh. New patch below.

> WBR, Sergei

What does "WBR" mean?

--linas


Clarify why twi appears in the i/o macros.

Signed-off-by: Linas Vepstas <linas at austin.ibm.com>
Signed-off-by: Segher Boessenkool <segher at kernel.crashing.org>

----
 include/asm-powerpc/io.h |   11 +++++++++++
 1 file changed, 11 insertions(+)

Index: linux-2.6.19-git7/include/asm-powerpc/io.h
===================================================================
--- linux-2.6.19-git7.orig/include/asm-powerpc/io.h	2006-12-06 13:38:43.000000000 -0600
+++ linux-2.6.19-git7/include/asm-powerpc/io.h	2006-12-06 13:41:50.000000000 -0600
@@ -78,6 +78,17 @@ extern unsigned long pci_dram_offset;
  * Note: I might drop the _ns suffix on the stream operations soon as it is
  * simply normal for stream operations to not swap in the first place.
  *
+ * Read operations have additional twi & isync to make sure the read
+ * is actually performed (i.e. the data has come back) before we start
+ * executing any following instructions.
+ *
+ * A data-dependent branch followed by an isync ensures that
+ * no instructions after the isync in program order will be
+ * (speculatively) executed before the isync has completed,
+ * and the isync won't complete until the branch is resolved.
+ * The load that the twi depends on has to complete before
+ * anything else is executed; in particular, it's a barrier
+ * to keep MMIO reads ordered before main-storage accesses.
  */
 
 #ifdef CONFIG_PPC64