[commit: ghc] master: Update documentation concerning prefetch ops (37ae422)

[git at git.haskell.org]

Repository : ssh://git@git.haskell.org/ghc

On branch  : master
Link       : http://ghc.haskell.org/trac/ghc/changeset/37ae422fc1131245705a686d1e3144b3f9e9aa81/ghc

>---------------------------------------------------------------

commit 37ae422fc1131245705a686d1e3144b3f9e9aa81
Author: Carter Tazio Schonwald <carter.schonwald at gmail.com>
Date:   Sat Nov 2 19:12:53 2013 -0400

    Update documentation concerning prefetch ops
    
    Also remove can_fail=True since it's likely unnecessary upon discussion
    (see #8256.)
    
    Signed-off-by: Austin Seipp <austin at well-typed.com>


>---------------------------------------------------------------

37ae422fc1131245705a686d1e3144b3f9e9aa81
 compiler/prelude/primops.txt.pp |   37 +++++++++++++++----------------------
 1 file changed, 15 insertions(+), 22 deletions(-)

diff --git a/compiler/prelude/primops.txt.pp b/compiler/prelude/primops.txt.pp
index 872a2bc..37591af 100644
--- a/compiler/prelude/primops.txt.pp
+++ b/compiler/prelude/primops.txt.pp
@@ -2608,13 +2608,6 @@ section "Prefetch"
   convention follows the naming convention of the prefetch intrinsic found
   in the GCC and Clang C compilers.
 
-  The prefetch primops are all marked with the can_fail=True attribute, but
-  they will never fail. The motivation for enabling the can_fail attribute is
-  so that prefetches are not hoisted/let floated out. This is because prefetch
-  is a tool for optimizing usage of system memory bandwidth, and preventing let
-  hoising makes *WHEN* the prefetch happens a bit more predictable.
-
-
   On the LLVM backend, prefetch*N# uses the LLVM prefetch intrinsic
   with locality level N. The code generated by LLVM is target architecture
   dependent, but should agree with the GHC NCG on x86 systems.
@@ -2636,13 +2629,25 @@ section "Prefetch"
 
   The "Intel 64 and IA-32 Architectures Optimization Reference Manual" is
   especially a helpful read, even if your software is meant for other CPU
-  architectures or vendor hardware.
+  architectures or vendor hardware. The manual can be found at
+  http://www.intel.com/content/www/us/en/architecture-and-technology/64-ia-32-architectures-optimization-manual.html .
 
-  http://www.intel.com/content/www/us/en/architecture-and-technology/64-ia-32-architectures-optimization-manual.html
+  The {\tt prefetchMutableByteArray} family of operations has the order of operations
+  determined by passing around the {\tt State#} token.
 
+  For the {\tt prefetchByteArray}
+  and {\tt prefetchAddr} families of operations, consider the following example:
+
+  {\tt let a1 = prefetchByteArray2# a n in ...a1... }
+
+  In the above fragement, {\tt a} is the input variable for the prefetch
+  and {\tt a1 == a} will be true. To ensure that the prefetch is not treated as deadcode,
+  the body of the let should only use {\tt a1} and NOT {\tt a}. The same principle
+  applies for uses of prefetch in a loop.
+
+  }
 
 
-   }
 ------------------------------------------------------------------------
 
 
@@ -2651,57 +2656,45 @@ section "Prefetch"
 ---
 primop PrefetchByteArrayOp3 "prefetchByteArray3#" GenPrimOp
    ByteArray# -> Int# -> ByteArray#
-   with can_fail = True
 
 primop PrefetchMutableByteArrayOp3 "prefetchMutableByteArray3#" GenPrimOp
    MutableByteArray# s -> Int# -> State# s -> State# s
-   with can_fail = True
 
 primop PrefetchAddrOp3 "prefetchAddr3#" GenPrimOp
     Addr# -> Int# -> Addr#
-    with can_fail = True
 
 ----
 
 primop PrefetchByteArrayOp2 "prefetchByteArray2#" GenPrimOp
    ByteArray# -> Int# -> ByteArray#
-   with can_fail = True
 
 primop PrefetchMutableByteArrayOp2 "prefetchMutableByteArray2#" GenPrimOp
    MutableByteArray# s -> Int# -> State# s -> State# s
-   with can_fail = True
 
 primop PrefetchAddrOp2 "prefetchAddr2#" GenPrimOp
    Addr# -> Int# -> Addr#
-   with can_fail = True
 
 ----
 
 primop PrefetchByteArrayOp1 "prefetchByteArray1#" GenPrimOp
    ByteArray# -> Int# -> ByteArray#
-   with can_fail = True
 
 primop PrefetchMutableByteArrayOp1 "prefetchMutableByteArray1#" GenPrimOp
    MutableByteArray# s -> Int# -> State# s -> State# s
-   with can_fail = True
 
 primop PrefetchAddrOp1 "prefetchAddr1#" GenPrimOp
    Addr# -> Int# -> Addr#
-   with can_fail = True
 
 ----
 
 primop PrefetchByteArrayOp0 "prefetchByteArray0#" GenPrimOp
    ByteArray# -> Int# -> ByteArray#
-   with can_fail = True
 
 primop PrefetchMutableByteArrayOp0 "prefetchMutableByteArray0#" GenPrimOp
    MutableByteArray# s -> Int# -> State# s -> State# s
-   with can_fail = True
 
 primop PrefetchAddrOp0 "prefetchAddr0#" GenPrimOp
    Addr# -> Int# -> Addr#
-   with can_fail = True