maxjhandsome
/
llvm-project
forked from OSchip/llvm-project
1
0
Fork 0
Code Issues Pull Requests Packages Releases Wiki Activity
llvm-project/llvm/docs/CommandGuide/llvm-profdata.rst

199 lines
5.1 KiB
ReStructuredText
Raw Normal View History

docs: update the command guide documentation for llvm-profdata. Differential Revision: http://reviews.llvm.org/D4726 llvm-svn: 214331
2014-07-31 04:30:11 +08:00
llvm-profdata - Profile data tool
=================================
PGO: llvm-profdata: tool for merging profiles Introducing llvm-profdata, a tool for merging profile data generated by PGO instrumentation in clang. - The name indicates a file extension of <name>.profdata. Eventually profile data output by clang should be changed to that extension. - llvm-profdata merges two profiles. However, the name is more general, since it will likely pick up more tasks (such as summarizing a single profile). - llvm-profdata parses the current text-based format, but will be updated once we settle on a binary format. <rdar://problem/15949645> llvm-svn: 201535
2014-02-18 07:22:49 +08:00
SYNOPSIS
--------
docs: update the command guide documentation for llvm-profdata. Differential Revision: http://reviews.llvm.org/D4726 llvm-svn: 214331
2014-07-31 04:30:11 +08:00
:program:`llvm-profdata` *command* [*args...*]
PGO: llvm-profdata: tool for merging profiles Introducing llvm-profdata, a tool for merging profile data generated by PGO instrumentation in clang. - The name indicates a file extension of <name>.profdata. Eventually profile data output by clang should be changed to that extension. - llvm-profdata merges two profiles. However, the name is more general, since it will likely pick up more tasks (such as summarizing a single profile). - llvm-profdata parses the current text-based format, but will be updated once we settle on a binary format. <rdar://problem/15949645> llvm-svn: 201535
2014-02-18 07:22:49 +08:00
DESCRIPTION
-----------
docs: update the command guide documentation for llvm-profdata. Differential Revision: http://reviews.llvm.org/D4726 llvm-svn: 214331
2014-07-31 04:30:11 +08:00
The :program:`llvm-profdata` tool is a small utility for working with profile
data files.
PGO: llvm-profdata: tool for merging profiles Introducing llvm-profdata, a tool for merging profile data generated by PGO instrumentation in clang. - The name indicates a file extension of <name>.profdata. Eventually profile data output by clang should be changed to that extension. - llvm-profdata merges two profiles. However, the name is more general, since it will likely pick up more tasks (such as summarizing a single profile). - llvm-profdata parses the current text-based format, but will be updated once we settle on a binary format. <rdar://problem/15949645> llvm-svn: 201535
2014-02-18 07:22:49 +08:00
docs: update the command guide documentation for llvm-profdata. Differential Revision: http://reviews.llvm.org/D4726 llvm-svn: 214331
2014-07-31 04:30:11 +08:00
COMMANDS
--------
docs: Try to fix a couple of internal links in the llvm-profdata manual These links seem broken on llvm.org/docs. Change them to use the sphinx-recommended style to see if that helps. llvm-svn: 232001
2015-03-12 09:38:50 +08:00
* :ref:`merge <profdata-merge>`
* :ref:`show <profdata-show>`
docs: update the command guide documentation for llvm-profdata. Differential Revision: http://reviews.llvm.org/D4726 llvm-svn: 214331
2014-07-31 04:30:11 +08:00
.. program:: llvm-profdata merge
docs: Try to fix a couple of internal links in the llvm-profdata manual These links seem broken on llvm.org/docs. Change them to use the sphinx-recommended style to see if that helps. llvm-svn: 232001
2015-03-12 09:38:50 +08:00
.. _profdata-merge:
docs: update the command guide documentation for llvm-profdata. Differential Revision: http://reviews.llvm.org/D4726 llvm-svn: 214331
2014-07-31 04:30:11 +08:00
MERGE
-----
SYNOPSIS
^^^^^^^^
[llvm-profdata] Add support for weighted merge of profile data (2nd try) Summary: This change adds support for specifying a weight when merging profile data with the llvm-profdata tool. Weights are specified by using the --weighted-input=<weight>,<filename> option. Input files not specified with this option (normal positional list after options) are given a default weight of 1. Adding support for arbitrary weighting of input profile data allows for relative importance to be placed on the input data from multiple training runs. Both sampled and instrumented profiles are supported. Reviewers: davidxl, dnovillo, bogner, silvas Subscribers: silvas, davidxl, llvm-commits Differential Revision: http://reviews.llvm.org/D15306 llvm-svn: 255659
2015-12-16 01:37:09 +08:00
:program:`llvm-profdata merge` [*options*] [*filename...*]
docs: update the command guide documentation for llvm-profdata. Differential Revision: http://reviews.llvm.org/D4726 llvm-svn: 214331
2014-07-31 04:30:11 +08:00
DESCRIPTION
^^^^^^^^^^^
:program:`llvm-profdata merge` takes several profile data files
generated by PGO instrumentation and merges them together into a single
indexed profile data file.
PGO: llvm-profdata: tool for merging profiles Introducing llvm-profdata, a tool for merging profile data generated by PGO instrumentation in clang. - The name indicates a file extension of <name>.profdata. Eventually profile data output by clang should be changed to that extension. - llvm-profdata merges two profiles. However, the name is more general, since it will likely pick up more tasks (such as summarizing a single profile). - llvm-profdata parses the current text-based format, but will be updated once we settle on a binary format. <rdar://problem/15949645> llvm-svn: 201535
2014-02-18 07:22:49 +08:00
[llvm-profdata] Add support for weighted merge of profile data (2nd try) Summary: This change adds support for specifying a weight when merging profile data with the llvm-profdata tool. Weights are specified by using the --weighted-input=<weight>,<filename> option. Input files not specified with this option (normal positional list after options) are given a default weight of 1. Adding support for arbitrary weighting of input profile data allows for relative importance to be placed on the input data from multiple training runs. Both sampled and instrumented profiles are supported. Reviewers: davidxl, dnovillo, bogner, silvas Subscribers: silvas, davidxl, llvm-commits Differential Revision: http://reviews.llvm.org/D15306 llvm-svn: 255659
2015-12-16 01:37:09 +08:00
By default profile data is merged without modification. This means that the
relative importance of each input file is proportional to the number of samples
or counts it contains. In general, the input from a longer training run will be
interpreted as relatively more important than a shorter run. Depending on the
nature of the training runs it may be useful to adjust the weight given to each
input file by using the ``-weighted-input`` option.
Retry^4 "[llvm-profdata] Add option to ingest filepaths from a file" Changes since the initial commit: - Use echo instead of printf. This should side-step the character escaping issues on Windows. Differential Revision: http://reviews.llvm.org/D20980 llvm-svn: 272068
2016-06-08 06:47:31 +08:00
Profiles passed in via ``-weighted-input``, ``-input-files``, or via positional
arguments are processed once for each time they are seen.
[llvm-profdata] Add support for weighted merge of profile data (2nd try) Summary: This change adds support for specifying a weight when merging profile data with the llvm-profdata tool. Weights are specified by using the --weighted-input=<weight>,<filename> option. Input files not specified with this option (normal positional list after options) are given a default weight of 1. Adding support for arbitrary weighting of input profile data allows for relative importance to be placed on the input data from multiple training runs. Both sampled and instrumented profiles are supported. Reviewers: davidxl, dnovillo, bogner, silvas Subscribers: silvas, davidxl, llvm-commits Differential Revision: http://reviews.llvm.org/D15306 llvm-svn: 255659
2015-12-16 01:37:09 +08:00
PGO: llvm-profdata: tool for merging profiles Introducing llvm-profdata, a tool for merging profile data generated by PGO instrumentation in clang. - The name indicates a file extension of <name>.profdata. Eventually profile data output by clang should be changed to that extension. - llvm-profdata merges two profiles. However, the name is more general, since it will likely pick up more tasks (such as summarizing a single profile). - llvm-profdata parses the current text-based format, but will be updated once we settle on a binary format. <rdar://problem/15949645> llvm-svn: 201535
2014-02-18 07:22:49 +08:00
OPTIONS
docs: update the command guide documentation for llvm-profdata. Differential Revision: http://reviews.llvm.org/D4726 llvm-svn: 214331
2014-07-31 04:30:11 +08:00
^^^^^^^
.. option:: -help
Print a summary of command line options.
.. option:: -output=output, -o=output
Specify the output file name. *Output* cannot be ``-`` as the resulting
indexed profile data can't be written to standard output.
[llvm-profdata] Add support for weighted merge of profile data (2nd try) Summary: This change adds support for specifying a weight when merging profile data with the llvm-profdata tool. Weights are specified by using the --weighted-input=<weight>,<filename> option. Input files not specified with this option (normal positional list after options) are given a default weight of 1. Adding support for arbitrary weighting of input profile data allows for relative importance to be placed on the input data from multiple training runs. Both sampled and instrumented profiles are supported. Reviewers: davidxl, dnovillo, bogner, silvas Subscribers: silvas, davidxl, llvm-commits Differential Revision: http://reviews.llvm.org/D15306 llvm-svn: 255659
2015-12-16 01:37:09 +08:00
.. option:: -weighted-input=weight,filename
[docs] Be a bit more precise. llvm-svn: 271083
2016-05-28 09:03:36 +08:00
Specify an input file name along with a weight. The profile counts of the
supplied ``filename`` will be scaled (multiplied) by the supplied
``weight``, where where ``weight`` is a decimal integer >= 1.
Input files specified without using this option are assigned a default
weight of 1. Examples are shown below.
[llvm-profdata] Add support for weighted merge of profile data (2nd try) Summary: This change adds support for specifying a weight when merging profile data with the llvm-profdata tool. Weights are specified by using the --weighted-input=<weight>,<filename> option. Input files not specified with this option (normal positional list after options) are given a default weight of 1. Adding support for arbitrary weighting of input profile data allows for relative importance to be placed on the input data from multiple training runs. Both sampled and instrumented profiles are supported. Reviewers: davidxl, dnovillo, bogner, silvas Subscribers: silvas, davidxl, llvm-commits Differential Revision: http://reviews.llvm.org/D15306 llvm-svn: 255659
2015-12-16 01:37:09 +08:00
Retry^4 "[llvm-profdata] Add option to ingest filepaths from a file" Changes since the initial commit: - Use echo instead of printf. This should side-step the character escaping issues on Windows. Differential Revision: http://reviews.llvm.org/D20980 llvm-svn: 272068
2016-06-08 06:47:31 +08:00
.. option:: -input-files=path, -f=path
Specify a file which contains a list of files to merge. The entries in this
file are newline-separated. Lines starting with '#' are skipped. Entries may
be of the form <filename> or <weight>,<filename>.
Update documentation for llvm-profdata. These options have been present for a while, but I had never updated the documentation. Fixed. llvm-svn: 238511
2015-05-29 05:57:17 +08:00
.. option:: -instr (default)
Fix sphinx-build error when building documentation. Consolidate the description of -binary/-text option description to avoid duplicate ID error by sphinux-build. llvm-svn: 254018
2015-11-25 04:48:25 +08:00
Specify that the input profile is an instrumentation-based profile.
Update documentation for llvm-profdata. These options have been present for a while, but I had never updated the documentation. Fixed. llvm-svn: 238511
2015-05-29 05:57:17 +08:00
.. option:: -sample
Fix sphinx-build error when building documentation. Consolidate the description of -binary/-text option description to avoid duplicate ID error by sphinux-build. llvm-svn: 254018
2015-11-25 04:48:25 +08:00
Specify that the input profile is a sample-based profile.
The format of the generated file can be generated in one of three ways:
Update documentation for llvm-profdata. These options have been present for a while, but I had never updated the documentation. Fixed. llvm-svn: 238511
2015-05-29 05:57:17 +08:00
.. option:: -binary (default)
Fix sphinx-build error when building documentation. Consolidate the description of -binary/-text option description to avoid duplicate ID error by sphinux-build. llvm-svn: 254018
2015-11-25 04:48:25 +08:00
Emit the profile using a binary encoding. For instrumentation-based profile
the output format is the indexed binary format.
Update documentation for llvm-profdata. These options have been present for a while, but I had never updated the documentation. Fixed. llvm-svn: 238511
2015-05-29 05:57:17 +08:00
.. option:: -text
Fix sphinx-build error when building documentation. Consolidate the description of -binary/-text option description to avoid duplicate ID error by sphinux-build. llvm-svn: 254018
2015-11-25 04:48:25 +08:00
Emit the profile in text mode. This option can also be used with both
sample-based and instrumentation-based profile. When this option is used
the profile will be dumped in the text format that is parsable by the profile
reader.
Update documentation for llvm-profdata. These options have been present for a while, but I had never updated the documentation. Fixed. llvm-svn: 238511
2015-05-29 05:57:17 +08:00
.. option:: -gcc
Emit the profile using GCC's gcov format (Not yet supported).
[Profiling] Add a -sparse mode to llvm-profdata merge Add an option to llvm-profdata merge for writing out sparse indexed profiles. These profiles omit InstrProfRecords for functions which are never executed. Differential Revision: http://reviews.llvm.org/D16727 llvm-svn: 259258
2016-01-30 06:54:45 +08:00
.. option:: -sparse[=true|false]
Do not emit function records with 0 execution count. Can only be used in
conjunction with -instr. Defaults to false, since it can inhibit compiler
optimization during PGO.
[llvm-profdata] Add support for weighted merge of profile data (2nd try) Summary: This change adds support for specifying a weight when merging profile data with the llvm-profdata tool. Weights are specified by using the --weighted-input=<weight>,<filename> option. Input files not specified with this option (normal positional list after options) are given a default weight of 1. Adding support for arbitrary weighting of input profile data allows for relative importance to be placed on the input data from multiple training runs. Both sampled and instrumented profiles are supported. Reviewers: davidxl, dnovillo, bogner, silvas Subscribers: silvas, davidxl, llvm-commits Differential Revision: http://reviews.llvm.org/D15306 llvm-svn: 255659
2015-12-16 01:37:09 +08:00
EXAMPLES
^^^^^^^^
Basic Usage
+++++++++++
Merge three profiles:
::
llvm-profdata merge foo.profdata bar.profdata baz.profdata -output merged.profdata
Weighted Input
++++++++++++++
The input file `foo.profdata` is especially important, multiply its counts by 10:
::
llvm-profdata merge -weighted-input=10,foo.profdata bar.profdata baz.profdata -output merged.profdata
Exactly equivalent to the previous invocation (explicit form; useful for programmatic invocation):
::
llvm-profdata merge -weighted-input=10,foo.profdata -weighted-input=1,bar.profdata -weighted-input=1,baz.profdata -output merged.profdata
docs: update the command guide documentation for llvm-profdata. Differential Revision: http://reviews.llvm.org/D4726 llvm-svn: 214331
2014-07-31 04:30:11 +08:00
.. program:: llvm-profdata show
docs: Try to fix a couple of internal links in the llvm-profdata manual These links seem broken on llvm.org/docs. Change them to use the sphinx-recommended style to see if that helps. llvm-svn: 232001
2015-03-12 09:38:50 +08:00
.. _profdata-show:
docs: update the command guide documentation for llvm-profdata. Differential Revision: http://reviews.llvm.org/D4726 llvm-svn: 214331
2014-07-31 04:30:11 +08:00
SHOW
----
SYNOPSIS
^^^^^^^^
:program:`llvm-profdata show` [*options*] [*filename*]
DESCRIPTION
^^^^^^^^^^^
:program:`llvm-profdata show` takes a profile data file and displays the
information about the profile counters for this file and
for any of the specified function(s).
If *filename* is omitted or is ``-``, then **llvm-profdata show** reads its
input from standard input.
OPTIONS
^^^^^^^
.. option:: -all-functions
Print details for every function.
.. option:: -counts
Print the counter values for the displayed functions.
.. option:: -function=string
Print details for a function if the function's name contains the given string.
.. option:: -help
Print a summary of command line options.
PGO: llvm-profdata: tool for merging profiles Introducing llvm-profdata, a tool for merging profile data generated by PGO instrumentation in clang. - The name indicates a file extension of <name>.profdata. Eventually profile data output by clang should be changed to that extension. - llvm-profdata merges two profiles. However, the name is more general, since it will likely pick up more tasks (such as summarizing a single profile). - llvm-profdata parses the current text-based format, but will be updated once we settle on a binary format. <rdar://problem/15949645> llvm-svn: 201535
2014-02-18 07:22:49 +08:00
docs: update the command guide documentation for llvm-profdata. Differential Revision: http://reviews.llvm.org/D4726 llvm-svn: 214331
2014-07-31 04:30:11 +08:00
.. option:: -output=output, -o=output
PGO: llvm-profdata: tool for merging profiles Introducing llvm-profdata, a tool for merging profile data generated by PGO instrumentation in clang. - The name indicates a file extension of <name>.profdata. Eventually profile data output by clang should be changed to that extension. - llvm-profdata merges two profiles. However, the name is more general, since it will likely pick up more tasks (such as summarizing a single profile). - llvm-profdata parses the current text-based format, but will be updated once we settle on a binary format. <rdar://problem/15949645> llvm-svn: 201535
2014-02-18 07:22:49 +08:00
docs: update the command guide documentation for llvm-profdata. Differential Revision: http://reviews.llvm.org/D4726 llvm-svn: 214331
2014-07-31 04:30:11 +08:00
Specify the output file name. If *output* is ``-`` or it isn't specified,
then the output is sent to standard output.
PGO: llvm-profdata: tool for merging profiles Introducing llvm-profdata, a tool for merging profile data generated by PGO instrumentation in clang. - The name indicates a file extension of <name>.profdata. Eventually profile data output by clang should be changed to that extension. - llvm-profdata merges two profiles. However, the name is more general, since it will likely pick up more tasks (such as summarizing a single profile). - llvm-profdata parses the current text-based format, but will be updated once we settle on a binary format. <rdar://problem/15949645> llvm-svn: 201535
2014-02-18 07:22:49 +08:00
Update documentation for llvm-profdata. These options have been present for a while, but I had never updated the documentation. Fixed. llvm-svn: 238511
2015-05-29 05:57:17 +08:00
.. option:: -instr (default)
Specify that the input profile is an instrumentation-based profile.
[PGO] Add --text option for llvm-profdata show|merge commands The new option is similar to the SampleProfile dump option. - dump raw/indexed format into text profile format - merge the profile and output into text profile format. Note that Value Profiling data text format is not yet designed. That functionality will be added later. Differential Revision: http://reviews.llvm.org/D14894 llvm-svn: 253913
2015-11-24 04:47:38 +08:00
.. option:: -text
Instruct the profile dumper to show profile counts in the text format of the
instrumentation-based profile data representation. By default, the profile
information is dumped in a more human readable form (also in text) with
annotations.
Update documentation for llvm-profdata. These options have been present for a while, but I had never updated the documentation. Fixed. llvm-svn: 238511
2015-05-29 05:57:17 +08:00
.. option:: -sample
Specify that the input profile is a sample-based profile.
PGO: llvm-profdata: tool for merging profiles Introducing llvm-profdata, a tool for merging profile data generated by PGO instrumentation in clang. - The name indicates a file extension of <name>.profdata. Eventually profile data output by clang should be changed to that extension. - llvm-profdata merges two profiles. However, the name is more general, since it will likely pick up more tasks (such as summarizing a single profile). - llvm-profdata parses the current text-based format, but will be updated once we settle on a binary format. <rdar://problem/15949645> llvm-svn: 201535
2014-02-18 07:22:49 +08:00
EXIT STATUS
-----------
docs: update the command guide documentation for llvm-profdata. Differential Revision: http://reviews.llvm.org/D4726 llvm-svn: 214331
2014-07-31 04:30:11 +08:00
:program:`llvm-profdata` returns 1 if the command is omitted or is invalid,
if it cannot read input files, or if there is a mismatch between their data.