[clang] [llvm] Fix documentation on PGO/coverage related options. (PR #73845)

[David Li via cfe-commits]

https://github.com/david-xl updated https://github.com/llvm/llvm-project/pull/73845

>From b2c9081a0c3d5a982c2a23857bf986ec80c83cb5 Mon Sep 17 00:00:00 2001
From: David Li <davidxl at google.com>
Date: Mon, 27 Nov 2023 13:49:25 -0800
Subject: [PATCH 1/2] Fix stale comment

---
 llvm/lib/Transforms/Instrumentation/InstrProfiling.cpp | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/llvm/lib/Transforms/Instrumentation/InstrProfiling.cpp b/llvm/lib/Transforms/Instrumentation/InstrProfiling.cpp
index 601903c29f799a2..73a7116f74e1180 100644
--- a/llvm/lib/Transforms/Instrumentation/InstrProfiling.cpp
+++ b/llvm/lib/Transforms/Instrumentation/InstrProfiling.cpp
@@ -6,7 +6,7 @@
 //
 //===----------------------------------------------------------------------===//
 //
-// This pass lowers instrprof_* intrinsics emitted by a frontend for profiling.
+// This pass lowers instrprof_* intrinsics emitted by an instrumentor.
 // It also builds the data structures and initialization code needed for
 // updating execution counts and emitting the profile at runtime.
 //

>From dfd0ae0197b8e7425af1fd02636dda876b54d5bc Mon Sep 17 00:00:00 2001
From: David Li <davidxl at google.com>
Date: Wed, 29 Nov 2023 11:56:31 -0800
Subject: [PATCH 2/2] Fix PGO documentation in user manual

---
 clang/docs/UsersManual.rst | 45 ++++++++++++++++++++++++++------------
 1 file changed, 31 insertions(+), 14 deletions(-)

diff --git a/clang/docs/UsersManual.rst b/clang/docs/UsersManual.rst
index 2e658557b0e310c..51b9cc246ea8b55 100644
--- a/clang/docs/UsersManual.rst
+++ b/clang/docs/UsersManual.rst
@@ -2348,9 +2348,10 @@ differences between the two:
 
 1. Profile data generated with one cannot be used by the other, and there is no
    conversion tool that can convert one to the other. So, a profile generated
-   via ``-fprofile-instr-generate`` must be used with ``-fprofile-instr-use``.
-   Similarly, sampling profiles generated by external profilers must be
-   converted and used with ``-fprofile-sample-use``.
+   via ``-fprofile-generate`` or ``-fprofile-instr-generate`` must be used with
+   ``-fprofile-use`` or ``-fprofile-instr-use``.  Similarly, sampling profiles
+   generated by external profilers must be converted and used with ``-fprofile-sample-use``
+   or ``-fauto-profile``.
 
 2. Instrumentation profile data can be used for code coverage analysis and
    optimization.
@@ -2607,11 +2608,25 @@ overhead during the profiling, but it provides more detailed results than a
 sampling profiler. It also provides reproducible results, at least to the
 extent that the code behaves consistently across runs.
 
+Clang supports two types of instrumentation: frontend-based and IR-based.
+Frontend-based instrumentation can be enabled with the option ``-fprofile-instr-generate``,
+and IR-based instrumentation can be enabled with the option ``-fprofile-generate``.
+For best performance with PGO, IR-based instrumentation should be used. It has
+the benefits of lower instrumentation overhead, smaller raw profile size, and
+better runtime performance. Frontend-based instrumentation, on the other hand,
+has better source correlation, so it should be used with source line-based
+coverage testing.
+
+The flag ``-fcs-profile-generate`` also instruments programs using the same
+instrumentation method as ``-fprofile-generate``. However, it performs a
+post-inline late instrumentation and can produce context-sensitive profiles.
+
+
 Here are the steps for using profile guided optimization with
 instrumentation:
 
 1. Build an instrumented version of the code by compiling and linking with the
-   ``-fprofile-instr-generate`` option.
+   ``-fprofile-generate`` or ``-fprofile-instr-generate`` option.
 
    .. code-block:: console
 
@@ -2674,8 +2689,8 @@ instrumentation:
    Note that this step is necessary even when there is only one "raw" profile,
    since the merge operation also changes the file format.
 
-4. Build the code again using the ``-fprofile-instr-use`` option to specify the
-   collected profile data.
+4. Build the code again using the ``-fprofile-use`` or ``-fprofile-instr-use``
+   option to specify the collected profile data.
 
    .. code-block:: console
 
@@ -2685,13 +2700,10 @@ instrumentation:
    profile. As you make changes to your code, clang may no longer be able to
    use the profile data. It will warn you when this happens.
 
-Profile generation using an alternative instrumentation method can be
-controlled by the GCC-compatible flags ``-fprofile-generate`` and
-``-fprofile-use``. Although these flags are semantically equivalent to
-their GCC counterparts, they *do not* handle GCC-compatible profiles.
-They are only meant to implement GCC's semantics with respect to
-profile creation and use. Flag ``-fcs-profile-generate`` also instruments
-programs using the same instrumentation method as ``-fprofile-generate``.
+Note that ``-fprofile-use`` option is semantically equivalent to
+its GCC counterpart, it *does not* handle profile formats produced by GCC.
+Both ``-fprofile-use`` and ``-fprofile-instr-use`` accept profiles in the
+indexed format, regardeless whether it is produced by frontend or the IR pass.
 
 .. option:: -fprofile-generate[=<dirname>]
 
@@ -4401,6 +4413,9 @@ Execute ``clang-cl /?`` to see a list of supported options:
                               Instrument only functions from files where names don't match all the regexes separated by a semi-colon
       -fprofile-filter-files=<value>
                               Instrument only functions from files where names match any regex separated by a semi-colon
+      -fprofile-generate[=<dirname>]
+                              Generate instrumented code to collect execution counts into a raw profile file in <dirname>
+                              (overridden by LLVM_PROFILE_FILE env var)
       -fprofile-instr-generate=<file>
                               Generate instrumented code to collect execution counts into <file>
                               (overridden by LLVM_PROFILE_FILE env var)
@@ -4408,6 +4423,8 @@ Execute ``clang-cl /?`` to see a list of supported options:
                               Generate instrumented code to collect execution counts into default.profraw file
                               (overridden by '=' form of option or LLVM_PROFILE_FILE env var)
       -fprofile-instr-use=<value>
+                              Use instrumentation data for coverage testing or profile-guided optimization
+      -fprofile--use=<value>
                               Use instrumentation data for profile-guided optimization
       -fprofile-remapping-file=<file>
                               Use the remappings described in <file> to match the profile data against names in the program
@@ -4569,7 +4586,7 @@ clang-cl supports several features that require runtime library support:
 - Address Sanitizer (ASan): ``-fsanitize=address``
 - Undefined Behavior Sanitizer (UBSan): ``-fsanitize=undefined``
 - Code coverage: ``-fprofile-instr-generate -fcoverage-mapping``
-- Profile Guided Optimization (PGO): ``-fprofile-instr-generate``
+- Profile Guided Optimization (PGO): ``-fprofile-generate``
 - Certain math operations (int128 division) require the builtins library
 
 In order to use these features, the user must link the right runtime libraries