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 • order
23
25 SYNOPSIS
26 llvm-profdata merge [options] [filename...]
27 DESCRIPTION
29 llvm-profdata merge takes several profile data files generated by PGO
30 instrumentation and merges them together into a single indexed profile
31 data file.
32 By default profile data is merged without modification. This means that
34 the relative importance of each input file is proportional to the num‐
35 ber of samples or counts it contains. In general, the input from a
36 longer training run will be interpreted as relatively more important
37 than a shorter run. Depending on the nature of the training runs it may
38 be useful to adjust the weight given to each input file by using the
39 -weighted-input option.
40 Profiles passed in via -weighted-input, -input-files, or via positional
42 arguments are processed once for each time they are seen.
43 OPTIONS
45 --help Print a summary of command line options.
46 --output=<output>, -o
48 Specify the output file name. Output cannot be - as the result‐
49 ing indexed profile data can't be written to standard output.
50 --weighted-input=<weight,filename>
52 Specify an input file name along with a weight. The profile
53 counts of the supplied filename will be scaled (multiplied) by
54 the supplied weight, where weight is a decimal integer >= 1.
55 Input files specified without using this option are assigned a
56 default weight of 1. Examples are shown below.
57 --input-files=<path>, -f
59 Specify a file which contains a list of files to merge. The en‐
60 tries in this file are newline-separated. Lines starting with
61 '#' are skipped. Entries may be of the form <filename> or
62 <weight>,<filename>.
63 --remapping-file=<path>, -r
65 Specify a file which contains a remapping from symbol names in
66 the input profile to the symbol names that should be used in the
67 output profile. The file should consist of lines of the form
68 <input-symbol> <output-symbol>. Blank lines and lines starting
69 with # are skipped.
70 The llvm-cxxmap tool can be used to generate the symbol remap‐
72 ping file.
73 --instr (default)
75 Specify that the input profile is an instrumentation-based pro‐
76 file.
77 --sample
79 Specify that the input profile is a sample-based profile.
80 The format of the generated file can be generated in one of
82 three ways:
83 --binary (default)
85 Emit the profile using a binary encoding. For instrumenta‐
87 tion-based profile the output format is the indexed binary for‐
88 mat.
89 --extbinary
91 Emit the profile using an extensible binary encoding. This op‐
93 tion can only be used with sample-based profile. The extensible
94 binary encoding can be more compact with compression enabled and
95 can be loaded faster than the default binary encoding.
96 --text
98 Emit the profile in text mode. This option can also be used with
100 both sample-based and instrumentation-based profile. When this
101 option is used the profile will be dumped in the text format
102 that is parsable by the profile reader.
103 --gcc
105 Emit the profile using GCC's gcov format (Not yet supported).
107 --sparse[=true|false]
109 Do not emit function records with 0 execution count. Can only be
110 used in conjunction with -instr. Defaults to false, since it can
111 inhibit compiler optimization during PGO.
112 --num-threads=<N>, -j
114 Use N threads to perform profile merging. When N=0, llvm-prof‐
115 data auto-detects an appropriate number of threads to use. This
116 is the default.
117 --failure-mode=[any|all]
119 Set the failure mode. There are two options: 'any' causes the
120 merge command to fail if any profiles are invalid, and 'all'
121 causes the merge command to fail only if all profiles are in‐
122 valid. If 'all' is set, information from any invalid profiles is
123 excluded from the final merged product. The default failure mode
124 is 'any'.
125 --prof-sym-list=<path>
127 Specify a file which contains a list of symbols to generate pro‐
128 file symbol list in the profile. This option can only be used
129 with sample-based profile in extbinary format. The entries in
130 this file are newline-separated.
131 --compress-all-sections=[true|false]
133 Compress all sections when writing the profile. This option can
134 only be used with sample-based profile in extbinary format.
135 --use-md5=[true|false]
137 Use MD5 to represent string in name table when writing the pro‐
138 file. This option can only be used with sample-based profile in
139 extbinary format.
140 --gen-partial-profile=[true|false]
142 Mark the profile to be a partial profile which only provides
143 partial profile coverage for the optimized target. This option
144 can only be used with sample-based profile in extbinary format.
145 --convert-sample-profile-layout=[nest|flat]
147 Convert the merged profile into a profile with a new layout.
148 Supported layout are nest (Nested profile, the input should be
149 CS flat profile) and flat (Profile with nested inlinees flat‐
150 tened out).
151 --supplement-instr-with-sample=<file>
153 Supplement an instrumentation profile with sample profile. The
154 sample profile is the input of the flag. Output will be in in‐
155 strumentation format (only works with -instr).
156 --zero-counter-threshold=<float>
158 For the function which is cold in instr profile but hot in sam‐
159 ple profile, if the ratio of the number of zero counters divided
160 by the total number of counters is above the threshold, the pro‐
161 file of the function will be regarded as being harmful for per‐
162 formance and will be dropped.
163 --instr-prof-cold-threshold=<int>
165 User specified cold threshold for instr profile which will over‐
166 ride the cold threshold got from profile summary.
167 --suppl-min-size-threshold=<int>
169 If the size of a function is smaller than the threshold, assume
170 it can be inlined by PGO early inliner and it will not be ad‐
171 justed based on sample profile.
172 --debug-info=<path>
174 Specify the executable or .dSYM that contains debug info for the
175 raw profile. When -debug-info-correlate was used for instrumen‐
176 tation, use this option to correlate the raw profile.
177 --temporal-profile-trace-reservoir-size
179 The maximum number of temporal profile traces to be stored in
180 the output profile. If more traces are added, we will use reser‐
181 voir sampling to select which traces to keep. Note that changing
182 this value between different merge invocations on the same in‐
183 dexed profile could result in sample bias. The default value is
184 100.
185 --temporal-profile-max-trace-length
187 The maximum number of functions in a single temporal profile
188 trace. Longer traces will be truncated. The default value is
189 1000.
190 EXAMPLES
192 Basic Usage
193 Merge three profiles:
194 llvm-profdata merge foo.profdata bar.profdata baz.profdata -output merged.profdata
196 Weighted Input
198 The input file foo.profdata is especially important, multiply its
199 counts by 10:
200 llvm-profdata merge --weighted-input=10,foo.profdata bar.profdata baz.profdata --output merged.profdata
202 Exactly equivalent to the previous invocation (explicit form; useful
204 for programmatic invocation):
205 llvm-profdata merge --weighted-input=10,foo.profdata --weighted-input=1,bar.profdata --weighted-input=1,baz.profdata --output merged.profdata
207
209 SYNOPSIS
210 llvm-profdata show [options] [filename]
211 DESCRIPTION
213 llvm-profdata show takes a profile data file and displays the informa‐
214 tion about the profile counters for this file and for any of the speci‐
215 fied function(s).
216 If filename is omitted or is -, then llvm-profdata show reads its input
218 from standard input.
219 OPTIONS
221 --all-functions
222 Print details for every function.
223 --binary-ids
225 Print embedded binary ids in a profile.
226 --counts
228 Print the counter values for the displayed functions.
229 --show-format=<text|json|yaml>
231 Emit output in the selected format if supported by the provided
232 profile type.
233 --function=<string>
235 Print details for a function if the function's name contains the
236 given string.
237 --help Print a summary of command line options.
239 --output=<output>, -o
241 Specify the output file name. If output is - or it isn't speci‐
242 fied, then the output is sent to standard output.
243 --instr (default)
245 Specify that the input profile is an instrumentation-based pro‐
246 file.
247 --text Instruct the profile dumper to show profile counts in the text
249 format of the instrumentation-based profile data representation.
250 By default, the profile information is dumped in a more human
251 readable form (also in text) with annotations.
252 --topn=<n>
254 Instruct the profile dumper to show the top n functions with the
255 hottest basic blocks in the summary section. By default, the
256 topn functions are not dumped.
257 --sample
259 Specify that the input profile is a sample-based profile.
260 --memop-sizes
262 Show the profiled sizes of the memory intrinsic calls for shown
263 functions.
264 --value-cutoff=<n>
266 Show only those functions whose max count values are greater or
267 equal to n. By default, the value-cutoff is set to 0.
268 --list-below-cutoff
270 Only output names of functions whose max count value are below
271 the cutoff value.
272 --profile-version
274 Print profile version.
275 --showcs
277 Only show context sensitive profile counts. The default is to
278 filter all context sensitive profile counts.
279 --show-prof-sym-list=[true|false]
281 Show profile symbol list if it exists in the profile. This op‐
282 tion is only meaningful for sample-based profile in extbinary
283 format.
284 --show-sec-info-only=[true|false]
286 Show basic information about each section in the profile. This
287 option is only meaningful for sample-based profile in extbinary
288 format.
289 --debug-info=<path>
291 Specify the executable or .dSYM that contains debug info for the
292 raw profile. When -debug-info-correlate was used for instrumen‐
293 tation, use this option to show the correlated functions from
294 the raw profile.
295 --covered
297 Show only the functions that have been executed, i.e., functions
298 with non-zero counts.
299
301 SYNOPSIS
302 llvm-profdata overlap [options] [base profile file] [test profile file]
303 DESCRIPTION
305 llvm-profdata overlap takes two profile data files and displays the
306 overlap of counter distribution between the whole files and between any
307 of the specified functions.
308 In this command, overlap is defined as follows: Suppose base profile
310 file has the following counts: {c1_1, c1_2, ..., c1_n, c1_u_1, c2_u_2,
311 ..., c2_u_s}, and test profile file has {c2_1, c2_2, ..., c2_n, c2_v_1,
312 c2_v_2, ..., c2_v_t}. Here c{1|2}_i (i = 1 .. n) are matched counters
313 and c1_u_i (i = 1 .. s) and c2_v_i (i = 1 .. v) are unmatched counters
314 (or counters only existing in) base profile file and test profile file,
315 respectively. Let sum_1 = c1_1 + c1_2 + ... + c1_n + c1_u_1 + c2_u_2
316 + ... + c2_u_s, and sum_2 = c2_1 + c2_2 + ... + c2_n + c2_v_1 + c2_v_2
317 + ... + c2_v_t. overlap = min(c1_1/sum_1, c2_1/sum_2) +
318 min(c1_2/sum_1, c2_2/sum_2) + ... + min(c1_n/sum_1, c2_n/sum_2).
319 The result overlap distribution is a percentage number, ranging from
321 0.0% to 100.0%, where 0.0% means there is no overlap and 100.0% means a
322 perfect overlap.
323 Here is an example, if base profile file has counts of {400, 600}, and
325 test profile file has matched counts of {60000, 40000}. The overlap is
326 80%.
327 OPTIONS
329 --function=<string>
330 Print details for a function if the function's name contains the
331 given string.
332 --help Print a summary of command line options.
334 --output=<output>, -o
336 Specify the output file name. If output is - or it isn't speci‐
337 fied, then the output is sent to standard output.
338 --value-cutoff=<n>
340 Show only those functions whose max count values are greater or
341 equal to n. By default, the value-cutoff is set to max of un‐
342 signed long long.
343 --cs Only show overlap for the context sensitive profile counts. The
345 default is to show non-context sensitive profile counts.
346
348 SYNOPSIS
349 llvm-profdata order [options] [filename]
350 DESCRIPTION
352 llvm-profdata order uses temporal profiling traces from a profile and
353 finds a function order that reduces the number of page faults for those
354 traces. This output can be directly passed to lld via --symbol-order‐
355 ing-file= for ELF or -order-file for Mach-O. If the traces found in the
356 profile are representative of the real world, then this order should
357 improve startup performance.
358 OPTIONS
360 --help Print a summary of command line options.
361 --output=<output>, -o
363 Specify the output file name. If output is - or it isn't speci‐
364 fied, then the output is sent to standard output.
365
367 llvm-profdata returns 1 if the command is omitted or is invalid, if it
368 cannot read input files, or if there is a mismatch between their data.
369
371 Maintained by the LLVM Team (https://llvm.org/).
372
374 2003-2023, LLVM Project
37517 2023-11-28 LLVM-PROFDATA(1)