diff options
| -rw-r--r-- | polly/docs/UsingPollyWithClang.rst | 146 | ||||
| -rw-r--r-- | polly/docs/index.rst | 8 |
2 files changed, 154 insertions, 0 deletions
diff --git a/polly/docs/UsingPollyWithClang.rst b/polly/docs/UsingPollyWithClang.rst new file mode 100644 index 00000000000..fd21cdf6675 --- /dev/null +++ b/polly/docs/UsingPollyWithClang.rst @@ -0,0 +1,146 @@ +====================== +Using Polly with Clang +====================== + +This documentation discusses how Polly can be used in Clang to automatically +optimize C/C++ code during compilation. + + +.. warning:: + + Warning: clang/LLVM/Polly need to be in sync (compiled from the same SVN + revision). + +Make Polly available from Clang +=============================== + +By default Polly is configured as a shared library plugin that is loaded in +tools like clang, opt, and bugpoint when they start their execution. By loading +Polly into clang (or opt) the Polly options become automatically available. You +can load Polly either by adding the relevant commands to the CPPFLAGS or by +creating an alias. + +.. code-block:: console + + $ export CPPFLAGS="-Xclang -load -Xclang ${POLLY_BUILD_DIR}/lib/LLVMPolly.so" + +or + +.. code-block:: console + + $ alias pollycc clang -Xclang -load -Xclang ${POLLY_BUILD_DIR}/lib/LLVMPolly.so + +To avoid having to load Polly in the tools, Polly can optionally be configured +with cmake to be statically linked in the tools: + +.. code-block:: console + + $ cmake -D LINK_POLLY_INTO_TOOLS:Bool=ON + +Optimizing with Polly +===================== + +Optimizing with Polly is as easy as adding -O3 -mllvm -polly to your compiler +flags (Polly is only available at -O3). + +.. code-block:: console + + pollycc -O3 -mllvm -polly file.c + +Automatic OpenMP code generation +================================ + +To automatically detect parallel loops and generate OpenMP code for them you +also need to add -mllvm -polly-parallel -lgomp to your CFLAGS. + +.. code-block:: console + + pollycc -O3 -mllvm -polly -mllvm -polly-parallel -lgomp file.c + +Automatic Vector code generation +================================ + +Automatic vector code generation can be enabled by adding -mllvm +-polly-vectorizer=stripmine to your CFLAGS. + +.. code-block:: console + + pollycc -O3 -mllvm -polly -mllvm -polly-vectorizer=stripmine file.c + +Extract a preoptimized LLVM-IR file +=================================== + +Often it is useful to derive from a C-file the LLVM-IR code that is actually +optimized by Polly. Normally the LLVM-IR is automatically generated from the C +code by first lowering C to LLVM-IR (clang) and by subsequently applying a set +of preparing transformations on the LLVM-IR. To get the LLVM-IR after the +preparing transformations have been applied run Polly with '-O0'. + +.. code-block:: console + + pollycc -O0 -mllvm -polly -S -emit-llvm file.c + +Further options +=============== +Polly supports further options that are mainly useful for the development or the +analysis of Polly. The relevant options can be added to clang by appending +-mllvm -option-name to the CFLAGS or the clang command line. + +Limit Polly to a single function +-------------------------------- + +To limit the execution of Polly to a single function, use the option +-polly-only-func=functionname. + +Disable LLVM-IR generation +-------------------------- + +Polly normally regenerates LLVM-IR from the Polyhedral representation. To only +see the effects of the preparing transformation, but to disable Polly code +generation add the option polly-no-codegen. + +Graphical view of the SCoPs +--------------------------- +Polly can use graphviz to show the SCoPs it detects in a program. The relevant +options are -polly-show, -polly-show-only, -polly-dot and -polly-dot-only. The +'show' options automatically run dotty or another graphviz viewer to show the +scops graphically. The 'dot' options store for each function a dot file that +highlights the detected SCoPs. If 'only' is appended at the end of the option, +the basic blocks are shown without the statements the contain. + +Change/Disable the Optimizer +---------------------------- + +Polly uses by default the isl scheduling optimizer. The isl optimizer optimizes +for data-locality and parallelism using the Pluto algorithm. For research it is +also possible to run PoCC as external optimizer. PoCC provides access to the +original Pluto implementation. To use PoCC add -polly-optimizer=pocc to the +command line (only available if Polly was compiled with scoplib support) +[removed after LLVM 3.4.2]. To disable the optimizer entirely use the option +-polly-optimizer=none. + +Disable tiling in the optimizer +------------------------------- + +By default both optimizers perform tiling, if possible. In case this is not +wanted the option -polly-tiling=false can be used to disable it. (This option +disables tiling for both optimizers). + +Ignore possible aliasing +------------------------ + +By default we only detect scops, if we can prove that the different array +bases can not alias. This is correct do if we optimize automatically. However, +without special user annotations like 'restrict' we can often not prove that +no aliasing is possible. In case the user knows no aliasing can happen in the +code the -polly-ignore-aliasing can be used to disable the check for possible +aliasing. + +Import / Export +--------------- + +The flags -polly-import and -polly-export allow the export and reimport of the +polyhedral representation. By exporting, modifying and reimporting the +polyhedral representation externally calculated transformations can be +applied. This enables external optimizers or the manual optimization of +specific SCoPs. diff --git a/polly/docs/index.rst b/polly/docs/index.rst index b5f456121b5..e5001f8228a 100644 --- a/polly/docs/index.rst +++ b/polly/docs/index.rst @@ -7,6 +7,14 @@ .. toctree:: :maxdepth: 1 +Using Polly +=========== + +.. toctree:: + :maxdepth: 1 + + UsingPollyWithClang + Indices and tables ================== |
