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 where weight is a decimal integer  >=
53              1.  Input files specified without using this option are assigned
54              a 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              -text
89
90              Emit the profile in text mode. This option can also be used with
91              both  sample-based  and instrumentation-based profile. When this
92              option is used the profile will be dumped  in  the  text  format
93              that is parsable by the profile reader.
94
95              -gcc
96
97              Emit the profile using GCC's gcov format (Not yet supported).
98
99       -sparse[=true|false]
100              Do not emit function records with 0 execution count. Can only be
101              used in conjunction with -instr. Defaults to false, since it can
102              inhibit compiler optimization during PGO.
103
104       -num-threads=N, -j=N
105              Use  N  threads to perform profile merging. When N=0, llvm-prof‐
106              data auto-detects an appropriate number of threads to use.  This
107              is the default.
108
109       -failure-mode=[any|all]
110              Set  the  failure  mode. There are two options: 'any' causes the
111              merge command to fail if any profiles  are  invalid,  and  'all'
112              causes  the  merge  command to fail only if all profiles are in‐
113              valid. If 'all' is set, information from any invalid profiles is
114              excluded from the final merged product. The default failure mode
115              is 'any'.
116
117   EXAMPLES
118   Basic Usage
119       Merge three profiles:
120
121          llvm-profdata merge foo.profdata bar.profdata baz.profdata -output merged.profdata
122
123   Weighted Input
124       The input file  foo.profdata  is  especially  important,  multiply  its
125       counts by 10:
126
127          llvm-profdata merge -weighted-input=10,foo.profdata bar.profdata baz.profdata -output merged.profdata
128
129       Exactly  equivalent  to  the previous invocation (explicit form; useful
130       for programmatic invocation):
131
132          llvm-profdata merge -weighted-input=10,foo.profdata -weighted-input=1,bar.profdata -weighted-input=1,baz.profdata -output merged.profdata
133

SHOW

135   SYNOPSIS
136       llvm-profdata show [options] [filename]
137
138   DESCRIPTION
139       llvm-profdata show takes a profile data file and displays the  informa‐
140       tion about the profile counters for this file and for any of the speci‐
141       fied function(s).
142
143       If filename is omitted or is -, then llvm-profdata show reads its input
144       from standard input.
145
146   OPTIONS
147       -all-functions
148              Print details for every function.
149
150       -counts
151              Print the counter values for the displayed functions.
152
153       -function=string
154              Print details for a function if the function's name contains the
155              given string.
156
157       -help  Print a summary of command line options.
158
159       -output=output, -o=output
160              Specify the output file name.  If output is - or it isn't speci‐
161              fied, then the output is sent to standard output.
162
163       -instr (default)
164              Specify  that the input profile is an instrumentation-based pro‐
165              file.
166
167       -text  Instruct the profile dumper to show profile counts in  the  text
168              format of the instrumentation-based profile data representation.
169              By default, the profile information is dumped in  a  more  human
170              readable form (also in text) with annotations.
171
172       -topn=n
173              Instruct the profile dumper to show the top n functions with the
174              hottest basic blocks in the summary  section.  By  default,  the
175              topn functions are not dumped.
176
177       -sample
178              Specify that the input profile is a sample-based profile.
179
180       -memop-sizes
181              Show  the profiled sizes of the memory intrinsic calls for shown
182              functions.
183
184       -value-cutoff=n
185              Show only those functions whose max count values are greater  or
186              equal to n.  By default, the value-cutoff is set to 0.
187
188       -list-below-cutoff
189              Only  output  names of functions whose max count value are below
190              the cutoff value.
191
192       -showcs
193              Only show context sensitive profile counts. The  default  is  to
194              filter all context sensitive profile counts.
195

OVERLAP

197   SYNOPSIS
198       llvm-profdata overlap [options] [base profile file] [test profile file]
199
200   DESCRIPTION
201       llvm-profdata  overlap  takes  two  profile data files and displays the
202       overlap of counter distribution between the whole files and between any
203       of the specified functions.
204
205       In  this  command,  overlap is defined as follows: Suppose base profile
206       file has the following counts: {c1_1, c1_2, ..., c1_n, c1_u_1,  c2_u_2,
207       ..., c2_u_s}, and test profile file has {c2_1, c2_2, ..., c2_n, c2_v_1,
208       c2_v_2, ..., c2_v_t}.  Here c{1|2}_i (i = 1 .. n) are matched  counters
209       and  c1_u_i (i = 1 .. s) and c2_v_i (i = 1 .. v) are unmatched counters
210       (or counters only existing in) base profile file and test profile file,
211       respectively.  Let sum_1 = c1_1 + c1_2 +  ... + c1_n +  c1_u_1 + c2_u_2
212       + ... + c2_u_s, and sum_2 = c2_1 + c2_2 + ... + c2_n + c2_v_1 +  c2_v_2
213       +   ...   +   c2_v_t.    overlap   =   min(c1_1/sum_1,   c2_1/sum_2)  +
214       min(c1_2/sum_1, c2_2/sum_2) + ...  + min(c1_n/sum_1, c2_n/sum_2).
215
216       The result overlap distribution is a percentage  number,  ranging  from
217       0.0% to 100.0%, where 0.0% means there is no overlap and 100.0% means a
218       perfect overlap.
219
220       Here is an example, if base profile file has counts of {400, 600},  and
221       test  profile file has matched counts of {60000, 40000}. The overlap is
222       80%.
223
224   OPTIONS
225       -function=string
226              Print details for a function if the function's name contains the
227              given string.
228
229       -help  Print a summary of command line options.
230
231       -o=output or -o output
232              Specify the output file name.  If output is - or it isn't speci‐
233              fied, then the output is sent to standard output.
234
235       -value-cutoff=n
236              Show only those functions whose max count values are greater  or
237              equal  to  n.  By default, the value-cutoff is set to max of un‐
238              signed long long.
239
240       -cs    Only show overlap for the context sensitive profile counts.  The
241              default is to show non-context sensitive profile counts.
242

EXIT STATUS

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

AUTHOR

248       Maintained by the LLVM Team (https://llvm.org/).
249
251       2003-2021, LLVM Project
252
253
254
255
25610                                2021-07-22                  LLVM-PROFDATA(1)
Impressum