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   EXAMPLES
145   Basic Usage
146       Merge three profiles:
147
148          llvm-profdata merge foo.profdata bar.profdata baz.profdata -output merged.profdata
149
150   Weighted Input
151       The  input  file  foo.profdata  is  especially  important, multiply its
152       counts by 10:
153
154          llvm-profdata merge -weighted-input=10,foo.profdata bar.profdata baz.profdata -output merged.profdata
155
156       Exactly equivalent to the previous invocation  (explicit  form;  useful
157       for programmatic invocation):
158
159          llvm-profdata merge -weighted-input=10,foo.profdata -weighted-input=1,bar.profdata -weighted-input=1,baz.profdata -output merged.profdata
160

SHOW

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

OVERLAP

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

EXIT STATUS

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

AUTHOR

285       Maintained by the LLVM Team (https://llvm.org/).
286
288       2003-2021, LLVM Project
289
290
291
292
29311                                2021-07-22                  LLVM-PROFDATA(1)
Impressum