1llvm-profdata - Profile data tool
2=================================
3
4SYNOPSIS
5--------
6
7:program:`llvm-profdata` *command* [*args...*]
8
9DESCRIPTION
10-----------
11
12The :program:`llvm-profdata` tool is a small utility for working with profile
13data files.
14
15COMMANDS
16--------
17
18* :ref:`merge <profdata-merge>`
19* :ref:`show <profdata-show>`
20
21.. program:: llvm-profdata merge
22
23.. _profdata-merge:
24
25MERGE
26-----
27
28SYNOPSIS
29^^^^^^^^
30
31:program:`llvm-profdata merge` [*options*] [*filename...*]
32
33DESCRIPTION
34^^^^^^^^^^^
35
36:program:`llvm-profdata merge` takes several profile data files
37generated by PGO instrumentation and merges them together into a single
38indexed profile data file.
39
40By default profile data is merged without modification. This means that the
41relative importance of each input file is proportional to the number of samples
42or counts it contains. In general, the input from a longer training run will be
43interpreted as relatively more important than a shorter run. Depending on the
44nature of the training runs it may be useful to adjust the weight given to each
45input file by using the ``-weighted-input`` option.
46
47
48OPTIONS
49^^^^^^^
50
51.. option:: -help
52
53 Print a summary of command line options.
54
55.. option:: -output=output, -o=output
56
57 Specify the output file name.  *Output* cannot be ``-`` as the resulting
58 indexed profile data can't be written to standard output.
59
60.. option:: -weighted-input=weight,filename
61
62 Specify an input file name along with a weight. The profile counts of the input
63 file will be scaled (multiplied) by the supplied ``weight``, where where ``weight``
64 is a decimal integer >= 1. Input files specified without using this option are
65 assigned a default weight of 1. Examples are shown below.
66
67.. option:: -instr (default)
68
69 Specify that the input profile is an instrumentation-based profile.
70
71.. option:: -sample
72
73 Specify that the input profile is a sample-based profile.
74
75 The format of the generated file can be generated in one of three ways:
76
77 .. option:: -binary (default)
78
79 Emit the profile using a binary encoding. For instrumentation-based profile
80 the output format is the indexed binary format.
81
82 .. option:: -text
83
84 Emit the profile in text mode. This option can also be used with both
85 sample-based and instrumentation-based profile. When this option is used
86 the profile will be dumped in the text format that is parsable by the profile
87 reader.
88
89 .. option:: -gcc
90
91 Emit the profile using GCC's gcov format (Not yet supported).
92
93 .. option:: -sparse[=true|false]
94
95 Do not emit function records with 0 execution count. Can only be used in
96 conjunction with -instr. Defaults to false, since it can inhibit compiler
97 optimization during PGO.
98
99EXAMPLES
100^^^^^^^^
101Basic Usage
102+++++++++++
103Merge three profiles:
104
105::
106
107    llvm-profdata merge foo.profdata bar.profdata baz.profdata -output merged.profdata
108
109Weighted Input
110++++++++++++++
111The input file `foo.profdata` is especially important, multiply its counts by 10:
112
113::
114
115    llvm-profdata merge -weighted-input=10,foo.profdata bar.profdata baz.profdata -output merged.profdata
116
117Exactly equivalent to the previous invocation (explicit form; useful for programmatic invocation):
118
119::
120
121    llvm-profdata merge -weighted-input=10,foo.profdata -weighted-input=1,bar.profdata -weighted-input=1,baz.profdata -output merged.profdata
122
123.. program:: llvm-profdata show
124
125.. _profdata-show:
126
127SHOW
128----
129
130SYNOPSIS
131^^^^^^^^
132
133:program:`llvm-profdata show` [*options*] [*filename*]
134
135DESCRIPTION
136^^^^^^^^^^^
137
138:program:`llvm-profdata show` takes a profile data file and displays the
139information about the profile counters for this file and
140for any of the specified function(s).
141
142If *filename* is omitted or is ``-``, then **llvm-profdata show** reads its
143input from standard input.
144
145OPTIONS
146^^^^^^^
147
148.. option:: -all-functions
149
150 Print details for every function.
151
152.. option:: -counts
153
154 Print the counter values for the displayed functions.
155
156.. option:: -function=string
157
158 Print details for a function if the function's name contains the given string.
159
160.. option:: -help
161
162 Print a summary of command line options.
163
164.. option:: -output=output, -o=output
165
166 Specify the output file name.  If *output* is ``-`` or it isn't specified,
167 then the output is sent to standard output.
168
169.. option:: -instr (default)
170
171 Specify that the input profile is an instrumentation-based profile.
172
173.. option:: -text
174
175 Instruct the profile dumper to show profile counts in the text format of the
176 instrumentation-based profile data representation. By default, the profile
177 information is dumped in a more human readable form (also in text) with
178 annotations.
179
180.. option:: -sample
181
182 Specify that the input profile is a sample-based profile.
183
184EXIT STATUS
185-----------
186
187:program:`llvm-profdata` returns 1 if the command is omitted or is invalid,
188if it cannot read input files, or if there is a mismatch between their data.
189