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

From: [email-masked] (Linas Vepstas)
Date: Wed, 6 Dec 2006 16:22:47 -0600

Paul,

Please apply.

On Wed, Dec 06, 2006 at 11:24:32PM +0300, Sergei Shtylyov wrote:
> >>  A minor type here -- double "the".
>    And here as well. :-)

I forgot to say "quilt refresh" !? My quality control mechanism
broke.

So again ... 

--linas

Clarify why twi appears in the i/o macros. Shorten some over-length
lines, while we're at it.

Signed-off-by: Linas Vepstas <[email-masked]>
Signed-off-by: Segher Boessenkool <[email-masked]>

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

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 16:11:31.000000000 -0600
+++ linux-2.6.19-git7/include/asm-powerpc/io.h	2006-12-06 16:19:40.000000000 -0600
@@ -62,22 +62,33 @@ extern unsigned long pci_dram_offset;
  *
  * Low level MMIO accessors
  *
- * This provides the non-bus specific accessors to MMIO. Those are PowerPC
- * specific and thus shouldn't be used in generic code. The accessors
- * provided here are:
+ * This provides the non-bus specific accessors to MMIO. Those are 
+ * PowerPC specific and thus shouldn't be used in generic code. The 
+ * accessors provided here are:
  *
  *	in_8, in_le16, in_be16, in_le32, in_be32, in_le64, in_be64
  *	out_8, out_le16, out_be16, out_le32, out_be32, out_le64, out_be64
  *	_insb, _insw_ns, _insl_ns, _outsb, _outsw_ns, _outsl_ns
  *
- * Those operate directly on a kernel virtual address. Note that the prototype
- * for the out_* accessors has the arguments in opposite order from the usual
- * linux PCI accessors. Unlike those, they take the address first and the value
- * next.
- *
- * 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.
- *
+ * Those operate directly on a kernel virtual address. Note that the 
+ * prototype for the out_* accessors has the arguments in opposite 
+ * order from the usual linux PCI accessors. Unlike those, they take 
+ * the address first and the value next.
+ *
+ * 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