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

16       · merge
17
18       · show
19
20       · overlap
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
58              entries  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   EXAMPLES
110   Basic Usage
111       Merge three profiles:
112
113          llvm-profdata merge foo.profdata bar.profdata baz.profdata -output merged.profdata
114
115   Weighted Input
116       The  input  file  foo.profdata  is  especially  important, multiply its
117       counts by 10:
118
119          llvm-profdata merge -weighted-input=10,foo.profdata bar.profdata baz.profdata -output merged.profdata
120
121       Exactly equivalent to the previous invocation  (explicit  form;  useful
122       for programmatic invocation):
123
124          llvm-profdata merge -weighted-input=10,foo.profdata -weighted-input=1,bar.profdata -weighted-input=1,baz.profdata -output merged.profdata
125

SHOW

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

OVERLAP

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

EXIT STATUS

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

AUTHOR

240       Maintained by the LLVM Team (https://llvm.org/).
241
243       2003-2019, LLVM Project
244
245
246
247
2489                                 2019-09-19                  LLVM-PROFDATA(1)
Impressum