r238504 - Improve user documentation on profiling.

[Diego Novillo]

Author: dnovillo
Date: Thu May 28 16:30:04 2015
New Revision: 238504

URL: http://llvm.org/viewvc/llvm-project?rev=238504&view=rev
Log:
Improve user documentation on profiling.

This clarifies the relationship between instrumentation and sampling based PGO,
code coverage analysis and the different formats supported by sample
profiling.

Modified:
    cfe/trunk/docs/UsersManual.rst

Modified: cfe/trunk/docs/UsersManual.rst
URL: http://llvm.org/viewvc/llvm-project/cfe/trunk/docs/UsersManual.rst?rev=238504&r1=238503&r2=238504&view=diff
==============================================================================
--- cfe/trunk/docs/UsersManual.rst (original)
+++ cfe/trunk/docs/UsersManual.rst Thu May 28 16:30:04 2015
@@ -1216,6 +1216,32 @@ behavior. Code that is not exercised in
 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
+   converted and used with ``-fprofile-sample-use``.
+
+2. Instrumentation profile data can be used for code coverage analysis and
+   optimization.
+
+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
+   by LLVM. The section on sampling profilers describes one of the supported
+   sampling profile formats.
+
+
 Using Sampling Profilers
 ^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -1283,21 +1309,38 @@ usual build cycle when using sample prof
      $ clang++ -O2 -gline-tables-only -fprofile-sample-use=code.prof code.cc -o code
 
 
-Sample Profile Format
-"""""""""""""""""""""
+Sample Profile Formats
+""""""""""""""""""""""
 
-If you are not using Linux Perf to collect profiles, you will need to
-write a conversion tool from your profiler to LLVM's format. This section
-explains the file format expected by the backend.
-
-NOTE: This format is not intended to be used for code coverage. For that,
-you need to use Clang's instrumentation based profiling
-(``-fprofile-instr-generate``).
-
-Sample profiles are written as ASCII text. The file is divided into sections,
-which correspond to each of the functions executed at runtime. Each
-section has the following format (taken from
-https://github.com/google/autofdo/blob/master/profile_writer.h):
+Since external profilers generate profile data in a variety of custom formats,
+the data generated by the profiler must be converted into a format that can be
+read by the backend. LLVM supports three different sample profile formats:
+
+1. ASCII text. This is the easiest one to generate. The file is divided into
+   sections, which correspond to each of the functions with profile
+   information. The format is described below.
+
+2. Binary encoding. This uses a more efficient encoding that yields smaller
+   profile files, which may be useful when generating large profiles. It can be
+   generated from the text format using the ``llvm-profdata`` tool.
+
+3. GCC encoding. This is based on the gcov format, which is accepted by GCC. It
+   is only interesting in environments where GCC and Clang co-exist. Similarly
+   to the binary encoding, it can be generated using the ``llvm-profdata`` tool.
+
+If you are using Linux Perf to generate sampling profiles, you can use the
+conversion tool ``create_llvm_prof`` described in the previous section.
+Otherwise, you will need to write a conversion tool that converts your
+profiler's native format into one of these three.
+
+
+Sample Profile Text Format
+""""""""""""""""""""""""""
+
+This section describes the ASCII text format for sampling profiles. It is,
+arguably, the easiest one to generate. If you are interested in generating any
+of the other two, consult the ``ProfileData`` library in in LLVM's source tree
+(specifically, ``llvm/lib/ProfileData/SampleProfWriter.cpp``).
 
 .. code-block:: console
 
@@ -1404,8 +1447,8 @@ instrumentation:
      $ LLVM_PROFILE_FILE="code-%p.profraw" ./code
 
 3. Combine profiles from multiple runs and convert the "raw" profile format to
-   the input expected by clang. Use the ``merge`` command of the llvm-profdata
-   tool to do this.
+   the input expected by clang. Use the ``merge`` command of the
+   ``llvm-profdata`` tool to do this.
 
    .. code-block:: console