[clang] Fix documentation on PGO/coverage related options. (PR #73845)
https://github.com/david-xl closed https://github.com/llvm/llvm-project/pull/73845 ___ cfe-commits mailing list cfe-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
[clang] Fix documentation on PGO/coverage related options. (PR #73845)
https://github.com/david-xl updated https://github.com/llvm/llvm-project/pull/73845 >From 4c0f907dc778e8cfd0e41008b8b2970a016201b0 Mon Sep 17 00:00:00 2001 From: David Li Date: Wed, 29 Nov 2023 11:56:31 -0800 Subject: [PATCH] Fix PGO documentation in user manual --- clang/docs/UsersManual.rst | 54 +++--- 1 file changed, 38 insertions(+), 16 deletions(-) diff --git a/clang/docs/UsersManual.rst b/clang/docs/UsersManual.rst index 2e658557b0e31..9d64195ee338e 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. @@ -2598,6 +2599,8 @@ 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. +.. _prof_instr: + Profiling with Instrumentation ^^ @@ -2607,11 +2610,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 +2691,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 +2702,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[=] @@ -4401,13 +4415,21 @@ 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= Instrument only functions from files where names match any regex separated by a semi-colon - -fprofile-instr-generate= - Generate instrumented code to collect execution counts into +
[clang] Fix documentation on PGO/coverage related options. (PR #73845)
https://github.com/petrhosek approved this pull request. https://github.com/llvm/llvm-project/pull/73845 ___ cfe-commits mailing list cfe-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
[clang] Fix documentation on PGO/coverage related options. (PR #73845)
@@ -4401,13 +4413,18 @@ 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= Instrument only functions from files where names match any regex separated by a semi-colon + -fprofile-generate[=] david-xl wrote: -fprofile-generate= in GCC specifies a path which is a directory name (the reason is that GCC's profile data is dumped per module, so there is no single profile name). When we introduced this option in Clang/LLVM, we just matched that behavior. https://github.com/llvm/llvm-project/pull/73845 ___ cfe-commits mailing list cfe-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
[clang] Fix documentation on PGO/coverage related options. (PR #73845)
@@ -4401,13 +4415,21 @@ 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= Instrument only functions from files where names match any regex separated by a semi-colon - -fprofile-instr-generate= - Generate instrumented code to collect execution counts into + -fprofile-generate= + Generate instrumented code to collect execution counts into a raw profile file in the directory specified by the argument. The filename uses the %m format. See :ref:`Profiling With Instrumentation ` section for details. david-xl wrote: Fixed. https://github.com/llvm/llvm-project/pull/73845 ___ cfe-commits mailing list cfe-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
[clang] Fix documentation on PGO/coverage related options. (PR #73845)
@@ -4401,13 +4415,21 @@ 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= Instrument only functions from files where names match any regex separated by a semi-colon - -fprofile-instr-generate= - Generate instrumented code to collect execution counts into + -fprofile-generate= + Generate instrumented code to collect execution counts into a raw profile file in the directory specified by the argument. The filename uses the %m format. See :ref:`Profiling With Instrumentation ` section for details. + (overridden by LLVM_PROFILE_FILE env var) + -fprofile-generate + Generate instrumented code to collect execution counts into default_%m.profraw file + (overridden by '=' form of option or LLVM_PROFILE_FILE env var) + -fprofile-instr-generate= david-xl wrote: done (-fprofile-instr-generate was there before. I added -fprofile-generate). https://github.com/llvm/llvm-project/pull/73845 ___ cfe-commits mailing list cfe-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
[clang] Fix documentation on PGO/coverage related options. (PR #73845)
https://github.com/david-xl updated https://github.com/llvm/llvm-project/pull/73845 >From 29b5b28f52c88ebd862163c4feb1573460c5c79e Mon Sep 17 00:00:00 2001 From: David Li Date: Wed, 29 Nov 2023 11:56:31 -0800 Subject: [PATCH] Fix PGO documentation in user manual --- clang/docs/UsersManual.rst | 54 +++--- 1 file changed, 38 insertions(+), 16 deletions(-) diff --git a/clang/docs/UsersManual.rst b/clang/docs/UsersManual.rst index 2e658557b0e310c..17e52a715e79e86 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. @@ -2598,6 +2599,8 @@ 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. +.. _prof_instr: + Profiling with Instrumentation ^^ @@ -2607,11 +2610,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 +2691,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 +2702,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[=] @@ -4401,13 +4415,21 @@ 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= Instrument only functions from files where names match any regex separated by a semi-colon - -fprofile-instr-generate= - Generate instrumented code to collect execution counts into +
[clang] Fix documentation on PGO/coverage related options. (PR #73845)
@@ -4401,13 +4413,18 @@ 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= Instrument only functions from files where names match any regex separated by a semi-colon + -fprofile-generate[=] petrhosek wrote: This is really surprising but I just tested this and you're correct. Do you know why that's the case, that is why `-fprofile-generate=` and `-fprofile-instr-generate=` have a different behavior? https://github.com/llvm/llvm-project/pull/73845 ___ cfe-commits mailing list cfe-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
[clang] Fix documentation on PGO/coverage related options. (PR #73845)
@@ -4401,13 +4415,21 @@ 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= Instrument only functions from files where names match any regex separated by a semi-colon - -fprofile-instr-generate= - Generate instrumented code to collect execution counts into + -fprofile-generate= + Generate instrumented code to collect execution counts into a raw profile file in the directory specified by the argument. The filename uses the %m format. See :ref:`Profiling With Instrumentation ` section for details. + (overridden by LLVM_PROFILE_FILE env var) + -fprofile-generate + Generate instrumented code to collect execution counts into default_%m.profraw file + (overridden by '=' form of option or LLVM_PROFILE_FILE env var) + -fprofile-instr-generate= petrhosek wrote: Can you also add `-fprofile-instr-generate` case below for consistency? https://github.com/llvm/llvm-project/pull/73845 ___ cfe-commits mailing list cfe-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
[clang] Fix documentation on PGO/coverage related options. (PR #73845)
@@ -4401,13 +4415,21 @@ 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= Instrument only functions from files where names match any regex separated by a semi-colon - -fprofile-instr-generate= - Generate instrumented code to collect execution counts into + -fprofile-generate= + Generate instrumented code to collect execution counts into a raw profile file in the directory specified by the argument. The filename uses the %m format. See :ref:`Profiling With Instrumentation ` section for details. petrhosek wrote: Should the second sentence say "The filename uses the default_%m.profraw."? https://github.com/llvm/llvm-project/pull/73845 ___ cfe-commits mailing list cfe-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
[clang] Fix documentation on PGO/coverage related options. (PR #73845)
https://github.com/david-xl updated https://github.com/llvm/llvm-project/pull/73845 >From 4cf62b1b780edef9902b5ec50b56d676810c3922 Mon Sep 17 00:00:00 2001 From: David Li Date: Wed, 29 Nov 2023 11:56:31 -0800 Subject: [PATCH] Fix PGO documentation in user manual --- clang/docs/UsersManual.rst | 54 +++--- 1 file changed, 38 insertions(+), 16 deletions(-) diff --git a/clang/docs/UsersManual.rst b/clang/docs/UsersManual.rst index 2e658557b0e310c..6e9a7cd4cc17064 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. @@ -2598,6 +2599,8 @@ 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. +.. _prof_instr: + Profiling with Instrumentation ^^ @@ -2607,11 +2610,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 +2691,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 +2702,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[=] @@ -4401,13 +4415,21 @@ 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= Instrument only functions from files where names match any regex separated by a semi-colon - -fprofile-instr-generate= - Generate instrumented code to collect execution counts into +
[clang] Fix documentation on PGO/coverage related options. (PR #73845)
https://github.com/david-xl updated https://github.com/llvm/llvm-project/pull/73845 >From 15dd2029a68a6fdbbc4eee5764ce966e0533880f Mon Sep 17 00:00:00 2001 From: David Li Date: Wed, 29 Nov 2023 11:56:31 -0800 Subject: [PATCH] Fix PGO documentation in user manual --- clang/docs/UsersManual.rst | 51 ++ 1 file changed, 35 insertions(+), 16 deletions(-) diff --git a/clang/docs/UsersManual.rst b/clang/docs/UsersManual.rst index 2e658557b0e310c..af10a73285ce6cf 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. @@ -2598,6 +2599,8 @@ 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. +.. _prof_instr: + Profiling with Instrumentation ^^ @@ -2607,11 +2610,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 +2691,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 +2702,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[=] @@ -4401,13 +4415,18 @@ 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= Instrument only functions from files where names match any regex separated by a semi-colon - -fprofile-instr-generate= - Generate instrumented code to collect execution counts into +
[clang] Fix documentation on PGO/coverage related options. (PR #73845)
https://github.com/david-xl updated https://github.com/llvm/llvm-project/pull/73845 >From 7f64cc07b2883b9fde672510a3b7c1b71cfb4dfd Mon Sep 17 00:00:00 2001 From: David Li Date: Wed, 29 Nov 2023 11:56:31 -0800 Subject: [PATCH] Fix PGO documentation in user manual --- clang/docs/UsersManual.rst | 49 ++ 1 file changed, 34 insertions(+), 15 deletions(-) diff --git a/clang/docs/UsersManual.rst b/clang/docs/UsersManual.rst index 2e658557b0e310c..aac2b9691284921 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. @@ -2598,6 +2599,8 @@ 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. +.. _prof_instr: + Profiling with Instrumentation ^^ @@ -2607,11 +2610,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 +2691,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 +2702,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[=] @@ -4401,13 +4415,18 @@ 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= Instrument only functions from files where names match any regex separated by a semi-colon - -fprofile-instr-generate= + -fprofile-generate[=] + Generate instrumented code to collect
[clang] Fix documentation on PGO/coverage related options. (PR #73845)
@@ -4401,13 +4413,18 @@ 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= Instrument only functions from files where names match any regex separated by a semi-colon + -fprofile-generate[=] david-xl wrote: Updated description. It is actually a dirname, not pattern. https://github.com/llvm/llvm-project/pull/73845 ___ cfe-commits mailing list cfe-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
[clang] Fix documentation on PGO/coverage related options. (PR #73845)
@@ -4401,13 +4413,18 @@ 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= Instrument only functions from files where names match any regex separated by a semi-colon + -fprofile-generate[=] + Generate instrumented code to collect execution counts into a raw profile file in + (overridden by LLVM_PROFILE_FILE env var) -fprofile-instr-generate= Generate instrumented code to collect execution counts into (overridden by LLVM_PROFILE_FILE env var) -fprofile-instr-generate 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= + Use instrumentation data for coverage testing or profile-guided optimization + -fprofile--use= david-xl wrote: fixed. https://github.com/llvm/llvm-project/pull/73845 ___ cfe-commits mailing list cfe-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
[clang] Fix documentation on PGO/coverage related options. (PR #73845)
@@ -4401,13 +4413,18 @@ 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= Instrument only functions from files where names match any regex separated by a semi-colon + -fprofile-generate[=] + Generate instrumented code to collect execution counts into a raw profile file in + (overridden by LLVM_PROFILE_FILE env var) -fprofile-instr-generate= david-xl wrote: Done https://github.com/llvm/llvm-project/pull/73845 ___ cfe-commits mailing list cfe-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
[clang] Fix documentation on PGO/coverage related options. (PR #73845)
https://github.com/david-xl updated https://github.com/llvm/llvm-project/pull/73845 >From ce4c93c2b250e2f4b6703f6321397dd774333f35 Mon Sep 17 00:00:00 2001 From: David Li Date: Wed, 29 Nov 2023 11:56:31 -0800 Subject: [PATCH] Fix PGO documentation in user manual --- clang/docs/UsersManual.rst | 50 ++ 1 file changed, 35 insertions(+), 15 deletions(-) diff --git a/clang/docs/UsersManual.rst b/clang/docs/UsersManual.rst index 2e658557b0e310c..5d49ec70540a7e4 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. @@ -2598,6 +2599,8 @@ 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. +.. _prof_instr: + Profiling with Instrumentation ^^ @@ -2607,11 +2610,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 +2691,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 +2702,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[=] @@ -4401,13 +4415,19 @@ 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= Instrument only functions from files where names match any regex separated by a semi-colon - -fprofile-instr-generate= + -fprofile-generate[=] + Generate instrumented code to collect
[clang] Fix documentation on PGO/coverage related options. (PR #73845)
@@ -4401,13 +4413,18 @@ 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= Instrument only functions from files where names match any regex separated by a semi-colon + -fprofile-generate[=] + Generate instrumented code to collect execution counts into a raw profile file in + (overridden by LLVM_PROFILE_FILE env var) -fprofile-instr-generate= Generate instrumented code to collect execution counts into (overridden by LLVM_PROFILE_FILE env var) -fprofile-instr-generate 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= + Use instrumentation data for coverage testing or profile-guided optimization + -fprofile--use= petrhosek wrote: This a nit, but there should be only a single `-`, so `-fprofile-use` not `-fprofile--use`. https://github.com/llvm/llvm-project/pull/73845 ___ cfe-commits mailing list cfe-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
[clang] Fix documentation on PGO/coverage related options. (PR #73845)
@@ -4401,13 +4413,18 @@ 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= Instrument only functions from files where names match any regex separated by a semi-colon + -fprofile-generate[=] + Generate instrumented code to collect execution counts into a raw profile file in + (overridden by LLVM_PROFILE_FILE env var) -fprofile-instr-generate= petrhosek wrote: Can we also update this line to match `-fprofile-generate`? https://github.com/llvm/llvm-project/pull/73845 ___ cfe-commits mailing list cfe-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
[clang] Fix documentation on PGO/coverage related options. (PR #73845)
@@ -4401,13 +4413,18 @@ 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= Instrument only functions from files where names match any regex separated by a semi-colon + -fprofile-generate[=] petrhosek wrote: Rather than ``, I think it'd be better to say `` and point to https://clang.llvm.org/docs/UsersManual.html#profiling-with-instrumentation for more details. https://github.com/llvm/llvm-project/pull/73845 ___ cfe-commits mailing list cfe-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
[clang] Fix documentation on PGO/coverage related options. (PR #73845)
https://github.com/david-xl updated https://github.com/llvm/llvm-project/pull/73845 >From 627d664f0281d6db778f5d624710a7066e6c362f Mon Sep 17 00:00:00 2001 From: David Li Date: Wed, 29 Nov 2023 11:56:31 -0800 Subject: [PATCH] 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[=] @@ -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= Instrument only functions from files where names match any regex separated by a semi-colon + -fprofile-generate[=] + Generate instrumented code to collect execution counts into a raw profile file in + (overridden by LLVM_PROFILE_FILE env var) -fprofile-instr-generate= Generate instrumented code to collect execution counts into (overridden by LLVM_PROFILE_FILE env var) @@
[llvm] [clang] Fix documentation on PGO/coverage related options. (PR #73845)
https://github.com/david-xl created https://github.com/llvm/llvm-project/pull/73845 Update the user manual to provide guidance on the usage for different flavors of instrumentations. >From b2c9081a0c3d5a982c2a23857bf986ec80c83cb5 Mon Sep 17 00:00:00 2001 From: David Li 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 e13f42f2e0fb666dac13c28579d2edba9ae8b8e9 Mon Sep 17 00:00:00 2001 From: David Li Date: Wed, 29 Nov 2023 11:56:31 -0800 Subject: [PATCH 2/2] Fix PGO documentation in user manual --- clang/docs/UsersManual.rst | 37 ++--- 1 file changed, 26 insertions(+), 11 deletions(-) diff --git a/clang/docs/UsersManual.rst b/clang/docs/UsersManual.rst index 2e658557b0e310c..1d2165157b8be8a 100644 --- a/clang/docs/UsersManual.rst +++ b/clang/docs/UsersManual.rst @@ -2607,11 +2607,24 @@ 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. +There are two types of instrumentation available in Clang: frontend based and +IR based. The frontend based instrumentation can be turned on with option +``-fprofile-instr-generate`` and the IR based instrumentation can be turned +on with ``-fprofile-generate`` option. For best performance with PGO, the IR +based instrumentation should be used. It has the benefits of lower instrumentation +overhead, smaller raw profile size, and better runtime performance. Frontend +based instrumnetaition, on the other hand, has better source correlation so should +be used with source line based coverage testing. + +Flag ``-fcs-profile-generate`` also instruments programs using the same +instrumentation method as ``-fprofile-generate``. It does a post-inline late +instrumentation and can produce context sensientive profile. + 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 +2687,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 +2698,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[=] @@ -4401,6 +4411,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= Instrument only functions from files where names match any regex separated by a semi-colon + -fprofile-generate[=] + Generate instrumented code to collect execution counts into a raw profile
