Update documentation and release notes for llvm-profgen COFF support #84864
Conversation
This change: - Updates the existing Clang User's Manual section on SPGO so that it describes how to use llvm-profgen to perform SPGO on Windows. This is new functionality implemented in llvm#83972. - Fixes a minor typo in the existing llvm-profgen invocation example. - Adds an LLVM release note on this new functionality in llvm-profgen.
|
Thank you for submitting a Pull Request (PR) to the LLVM Project! This PR will be automatically labeled and the relevant teams will be If you wish to, you can add reviewers by using the "Reviewers" section on this page. If this is not working for you, it is probably because you do not have write If you have received no comments on your PR for a week, you can request a review If you have further questions, they may be answered by the LLVM GitHub User Guide. You can also ask questions in a comment on this PR, on the LLVM Discord or on the forums. |
| into the format that the LLVM optimizer understands. | ||
|
|
||
| Two such profilers are the the Linux Perf profiler | ||
| (https://perf.wiki.kernel.org/) and Intel's Sampling Enabling Product (SEP), |
There was a problem hiding this comment.
I think we can make it clear that perf is only on Linux while SEP is Linux and Windows.
There was a problem hiding this comment.
Thanks -- I've made this more clear in a5e879c.
clang/docs/UsersManual.rst
Outdated
| <https://software.intel.com/content/www/us/en/develop/tools/oneapi/components/vtune-profiler.html>`_. | ||
|
|
||
| The LLVM tool ``llvm-profgen`` can convert output of either Perf or SEP. An | ||
| external tool, AutoFDO, also supports Linux Perf output. |
There was a problem hiding this comment.
maybe link to AutoFDO or explain what it's used for here?
There was a problem hiding this comment.
Yes, probably a good idea to include a link here now that it's the first mention of AutoFDO. Fixed in a5e879c.
clang/docs/UsersManual.rst
Outdated
|
|
||
| .. code-block:: console | ||
|
|
||
| $ clang++ -O2 -gline-tables-only code.cc -o code | ||
|
|
||
| It is also possible to include DWARF in Windows binaries: |
There was a problem hiding this comment.
Maybe this should be worded that while codeview is the standard on Windows, you can use DWARF instead.
There was a problem hiding this comment.
Codeview is the standard in MSVC style environments, while DWARF is the standard in MinGW too.
There was a problem hiding this comment.
I've expanded on this a little in a5e879c.
|
@llvm/pr-subscribers-clang Author: Tim Creech (tcreech-intel) ChangesThis change:
Full diff: https://github.com/llvm/llvm-project/pull/84864.diff 2 Files Affected:
diff --git a/clang/docs/UsersManual.rst b/clang/docs/UsersManual.rst
index 7391e4cf3a9aeb..b83e6deac75e3f 100644
--- a/clang/docs/UsersManual.rst
+++ b/clang/docs/UsersManual.rst
@@ -2410,20 +2410,39 @@ usual build cycle when using sample profilers for optimization:
1. Build the code with source line table information. You can use all the
usual build flags that you always build your application with. The only
- requirement is that you add ``-gline-tables-only`` or ``-g`` to the
- command line. This is important for the profiler to be able to map
- instructions back to source line locations.
+ requirement is that DWARF debug info including source line information is
+ generated. This DWARF information is important for the profiler to be able
+ to map instructions back to source line locations.
+
+ On Linux, ``-g`` or just ``-gline-tables-only`` is sufficient:
.. code-block:: console
$ clang++ -O2 -gline-tables-only code.cc -o code
+ While MSVC-style targets default to CodeView debug information, DWARF debug
+ information is required to generate source-level LLVM profiles. Use
+ ``-gdwarf`` to include DWARF debug information:
+
+ .. code-block:: console
+
+ $ clang-cl -O2 -gdwarf -gline-tables-only coff-profile.cpp -fuse-ld=lld -link -debug:dwarf
+
2. Run the executable under a sampling profiler. The specific profiler
you use does not really matter, as long as its output can be converted
- into the format that the LLVM optimizer understands. Currently, there
- exists a conversion tool for the Linux Perf profiler
- (https://perf.wiki.kernel.org/), so these examples assume that you
- are using Linux Perf to profile your code.
+ into the format that the LLVM optimizer understands.
+
+ Two such profilers are the the Linux Perf profiler
+ (https://perf.wiki.kernel.org/) and Intel's Sampling Enabling Product (SEP),
+ available as part of `Intel VTune
+ <https://software.intel.com/content/www/us/en/develop/tools/oneapi/components/vtune-profiler.html>`_.
+ While Perf is Linux-specific, SEP can be used on Linux, Windows, and FreeBSD.
+
+ The LLVM tool ``llvm-profgen`` can convert output of either Perf or SEP. An
+ external project, `AutoFDO <https://github.com/google/autofdo>`_, also
+ provides a ``create_llvm_prof`` tool which supports Linux Perf output.
+
+ When using Perf:
.. code-block:: console
@@ -2434,11 +2453,19 @@ usual build cycle when using sample profilers for optimization:
it provides better call information, which improves the accuracy of
the profile data.
-3. Convert the collected profile data to LLVM's sample profile format.
- This is currently supported via the AutoFDO converter ``create_llvm_prof``.
- It is available at https://github.com/google/autofdo. Once built and
- installed, you can convert the ``perf.data`` file to LLVM using
- the command:
+ When using SEP:
+
+ .. code-block:: console
+
+ $ sep -start -out code.tb7 -ec BR_INST_RETIRED.NEAR_TAKEN:precise=yes:pdir -lbr no_filter:usr -perf-script brstack -app ./code
+
+ This produces a ``code.perf.data.script`` output which can be used with
+ ``llvm-profgen``'s ``--perfscript`` input option.
+
+3. Convert the collected profile data to LLVM's sample profile format. This is
+ currently supported via the `AutoFDO <https://github.com/google/autofdo>`_
+ converter ``create_llvm_prof``. Once built and installed, you can convert
+ the ``perf.data`` file to LLVM using the command:
.. code-block:: console
@@ -2454,7 +2481,14 @@ usual build cycle when using sample profilers for optimization:
.. code-block:: console
- $ llvm-profgen --binary=./code --output=code.prof--perfdata=perf.data
+ $ llvm-profgen --binary=./code --output=code.prof --perfdata=perf.data
+
+ When using SEP the output is in the textual format corresponding to
+ ``llvm-profgen --perfscript``. For example:
+
+ .. code-block:: console
+
+ $ llvm-profgen --binary=./code --output=code.prof --perfscript=perf.data.script
4. Build the code again using the collected profile. This step feeds
diff --git a/llvm/docs/ReleaseNotes.rst b/llvm/docs/ReleaseNotes.rst
index b34a5f31c5eb0a..c2bbc647bc18e6 100644
--- a/llvm/docs/ReleaseNotes.rst
+++ b/llvm/docs/ReleaseNotes.rst
@@ -157,6 +157,11 @@ Changes to the LLVM tools
``--set-symbols-visibility`` options for ELF input to change the
visibility of symbols.
+* llvm-profgen now supports COFF+DWARF binaries. This enables Sample-based PGO
+ on Windows using Intel VTune's SEP. For details on usage, see the `end-user
+ documentation for SPGO
+ <https://clang.llvm.org/docs/UsersManual.html#using-sampling-profilers>`_.
+
Changes to LLDB
---------------------------------
|
|
please resolve the conflicts. |
Resolve a simple conflict in ReleaseNotes.rst by keeping both new notes.
Thanks for the review, @williamweixiao. I've resolved the conflicts in 2312821. |
|
@tcreech-intel Congratulations on having your first Pull Request (PR) merged into the LLVM Project! Your changes will be combined with recent changes from other authors, then tested Please check whether problems have been caused by your change specifically, as How to do this, and the rest of the post-merge process, is covered in detail here. If your change does cause a problem, it may be reverted, or you can revert it yourself. If you don't get any reports, no action is required from you. Your changes are working as expected, well done! |
This change: