.. contents::
:local:
-LLVM has two kind vectorizers: The :ref:`Loop Vectorizer <loop-vectorizer>`,
+LLVM has two vectorizers: The :ref:`Loop Vectorizer <loop-vectorizer>`,
which operates on Loops, and the :ref:`SLP Vectorizer
-<slp-vectorizer>`, which optimizes straight-line code. These vectorizers
+<slp-vectorizer>`. These vectorizers
focus on different optimization opportunities and use different techniques.
-The BB vectorizer merges multiple scalars that are found in the code into
-vectors while the Loop Vectorizer widens instructions in the original loop
-to operate on multiple consecutive loop iterations.
+The SLP vectorizer merges multiple scalars that are found in the code into
+vectors while the Loop Vectorizer widens instructions in loops
+to operate on multiple consecutive iterations.
+
+Both the Loop Vectorizer and the SLP Vectorizer are enabled by default.
.. _loop-vectorizer:
Usage
-----
-LLVM's Loop Vectorizer is now enabled by default for -O3.
-We plan to enable parts of the Loop Vectorizer on -O2 and -Os in future releases.
-The vectorizer can be disabled using the command line:
+The Loop Vectorizer is enabled by default, but it can be disabled
+through clang using the command line flag:
.. code-block:: console
$ clang -mllvm -force-vector-width=8 ...
$ opt -loop-vectorize -force-vector-width=8 ...
-Users can control the unroll factor using the command line flag "-force-vector-unroll"
+Users can control the unroll factor using the command line flag "-force-vector-interleave"
.. code-block:: console
- $ clang -mllvm -force-vector-unroll=2 ...
- $ opt -loop-vectorize -force-vector-unroll=2 ...
+ $ clang -mllvm -force-vector-interleave=2 ...
+ $ opt -loop-vectorize -force-vector-interleave=2 ...
+
+Pragma loop hint directives
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The ``#pragma clang loop`` directive allows loop vectorization hints to be
+specified for the subsequent for, while, do-while, or c++11 range-based for
+loop. The directive allows vectorization and interleaving to be enabled or
+disabled. Vector width as well as interleave count can also be manually
+specified. The following example explicitly enables vectorization and
+interleaving:
+
+.. code-block:: c++
+
+ #pragma clang loop vectorize(enable) interleave(enable)
+ while(...) {
+ ...
+ }
+
+The following example implicitly enables vectorization and interleaving by
+specifying a vector width and interleaving count:
+
+.. code-block:: c++
+
+ #pragma clang loop vectorize_width(2) interleave_count(2)
+ for(...) {
+ ...
+ }
+
+See the Clang
+`language extensions
+<http://clang.llvm.org/docs/LanguageExtensions.html#extensions-for-loop-hint-optimizations>`_
+for details.
+
+Diagnostics
+-----------
+
+Many loops cannot be vectorized including loops with complicated control flow,
+unvectorizable types, and unvectorizable calls. The loop vectorizer generates
+optimization remarks which can be queried using command line options to identify
+and diagnose loops that are skipped by the loop-vectorizer.
+
+Optimization remarks are enabled using:
+
+``-Rpass=loop-vectorize`` identifies loops that were successfully vectorized.
+
+``-Rpass-missed=loop-vectorize`` identifies loops that failed vectorization and
+indicates if vectorization was specified.
+
+``-Rpass-analysis=loop-vectorize`` identifies the statements that caused
+vectorization to fail. If in addition ``-fsave-optimization-record`` is
+provided, multiple causes of vectorization failure may be listed (this behavior
+might change in the future).
+
+Consider the following loop:
+
+.. code-block:: c++
+
+ #pragma clang loop vectorize(enable)
+ for (int i = 0; i < Length; i++) {
+ switch(A[i]) {
+ case 0: A[i] = i*2; break;
+ case 1: A[i] = i; break;
+ default: A[i] = 0;
+ }
+ }
+
+The command line ``-Rpass-missed=loop-vectorized`` prints the remark:
+
+.. code-block:: console
+
+ no_switch.cpp:4:5: remark: loop not vectorized: vectorization is explicitly enabled [-Rpass-missed=loop-vectorize]
+
+And the command line ``-Rpass-analysis=loop-vectorize`` indicates that the
+switch statement cannot be vectorized.
+
+.. code-block:: console
+
+ no_switch.cpp:4:5: remark: loop not vectorized: loop contains a switch statement [-Rpass-analysis=loop-vectorize]
+ switch(A[i]) {
+ ^
+
+To ensure line and column numbers are produced include the command line options
+``-gline-tables-only`` and ``-gcolumn-info``. See the Clang `user manual
+<http://clang.llvm.org/docs/UsersManual.html#options-to-emit-optimization-reports>`_
+for details
Features
--------
.. code-block:: c++
- int foo(int *A, int *B, int n, int k) {
- for (int i = 0; i < n; ++i)
- A[i*7] += B[i*k];
+ int foo(int * A, int * B, int n) {
+ for (intptr_t i = 0; i < n; ++i)
+ A[i] += B[i * 4];
}
+In many situations the cost model will inform LLVM that this is not beneficial
+and LLVM will only vectorize such code if forced with "-mllvm -force-vector-width=#".
+
Vectorization of Mixed Types
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Performance
-----------
-This section shows the the execution time of Clang on a simple benchmark:
+This section shows the execution time of Clang on a simple benchmark:
`gcc-loops <http://llvm.org/viewvc/llvm-project/test-suite/trunk/SingleSource/UnitTests/Vectorizer/>`_.
This benchmarks is a collection of loops from the GCC autovectorization
`page <http://gcc.gnu.org/projects/tree-ssa/vectorization.html>`_ by Dorit Nuzman.
.. image:: linpack-pc.png
+Ongoing Development Directions
+------------------------------
+
+.. toctree::
+ :hidden:
+
+ Proposals/VectorizationPlan
+
+:doc:`Proposals/VectorizationPlan`
+ Modeling the process and upgrading the infrastructure of LLVM's Loop Vectorizer.
+
.. _slp-vectorizer:
The SLP Vectorizer
-------
The goal of SLP vectorization (a.k.a. superword-level parallelism) is
-to combine similar independent instructions within simple control-flow regions
-into vector instructions. Memory accesses, arithemetic operations, comparison
-operations and some math functions can all be vectorized using this technique
-(subject to the capabilities of the target architecture).
+to combine similar independent instructions
+into vector instructions. Memory accesses, arithmetic operations, comparison
+operations, PHI-nodes, can all be vectorized using this technique.
For example, the following function performs very similar operations on its
inputs (a1, b1) and (a2, b2). The basic-block vectorizer may combine these
A[1] = a2*(a2 + b2)/b2 + 50*b2/a2;
}
+The SLP-vectorizer processes the code bottom-up, across basic blocks, in search of scalars to combine.
Usage
------
-The SLP Vectorizer is not enabled by default, but it can be enabled
+The SLP Vectorizer is enabled by default, but it can be disabled
through clang using the command line flag:
.. code-block:: console
- $ clang -fslp-vectorize file.c
-
-LLVM has a second phase basic block vectorization phase
-which is more compile-time intensive (The BB vectorizer). This optimization
-can be enabled through clang using the command line flag:
-
-.. code-block:: console
-
- $ clang -fslp-vectorize-aggressive file.c
-
-
-The SLP vectorizer is in early development stages but can already vectorize
-and accelerate many programs in the LLVM test suite.
-
-======================= ============
-Benchmark Name Gain
-======================= ============
-Misc/flops-7 -32.70%
-Misc/matmul_f64_4x4 -23.23%
-Olden/power -21.45%
-Misc/flops-4 -14.90%
-ASC_Sequoia/AMGmk -13.85%
-TSVC/LoopRerolling-flt -11.76%
-Misc/flops-6 -9.70%
-Misc/flops-5 -8.54%
-Misc/flops -8.12%
-TSVC/NodeSplitting-dbl -6.96%
-Misc-C++/sphereflake -6.74%
-Ptrdist/yacr2 -6.31%
-======================= ============
-
+ $ clang -fno-slp-vectorize file.c