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* :ref:`overlap <profdata-overlap>`
21
22.. program:: llvm-profdata merge
23
24.. _profdata-merge:
25
26MERGE
27-----
28
29SYNOPSIS
30^^^^^^^^
31
32:program:`llvm-profdata merge` [*options*] [*filename...*]
33
34DESCRIPTION
35^^^^^^^^^^^
36
37:program:`llvm-profdata merge` takes several profile data files
38generated by PGO instrumentation and merges them together into a single
39indexed profile data file.
40
41By default profile data is merged without modification. This means that the
42relative importance of each input file is proportional to the number of samples
43or counts it contains. In general, the input from a longer training run will be
44interpreted as relatively more important than a shorter run. Depending on the
45nature of the training runs it may be useful to adjust the weight given to each
46input file by using the ``-weighted-input`` option.
47
48Profiles passed in via ``-weighted-input``, ``-input-files``, or via positional
49arguments are processed once for each time they are seen.
50
51
52OPTIONS
53^^^^^^^
54
55.. option:: -help
56
57 Print a summary of command line options.
58
59.. option:: -output=output, -o=output
60
61 Specify the output file name.  *Output* cannot be ``-`` as the resulting
62 indexed profile data can't be written to standard output.
63
64.. option:: -weighted-input=weight,filename
65
66 Specify an input file name along with a weight. The profile counts of the
67 supplied ``filename`` will be scaled (multiplied) by the supplied
68 ``weight``, where where ``weight`` is a decimal integer >= 1.
69 Input files specified without using this option are assigned a default
70 weight of 1. Examples are shown below.
71
72.. option:: -input-files=path, -f=path
73
74  Specify a file which contains a list of files to merge. The entries in this
75  file are newline-separated. Lines starting with '#' are skipped. Entries may
76  be of the form <filename> or <weight>,<filename>.
77
78.. option:: -remapping-file=path, -r=path
79
80  Specify a file which contains a remapping from symbol names in the input
81  profile to the symbol names that should be used in the output profile. The
82  file should consist of lines of the form ``<input-symbol> <output-symbol>``.
83  Blank lines and lines starting with ``#`` are skipped.
84
85  The :doc:`llvm-cxxmap <llvm-cxxmap>` tool can be used to generate the symbol
86  remapping file.
87
88.. option:: -instr (default)
89
90 Specify that the input profile is an instrumentation-based profile.
91
92.. option:: -sample
93
94 Specify that the input profile is a sample-based profile.
95
96 The format of the generated file can be generated in one of three ways:
97
98 .. option:: -binary (default)
99
100 Emit the profile using a binary encoding. For instrumentation-based profile
101 the output format is the indexed binary format.
102
103 .. option:: -text
104
105 Emit the profile in text mode. This option can also be used with both
106 sample-based and instrumentation-based profile. When this option is used
107 the profile will be dumped in the text format that is parsable by the profile
108 reader.
109
110 .. option:: -gcc
111
112 Emit the profile using GCC's gcov format (Not yet supported).
113
114.. option:: -sparse[=true|false]
115
116 Do not emit function records with 0 execution count. Can only be used in
117 conjunction with -instr. Defaults to false, since it can inhibit compiler
118 optimization during PGO.
119
120.. option:: -num-threads=N, -j=N
121
122 Use N threads to perform profile merging. When N=0, llvm-profdata auto-detects
123 an appropriate number of threads to use. This is the default.
124
125EXAMPLES
126^^^^^^^^
127Basic Usage
128+++++++++++
129Merge three profiles:
130
131::
132
133    llvm-profdata merge foo.profdata bar.profdata baz.profdata -output merged.profdata
134
135Weighted Input
136++++++++++++++
137The input file `foo.profdata` is especially important, multiply its counts by 10:
138
139::
140
141    llvm-profdata merge -weighted-input=10,foo.profdata bar.profdata baz.profdata -output merged.profdata
142
143Exactly equivalent to the previous invocation (explicit form; useful for programmatic invocation):
144
145::
146
147    llvm-profdata merge -weighted-input=10,foo.profdata -weighted-input=1,bar.profdata -weighted-input=1,baz.profdata -output merged.profdata
148
149.. program:: llvm-profdata show
150
151.. _profdata-show:
152
153SHOW
154----
155
156SYNOPSIS
157^^^^^^^^
158
159:program:`llvm-profdata show` [*options*] [*filename*]
160
161DESCRIPTION
162^^^^^^^^^^^
163
164:program:`llvm-profdata show` takes a profile data file and displays the
165information about the profile counters for this file and
166for any of the specified function(s).
167
168If *filename* is omitted or is ``-``, then **llvm-profdata show** reads its
169input from standard input.
170
171OPTIONS
172^^^^^^^
173
174.. option:: -all-functions
175
176 Print details for every function.
177
178.. option:: -counts
179
180 Print the counter values for the displayed functions.
181
182.. option:: -function=string
183
184 Print details for a function if the function's name contains the given string.
185
186.. option:: -help
187
188 Print a summary of command line options.
189
190.. option:: -output=output, -o=output
191
192 Specify the output file name.  If *output* is ``-`` or it isn't specified,
193 then the output is sent to standard output.
194
195.. option:: -instr (default)
196
197 Specify that the input profile is an instrumentation-based profile.
198
199.. option:: -text
200
201 Instruct the profile dumper to show profile counts in the text format of the
202 instrumentation-based profile data representation. By default, the profile
203 information is dumped in a more human readable form (also in text) with
204 annotations.
205
206.. option:: -topn=n
207
208 Instruct the profile dumper to show the top ``n`` functions with the
209 hottest basic blocks in the summary section. By default, the topn functions
210 are not dumped.
211
212.. option:: -sample
213
214 Specify that the input profile is a sample-based profile.
215
216.. option:: -memop-sizes
217
218 Show the profiled sizes of the memory intrinsic calls for shown functions.
219
220.. option:: -value-cutoff=n
221
222 Show only those functions whose max count values are greater or equal to ``n``.
223 By default, the value-cutoff is set to 0.
224
225.. option:: -list-below-cutoff
226
227 Only output names of functions whose max count value are below the cutoff
228 value.
229
230.. option:: -showcs
231
232 Only show context sensitive profile counts. The default is to filter all
233 context sensitive profile counts.
234
235.. program:: llvm-profdata overlap
236
237.. _profdata-overlap:
238
239OVERLAP
240-------
241
242SYNOPSIS
243^^^^^^^^
244
245:program:`llvm-profdata overlap` [*options*] [*base profile file*] [*test profile file*]
246
247DESCRIPTION
248^^^^^^^^^^^
249
250:program:`llvm-profdata overlap` takes two profile data files and displays the
251*overlap* of counter distribution between the whole files and between any of the
252specified functions.
253
254In this command, *overlap* is defined as follows:
255Suppose *base profile file* has the following counts:
256{c1_1, c1_2, ..., c1_n, c1_u_1, c2_u_2, ..., c2_u_s},
257and *test profile file* has
258{c2_1, c2_2, ..., c2_n, c2_v_1, c2_v_2, ..., c2_v_t}.
259Here c{1|2}_i (i = 1 .. n) are matched counters and c1_u_i (i = 1 .. s) and
260c2_v_i (i = 1 .. v) are unmatched counters (or counters only existing in)
261*base profile file* and *test profile file*, respectively.
262Let sum_1 = c1_1 + c1_2 +  ... + c1_n +  c1_u_1 + c2_u_2 + ... + c2_u_s, and
263sum_2 = c2_1 + c2_2 + ... + c2_n + c2_v_1 + c2_v_2 + ... + c2_v_t.
264*overlap* = min(c1_1/sum_1, c2_1/sum_2) + min(c1_2/sum_1, c2_2/sum_2) + ...
265+ min(c1_n/sum_1, c2_n/sum_2).
266
267The result overlap distribution is a percentage number, ranging from 0.0% to
268100.0%, where 0.0% means there is no overlap and 100.0% means a perfect
269overlap.
270
271Here is an example, if *base profile file* has counts of {400, 600}, and
272*test profile file* has matched counts of {60000, 40000}. The *overlap* is 80%.
273
274
275OPTIONS
276^^^^^^^
277
278.. option:: -function=string
279
280 Print details for a function if the function's name contains the given string.
281
282.. option:: -help
283
284 Print a summary of command line options.
285
286.. option:: -o=output or -o output
287
288 Specify the output file name.  If *output* is ``-`` or it isn't specified,
289 then the output is sent to standard output.
290
291.. option:: -value-cutoff=n
292
293 Show only those functions whose max count values are greater or equal to ``n``.
294 By default, the value-cutoff is set to max of unsigned long long.
295
296.. option:: -cs
297
298 Only show overlap for the context sensitive profile counts. The default is to show
299 non-context sensitive profile counts.
300
301EXIT STATUS
302-----------
303
304:program:`llvm-profdata` returns 1 if the command is omitted or is invalid,
305if it cannot read input files, or if there is a mismatch between their data.
306