diff options
| -rw-r--r-- | polly/docs/UsingPollyWithClang.rst | 74 |
1 files changed, 66 insertions, 8 deletions
diff --git a/polly/docs/UsingPollyWithClang.rst b/polly/docs/UsingPollyWithClang.rst index ade5b41c2e7..3198a417caa 100644 --- a/polly/docs/UsingPollyWithClang.rst +++ b/polly/docs/UsingPollyWithClang.rst @@ -47,18 +47,76 @@ Automatic vector code generation can be enabled by adding -mllvm clang -O3 -mllvm -polly -mllvm -polly-vectorizer=stripmine file.c -Extract a preoptimized LLVM-IR file -=================================== +Isolate the Polly passes +======================== -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'. +Polly's analysis and transformation passes are run with many other +passes of the pass manager's pipeline. Some of passes that run before +Polly are essential for its working, for instance the canonicalization +of loop. Therefore Polly is unable to optimize code straight out of +clang's -O0 output. + +To get the LLVM-IR that Polly sees in the optimization pipeline, use the +command: + +.. code-block:: console + + clang file.c -c -O3 -mllvm -polly -mllvm -polly-dump-before-file=before-polly.ll + +This writes a file 'before-polly.ll' containing the LLVM-IR as passed to +polly, after SSA transformation, loop canonicalization, inlining and +other passes. + +Thereafter, any Polly pass can be run over 'before-polly.ll' using the +'opt' tool. To found out which Polly passes are active in the standard +pipeline, see the output of + +.. code-block:: console + + clang file.c -c -O3 -mllvm -polly -mllvm -debug-pass=Arguments + +The Polly's passes are those between '-polly-detect' and +'-polly-codegen'. Analysis passes can be omitted. At the time of this +writing, the default Polly pass pipeline is: + +.. code-block:: console + + opt before-polly.ll -polly-simplify -polly-optree -polly-delicm -polly-simplify -polly-prune-unprofitable -polly-opt-isl -polly-codegen + +Note that this uses LLVM's old/legacy pass manager. + +For completeness, here are some other methods that generates IR +suitable for processing with Polly from C/C++/Objective C source code. +The previous method is the recommended one. + +The following generates unoptimized LLVM-IR ('-O0', which is the +default) and runs the canonicalizing passes on it +('-polly-canonicalize'). This does /not/ include all the passes that run +before Polly in the default pass pipeline. The '-disable-O0-optnone' +option is required because otherwise clang adds an 'optnone' attribute +to all functions such that it is skipped by most optimization passes. +This is meant to stop LTO builds to optimize these functions in the +linking phase anyway. + +.. code-block:: console + + clang file.c -c -O0 -Xclang -disable-O0-optnone -emit-llvm -S -o - | opt -polly-canonicalize -S + +The option '-disable-llvm-passes' disables all LLVM passes, even those +that run at -O0. Passing -O1 (or any optimization level other than -O0) +avoids that the 'optnone' attribute is added. + +.. code-block:: console + + clang file.c -c -O1 -Xclang -disable-llvm-passes -emit-llvm -S -o - | opt -polly-canonicalize -S + +As another alternative, Polly can be pushed in front of the pass +pipeline, and then its output dumped. This implicitly runs the +'-polly-canonicalize' passes. .. code-block:: console - clang -O0 -mllvm -polly -S -emit-llvm file.c + clang file.c -c -O3 -mllvm -polly -mllvm -polly-position=early -mllvm -polly-dump-before-file=before-polly.ll Further options =============== |
