[commit: ghc] master: Document -fvectorise and -favoid-vect. (#5801) (c0f96bd)

[David Terei]

Repository : ssh://darcs.haskell.org//srv/darcs/ghc

On branch  : master

http://hackage.haskell.org/trac/ghc/changeset/c0f96bdcf16866d91941802649d470176dcf9e7a

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

commit c0f96bdcf16866d91941802649d470176dcf9e7a
Author: David Terei <davidterei at gmail.com>
Date:   Thu Jan 31 17:48:37 2013 -0800

    Document -fvectorise and -favoid-vect. (#5801)

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

 docs/users_guide/parallel.xml |    2 +-
 docs/users_guide/using.xml    |   28 ++++++++++++++++++++++------
 2 files changed, 23 insertions(+), 7 deletions(-)

diff --git a/docs/users_guide/parallel.xml b/docs/users_guide/parallel.xml
index b8e7316..05092bc 100644
--- a/docs/users_guide/parallel.xml
+++ b/docs/users_guide/parallel.xml
@@ -185,7 +185,7 @@ nfib n | n &#60;= 1 = 1
       parallel <literal>map</literal>.</para>
   </sect2>
 
-<sect2><title>Data Parallel Haskell</title>
+<sect2 id="dph"><title>Data Parallel Haskell</title>
   <para>GHC includes experimental support for Data Parallel Haskell (DPH). This code
         is highly unstable and is only provided as a technology preview. More
         information can be found on the corresponding <ulink
diff --git a/docs/users_guide/using.xml b/docs/users_guide/using.xml
index adc3694..6574e9e 100644
--- a/docs/users_guide/using.xml
+++ b/docs/users_guide/using.xml
@@ -2278,9 +2278,15 @@ last (x : xs) = last' x xs
             <indexterm><primary><option></option></primary></indexterm>
           </term>
           <listitem>
-            <para>Data Parallel Haskell.
-            </para>
-            TODO: Document optimisation
+            <para>Part of <link linkend="dph">Data Parallel Haskell
+            (DPH)</link>.</para>
+
+            <para><emphasis>Off by default.</emphasis> Enable the
+            <emphasis>vectorisation</emphasis> optimisation transformation. This
+            optimisation transforms the nested data parallelism code of programs
+            using DPH into flat data parallelism. Flat data parallel programs
+            should have better load balancing, enable SIMD parallelism and
+            friendlier cache behaviour.</para>
           </listitem>
         </varlistentry>
 
@@ -2290,9 +2296,19 @@ last (x : xs) = last' x xs
             <indexterm><primary><option></option></primary></indexterm>
           </term>
           <listitem>
-            <para>Data Parallel Haskell.
-            </para>
-            TODO: Document optimisation
+            <para>Part of <link linkend="dph">Data Parallel Haskell
+            (DPH)</link>.</para>
+
+            <para><emphasis>Off by default.</emphasis> Enable the
+            <emphasis>vectorisation</emphasis> avoidance optimisation. This
+            optimisation only works when used in combination with the
+            <option>-fvectorise</option> transformation.</para>
+
+            <para>While vectorisation of code using DPH is often a big win, it
+            can also produce worse results for some kinds of code. This
+            optimisation modifies the vectorisation transformation to try to
+            determine if a function would be better of unvectorised and if
+            so, do just that.</para>
           </listitem>
         </varlistentry>