docs/UsingPollyWithClang.rst

   1 ======================
   2 Using Polly with Clang
   3 ======================
   4
   5 This documentation discusses how Polly can be used in Clang to automatically
   6 optimize C/C++ code during compilation.
   7
   8
   9 .. warning::
  10
  11   Warning: clang/LLVM/Polly need to be in sync (compiled from the same SVN
  12   revision).
  13
  14 Make Polly available from Clang
  15 ===============================
  16
  17 Polly is available through clang, opt, and bugpoint, if Polly was checked out
  18 into tools/polly before compilation. No further configuration is needed.
  19
  20 Optimizing with Polly
  21 =====================
  22
  23 Optimizing with Polly is as easy as adding -O3 -mllvm -polly to your compiler
  24 flags (Polly is only available at -O3).
  25
  26 .. code-block:: console
  27
  28   clang -O3 -mllvm -polly file.c
  29
  30 Automatic OpenMP code generation
  31 ================================
  32
  33 To automatically detect parallel loops and generate OpenMP code for them you
  34 also need to add -mllvm -polly-parallel -lgomp to your CFLAGS.
  35
  36 .. code-block:: console
  37
  38   clang -O3 -mllvm -polly -mllvm -polly-parallel -lgomp file.c
  39
  40 Automatic Vector code generation
  41 ================================
  42
  43 Automatic vector code generation can be enabled by adding -mllvm
  44 -polly-vectorizer=stripmine to your CFLAGS.
  45
  46 .. code-block:: console
  47
  48   clang -O3 -mllvm -polly -mllvm -polly-vectorizer=stripmine file.c
  49
  50 Extract a preoptimized LLVM-IR file
  51 ===================================
  52
  53 Often it is useful to derive from a C-file the LLVM-IR code that is actually
  54 optimized by Polly. Normally the LLVM-IR is automatically generated from the C
  55 code by first lowering C to LLVM-IR (clang) and by subsequently applying a set
  56 of preparing transformations on the LLVM-IR. To get the LLVM-IR after the
  57 preparing transformations have been applied run Polly with '-O0'.
  58
  59 .. code-block:: console
  60
  61   clang -O0 -mllvm -polly -S -emit-llvm file.c
  62
  63 Further options
  64 ===============
  65 Polly supports further options that are mainly useful for the development or the
  66 analysis of Polly. The relevant options can be added to clang by appending
  67 -mllvm -option-name to the CFLAGS or the clang command line.
  68
  69 Limit Polly to a single function
  70 --------------------------------
  71
  72 To limit the execution of Polly to a single function, use the option
  73 -polly-only-func=functionname.
  74
  75 Disable LLVM-IR generation
  76 --------------------------
  77
  78 Polly normally regenerates LLVM-IR from the Polyhedral representation. To only
  79 see the effects of the preparing transformation, but to disable Polly code
  80 generation add the option polly-no-codegen.
  81
  82 Graphical view of the SCoPs
  83 ---------------------------
  84 Polly can use graphviz to show the SCoPs it detects in a program. The relevant
  85 options are -polly-show, -polly-show-only, -polly-dot and -polly-dot-only. The
  86 'show' options automatically run dotty or another graphviz viewer to show the
  87 scops graphically. The 'dot' options store for each function a dot file that
  88 highlights the detected SCoPs. If 'only' is appended at the end of the option,
  89 the basic blocks are shown without the statements the contain.
  90
  91 Change/Disable the Optimizer
  92 ----------------------------
  93
  94 Polly uses by default the isl scheduling optimizer. The isl optimizer optimizes
  95 for data-locality and parallelism using the Pluto algorithm.
  96 To disable the optimizer entirely use the option -polly-optimizer=none.
  97
  98 Disable tiling in the optimizer
  99 -------------------------------
 100
 101 By default both optimizers perform tiling, if possible. In case this is not
 102 wanted the option -polly-tiling=false can be used to disable it. (This option
 103 disables tiling for both optimizers).
 104
 105 Import / Export
 106 ---------------
 107
 108 The flags -polly-import and -polly-export allow the export and reimport of the
 109 polyhedral representation. By exporting, modifying and reimporting the
 110 polyhedral representation externally calculated transformations can be
 111 applied. This enables external optimizers or the manual optimization of
 112 specific SCoPs.
 113
 114 Viewing Polly Diagnostics with opt-viewer
 115 -----------------------------------------
 116
 117 The flag -fsave-optimization-record will generate .opt.yaml files when compiling
 118 your program. These yaml files contain information about each emitted remark.
 119 Ensure that you have Python 2.7 with PyYaml and Pygments Python Packages.
 120 To run opt-viewer:
 121
 122 .. code-block:: console
 123
 124    llvm/tools/opt-viewer/opt-viewer.py -source-dir /path/to/program/src/ \
 125       /path/to/program/src/foo.opt.yaml \
 126       /path/to/program/src/bar.opt.yaml \
 127       -o ./output
 128
 129 Include all yaml files (use \*.opt.yaml when specifying which yaml files to view)
 130 to view all diagnostics from your program in opt-viewer. Compile with `PGO
 131 <https://clang.llvm.org/docs/UsersManual.html#profiling-with-instrumentation>`_ to view
 132 Hotness information in opt-viewer. Resulting html files can be viewed in an internet browser.