#pragma clang loop - documentation

[Aaron Ballman]

Mostly LGTM (just a single nit below).

> Index: docs/LanguageExtensions.rst
> ===================================================================
> --- docs/LanguageExtensions.rst (revision 210604)
> +++ docs/LanguageExtensions.rst (working copy)
> @@ -1764,3 +1764,61 @@
>  it causes the instantiation of ``twice`` and ``thrice`` with an ``int`` type; of
>  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 controlling vectorization, interleaving, and unrolling.
> +
> +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(...) {
> +    ...
> +  }
> +
> +A vectorized loop performs multiple iterations of the original loop
> +simultaneously using vector instructions. The vector width is determined
> +automatically when vectorization is enabled. It can also be specified by
> +``vectorize_width(_value_)``, a width of 1 implies no vectorization.

It's not entirely clear of what the value actually means.

> +
> +.. code-block:: c++
> +
> +
> +  #pragma clang loop vectorize_width(2)
> +  for(...) {
> +    ...
> +  }
> +
> +An interleaved loop performs multiple iterations of the original loop by
> +interleaving their instructions. The interleave count is the number of
> +iterations of the original loop that are performed within a single iteration of
> +the interleaved loop. The interleave count is determined automatically when
> +interleaving is enabled. It can also be specified by
> +``interleave_count(_value_)``, an interleave count of 1 implies no interleaving.
> +
> +.. code-block:: c++
> +
> +  #pragma clang loop interleave_count(2)
> +  for(...) {
> +    ...
> +  }
> +
> +Prevent a loop from being vectorized with ``vectorize(disable)`` and interleaved
> +with ``interleave(disable)``.
> +
> +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(...) {
> +    ...
> +  }
> Index: docs/ReleaseNotes.rst
> ===================================================================
> --- docs/ReleaseNotes.rst (revision 210604)
> +++ docs/ReleaseNotes.rst (working copy)
> @@ -97,6 +97,14 @@
>  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.
> +
>  C Language Changes in Clang
>  ---------------------------
>
> Index: include/clang/Basic/Attr.td
> ===================================================================
> --- include/clang/Basic/Attr.td (revision 210604)
> +++ include/clang/Basic/Attr.td (working copy)
> @@ -1805,5 +1805,5 @@
>    }
>    }];
>
> -  let Documentation = [Undocumented];
> +  let Documentation = [LoopHintDocs];
>  }
> Index: include/clang/Basic/AttrDocs.td
> ===================================================================
> --- include/clang/Basic/AttrDocs.td (revision 210604)
> +++ include/clang/Basic/AttrDocs.td (working copy)
> @@ -1012,3 +1012,14 @@
>    }];
>  }
>
> +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
> +<http://clang.llvm.org/docs/LanguageExtensions.html##extensions-for-loop-hint-optimizations>'_
> +for details.
> +  }];
> +}
>

~Aaron

On Tue, Jun 10, 2014 at 9:20 PM, Tyler Nowicki <tnowicki at apple.com> wrote:
> Hi,
>
> Here is a patch for the loop hints documentation. I’m not exactly sure if I wrote the attribute documentation correctly. If I missed something please let me know.
>
> Tyler
>