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.

llvm-svn: 238504

clang/docs/UsersManual.rst

@@ -1216,6 +1216,32 @@ behavior. Code that is not exercised in the profile will be optimized as if it
 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 profilers for optimization:
      $ clang++ -O2 -gline-tables-only -fprofile-sample-use=code.prof code.cc -o code
 
 
-Sample Profile Format
-"""""""""""""""""""""
+Sample Profile Formats
+""""""""""""""""""""""
+
+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.
 
-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 Profile Text Format
+""""""""""""""""""""""""""
 
-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):
+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