maxjhandsome
/
llvm-project
forked from OSchip/llvm-project
1
0
Fork 0
Code Issues Pull Requests Packages Releases Wiki Activity

[Profile] Document new profile file name modifiers 

Differential Revision: http://reviews.llvm.org/D22593

llvm-svn: 276207
This commit is contained in:
Xinliang David Li 2016-07-20 23:32:50 +00:00
parent f84bb6fa67
commit 7cd5e38d75
1 changed files with 34 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

36
clang/docs/UsersManual.rst
View File

@ -1470,8 +1470,13 @@ instrumentation:
2. Run the instrumented executable with inputs that reflect the typical usage.
By default, the profile data will be written to a ``default.profraw`` file
in the current directory. You can override that default by setting the
``LLVM_PROFILE_FILE`` environment variable to specify an alternate file.
in the current directory. You can override that default by using option
``-fprofile-instr-generate=`` or by setting the ``LLVM_PROFILE_FILE``
environment variable to specify an alternate file. If non-default file name
is specified by both the environment variable and the command line option,
the environment variable takes precedence. The file name pattern specified
can include different modifiers: ``%p``, ``%h``, and ``%m``.
Any instance of ``%p`` in that file name will be replaced by the process
ID, so that you can easily distinguish the profile output from multiple
runs.
@ -1480,6 +1485,33 @@ instrumentation:
$ LLVM_PROFILE_FILE="code-%p.profraw" ./code
The modifier ``%h`` can be used in scenarios where the same instrumented
binary is run in multiple different host machines dumping profile data
to a shared network based storage. The ``%h`` specifier will be substituted
with the hostname so that profiles collected from different hosts do not
clobber each other.
While the use of ``%p`` specifier can reduce the likelihood for the profiles
dumped from different processes to clobber each other, such clobbering can still
happen because of the ``pid`` re-use by the OS. Another side-effect of using
``%p`` is that the storage requirement for raw profile data files is greatly
increased. To avoid issues like this, the ``%m`` specifier can used in the profile
name. When this specifier is used, the profiler runtime will substitute ``%m``
with a unique integer identifier associated with the instrumented binary. Additionally,
multiple raw profiles dumped from different processes that share a file system (can be
on different hosts) will be automatically merged by the profiler runtime during the
dumping. If the program links in multiple instrumented shared libraries, each library
will dump the profile data into its own profile data file (with its unique integer
id embedded in the profile name). Note that the merging enabled by ``%m`` is for raw
profile data generated by profiler runtime. The resulting merged "raw" profile data
file still needs to be converted to a different format expected by the compiler (
see step 3 below).
.. code-block:: console
$ LLVM_PROFILE_FILE="code-%m.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.