Add loop unrolling metadata descriptions to LangRef.rst

[meheff]

Summary

This patch adds descriptions of the loop unrolling metadata optimization hints ("llvm.loop.unroll.*") to LangRefs.rst. The change also tweaks the language for the vectorization optimization hints to be consistent with the unrolling ones and the language in tools/clang/docs/LanguageExtension.rst.

[hfinkel]

Thanks for working on this!

docs/LangRef.rst

2913

You should add a note here that an IR-producer looking at affect this safety determination might find the llvm.mem.parallel_loop_access metadata useful.

2957

We should say something explaining how this is different from llvm.loop.vectorize.unroll (which actually does interleaving -- maybe we should rename it?). This is for concatenation unrolling (where the loop body is essentially replicated several times by the unroller, although other optimizations may intermix instructions from different unrolled iterations).

2965

I find this confusing. Specifically, to get partial unrolling, what needs to happen? If I want partial unrolling with a specific count, do I need both the 'count' and 'enable' metadata?

[meheff]

docs/LangRef.rst

2913

I'll add this.

2957

I think the fix here is to rename llvm.loop.vectorize.unroll to llvm.loop.vectorize.interleave. Then there is no chance of conflating the vectorize metadata with the unroll metadata. I'll work on a patch for this.

2965

I added a bit more explanation about that case.

I'd imagine an underlying cause of confusion is that `llvm.loop.unroll.enable 1` doesn't exactly mean enable. It means try to fully unroll the loop. So we want the following possible hints:

don't unroll
unroll fully
unroll by N

This doesn't exactly map nicely to the two metadata we have (one with boolean operand, one with i32). Maybe a cleaner way to have done this is with the following metadata:

llvm.loop.unroll.disable (no operand)
llvm.loop.unroll.fully_unroll (no operand)
llvm.loop.unroll.count i32

And only allow a single loop unroll metadata node per loop. Worth making this change?

[hfinkel]

• Original Message -----

From: "Mark Heffernan" <[e-mail]>
To: [e-mail], [e-mail]
Cc: [e-mail]
Sent: Friday, July 18, 2014 12:25:31 PM
Subject: Re: [PATCH] Add loop unrolling metadata descriptions to LangRef.rst

Comment at: docs/LangRef.rst:2913
@@ +2912,3 @@
+vectorizer will only vectorize loops if it believes it is valid to
do
+so.

+

[e-mail] wrote:

You should add a note here that an IR-producer looking at affect
this safety determination might find the
llvm.mem.parallel_loop_access metadata useful.

I'll add this.

Comment at: docs/LangRef.rst:2957
@@ +2956,3 @@
+optimizer believes it is valid to do so.
+

+'`llvm.loop.unroll.enable`' Metadata

[e-mail] wrote:

We should say something explaining how this is different from
llvm.loop.vectorize.unroll (which actually does interleaving --
maybe we should rename it?). This is for concatenation unrolling
(where the loop body is essentially replicated several times by
the unroller, although other optimizations may intermix
instructions from different unrolled iterations).

I think the fix here is to rename llvm.loop.vectorize.unroll to
llvm.loop.vectorize.interleave. Then there is no chance of
conflating the vectorize metadata with the unroll metadata. I'll
work on a patch for this.

Great, thanks!

Comment at: docs/LangRef.rst:2965
@@ +2964,3 @@
+bit operand value is 0 loop unrolling is disabled. A value of 1
+indicates that the loop should be fully unrolled. For example:

+

[e-mail] wrote:

I find this confusing. Specifically, to get partial unrolling, what
needs to happen? If I want partial unrolling with a specific
count, do I need both the 'count' and 'enable' metadata?

I added a bit more explanation about that case.

I'd imagine an underlying cause of confusion is that
`llvm.loop.unroll.enable 1` doesn't exactly mean enable. It means
try to fully unroll the loop. So we want the following possible
hints:

don't unroll
unroll fully
unroll by N

This doesn't exactly map nicely to the two metadata we have (one with
boolean operand, one with i32). Maybe a cleaner way to have done
this is with the following metadata:

llvm.loop.unroll.disable (no operand)
llvm.loop.unroll.fully_unroll (no operand)
llvm.loop.unroll.count i32

And only allow a single loop unroll metadata node per loop. Worth
making this change?

Yes, I think so. Maybe we can even do it before we branch for the release :-)

-Hal

http://reviews.llvm.org/D4576

[meheff]

docs/LangRef.rst

2965

I should add that this confusion is also baked into the pragma syntax. The following means unroll fully:

#pragma clang loop unroll(enable)

docs/LangRef.rst

 The following example contains loop identifier metadata for two separate loop
 constructs:
 
 .. code-block:: llvm
 
     !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 valid to do
+so.
+
+'``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 valid 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 }
 
 '``llvm.mem``'
 ^^^^^^^^^^^^^^^
 
 Metadata types used to annotate memory accesses with information helpful
 for optimizations are prefixed with ``llvm.mem``.
 
 '``llvm.mem.parallel_loop_access``' Metadata
inner.for.end:
      br i1 %exitcond, label %outer.for.end, label %outer.for.body, !llvm.loop !2
 
    outer.for.end:                                          ; preds = %for.body
    ...
    !0 = metadata !{ metadata !1, metadata !2 } ; a list of loop identifiers
    !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
 =====================
 
 Information about the module as a whole is difficult to convey to LLVM's
 subsystems. The LLVM IR isn't sufficient to transmit this information.
 The ``llvm.module.flags`` named metadata exists in order to facilitate
 this. These flags are in the form of key / value pairs --- much like a
 dictionary --- making it easy for any subsystem who cares about a flag to