From 893752af3a86bcf1e184dea949ecd16810a858e0 Mon Sep 17 00:00:00 2001 From: Mark Heffernan Date: Fri, 18 Jul 2014 19:24:51 +0000 Subject: [PATCH] Add loop unrolling metadata descriptions to docs/LangRef.rst. llvm-svn: 213397 --- llvm/docs/LangRef.rst | 151 ++++++++++++++++++++++++++++++++------------------ 1 file changed, 97 insertions(+), 54 deletions(-) diff --git a/llvm/docs/LangRef.rst b/llvm/docs/LangRef.rst index 497f658..3f7845f 100644 --- a/llvm/docs/LangRef.rst +++ b/llvm/docs/LangRef.rst @@ -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 directly: !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 ===================== -- 2.7.4