1
.\" Man page generated from reStructuredText.
3
.TH "LLVM-PROFDATA" "1" "2021-09-18" "13" "LLVM"
5
llvm-profdata \- Profile data tool
7
.nr rst2man-indent-level 0
11
level \\n[rst2man-indent-level]
12
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
19
.\" .rstReportMargin pre:
21
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
22
. nr rst2man-indent-level +1
23
.\" .rstReportMargin post:
27
.\" indent \\n[an-margin]
28
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
29
.nr rst2man-indent-level -1
30
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
31
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
35
\fBllvm\-profdata\fP \fIcommand\fP [\fIargs…\fP]
38
The \fBllvm\-profdata\fP tool is a small utility for working with profile
52
\fBllvm\-profdata merge\fP [\fIoptions\fP] [\fIfilename…\fP]
55
\fBllvm\-profdata merge\fP takes several profile data files
56
generated by PGO instrumentation and merges them together into a single
57
indexed profile data file.
59
By default profile data is merged without modification. This means that the
60
relative importance of each input file is proportional to the number of samples
61
or counts it contains. In general, the input from a longer training run will be
62
interpreted as relatively more important than a shorter run. Depending on the
63
nature of the training runs it may be useful to adjust the weight given to each
64
input file by using the \fB\-weighted\-input\fP option.
66
Profiles passed in via \fB\-weighted\-input\fP, \fB\-input\-files\fP, or via positional
67
arguments are processed once for each time they are seen.
72
Print a summary of command line options.
76
.B \-output=output, \-o=output
77
Specify the output file name. \fIOutput\fP cannot be \fB\-\fP as the resulting
78
indexed profile data can’t be written to standard output.
82
.B \-weighted\-input=weight,filename
83
Specify an input file name along with a weight. The profile counts of the
84
supplied \fBfilename\fP will be scaled (multiplied) by the supplied
85
\fBweight\fP, where \fBweight\fP is a decimal integer >= 1.
86
Input files specified without using this option are assigned a default
87
weight of 1. Examples are shown below.
91
.B \-input\-files=path, \-f=path
92
Specify a file which contains a list of files to merge. The entries in this
93
file are newline\-separated. Lines starting with ‘#’ are skipped. Entries may
94
be of the form <filename> or <weight>,<filename>.
98
.B \-remapping\-file=path, \-r=path
99
Specify a file which contains a remapping from symbol names in the input
100
profile to the symbol names that should be used in the output profile. The
101
file should consist of lines of the form \fB<input\-symbol> <output\-symbol>\fP\&.
102
Blank lines and lines starting with \fB#\fP are skipped.
104
The llvm\-cxxmap tool can be used to generate the symbol
110
Specify that the input profile is an instrumentation\-based profile.
115
Specify that the input profile is a sample\-based profile.
117
The format of the generated file can be generated in one of three ways:
120
.B \-binary (default)
123
Emit the profile using a binary encoding. For instrumentation\-based profile
124
the output format is the indexed binary format.
130
Emit the profile using an extensible binary encoding. This option can only
131
be used with sample\-based profile. The extensible binary encoding can be
132
more compact with compression enabled and can be loaded faster than the
133
default binary encoding.
139
Emit the profile in text mode. This option can also be used with both
140
sample\-based and instrumentation\-based profile. When this option is used
141
the profile will be dumped in the text format that is parsable by the profile
148
Emit the profile using GCC’s gcov format (Not yet supported).
152
.B \-sparse[=true|false]
153
Do not emit function records with 0 execution count. Can only be used in
154
conjunction with \-instr. Defaults to false, since it can inhibit compiler
155
optimization during PGO.
159
.B \-num\-threads=N, \-j=N
160
Use N threads to perform profile merging. When N=0, llvm\-profdata auto\-detects
161
an appropriate number of threads to use. This is the default.
165
.B \-failure\-mode=[any|all]
166
Set the failure mode. There are two options: ‘any’ causes the merge command to
167
fail if any profiles are invalid, and ‘all’ causes the merge command to fail
168
only if all profiles are invalid. If ‘all’ is set, information from any
169
invalid profiles is excluded from the final merged product. The default
170
failure mode is ‘any’.
174
.B \-prof\-sym\-list=path
175
Specify a file which contains a list of symbols to generate profile symbol
176
list in the profile. This option can only be used with sample\-based profile
177
in extbinary format. The entries in this file are newline\-separated.
181
.B \-compress\-all\-sections=[true|false]
182
Compress all sections when writing the profile. This option can only be used
183
with sample\-based profile in extbinary format.
187
.B \-use\-md5=[true|false]
188
Use MD5 to represent string in name table when writing the profile.
189
This option can only be used with sample\-based profile in extbinary format.
193
.B \-gen\-partial\-profile=[true|false]
194
Mark the profile to be a partial profile which only provides partial profile
195
coverage for the optimized target. This option can only be used with
196
sample\-based profile in extbinary format.
200
.B \-supplement\-instr\-with\-sample=path_to_sample_profile
201
Supplement an instrumentation profile with sample profile. The sample profile
202
is the input of the flag. Output will be in instrumentation format (only works
207
.B \-zero\-counter\-threshold=threshold_float_number
208
For the function which is cold in instr profile but hot in sample profile, if
209
the ratio of the number of zero counters divided by the the total number of
210
counters is above the threshold, the profile of the function will be regarded
211
as being harmful for performance and will be dropped.
215
.B \-instr\-prof\-cold\-threshold=threshold_int_number
216
User specified cold threshold for instr profile which will override the cold
217
threshold got from profile summary.
221
.B \-suppl\-min\-size\-threshold=threshold_int_number
222
If the size of a function is smaller than the threshold, assume it can be
223
inlined by PGO early inliner and it will not be adjusted based on sample
229
Merge three profiles:
235
llvm\-profdata merge foo.profdata bar.profdata baz.profdata \-output merged.profdata
242
The input file \fIfoo.profdata\fP is especially important, multiply its counts by 10:
248
llvm\-profdata merge \-weighted\-input=10,foo.profdata bar.profdata baz.profdata \-output merged.profdata
254
Exactly equivalent to the previous invocation (explicit form; useful for programmatic invocation):
260
llvm\-profdata merge \-weighted\-input=10,foo.profdata \-weighted\-input=1,bar.profdata \-weighted\-input=1,baz.profdata \-output merged.profdata
268
\fBllvm\-profdata show\fP [\fIoptions\fP] [\fIfilename\fP]
271
\fBllvm\-profdata show\fP takes a profile data file and displays the
272
information about the profile counters for this file and
273
for any of the specified function(s).
275
If \fIfilename\fP is omitted or is \fB\-\fP, then \fBllvm\-profdata show\fP reads its
276
input from standard input.
281
Print details for every function.
286
Print the counter values for the displayed functions.
291
Print details for a function if the function’s name contains the given string.
296
Print a summary of command line options.
300
.B \-output=output, \-o=output
301
Specify the output file name. If \fIoutput\fP is \fB\-\fP or it isn’t specified,
302
then the output is sent to standard output.
307
Specify that the input profile is an instrumentation\-based profile.
312
Instruct the profile dumper to show profile counts in the text format of the
313
instrumentation\-based profile data representation. By default, the profile
314
information is dumped in a more human readable form (also in text) with
320
Instruct the profile dumper to show the top \fBn\fP functions with the
321
hottest basic blocks in the summary section. By default, the topn functions
327
Specify that the input profile is a sample\-based profile.
332
Show the profiled sizes of the memory intrinsic calls for shown functions.
337
Show only those functions whose max count values are greater or equal to \fBn\fP\&.
338
By default, the value\-cutoff is set to 0.
342
.B \-list\-below\-cutoff
343
Only output names of functions whose max count value are below the cutoff
349
Only show context sensitive profile counts. The default is to filter all
350
context sensitive profile counts.
354
.B \-show\-prof\-sym\-list=[true|false]
355
Show profile symbol list if it exists in the profile. This option is only
356
meaningful for sample\-based profile in extbinary format.
360
.B \-show\-sec\-info\-only=[true|false]
361
Show basic information about each section in the profile. This option is
362
only meaningful for sample\-based profile in extbinary format.
367
\fBllvm\-profdata overlap\fP [\fIoptions\fP] [\fIbase profile file\fP] [\fItest profile file\fP]
370
\fBllvm\-profdata overlap\fP takes two profile data files and displays the
371
\fIoverlap\fP of counter distribution between the whole files and between any of the
374
In this command, \fIoverlap\fP is defined as follows:
375
Suppose \fIbase profile file\fP has the following counts:
376
{c1_1, c1_2, …, c1_n, c1_u_1, c2_u_2, …, c2_u_s},
377
and \fItest profile file\fP has
378
{c2_1, c2_2, …, c2_n, c2_v_1, c2_v_2, …, c2_v_t}.
379
Here c{1|2}_i (i = 1 .. n) are matched counters and c1_u_i (i = 1 .. s) and
380
c2_v_i (i = 1 .. v) are unmatched counters (or counters only existing in)
381
\fIbase profile file\fP and \fItest profile file\fP, respectively.
382
Let sum_1 = c1_1 + c1_2 + … + c1_n + c1_u_1 + c2_u_2 + … + c2_u_s, and
383
sum_2 = c2_1 + c2_2 + … + c2_n + c2_v_1 + c2_v_2 + … + c2_v_t.
384
\fIoverlap\fP = min(c1_1/sum_1, c2_1/sum_2) + min(c1_2/sum_1, c2_2/sum_2) + …
385
+ min(c1_n/sum_1, c2_n/sum_2).
387
The result overlap distribution is a percentage number, ranging from 0.0% to
388
100.0%, where 0.0% means there is no overlap and 100.0% means a perfect
391
Here is an example, if \fIbase profile file\fP has counts of {400, 600}, and
392
\fItest profile file\fP has matched counts of {60000, 40000}. The \fIoverlap\fP is 80%.
397
Print details for a function if the function’s name contains the given string.
402
Print a summary of command line options.
406
.B \-o=output or \-o output
407
Specify the output file name. If \fIoutput\fP is \fB\-\fP or it isn’t specified,
408
then the output is sent to standard output.
413
Show only those functions whose max count values are greater or equal to \fBn\fP\&.
414
By default, the value\-cutoff is set to max of unsigned long long.
419
Only show overlap for the context sensitive profile counts. The default is to show
420
non\-context sensitive profile counts.
424
\fBllvm\-profdata\fP returns 1 if the command is omitted or is invalid,
425
if it cannot read input files, or if there is a mismatch between their data.
427
Maintained by the LLVM Team (https://llvm.org/).
429
2003-2021, LLVM Project
430
.\" Generated by docutils manpage writer.