zequanwu updated this revision to Diff 355718.
zequanwu marked 4 inline comments as done.
zequanwu added a comment.
Address comments.
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
@@ -2120,20 +2120,20 @@
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
@@ -2185,29 +2185,32 @@
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
@@ -2326,7 +2329,7 @@
.. 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.
@@ -2334,7 +2337,7 @@
$ 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
@@ -3870,7 +3873,7 @@
- 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
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>
_______________________________________________
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
