[PATCH] D104871: [Docs] use -fprofile-generate for IR PGO and -fprofile-instr-generate for code coverage

[Zequan Wu via Phabricator via cfe-commits]

zequanwu updated this revision to Diff 354615.
zequanwu marked an inline comment as done.
zequanwu added a comment.

Update wording.


Repository:
  rG LLVM Github Monorepo

CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D104871/new/

https://reviews.llvm.org/D104871

Files:
  clang/docs/ClangCommandLineReference.rst
  clang/docs/UsersManual.rst


Index: clang/docs/UsersManual.rst
===================================================================
--- clang/docs/UsersManual.rst
+++ clang/docs/UsersManual.rst
@@ -1876,14 +1876,14 @@
 Although both techniques are used for similar purposes, there are important
 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
+1. For profile guided optimizations, we recommend using IR PGO, aka using 
+   ``-fprofile-generate`` with ``-fprofile-use``.
+   Sampling profiles generated by external profilers must be
    converted and used with ``-fprofile-sample-use``.
 
-2. Instrumentation profile data can be used for code coverage analysis and
-   optimization.
+2. Instrumentation profile data generated via ``-fprofile-generate`` can be used 
+   for optimization and data generated via 
+   ``-fprofile-instr-generate`` can be used for code coverage analysis.
 
 3. Sampling profiles can only be used for optimization. They cannot be used for
    code coverage analysis. Although it would be technically possible to use
@@ -2114,26 +2114,35 @@
 Profiling with Instrumentation
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Clang also supports profiling via instrumentation. This requires building a
-special instrumented version of the code and has some runtime
+Two types of instrumentations
+""""""""""""""""""""""""""
+
+1. ``-fprofile-generate`` is the LLVM IR-based instrumentation, which aims for 
+performance.
+
+2. ``-fprofile-instr-generate`` is the AST-based instrumentation used for code
+coverage analysis (:doc:`source based code coverage <SourceBasedCodeCoverage>`).
+
+This section forcuses on LLVM IR instrumentation. This requires 
+building a special instrumented version of the code and has some runtime
 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.
 
-Here are the steps for using profile guided optimization with
+Here are the steps for using profile guided optimization with LLVM IR
 instrumentation:
 
 1. Build an instrumented version of the code by compiling and linking with the
-   ``-fprofile-instr-generate`` option.
+   ``-fprofile-generate`` option.
 
    .. code-block:: console
 
-     $ clang++ -O2 -fprofile-instr-generate code.cc -o code
+     $ clang++ -O2 -fprofile-generate code.cc -o code
 
 2. Run the instrumented executable with inputs that reflect the typical usage.
    By default, the profile data will be written to a ``default.profraw`` file
    in the current directory. You can override that default by using option
-   ``-fprofile-instr-generate=`` or by setting the ``LLVM_PROFILE_FILE`` 
+   ``-fprofile-generate=`` or by setting the ``LLVM_PROFILE_FILE`` 
    environment variable to specify an alternate file. If non-default file name
    is specified by both the environment variable and the command line option,
    the environment variable takes precedence. The file name pattern specified
Index: clang/docs/ClangCommandLineReference.rst
===================================================================
--- clang/docs/ClangCommandLineReference.rst
+++ clang/docs/ClangCommandLineReference.rst
@@ -2141,7 +2141,7 @@
 
 .. option:: -fprofile-generate, -fno-profile-generate
 
-Generate instrumented code to collect execution counts into default.profraw (overridden by LLVM\_PROFILE\_FILE env var)
+Generate instrumented code to collect execution counts into default.profraw (overridden by LLVM\_PROFILE\_FILE env var), used for IR PGO.
 
 .. program:: clang1
 .. option:: -fprofile-generate=<directory>
@@ -2151,7 +2151,7 @@
 
 .. option:: -fprofile-instr-generate, -fno-profile-instr-generate
 
-Generate instrumented code to collect execution counts into default.profraw file (overridden by '=' form of option or LLVM\_PROFILE\_FILE env var)
+Generate instrumented code to collect execution counts into default.profraw file (overridden by '=' form of option or LLVM\_PROFILE\_FILE env var), used for code coverage analysis.
 
 .. program:: clang1
 .. option:: -fprofile-instr-generate=<file>


-------------- next part --------------
A non-text attachment was scrubbed...
Name: D104871.354615.patch
Type: text/x-patch
Size: 4394 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/cfe-commits/attachments/20210625/d6d07e3e/attachment.bin>