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

[Linas Vepstas]

Paul,
Please apply. This atch resulted from an email discussion
back in Sept.

--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-05 17:11:02.000000000 -0600
+++ linux-2.6.19-git7/include/asm-powerpc/io.h	2006-12-06 11:48:43.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
+ * 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