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]

git-svn-id: https://llvm.org/svn/llvm-project/cfe/trunk@211286 91177308-0d34-0410-b5e6-96231b3b80d8

diff --git a/docs/LanguageExtensions.rst b/docs/LanguageExtensions.rst
index a9ba9079c0928a4f775cc37632695f3506981255..de9d513d5b6fb2ed82ed8ed254cf9938806ce89b 100644 (file)
--- a/docs/LanguageExtensions.rst
+++ b/docs/LanguageExtensions.rst
@@ -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 architectures supported by your application.
 
 .. 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 architectures supported by your application.
 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++

diff --git a/docs/ReleaseNotes.rst b/docs/ReleaseNotes.rst
index a7bbbb5fdb8387ec84368002065d11ba86efada0..c99262eb357d6cc8d2602ab896d91b44fac7a1ee 100644 (file)
--- a/docs/ReleaseNotes.rst
+++ b/docs/ReleaseNotes.rst
@@ -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
 ---------------------------

diff --git a/include/clang/Basic/AttrDocs.td b/include/clang/Basic/AttrDocs.td
index 6c8c9a37aeb8346fab5c4fb087bb21c7b3c4bc0d..5ba14462b215aea79769416dd148246cc7382985 100644 (file)
--- a/include/clang/Basic/AttrDocs.td
+++ b/include/clang/Basic/AttrDocs.td
@@ -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.
   }];