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=output
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=path
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=path
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=N
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=path_to_sample_profile
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=threshold_float_number
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=threshold_int_number
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=threshold_int_number
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   EXAMPLES
166   Basic Usage
167       Merge three profiles:
168
169          llvm-profdata merge foo.profdata bar.profdata baz.profdata -output merged.profdata
170
171   Weighted Input
172       The input file  foo.profdata  is  especially  important,  multiply  its
173       counts by 10:
174
175          llvm-profdata merge -weighted-input=10,foo.profdata bar.profdata baz.profdata -output merged.profdata
176
177       Exactly  equivalent  to  the previous invocation (explicit form; useful
178       for programmatic invocation):
179
180          llvm-profdata merge -weighted-input=10,foo.profdata -weighted-input=1,bar.profdata -weighted-input=1,baz.profdata -output merged.profdata
181

SHOW

183   SYNOPSIS
184       llvm-profdata show [options] [filename]
185
186   DESCRIPTION
187       llvm-profdata show takes a profile data file and displays the  informa‐
188       tion about the profile counters for this file and for any of the speci‐
189       fied function(s).
190
191       If filename is omitted or is -, then llvm-profdata show reads its input
192       from standard input.
193
194   OPTIONS
195       -all-functions
196              Print details for every function.
197
198       -counts
199              Print the counter values for the displayed functions.
200
201       -function=string
202              Print details for a function if the function's name contains the
203              given string.
204
205       -help  Print a summary of command line options.
206
207       -output=output, -o=output
208              Specify the output file name.  If output is - or it isn't speci‐
209              fied, then the output is sent to standard output.
210
211       -instr (default)
212              Specify  that the input profile is an instrumentation-based pro‐
213              file.
214
215       -text  Instruct the profile dumper to show profile counts in  the  text
216              format of the instrumentation-based profile data representation.
217              By default, the profile information is dumped in  a  more  human
218              readable form (also in text) with annotations.
219
220       -topn=n
221              Instruct the profile dumper to show the top n functions with the
222              hottest basic blocks in the summary  section.  By  default,  the
223              topn functions are not dumped.
224
225       -sample
226              Specify that the input profile is a sample-based profile.
227
228       -memop-sizes
229              Show  the profiled sizes of the memory intrinsic calls for shown
230              functions.
231
232       -value-cutoff=n
233              Show only those functions whose max count values are greater  or
234              equal to n.  By default, the value-cutoff is set to 0.
235
236       -list-below-cutoff
237              Only  output  names of functions whose max count value are below
238              the cutoff value.
239
240       -showcs
241              Only show context sensitive profile counts. The  default  is  to
242              filter all context sensitive profile counts.
243
244       -show-prof-sym-list=[true|false]
245              Show  profile  symbol list if it exists in the profile. This op‐
246              tion is only meaningful for sample-based  profile  in  extbinary
247              format.
248
249       -show-sec-info-only=[true|false]
250              Show  basic  information about each section in the profile. This
251              option is only meaningful for sample-based profile in  extbinary
252              format.
253

OVERLAP

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

EXIT STATUS

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

AUTHOR

306       Maintained by the LLVM Team (https://llvm.org/).
307
309       2003-2023, LLVM Project
310
311
312
313
31412                                2023-07-20                  LLVM-PROFDATA(1)
Impressum