Documentation for loop unrolling pragmas.

[meheff]

Summary

This patch extends the documentation for "#pragma clang loop" hints to include the unroll and unroll_count directives.

[eliben]

docs/LanguageExtensions.rst

1796

Maybe s/loop count/loop trip count/ for clarify? There's another instance later on

1798

I find this sentence a bit confusing in the context of unroll pragmas which tell the unroller exactly how much we want to unroll. OTOH this sentence seems to be describing the unrolling heuristic?

[meheff]

Thanks for the comments. Tyler, I incorporated your suggested rewrite of the unrolling paragraph. Hopefully it is clearer now.

I also split the vectorization/interleaving pragmas and the unrolling pragmas into separate sections.

Please take another look.

docs/LanguageExtensions.rst

1796

Rewrote this bit.

1798

Rewrote this bit.

[eliben]

LGTM with a micro-nit: be consistent about one or two spaces after '.' -- I think one is fine and more globally consistent

[TylerNowicki]

LGTM!

[meheff]

In D4198#7, @eliben wrote:

LGTM with a micro-nit: be consistent about one or two spaces after '.' -- I think one is fine and more globally consistent

Done.

docs/LanguageExtensions.rst

 these two instantiations, ``twice`` will be optimized (because its definition
 was outside the region) and ``thrice`` will not be optimized.
 
 Extensions for loop hint optimizations
 ======================================
 
 The ``#pragma clang loop`` directive is used to specify hints for optimizing the
 subsequent for, while, do-while, or c++11 range-based for loop. The directive
-provides options for vectorization and interleaving. Loop hints can be specified
-before any loop and will be ignored if the optimization is not safe to apply.
+provides options for vectorization, interleaving, and unrolling. Loop hints can
+be specified before any loop and will be ignored if the optimization is not safe
+to apply.
+
+Vectorization and Interleaving
+------------------------------
 
 A vectorized loop performs multiple iterations of the original loop
 in parallel using vector instructions. The instruction set of the target
 processor determines which vector instructions are available and their vector
 widths. This restricts the types of loops that can be vectorized. The vectorizer
 automatically determines if the loop is safe and profitable to vectorize. A
 vector instruction cost model is used to select the vector width.
 
 Interleaving multiple loop iterations allows modern processors to further
 improve instruction-level parallelism (ILP) using advanced hardware features,
 such as multiple execution units and out-of-order execution. The vectorizer uses
 a cost model that depends on the register pressure and generated code size to
 select the interleaving count.
 
 Vectorization is enabled by ``vectorize(enable)`` and interleaving is enabled
 by ``interleave(enable)``. This is useful when compiling with ``-Os`` to
 manually enable vectorization or interleaving.
 
 .. code-block:: c++
 
   #pragma clang loop vectorize(enable)
   #pragma clang loop interleave(enable)
   for(...) {
     ...
   }
 
 The vector width is specified by ``vectorize_width(_value_)`` and the interleave
 count is specified by ``interleave_count(_value_)``, where
 _value_ is a positive integer. This is useful for specifying the optimal
 width/count of the set of target architectures supported by your application.
 
 .. code-block:: c++
 
-
   #pragma clang loop vectorize_width(2)
   #pragma clang loop interleave_count(2)
   for(...) {
     ...
   }
 
 Specifying a width/count of 1 disables the optimization, and is equivalent to
 ``vectorize(disable)`` or ``interleave(disable)``.
 
+Loop Unrolling
+--------------
+
+Unrolling a loop reduces the loop control overhead and exposes more
+opportunities for ILP. Loops can be fully or partially unrolled. Full unrolling
+eliminates the loop and replaces it with an enumerated sequence of loop
+iterations. Full unrolling is only possible if the loop trip count is known at
+compile time. Partial unrolling replicates the loop body within the loop and
+reduces the trip count.
+
+If ``unroll(enable)`` is specified the unroller will attempt to fully unroll the
+loop if the trip count is known at compile time.  If the loop count is not known
+or the fully unrolled code size is greater than the limit specified by the
+`-pragma-unroll-threshold` command line option the loop will be partially
+unrolled subject to the same limit.
+
+.. code-block:: c++
+
+  #pragma clang loop unroll(enable)
+  for(...) {
+    ...
+  }
+
+The unroll count can be specified explicitly with ``unroll_count(_value_)`` where
+_value_ is a positive integer.  If this value is greater than the trip count the
+loop will be fully unrolled.  Otherwise the loop is partially unrolled subject
+to the `-pragma-unroll-threshold` limit.
+
+.. code-block:: c++
+
+  #pragma clang loop unroll_count(8)
+  for(...) {
+    ...
+  }
+
+Unrolling of a loop can be prevented by specifying ``unroll(disable)``.
+
+Additional Information
+----------------------
+
 For convenience multiple loop hints can be specified on a single line.
 
 .. code-block:: c++
 
   #pragma clang loop vectorize_width(4) interleave_count(8)
   for(...) {
     ...
   }
 
 If an optimization cannot be applied any hints that apply to it will be ignored.
 For example, the hint ``vectorize_width(4)`` is ignored if the loop is not
 proven safe to vectorize. To identify and diagnose optimization issues use
 `-Rpass`, `-Rpass-missed`, and `-Rpass-analysis` command line options. See the
 user guide for details.

docs/ReleaseNotes.rst

 passes via three new flags: `-Rpass`, `-Rpass-missed` and `-Rpass-analysis`.
 These flags take a POSIX regular expression which indicates the name
 of the pass (or passes) that should emit optimization remarks.
 
 New Pragmas in Clang
 -----------------------
 
 Loop optimization hints can be specified using the new `#pragma clang loop`
-directive just prior to the desired loop. The directive allows vectorization
-and interleaving to be enabled or disabled, and the vector width and interleave
-count to be manually specified. See language extensions for details.
+directive just prior to the desired loop. The directive allows vectorization,
+interleaving, and unrolling to be enabled or disabled. Vector width as well
+as interleave and unrolling count can be manually specified.  See language
+extensions for details.
 
 C Language Changes in Clang
 ---------------------------
 
 ...
 
 C11 Feature Support
 ^^^^^^^^^^^^^^^^^^^

include/clang/Basic/AttrDocs.td

 This attribute is incompatible with the ``always_inline`` attribute.
   }];
 }
 
 def LoopHintDocs : Documentation {
   let Category = DocCatStmt;
   let Content = [{
 The ``#pragma clang loop'' directive allows loop optimization hints to be
-specified for the subsequent loop. The directive allows vectorization
-and interleaving to be enabled or disabled, and the vector width and interleave
-count to be manually specified. See `language extensions
+specified for the subsequent loop. The directive allows vectorization,
+interleaving, and unrolling to be enabled or disabled. Vector width as well
+as interleave and unrolling count can be manually specified. See
+`language extensions
 <http://clang.llvm.org/docs/LanguageExtensions.html#extensions-for-loop-hint-optimizations>'_
 for details.
   }];
 }