1LLVM-PROFDATA(1)                     LLVM                     LLVM-PROFDATA(1)
2
3
4

NAME

6       llvm-profdata - Profile data tool
7

SYNOPSIS

9       llvm-profdata command [args...]
10

DESCRIPTION

12       The llvm-profdata tool is a small utility for working with profile data
13       files.
14

COMMANDS

16merge
17
18show
19
20overlap
21

MERGE

23   SYNOPSIS
24       llvm-profdata merge [options] [filename...]
25
26   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
31       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
39       Profiles passed in via -weighted-input, -input-files, or via positional
40       arguments are processed once for each time they are seen.
41
42   OPTIONS
43       --help Print a summary of command line options.
44
45       --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
49       --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
56       --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
62       --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
69              The  llvm-cxxmap  tool can be used to generate the symbol remap‐
70              ping file.
71
72       --instr (default)
73              Specify that the input profile is an instrumentation-based  pro‐
74              file.
75
76       --sample
77              Specify that the input profile is a sample-based profile.
78
79              The  format  of  the  generated  file can be generated in one of
80              three ways:
81
82              --binary (default)
83
84              Emit the profile  using  a  binary  encoding.  For  instrumenta‐
85              tion-based  profile the output format is the indexed binary for‐
86              mat.
87
88              --extbinary
89
90              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
95              --text
96
97              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
102              --gcc
103
104              Emit the profile using GCC's gcov format (Not yet supported).
105
106       --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
111       --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
116       --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
124       --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
130       --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
134       --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
139       --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
144       --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
149       --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
156       --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
160       --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
165       --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
170   EXAMPLES
171   Basic Usage
172       Merge three profiles:
173
174          llvm-profdata merge foo.profdata bar.profdata baz.profdata -output merged.profdata
175
176   Weighted Input
177       The input file  foo.profdata  is  especially  important,  multiply  its
178       counts by 10:
179
180          llvm-profdata merge --weighted-input=10,foo.profdata bar.profdata baz.profdata --output merged.profdata
181
182       Exactly  equivalent  to  the previous invocation (explicit form; useful
183       for programmatic invocation):
184
185          llvm-profdata merge --weighted-input=10,foo.profdata --weighted-input=1,bar.profdata --weighted-input=1,baz.profdata --output merged.profdata
186

SHOW

188   SYNOPSIS
189       llvm-profdata show [options] [filename]
190
191   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
196       If filename is omitted or is -, then llvm-profdata show reads its input
197       from standard input.
198
199   OPTIONS
200       --all-functions
201              Print details for every function.
202
203       --binary-ids
204              Print embedded binary ids in a profile.
205
206       --counts
207              Print the counter values for the displayed functions.
208
209       --show-format=<text|json|yaml>
210              Emit  output in the selected format if supported by the provided
211              profile type.
212
213       --function=<string>
214              Print details for a function if the function's name contains the
215              given string.
216
217       --help Print a summary of command line options.
218
219       --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
223       --instr (default)
224              Specify that the input profile is an instrumentation-based  pro‐
225              file.
226
227       --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
232       --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
237       --sample
238              Specify that the input profile is a sample-based profile.
239
240       --memop-sizes
241              Show the profiled sizes of the memory intrinsic calls for  shown
242              functions.
243
244       --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
248       --list-below-cutoff
249              Only output names of functions whose max count value  are  below
250              the cutoff value.
251
252       --profile-version
253              Print profile version.
254
255       --showcs
256              Only  show  context  sensitive profile counts. The default is to
257              filter all context sensitive profile counts.
258
259       --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
264       --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
269       --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
275       --covered
276              Show only the functions that have been executed, i.e., functions
277              with non-zero counts.
278

OVERLAP

280   SYNOPSIS
281       llvm-profdata overlap [options] [base profile file] [test profile file]
282
283   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
288       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
299       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
303       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
307   OPTIONS
308       --function=<string>
309              Print details for a function if the function's name contains the
310              given string.
311
312       --help Print a summary of command line options.
313
314       --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
318       --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
323       --cs   Only  show overlap for the context sensitive profile counts. The
324              default is to show non-context sensitive profile counts.
325

EXIT STATUS

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

AUTHOR

331       Maintained by the LLVM Team (https://llvm.org/).
332
334       2003-2023, LLVM Project
335
336
337
338
33916                                2023-07-20                  LLVM-PROFDATA(1)
Impressum