[doc] Overhaul doc on preparing IR for processing by Polly.

The previously documented method did not work (anymore).

Suggested-by: Philip Pfaffe <philip.pfaffe@gmail.com>
llvm-svn: 329446

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
+Polly's analysis and transformation passes are run with many other
-optimized by Polly. Normally the LLVM-IR is automatically generated from the C
+passes of the pass manager's pipeline.  Some of passes that run before
-code by first lowering C to LLVM-IR (clang) and by subsequently applying a set
+Polly are essential for its working, for instance the canonicalization
-of preparing transformations on the LLVM-IR. To get the LLVM-IR after the
+of loop.  Therefore Polly is unable to optimize code straight out of
-preparing transformations have been applied run Polly with '-O0'.
+clang's -O0 output.
+
+To get the LLVM-IR that Polly sees in the optimization pipeline, use the
+command:
 
 .. code-block:: console
 
-  clang -O0 -mllvm -polly -S -emit-llvm file.c
+  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 file.c -c -O3 -mllvm -polly -mllvm -polly-position=early -mllvm -polly-dump-before-file=before-polly.ll
 
 Further options
 ===============