r211286 - Document unroll and unroll_count directives.

[Eli Bendersky]

Author: eliben
Date: Thu Jun 19 13:12:44 2014
New Revision: 211286

URL: http://llvm.org/viewvc/llvm-project?rev=211286&view=rev
Log:
Document unroll and unroll_count directives.

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

Patch by Mark Heffernan [http://reviews.llvm.org/D4198]


Modified:
    cfe/trunk/docs/LanguageExtensions.rst
    cfe/trunk/docs/ReleaseNotes.rst
    cfe/trunk/include/clang/Basic/AttrDocs.td

Modified: cfe/trunk/docs/LanguageExtensions.rst
URL: http://llvm.org/viewvc/llvm-project/cfe/trunk/docs/LanguageExtensions.rst?rev=211286&r1=211285&r2=211286&view=diff
==============================================================================
--- cfe/trunk/docs/LanguageExtensions.rst (original)
+++ cfe/trunk/docs/LanguageExtensions.rst Thu Jun 19 13:12:44 2014
@@ -1770,8 +1770,12 @@ 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
@@ -1805,7 +1809,6 @@ width/count of the set of target archite
 
 .. code-block:: c++
 
-
   #pragma clang loop vectorize_width(2)
   #pragma clang loop interleave_count(2)
   for(...) {
@@ -1815,6 +1818,46 @@ width/count of the set of target archite
 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++

Modified: cfe/trunk/docs/ReleaseNotes.rst
URL: http://llvm.org/viewvc/llvm-project/cfe/trunk/docs/ReleaseNotes.rst?rev=211286&r1=211285&r2=211286&view=diff
==============================================================================
--- cfe/trunk/docs/ReleaseNotes.rst (original)
+++ cfe/trunk/docs/ReleaseNotes.rst Thu Jun 19 13:12:44 2014
@@ -101,9 +101,10 @@ 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
 ---------------------------

Modified: cfe/trunk/include/clang/Basic/AttrDocs.td
URL: http://llvm.org/viewvc/llvm-project/cfe/trunk/include/clang/Basic/AttrDocs.td?rev=211286&r1=211285&r2=211286&view=diff
==============================================================================
--- cfe/trunk/include/clang/Basic/AttrDocs.td (original)
+++ cfe/trunk/include/clang/Basic/AttrDocs.td Thu Jun 19 13:12:44 2014
@@ -1016,9 +1016,10 @@ 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.
   }];