[PATCH] Add documentation for -Rpass*

[Richard Smith]

LGTM


On Mon, May 12, 2014 at 1:27 PM, Diego Novillo <dnovillo at google.com> wrote:

> Hi rsmith,
>
> This adds documentation for -Rpass, -Rpass-missed and -Rpass-analysis.
> It also adds release notes for 3.5.
>
> http://reviews.llvm.org/D3730
>
> Files:
>   docs/ReleaseNotes.rst
>   docs/UsersManual.rst
>
> Index: docs/ReleaseNotes.rst
> ===================================================================
> --- docs/ReleaseNotes.rst
> +++ docs/ReleaseNotes.rst
> @@ -92,6 +92,11 @@
>  `-fcatch-undefined-behavior` and `-fbounds-checking` were removed in
> favor of
>  `-fsanitize=` family of flags.
>
> +It is now possible to get optimization reports from the major
> transformation
> +passes via three new flags: `-Rpass`, `-Rpass-missed` and
> `-Rpass-analysis`.
> +These flags take a POSIX regular expression which indicates the name
> +of the pass (or passes) that should emit optimization remarks.
> +
>  C Language Changes in Clang
>  ---------------------------
>
> Index: docs/UsersManual.rst
> ===================================================================
> --- docs/UsersManual.rst
> +++ docs/UsersManual.rst
> @@ -531,6 +531,72 @@
>  The -fno-crash-diagnostics flag can be helpful for speeding the process
>  of generating a delta reduced test case.
>
> +Options to Emit Optimization Reports
> +------------------------------------
> +
> +Optimization reports trace, at a high-level, all the major decisions
> +done by compiler transformations. For instance, when the inliner
> +decides to inline function ``foo()`` into ``bar()``, or the loop unroller
> +decides to unroll a loop N times, or the vectorizer decides to
> +vectorize a loop body.
> +
> +Clang offers a family of flags which the optimizers can use to emit
> +a diagnostic in three cases:
> +
> +1. When the pass makes a transformation (:option:`-Rpass`).
> +
> +2. When the pass fails to make a transformation (:option:`-Rpass-missed`).
> +
> +3. When the pass determines whether or not to make a transformation
> +   (:option:`-Rpass-analysis`).
> +
> +NOTE: Although the discussion below focuses on :option:`-Rpass`, the exact
> +same options apply to :option:`-Rpass-missed` and
> :option:`-Rpass-analysis`.
> +
> +Since there are dozens of passes inside the compiler, each of these flags
> +take a regular expression that identifies the name of the pass which
> should
> +emit the associated diagnostic. For example, to get a report from the
> inliner,
> +compile the code with:
> +
> +.. code-block:: console
> +
> +   $ clang -O2 -Rpass=inline code.cc -o code
> +   code.cc:4:25: remark: foo inlined into bar [-Rpass=inline]
> +   int bar(int j) { return foo(j, j - 2); }
> +                           ^
> +
> +Note that remarks from the inliner are identified with `[-Rpass=inline]`.
> +To request a report from every optimization pass, you should use
> +:option:`-Rpass=.*` (in fact, you can use any valid POSIX regular
> +expression). However, do not expect a report from every transformation
> +made by the compiler. Optimization remarks do not really make sense
> +outside of the major transformations (e.g., inlining, vectorization,
> +loop optimizations) and not every optimization pass supports this
> +feature.
> +
> +Current limitations
> +^^^^^^^^^^^^^^^^^^^
> +
> +1. For :option:`-Rpass` to provide source location information, you
> +   need to enable debug line tables and column information. That is,
> +   you need to add :option:`-gmlt` (or any of the debug-generating
> +   flags) and :option:`-gcolumn-info`. If you omit these options,
> +   every remark will be accompanied by a note stating that line number
> +   information is missing.
> +
> +2. Optimization remarks that refer to function names will display the
> +   mangled name of the function. Since these remarks are emitted by the
> +   back end of the compiler, it does not know anything about the input
> +   language, nor its mangling rules.
> +
> +3. Some source locations are not displayed correctly. The front end has
> +   a more detailed source location tracking than the locations included
> +   in the debug info (e.g., the front end can locate code inside macro
> +   expansions). However, the locations used by :option:`-Rpass` are
> +   translated from debug annotations. That translation can be lossy,
> +   which results in some remarks having no location information.
> +
> +
>  Language and Target-Independent Features
>  ========================================
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/cfe-commits/attachments/20140512/327e70f4/attachment.html>