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 the total number of counters is above the threshold, the
153              profile of the function will be regarded as  being  harmful  for
154              performance 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       --counts
204              Print the counter values for the displayed functions.
205
206       --function=<string>
207              Print details for a function if the function's name contains the
208              given string.
209
210       --help Print a summary of command line options.
211
212       --output=<output>, -o
213              Specify the output file name.  If output is - or it isn't speci‐
214              fied, then the output is sent to standard output.
215
216       --instr (default)
217              Specify  that the input profile is an instrumentation-based pro‐
218              file.
219
220       --text Instruct the profile dumper to show profile counts in  the  text
221              format of the instrumentation-based profile data representation.
222              By default, the profile information is dumped in  a  more  human
223              readable form (also in text) with annotations.
224
225       --topn=<n>
226              Instruct the profile dumper to show the top n functions with the
227              hottest basic blocks in the summary  section.  By  default,  the
228              topn functions are not dumped.
229
230       --sample
231              Specify that the input profile is a sample-based profile.
232
233       --memop-sizes
234              Show  the profiled sizes of the memory intrinsic calls for shown
235              functions.
236
237       --value-cutoff=<n>
238              Show only those functions whose max count values are greater  or
239              equal to n.  By default, the value-cutoff is set to 0.
240
241       --list-below-cutoff
242              Only  output  names of functions whose max count value are below
243              the cutoff value.
244
245       --showcs
246              Only show context sensitive profile counts. The  default  is  to
247              filter all context sensitive profile counts.
248
249       --show-prof-sym-list=[true|false]
250              Show  profile  symbol list if it exists in the profile. This op‐
251              tion is only meaningful for sample-based  profile  in  extbinary
252              format.
253
254       --show-sec-info-only=[true|false]
255              Show  basic  information about each section in the profile. This
256              option is only meaningful for sample-based profile in  extbinary
257              format.
258

OVERLAP

260   SYNOPSIS
261       llvm-profdata overlap [options] [base profile file] [test profile file]
262
263   DESCRIPTION
264       llvm-profdata  overlap  takes  two  profile data files and displays the
265       overlap of counter distribution between the whole files and between any
266       of the specified functions.
267
268       In  this  command,  overlap is defined as follows: Suppose base profile
269       file has the following counts: {c1_1, c1_2, ..., c1_n, c1_u_1,  c2_u_2,
270       ..., c2_u_s}, and test profile file has {c2_1, c2_2, ..., c2_n, c2_v_1,
271       c2_v_2, ..., c2_v_t}.  Here c{1|2}_i (i = 1 .. n) are matched  counters
272       and  c1_u_i (i = 1 .. s) and c2_v_i (i = 1 .. v) are unmatched counters
273       (or counters only existing in) base profile file and test profile file,
274       respectively.  Let sum_1 = c1_1 + c1_2 +  ... + c1_n +  c1_u_1 + c2_u_2
275       + ... + c2_u_s, and sum_2 = c2_1 + c2_2 + ... + c2_n + c2_v_1 +  c2_v_2
276       +   ...   +   c2_v_t.    overlap   =   min(c1_1/sum_1,   c2_1/sum_2)  +
277       min(c1_2/sum_1, c2_2/sum_2) + ...  + min(c1_n/sum_1, c2_n/sum_2).
278
279       The result overlap distribution is a percentage  number,  ranging  from
280       0.0% to 100.0%, where 0.0% means there is no overlap and 100.0% means a
281       perfect overlap.
282
283       Here is an example, if base profile file has counts of {400, 600},  and
284       test  profile file has matched counts of {60000, 40000}. The overlap is
285       80%.
286
287   OPTIONS
288       --function=<string>
289              Print details for a function if the function's name contains the
290              given string.
291
292       --help Print a summary of command line options.
293
294       --output=<output>, -o
295              Specify the output file name.  If output is - or it isn't speci‐
296              fied, then the output is sent to standard output.
297
298       --value-cutoff=<n>
299              Show only those functions whose max count values are greater  or
300              equal  to  n.  By default, the value-cutoff is set to max of un‐
301              signed long long.
302
303       --cs   Only show overlap for the context sensitive profile counts.  The
304              default is to show non-context sensitive profile counts.
305

EXIT STATUS

307       llvm-profdata  returns 1 if the command is omitted or is invalid, if it
308       cannot read input files, or if there is a mismatch between their data.
309

AUTHOR

311       Maintained by the LLVM Team (https://llvm.org/).
312
314       2003-2023, LLVM Project
315
316
317
318
31914                                2023-07-20                  LLVM-PROFDATA(1)
Impressum