<div dir="ltr">I forgot to rebase my original patch after Richard approved the final form. Apologies for the additional commits this generated.<div><br></div><div><br></div><div>Diego.</div></div><div class="gmail_extra"><br>
<br><div class="gmail_quote">On Wed, Apr 23, 2014 at 11:21 AM, Diego Novillo <span dir="ltr"><<a href="mailto:dnovillo@google.com" target="_blank">dnovillo@google.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
Author: dnovillo<br>
Date: Wed Apr 23 10:21:07 2014<br>
New Revision: 206994<br>
<br>
URL: <a href="http://llvm.org/viewvc/llvm-project?rev=206994&view=rev" target="_blank">http://llvm.org/viewvc/llvm-project?rev=206994&view=rev</a><br>
Log:<br>
Add documentation for sample profiling support.<br>
<br>
Summary:<br>
This documents the usage of sample profilers with Clang and the<br>
profile format expected by LLVM's optimizers. It also documents the<br>
profile conversion tool used by Linux Perf.<br>
<br>
Reviewers: doug.gregor<br>
<br>
CC: cfe-commits<br>
<br>
Differential Revision: <a href="http://reviews.llvm.org/D3402" target="_blank">http://reviews.llvm.org/D3402</a><br>
<br>
Modified:<br>
cfe/trunk/docs/UsersManual.rst<br>
<br>
Modified: cfe/trunk/docs/UsersManual.rst<br>
URL: <a href="http://llvm.org/viewvc/llvm-project/cfe/trunk/docs/UsersManual.rst?rev=206994&r1=206993&r2=206994&view=diff" target="_blank">http://llvm.org/viewvc/llvm-project/cfe/trunk/docs/UsersManual.rst?rev=206994&r1=206993&r2=206994&view=diff</a><br>
==============================================================================<br>
--- cfe/trunk/docs/UsersManual.rst (original)<br>
+++ cfe/trunk/docs/UsersManual.rst Wed Apr 23 10:21:07 2014<br>
@@ -1065,6 +1065,135 @@ are listed below.<br>
only. This only applies to the AArch64 architecture.<br>
<br>
<br>
+Using Sampling Profilers for Optimization<br>
+-----------------------------------------<br>
+<br>
+Sampling profilers are used to collect runtime information, such as<br>
+hardware counters, while your application executes. They are typically<br>
+very efficient and do not incur in a large runtime overhead. The<br>
+sample data collected by the profiler can be used during compilation<br>
+to determine what are the most executed areas of the code.<br>
+<br>
+In particular, sample profilers can provide execution counts for all<br>
+instructions in the code, information on branches taken and function<br>
+invocation. The compiler can use this information in its optimization<br>
+cost models. For example, knowing that a branch is taken very<br>
+frequently helps the compiler make better decisions when ordering<br>
+basic blocks. Knowing that a function ``foo`` is called more<br>
+frequently than another ``bar`` helps the inliner.<br>
+<br>
+Using the data from a sample profiler requires some changes in the way<br>
+a program is built. Before the compiler can use profiling information,<br>
+the code needs to execute under the profiler. The following is the<br>
+usual build cycle when using sample profilers for optimization:<br>
+<br>
+1. Build the code with source line table information. You can use all the<br>
+ usual build flags that you always build your application with. The only<br>
+ requirement is that you add ``-gline-tables-ony`` or ``-g`` to the<br>
+ command line. This is important for the profiler to be able to map<br>
+ instructions back to source line locations.<br>
+<br>
+ .. code-block:: console<br>
+<br>
+ $ clang++ -O2 -gline-tables-only code.cc -o code<br>
+<br>
+2. Run the executable under a sampling profiler. The specific profiler<br>
+ you use does not really matter, as long as its output can be converted<br>
+ into the format that the LLVM optimizer understands. Currently, there<br>
+ exists a conversion tool for the Linux Perf profiler<br>
+ (<a href="https://perf.wiki.kernel.org/" target="_blank">https://perf.wiki.kernel.org/</a>), so these examples assume that you<br>
+ are using Linux Perf to profile your code.<br>
+<br>
+ .. code-block:: console<br>
+<br>
+ $ perf record -b ./code<br>
+<br>
+ Note the use of the ``-b`` flag. This tells Perf to use the Last Branch<br>
+ Record (LBR) to record call chains. While this is not strictly required,<br>
+ it provides better call information, which improves the accuracy of<br>
+ the profile data.<br>
+<br>
+3. Convert the collected profile data to LLVM's sample profile format.<br>
+ This is currently supported via the AutoFDO converter ``create_llvm_prof``.<br>
+ It is available at <a href="http://github.com/google/autofdo" target="_blank">http://github.com/google/autofdo</a>. Once built and<br>
+ installed, you can convert the ``perf.data`` file to LLVM using<br>
+ the command:<br>
+<br>
+ .. code-block:: console<br>
+<br>
+ $ create_llvm_prof --binary=./code --out=code.prof<br>
+<br>
+ This will read ``perf.data``, the binary file ``./code`` and emit<br>
+ the profile data in ``code.prof``. Note that if you ran ``perf``<br>
+ without the ``-b`` flag, you need to use ``--use_lbr=false`` when<br>
+ calling ``create_llvm_prof``.<br>
+<br>
+4. Build the code again using the collected profile. This step feeds<br>
+ the profile back to the optimizers. This should result in a binary<br>
+ that executes faster than the original one.<br>
+<br>
+ .. code-block:: console<br>
+<br>
+ $ clang++ -O2 -gline-tables-only -fprofile-sample-use=code.prof code.cc -o code<br>
+<br>
+<br>
+Sample Profile Format<br>
+^^^^^^^^^^^^^^^^^^^^^<br>
+<br>
+If you are not using Linux Perf to collect profiles, you will need to<br>
+write a conversion tool from your profiler to LLVM's format. This section<br>
+explains the file format expected by the backend.<br>
+<br>
+Sample profiles are written as ASCII text. The file is divided into sections,<br>
+which correspond to each of the functions executed at runtime. Each<br>
+section has the following format (taken from<br>
+<a href="https://github.com/google/autofdo/blob/master/profile_writer.h" target="_blank">https://github.com/google/autofdo/blob/master/profile_writer.h</a>):<br>
+<br>
+.. code-block:: console<br>
+<br>
+ function1:total_samples:total_head_samples<br>
+ offset1[.discriminator]: number_of_samples [fn1:num fn2:num ... ]<br>
+ offset2[.discriminator]: number_of_samples [fn3:num fn4:num ... ]<br>
+ ...<br>
+ offsetN[.discriminator]: number_of_samples [fn5:num fn6:num ... ]<br>
+<br>
+Function names must be mangled in order for the profile loader to<br>
+match them in the current translation unit. The two numbers in the<br>
+function header specify how many total samples were accumulated in the<br>
+function (first number), and the total number of samples accumulated<br>
+at the prologue of the function (second number). This head sample<br>
+count provides an indicator of how frequent is the function invoked.<br>
+<br>
+Each sampled line may contain several items. Some are optional (marked<br>
+below):<br>
+<br>
+a. Source line offset. This number represents the line number<br>
+ in the function where the sample was collected. The line number is<br>
+ always relative to the line where symbol of the function is<br>
+ defined. So, if the function has its header at line 280, the offset<br>
+ 13 is at line 293 in the file.<br>
+<br>
+b. [OPTIONAL] Discriminator. This is used if the sampled program<br>
+ was compiled with DWARF discriminator support<br>
+ (<a href="http://wiki.dwarfstd.org/index.php?title=Path_Discriminators" target="_blank">http://wiki.dwarfstd.org/index.php?title=Path_Discriminators</a>)<br>
+<br>
+c. Number of samples. This is the number of samples collected by<br>
+ the profiler at this source location.<br>
+<br>
+d. [OPTIONAL] Potential call targets and samples. If present, this<br>
+ line contains a call instruction. This models both direct and<br>
+ indirect calls. Each called target is listed together with the<br>
+ number of samples. For example,<br>
+<br>
+ .. code-block:: console<br>
+<br>
+ 130: 7 foo:3 bar:2 baz:7<br>
+<br>
+ The above means that at relative line offset 130 there is a call<br>
+ instruction that calls one of ``foo()``, ``bar()`` and ``baz()``.<br>
+ With ``baz()`` being the relatively more frequent call target.<br>
+<br>
+<br>
Controlling Size of Debug Information<br>
-------------------------------------<br>
<br>
<br>
<br>
_______________________________________________<br>
cfe-commits mailing list<br>
<a href="mailto:cfe-commits@cs.uiuc.edu">cfe-commits@cs.uiuc.edu</a><br>
<a href="http://lists.cs.uiuc.edu/mailman/listinfo/cfe-commits" target="_blank">http://lists.cs.uiuc.edu/mailman/listinfo/cfe-commits</a><br>
</blockquote></div><br></div>