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

[zequanwu]

Summary

Add docs to specify -fprofile-generate for IR PGO and -fprofile-instr-generate for code coverage.

[davidxl]

clang/docs/UsersManual.rst

1878–1879

This is not correct. As of today, -fprofile-use can be used with both -fprofile-generate and -fprofile-instr-generate. It does this by looking at the flag in the profile data.

The better way to document:

For profile guided optimizations, we recommend using IRPGO, aka using-fprofile-generate with -fprofile-use

[zequanwu]

Update wording.

[rnk]

clang/docs/UsersManual.rst

2117–2118

I like the original paragraph here. The casual reader doesn't need to know about the two flavors of instrumentation, that detail can be added at the end of this section.

2188

This should be fprofile-use, correct?

2199–2200

This is the right place to mention the fprofile-instr-generate / use flags.

It's worth retaining the note that, although Clang and GCC use the same command line flags to enable PGO, the profile data format is not compatible.

2213

This probably needs edits too, it's not the alternative.

[zequanwu]

Address comments.

clang/docs/ClangCommandLineReference.rst

 Instrument only functions from files where names don't match all the regexes separated by a semi-colon
 
 .. option:: -fprofile-filter-files=<arg>
 
 Instrument only functions from files where names match any regex separated by a semi-colon
 
 .. 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>
 .. program:: clang
 
 Generate instrumented code to collect execution counts into <directory>/default.profraw (overridden by LLVM\_PROFILE\_FILE env var)
 
 .. 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>
 .. program:: clang
 
 Generate instrumented code to collect execution counts into <file> (overridden by LLVM\_PROFILE\_FILE env var)
 
 .. option:: -fprofile-instr-use, -fno-profile-instr-use, -fprofile-use

clang/docs/UsersManual.rst

 is unimportant, and the compiler may make poor optimization choices for code
 that is disproportionately used while profiling.
 
 Differences Between Sampling and Instrumentation
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 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
    sampling profiles for code coverage, sample-based profiles are too
    coarse-grained for code coverage purposes; it would yield poor results.
 
 4. Sampling profiles must be generated by an external tool. The profile
    generated by that tool must then be converted into a format that can be read

 collected in main. All of those were at line 1 (the call to ``foo``).
 Of those, 31,977 were spent inside the body of ``bar``. The last line
 of the profile (``2: 0``) corresponds to line 2 inside ``main``. No
 samples were collected there.
 
 Profiling with Instrumentation
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Clang also supports profiling via 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
    can include different modifiers: ``%p``, ``%h``, and ``%m``.
 
    Any instance of ``%p`` in that file name will be replaced by the process
    ID, so that you can easily distinguish the profile output from multiple
    runs.
3. Combine profiles from multiple runs and convert the "raw" profile format to
 
    .. code-block:: console
 
      $ llvm-profdata merge -output=code.profdata code-*.profraw
 
    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
+4. Build the code again using the ``-fprofile-use`` option to specify the
    collected profile data.
 
    .. code-block:: console
 
-     $ clang++ -O2 -fprofile-instr-use=code.profdata code.cc -o code
+     $ clang++ -O2 -fprofile-use=code.profdata code.cc -o code
 
    You can repeat step 4 as often as you like without regenerating the
    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
+controlled by ``-fprofile-instr-generate``, which is the AST-based 
+instrumentation used for code coverage analysis 
+(:doc:`source based code coverage <SourceBasedCodeCoverage>`). 
+
+Although the flags ``-fprofile-generate`` and ``-fprofile-use`` 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``.
 
 .. option:: -fprofile-generate[=<dirname>]
 
   The ``-fprofile-generate`` and ``-fprofile-generate=`` flags will use
-  an alternative instrumentation method for profile generation. When
+  an instrumentation method for profile generation. When
   given a directory name, it generates the profile file
   ``default_%m.profraw`` in the directory named ``dirname`` if specified.
   If ``dirname`` does not exist, it will be created at runtime. ``%m`` specifier
   will be substituted with a unique id documented in step 2 above. In other words,
   with ``-fprofile-generate[=<dirname>]`` option, the "raw" profile data automatic
   merging is turned on by default, so there will no longer any risk of profile
   clobbering from different running processes.  For example,
 
.. option:: -fprofile-list=<pathname>
   This option can be used to apply profile instrumentation only to selected
   files or functions. ``pathname`` should point to a file in the
   :doc:`SanitizerSpecialCaseList` format which selects which files and
   functions to instrument.
 
   .. code-block:: console
 
     $ echo "fun:test" > fun.list
-    $ clang++ -O2 -fprofile-instr-generate -fprofile-list=fun.list code.cc -o code
+    $ clang++ -O2 -fprofile-generate -fprofile-list=fun.list code.cc -o code
 
 The option can be specified multiple times to pass multiple files.
 
 .. code-block:: console
 
     $ echo "!fun:*test*" > fun.list
     $ echo "src:code.cc" > src.list
-    % clang++ -O2 -fprofile-instr-generate -fcoverage-mapping -fprofile-list=fun.list -fprofile-list=code.list code.cc -o code
+    % clang++ -O2 -fprofile-generate -fcoverage-mapping -fprofile-list=fun.list -fprofile-list=code.list code.cc -o code
 
 To filter individual functions or entire source files using ``fun:<name>`` or
 ``src:<file>`` respectively. To exclude a function or a source file, use
 ``!fun:<name>`` or ``!src:<file>`` respectively. The format also supports
 wildcard expansion. The compiler generated functions are assumed to be located
 in the main source file.  It is also possible to restrict the filter to a
 particular instrumentation type by using a named section.
 

 Finding Clang runtime libraries
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 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
 into their program. These libraries are distributed alongside Clang in the
 library resource directory. Clang searches for the resource directory by
 searching relative to the Clang executable. For example, if LLVM is installed
 in ``C:\Program Files\LLVM``, then the profile runtime library will be located
 at the path