X-Git-Url: http://plrg.eecs.uci.edu/git/?a=blobdiff_plain;f=docs%2FVectorizers.rst;h=2b702179bf283e497f6b0436af232d697d54e62d;hb=e2995ff88f922cd9004ef6cae7b444b615808c0e;hp=693a148fa547aaefedc28fe920dacfd216833155;hpb=fc175d97ffd4a8de2525173a653caca62321a0c4;p=oota-llvm.git diff --git a/docs/Vectorizers.rst b/docs/Vectorizers.rst index 693a148fa54..2b702179bf2 100644 --- a/docs/Vectorizers.rst +++ b/docs/Vectorizers.rst @@ -6,12 +6,14 @@ Auto-Vectorization in LLVM :local: LLVM has two vectorizers: The :ref:`Loop Vectorizer `, -which operates on Loops, and the :ref:`Basic Block Vectorizer -`, which optimizes straight-line code. These vectorizers +which operates on Loops, and the :ref:`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: @@ -21,8 +23,8 @@ The Loop Vectorizer Usage ----- -LLVM's Loop Vectorizer is now enabled by default for -O3. -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 @@ -49,6 +51,89 @@ Users can control the unroll factor using the command line flag "-force-vector-u $ clang -mllvm -force-vector-unroll=2 ... $ opt -loop-vectorize -force-vector-unroll=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 +`_ +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. + +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 +`_ +for details + Features -------- @@ -180,11 +265,14 @@ that scatter/gathers memory. .. 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 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -301,10 +389,9 @@ Details ------- 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 @@ -317,18 +404,19 @@ into vector operations. 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 + $ clang -fno-slp-vectorize file.c -LLVM has a second phase basic block vectorization phase +LLVM has a second 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: @@ -336,24 +424,3 @@ can be enabled through clang using the command line flag: $ 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% -======================= ============ -