www/example_load_Polly_into_clang.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
   2           "http://www.w3.org/TR/html4/strict.dtd">
   3 <!-- Material used from: HTML 4.01 specs: http://www.w3.org/TR/html401/ -->
   4 <html>
   5 <head>
   6   <META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
   7   <title>Polly - Load Polly into clang</title>
   8   <link type="text/css" rel="stylesheet" href="menu.css">
   9   <link type="text/css" rel="stylesheet" href="content.css">
  10 </head>
  11 <body>
  12 <div id="box">
  13 <!--#include virtual="menu.html.incl"-->
  14 <div id="content">
  15 <!--=====================================================================-->
  16 <h1>Load Polly into clang and automatically run it at -O3</h1>
  17 <!--=====================================================================-->
  18
  19 <p><b>Warning:</b> Even though this example makes it very easy to use Polly,
  20 you should be aware that Polly is a young research project. It is expected
  21 to crash, produce invalid code or to hang in complex calculations even for
  22 simple examples. In case you see such a problem, please check the <a
  23 href="bugs.html">Bug database</a> and consider reporting a bug.
  24 <p>
  25 <b>Warning II:</b> clang/LLVM/Polly need to be in sync. This means
  26             you need to compile them yourself from a recent svn/git checkout</b>
  27 <h2>Load Polly into clang</h2>
  28
  29 By default Polly is configured as a shared library plugin that is loaded in
  30 tools like clang, opt, and bugpoint when they start their execution.
  31
  32 By loading Polly into clang (or opt) the Polly options become automatically
  33 available. You can load Polly either by adding the relevant commands to
  34 the CPPFLAGS or by creating an alias.
  35
  36 <pre class="code">
  37 $ export CPPFLAGS="-Xclang -load -Xclang ${POLLY_BUILD_DIR}/lib/LLVMPolly.so"
  38 </pre>
  39
  40 or
  41 <pre class="code">
  42 $ alias pollycc clang -Xclang -load -Xclang ${POLLY_BUILD_DIR}/lib/LLVMPolly.so
  43 </pre>
  44
  45 To avoid having to load Polly in the tools, Polly can optionally be configured
  46 with cmake to be statically linked in the tools:
  47
  48 <pre class="code">
  49 $ cmake -D LINK_POLLY_INTO_TOOLS:Bool=ON
  50 </pre>
  51
  52 <h2>Optimizing with Polly</h2>
  53
  54 Optimizing with Polly is as easy as adding <b>-O3 -mllvm -polly</b> to your
  55 compiler flags (Polly is only available at -O3).
  56
  57 <pre class="code">pollycc -O3 -mllvm -polly file.c</pre>
  58
  59 <h2>Automatic OpenMP code generation</h2>
  60
  61 To automatically detect parallel loops and generate OpenMP code for them you
  62 also need to add <b>-mllvm -polly-parallel -lgomp</b> to your CFLAGS.
  63
  64 <pre class="code">pollycc -O3 -mllvm -polly -mllvm -polly-parallel -lgomp file.c</pre>
  65
  66 <h2>Automatic Vector code generation</h2>
  67
  68 Automatic vector code generation can be enabled by adding <b>-mllvm
  69 -polly-vectorizer=stripmine</b> to your CFLAGS.
  70
  71 <pre class="code">pollycc -O3 -mllvm -polly -mllvm -polly-vectorizer=stripmine file.c</pre>
  72
  73 <h2>Extract a preoptimized LLVM-IR file</h2>
  74
  75 Often it is useful to derive from a C-file the LLVM-IR code that is actually
  76 optimized by Polly. Normally the LLVM-IR is automatically generated from
  77 the C code by first lowering C to LLVM-IR (clang) and by subsequently applying a
  78 set of preparing transformations on the LLVM-IR. To get the LLVM-IR after the
  79 preparing transformations have been applied run Polly with '-O0'.
  80
  81 <pre class="code">pollycc -O0 -mllvm -polly -S -emit-llvm file.c</pre>
  82
  83 <h2>Further options</h2>
  84
  85 Polly supports further options that are mainly useful for the development or
  86 the
  87 analysis of Polly. The relevant options can be added to clang by appending
  88 <b>-mllvm -option-name</b> to the CFLAGS or the clang
  89 command line.
  90
  91 <h3>Limit Polly to a single function</h3>
  92 To limit the execution of Polly to a single function, use the option
  93 <b>-polly-only-func=functionname</b>.
  94
  95 <h3>Disable LLVM-IR generation</h3>
  96 Polly normally regenerates LLVM-IR from the Polyhedral representation. To only
  97 see the effects of the preparing transformation, but to disable Polly code
  98 generation add the option <b>polly-no-codegen</b>.
  99
 100 <h3>Graphical view of the SCoPs</h3>
 101
 102 Polly can use graphviz to show the SCoPs it detects in a program. The relevant
 103 options are <b>-polly-show</b>, <b>-polly-show-only</b>, <b>-polly-dot</b> and
 104 <b>-polly-dot-only</b>. The 'show' options automatically run dotty or another
 105 graphviz viewer to show the scops graphically. The 'dot' options store for each
 106 function a dot file that highlights the detected SCoPs. If 'only' is appended at
 107 the end of the option, the basic blocks are shown without the statements the
 108 contain.
 109
 110 <h3>Change/Disable the Optimizer</h3>
 111 Polly uses by default the isl scheduling optimizer. The isl optimizer optimizes
 112 for data-locality and parallelism using the <a
 113 href="http://pluto-compiler.sf.net">Pluto</a> algorithm. For research it is also
 114 possible to run <a
 115 href="http://www-rocq.inria.fr/~pouchet/software/pocc/">PoCC</a> as external
 116 optimizer. PoCC provides access to the original Pluto implementation. To use
 117 PoCC add <b>-polly-optimizer=pocc</b> to the command line (only available if
 118 Polly was compiled with scoplib support) [removed after <a href="http://llvm.org/releases/download.html#3.4.2">LLVM 3.4.2</a>].
 119 To disable the optimizer entirely use the option <b>-polly-optimizer=none</b>.
 120
 121 <h3>Disable tiling in the optimizer</h3>
 122 By default both optimizers perform tiling, if possible. In case this is not
 123 wanted the option <b>-polly-tiling=false</b> can be used to disable it. (This
 124 option disables tiling for both optimizers).
 125
 126 <h3>Ignore possible aliasing</h3>
 127 By default we only detect scops, if we can prove that the different array bases
 128 can not alias. This is correct do if we optimize automatically.  However,
 129 without special user annotations like 'restrict' we can often not prove that
 130 no aliasing is possible. In case the user knows no aliasing can happen in the
 131 code the <b>-polly-ignore-aliasing</b> can be used to disable the check for
 132 possible aliasing.
 133
 134 <h3>Import / Export</h3>
 135 The flags <b>-polly-import</b> and <b>-polly-export</b> allow the export and
 136 reimport of the polyhedral representation. By exporting, modifying and
 137 reimporting the polyhedral representation externally calculated transformations
 138 can be applied. This enables external optimizers or the manual optimization of
 139 specific SCoPs.
 140 </div>
 141 </div>
 142 </body>
 143 </html>