Update the docs about the new unroll features.

[oota-llvm.git] / docs / Vectorizers.rst

diff --git a/docs/Vectorizers.rst b/docs/Vectorizers.rst
index 0d5e349e60d1300748a78850008e2c95a2e4bfe0..bbf337cec9516bc8aa34a48b30ea8cda822e72ee 100644 (file)
--- a/docs/Vectorizers.rst
+++ b/docs/Vectorizers.rst
@@ -35,6 +35,27 @@ will only vectorize loops that do not require a major increase in code size.
 
 We plan to enable the Loop Vectorizer by default as part of the LLVM 3.3 release.
 
+Command line flags
+^^^^^^^^^^^^^^^^^^
+
+The loop vectorizer uses a cost model to decide on the optimal vectorization factor
+and unroll factor. However, users of the vectorizer can force the vectorizer to use
+specific values. Both 'clang' and 'opt' support the flags below.
+
+Users can control the vectorization SIMD width using the command line flag "-force-vector-width".
+
+.. code-block:: console
+
+  $ clang  -mllvm -force-vector-width=8 ...
+  $ opt -loop-vectorize -force-vector-width=8 ...
+
+Users can control the unroll factor using the command line flag "-force-vector-unroll"
+
+.. code-block:: console
+
+  $ clang  -mllvm -force-vector-unroll=2 ...
+  $ opt -loop-vectorize -force-vector-unroll=2 ...
+
 Features
 --------
 
@@ -159,8 +180,8 @@ The Loop Vectorizer can vectorize loops that count backwards.
 Scatter / Gather
 ^^^^^^^^^^^^^^^^
 
-The Loop Vectorizer can vectorize code that becomes scatter/gather
-memory accesses.
+The Loop Vectorizer can vectorize code that becomes a sequence of scalar instructions 
+that scatter/gathers memory.
 
 .. code-block:: c++
 
@@ -183,18 +204,6 @@ vectorization is profitable.
       A[i] += 4 * B[i];
   }
 
-
-Vectorization of Special Idioms
--------------------------------
-
-The Loop Vectorizer can detect and vectorize  
-
-.. code-block:: c++
-
-  for ( k=1 ; k<n ; k++ ) {
-    x[k] = x[k-1] + y[k];
-  }
-
 Vectorization of function calls
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -215,6 +224,32 @@ See the table below for a list of these functions.
 |     |     | fmuladd |
 +-----+-----+---------+
 
+
+Partial unrolling during vectorization
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Modern processors feature multiple execution units, and only programs that contain a
+high degree of parallelism can fully utilize the entire width of the machine. 
+The Loop Vectorizer increases the instruction level parallelism (ILP) by 
+performing partial-unrolling of loops.
+
+In the example below the entire array is accumulated into the variable 'sum'.
+This is inefficient because only a single execution port can be used by the processor.
+By unrolling the code the Loop Vectorizer allows two or more execution ports
+to be used simultaneously.
+
+.. code-block:: c++
+
+  int foo(int *A, int *B, int n) {
+    unsigned sum = 0;
+    for (int i = 0; i < n; ++i)
+        sum += A[i];
+    return sum;
+  }
+
+The Loop Vectorizer uses a cost model to decide when it is profitable to unroll loops.
+The decision to unroll the loop depends on the register pressure and the generated code size. 
+
 Performance
 -----------