From 7cd5e38d758bcbcaf12721e87beb1db62fa8d926 Mon Sep 17 00:00:00 2001 From: Xinliang David Li Date: Wed, 20 Jul 2016 23:32:50 +0000 Subject: [PATCH] [Profile] Document new profile file name modifiers Differential Revision: http://reviews.llvm.org/D22593 llvm-svn: 276207 --- clang/docs/UsersManual.rst | 36 ++++++++++++++++++++++++++++++++++-- 1 file changed, 34 insertions(+), 2 deletions(-) diff --git a/clang/docs/UsersManual.rst b/clang/docs/UsersManual.rst index 8e591518d54d..77d77cc11fa3 100644 --- a/clang/docs/UsersManual.rst +++ b/clang/docs/UsersManual.rst @@ -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.