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