[llvm] r213397 - Add loop unrolling metadata descriptions to docs/LangRef.rst.

[Mark Heffernan]

Author: meheff
Date: Fri Jul 18 14:24:51 2014
New Revision: 213397

URL: http://llvm.org/viewvc/llvm-project?rev=213397&view=rev
Log:
Add loop unrolling metadata descriptions to docs/LangRef.rst.

Modified:
    llvm/trunk/docs/LangRef.rst

Modified: llvm/trunk/docs/LangRef.rst
URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/LangRef.rst?rev=213397&r1=213396&r2=213397&view=diff
==============================================================================
--- llvm/trunk/docs/LangRef.rst (original)
+++ llvm/trunk/docs/LangRef.rst Fri Jul 18 14:24:51 2014
@@ -2900,17 +2900,109 @@ constructs:
     !0 = metadata !{ metadata !0 }
     !1 = metadata !{ metadata !1 }
 
-The loop identifier metadata can be used to specify additional per-loop
-metadata. Any operands after the first operand can be treated as user-defined
-metadata. For example the ``llvm.loop.vectorize.unroll`` metadata is understood
-by the loop vectorizer to indicate how many times to unroll the loop:
+The loop identifier metadata can be used to specify additional
+per-loop metadata. Any operands after the first operand can be treated
+as user-defined metadata. For example the ``llvm.loop.unroll.count``
+suggests an unroll factor to the loop unroller:
 
 .. code-block:: llvm
 
       br i1 %exitcond, label %._crit_edge, label %.lr.ph, !llvm.loop !0
     ...
     !0 = metadata !{ metadata !0, metadata !1 }
-    !1 = metadata !{ metadata !"llvm.loop.vectorize.unroll", i32 2 }
+    !1 = metadata !{ metadata !"llvm.loop.vectorize.width", i32 4 }
+
+'``llvm.loop.vectorize``'
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Metadata prefixed with ``llvm.loop.vectorize`` is used to control
+per-loop vectorization parameters such as vectorization width and
+interleave count.  ``llvm.loop.vectorize`` metadata should be used in
+conjunction with ``llvm.loop`` loop identification metadata.  The
+``llvm.loop.vectorize`` metadata are only optimization hints and the
+vectorizer will only vectorize loops if it believes it is safe to do
+so.  The ``llvm.mem.parallel_loop_access`` metadata which contains
+information about loop-carried memory dependencies can be helpful in
+determining the safety of loop vectorization.
+
+'``llvm.loop.vectorize.unroll``' Metadata
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This metadata suggests an interleave count to the loop vectorizer.
+The first operand is the string ``llvm.loop.vectorize.unroll`` and the
+second operand is an integer specifying the interleave count. For
+example:
+
+.. code-block:: llvm
+
+   !0 = metadata !{ metadata !"llvm.loop.vectorize.unroll", i32 4 }
+
+Note that setting ``llvm.loop.vectorize.unroll`` to 1 disables
+interleaving multiple iterations of the loop.  If
+``llvm.loop.vectorize.unroll`` is set to 0 then the interleave count
+will be determined automatically.
+
+'``llvm.loop.vectorize.width``' Metadata
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This metadata sets the target width of the vectorizer. The first
+operand is the string ``llvm.loop.vectorize.width`` and the second
+operand is an integer specifying the width. For example:
+
+.. code-block:: llvm
+
+   !0 = metadata !{ metadata !"llvm.loop.vectorize.width", i32 4 }
+
+Note that setting ``llvm.loop.vectorize.width`` to 1 disables
+vectorization of the loop.  If ``llvm.loop.vectorize.width`` is set to
+0 or if the loop does not have this metadata the width will be
+determined automatically.
+
+'``llvm.loop.unroll``'
+^^^^^^^^^^^^^^^^^^^^^^
+
+Metadata prefixed with ``llvm.loop.unroll`` are loop unrolling
+optimization hints such as the unroll factor. ``llvm.loop.unroll``
+metadata should be used in conjunction with ``llvm.loop`` loop
+identification metadata. The ``llvm.loop.unroll`` metadata are only
+optimization hints and the unrolling will only be performed if the
+optimizer believes it is safe to do so.
+
+'``llvm.loop.unroll.enable``' Metadata
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This metadata either disables loop unrolling or suggests that the loop
+be unrolled fully. The first operand is the string
+``llvm.loop.unroll.enable`` and the second operand is a bit.  If the
+bit operand value is 0 loop unrolling is disabled. A value of 1
+indicates that the loop should be fully unrolled. For example:
+
+.. code-block:: llvm
+
+   !0 = metadata !{ metadata !"llvm.loop.unroll.enable", i1 0 }
+   !1 = metadata !{ metadata !"llvm.loop.unroll.enable", i1 1 }
+
+'``llvm.loop.unroll.count``' Metadata
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This metadata suggests an unroll factor to the loop unroller. The
+first operand is the string ``llvm.loop.unroll.count`` and the second
+operand is a positive integer specifying the unroll factor. For
+example:
+
+.. code-block:: llvm
+
+   !0 = metadata !{ metadata !"llvm.loop.unroll.count", i32 4 }
+
+If the trip count of the loop is less than the unroll count the loop
+will be partially unrolled.
+
+If a loop has both a ``llvm.loop.unroll.enable`` metadata and
+``llvm.loop.unroll.count`` metadata the behavior depends upon the
+value of the ``llvm.loop.unroll.enable`` operand.  If the value is 0,
+the loop will not be unrolled.  If the value is 1, the loop will be
+unrolled with a factor determined by the ``llvm.loop.unroll.count``
+operand effectively ignoring the ``llvm.loop.unroll.enable`` metadata.
 
 '``llvm.mem``'
 ^^^^^^^^^^^^^^^
@@ -2995,55 +3087,6 @@ the loop identifier metadata node direct
    !1 = metadata !{ metadata !1 } ; an identifier for the inner loop
    !2 = metadata !{ metadata !2 } ; an identifier for the outer loop
 
-'``llvm.loop.vectorize``'
-^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Metadata prefixed with ``llvm.loop.vectorize`` is used to control per-loop
-vectorization parameters such as vectorization factor and unroll factor.
-
-``llvm.loop.vectorize`` metadata should be used in conjunction with
-``llvm.loop`` loop identification metadata.
-
-'``llvm.loop.vectorize.unroll``' Metadata
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-This metadata instructs the loop vectorizer to unroll the specified
-loop exactly ``N`` times.
-
-The first operand is the string ``llvm.loop.vectorize.unroll`` and the second
-operand is an integer specifying the unroll factor. For example:
-
-.. code-block:: llvm
-
-   !0 = metadata !{ metadata !"llvm.loop.vectorize.unroll", i32 4 }
-
-Note that setting ``llvm.loop.vectorize.unroll`` to 1 disables
-unrolling of the loop.
-
-If ``llvm.loop.vectorize.unroll`` is set to 0 then the amount of
-unrolling will be determined automatically.
-
-'``llvm.loop.vectorize.width``' Metadata
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-This metadata sets the target width of the vectorizer to ``N``. Without
-this metadata, the vectorizer will choose a width automatically.
-Regardless of this metadata, the vectorizer will only vectorize loops if
-it believes it is valid to do so.
-
-The first operand is the string ``llvm.loop.vectorize.width`` and the
-second operand is an integer specifying the width. For example:
-
-.. code-block:: llvm
-
-   !0 = metadata !{ metadata !"llvm.loop.vectorize.width", i32 4 }
-
-Note that setting ``llvm.loop.vectorize.width`` to 1 disables
-vectorization of the loop.
-
-If ``llvm.loop.vectorize.width`` is set to 0 then the width will be
-determined automatically.
-
 Module Flags Metadata
 =====================