1LLVM-PROFDATA(1) LLVM LLVM-PROFDATA(1)
2
6 llvm-profdata - Profile data tool
7
9 llvm-profdata command [args...]
10
12 The llvm-profdata tool is a small utility for working with profile data
13 files.
14
16 • merge
17 • show
19 • overlap
21
23 SYNOPSIS
24 llvm-profdata merge [options] [filename...]
25 DESCRIPTION
27 llvm-profdata merge takes several profile data files generated by PGO
28 instrumentation and merges them together into a single indexed profile
29 data file.
30 By default profile data is merged without modification. This means that
32 the relative importance of each input file is proportional to the num‐
33 ber of samples or counts it contains. In general, the input from a
34 longer training run will be interpreted as relatively more important
35 than a shorter run. Depending on the nature of the training runs it may
36 be useful to adjust the weight given to each input file by using the
37 -weighted-input option.
38 Profiles passed in via -weighted-input, -input-files, or via positional
40 arguments are processed once for each time they are seen.
41 OPTIONS
43 --help Print a summary of command line options.
44 --output=<output>, -o
46 Specify the output file name. Output cannot be - as the result‐
47 ing indexed profile data can't be written to standard output.
48 --weighted-input=<weight,filename>
50 Specify an input file name along with a weight. The profile
51 counts of the supplied filename will be scaled (multiplied) by
52 the supplied weight, where weight is a decimal integer >= 1.
53 Input files specified without using this option are assigned a
54 default weight of 1. Examples are shown below.
55 --input-files=<path>, -f
57 Specify a file which contains a list of files to merge. The en‐
58 tries in this file are newline-separated. Lines starting with
59 '#' are skipped. Entries may be of the form <filename> or
60 <weight>,<filename>.
61 --remapping-file=<path>, -r
63 Specify a file which contains a remapping from symbol names in
64 the input profile to the symbol names that should be used in the
65 output profile. The file should consist of lines of the form
66 <input-symbol> <output-symbol>. Blank lines and lines starting
67 with # are skipped.
68 The llvm-cxxmap tool can be used to generate the symbol remap‐
70 ping file.
71 --instr (default)
73 Specify that the input profile is an instrumentation-based pro‐
74 file.
75 --sample
77 Specify that the input profile is a sample-based profile.
78 The format of the generated file can be generated in one of
80 three ways:
81 --binary (default)
83 Emit the profile using a binary encoding. For instrumenta‐
85 tion-based profile the output format is the indexed binary for‐
86 mat.
87 --extbinary
89 Emit the profile using an extensible binary encoding. This op‐
91 tion can only be used with sample-based profile. The extensible
92 binary encoding can be more compact with compression enabled and
93 can be loaded faster than the default binary encoding.
94 --text
96 Emit the profile in text mode. This option can also be used with
98 both sample-based and instrumentation-based profile. When this
99 option is used the profile will be dumped in the text format
100 that is parsable by the profile reader.
101 --gcc
103 Emit the profile using GCC's gcov format (Not yet supported).
105 --sparse[=true|false]
107 Do not emit function records with 0 execution count. Can only be
108 used in conjunction with -instr. Defaults to false, since it can
109 inhibit compiler optimization during PGO.
110 --num-threads=<N>, -j
112 Use N threads to perform profile merging. When N=0, llvm-prof‐
113 data auto-detects an appropriate number of threads to use. This
114 is the default.
115 --failure-mode=[any|all]
117 Set the failure mode. There are two options: 'any' causes the
118 merge command to fail if any profiles are invalid, and 'all'
119 causes the merge command to fail only if all profiles are in‐
120 valid. If 'all' is set, information from any invalid profiles is
121 excluded from the final merged product. The default failure mode
122 is 'any'.
123 --prof-sym-list=<path>
125 Specify a file which contains a list of symbols to generate pro‐
126 file symbol list in the profile. This option can only be used
127 with sample-based profile in extbinary format. The entries in
128 this file are newline-separated.
129 --compress-all-sections=[true|false]
131 Compress all sections when writing the profile. This option can
132 only be used with sample-based profile in extbinary format.
133 --use-md5=[true|false]
135 Use MD5 to represent string in name table when writing the pro‐
136 file. This option can only be used with sample-based profile in
137 extbinary format.
138 --gen-partial-profile=[true|false]
140 Mark the profile to be a partial profile which only provides
141 partial profile coverage for the optimized target. This option
142 can only be used with sample-based profile in extbinary format.
143 --supplement-instr-with-sample=<file>
145 Supplement an instrumentation profile with sample profile. The
146 sample profile is the input of the flag. Output will be in in‐
147 strumentation format (only works with -instr).
148 --zero-counter-threshold=<float>
150 For the function which is cold in instr profile but hot in sam‐
151 ple profile, if the ratio of the number of zero counters divided
152 by the total number of counters is above the threshold, the pro‐
153 file of the function will be regarded as being harmful for per‐
154 formance and will be dropped.
155 --instr-prof-cold-threshold=<int>
157 User specified cold threshold for instr profile which will over‐
158 ride the cold threshold got from profile summary.
159 --suppl-min-size-threshold=<int>
161 If the size of a function is smaller than the threshold, assume
162 it can be inlined by PGO early inliner and it will not be ad‐
163 justed based on sample profile.
164 --debug-info=<path>
166 Specify the executable or .dSYM that contains debug info for the
167 raw profile. When -debug-info-correlate was used for instrumen‐
168 tation, use this option to correlate the raw profile.
169 EXAMPLES
171 Basic Usage
172 Merge three profiles:
173 llvm-profdata merge foo.profdata bar.profdata baz.profdata -output merged.profdata
175 Weighted Input
177 The input file foo.profdata is especially important, multiply its
178 counts by 10:
179 llvm-profdata merge --weighted-input=10,foo.profdata bar.profdata baz.profdata --output merged.profdata
181 Exactly equivalent to the previous invocation (explicit form; useful
183 for programmatic invocation):
184 llvm-profdata merge --weighted-input=10,foo.profdata --weighted-input=1,bar.profdata --weighted-input=1,baz.profdata --output merged.profdata
186
188 SYNOPSIS
189 llvm-profdata show [options] [filename]
190 DESCRIPTION
192 llvm-profdata show takes a profile data file and displays the informa‐
193 tion about the profile counters for this file and for any of the speci‐
194 fied function(s).
195 If filename is omitted or is -, then llvm-profdata show reads its input
197 from standard input.
198 OPTIONS
200 --all-functions
201 Print details for every function.
202 --binary-ids
204 Print embedded binary ids in a profile.
205 --counts
207 Print the counter values for the displayed functions.
208 --show-format=<text|json|yaml>
210 Emit output in the selected format if supported by the provided
211 profile type.
212 --function=<string>
214 Print details for a function if the function's name contains the
215 given string.
216 --help Print a summary of command line options.
218 --output=<output>, -o
220 Specify the output file name. If output is - or it isn't speci‐
221 fied, then the output is sent to standard output.
222 --instr (default)
224 Specify that the input profile is an instrumentation-based pro‐
225 file.
226 --text Instruct the profile dumper to show profile counts in the text
228 format of the instrumentation-based profile data representation.
229 By default, the profile information is dumped in a more human
230 readable form (also in text) with annotations.
231 --topn=<n>
233 Instruct the profile dumper to show the top n functions with the
234 hottest basic blocks in the summary section. By default, the
235 topn functions are not dumped.
236 --sample
238 Specify that the input profile is a sample-based profile.
239 --memop-sizes
241 Show the profiled sizes of the memory intrinsic calls for shown
242 functions.
243 --value-cutoff=<n>
245 Show only those functions whose max count values are greater or
246 equal to n. By default, the value-cutoff is set to 0.
247 --list-below-cutoff
249 Only output names of functions whose max count value are below
250 the cutoff value.
251 --profile-version
253 Print profile version.
254 --showcs
256 Only show context sensitive profile counts. The default is to
257 filter all context sensitive profile counts.
258 --show-prof-sym-list=[true|false]
260 Show profile symbol list if it exists in the profile. This op‐
261 tion is only meaningful for sample-based profile in extbinary
262 format.
263 --show-sec-info-only=[true|false]
265 Show basic information about each section in the profile. This
266 option is only meaningful for sample-based profile in extbinary
267 format.
268 --debug-info=<path>
270 Specify the executable or .dSYM that contains debug info for the
271 raw profile. When -debug-info-correlate was used for instrumen‐
272 tation, use this option to show the correlated functions from
273 the raw profile.
274 --covered
276 Show only the functions that have been executed, i.e., functions
277 with non-zero counts.
278
280 SYNOPSIS
281 llvm-profdata overlap [options] [base profile file] [test profile file]
282 DESCRIPTION
284 llvm-profdata overlap takes two profile data files and displays the
285 overlap of counter distribution between the whole files and between any
286 of the specified functions.
287 In this command, overlap is defined as follows: Suppose base profile
289 file has the following counts: {c1_1, c1_2, ..., c1_n, c1_u_1, c2_u_2,
290 ..., c2_u_s}, and test profile file has {c2_1, c2_2, ..., c2_n, c2_v_1,
291 c2_v_2, ..., c2_v_t}. Here c{1|2}_i (i = 1 .. n) are matched counters
292 and c1_u_i (i = 1 .. s) and c2_v_i (i = 1 .. v) are unmatched counters
293 (or counters only existing in) base profile file and test profile file,
294 respectively. Let sum_1 = c1_1 + c1_2 + ... + c1_n + c1_u_1 + c2_u_2
295 + ... + c2_u_s, and sum_2 = c2_1 + c2_2 + ... + c2_n + c2_v_1 + c2_v_2
296 + ... + c2_v_t. overlap = min(c1_1/sum_1, c2_1/sum_2) +
297 min(c1_2/sum_1, c2_2/sum_2) + ... + min(c1_n/sum_1, c2_n/sum_2).
298 The result overlap distribution is a percentage number, ranging from
300 0.0% to 100.0%, where 0.0% means there is no overlap and 100.0% means a
301 perfect overlap.
302 Here is an example, if base profile file has counts of {400, 600}, and
304 test profile file has matched counts of {60000, 40000}. The overlap is
305 80%.
306 OPTIONS
308 --function=<string>
309 Print details for a function if the function's name contains the
310 given string.
311 --help Print a summary of command line options.
313 --output=<output>, -o
315 Specify the output file name. If output is - or it isn't speci‐
316 fied, then the output is sent to standard output.
317 --value-cutoff=<n>
319 Show only those functions whose max count values are greater or
320 equal to n. By default, the value-cutoff is set to max of un‐
321 signed long long.
322 --cs Only show overlap for the context sensitive profile counts. The
324 default is to show non-context sensitive profile counts.
325
327 llvm-profdata returns 1 if the command is omitted or is invalid, if it
328 cannot read input files, or if there is a mismatch between their data.
329
331 Maintained by the LLVM Team (https://llvm.org/).
332
334 2003-2023, LLVM Project
33516 2023-08-24 LLVM-PROFDATA(1)