1llvm-profdata - Profile data tool
2=================================
3
4SYNOPSIS
5--------
6
7:program:`llvm-profdata` *command* [*args...*]
8
9DESCRIPTION
10-----------
11
12The :program:`llvm-profdata` tool is a small utility for working with profile
13data files.
14
15COMMANDS
16--------
17
18* :ref:`merge <profdata-merge>`
19* :ref:`show <profdata-show>`
20
21.. program:: llvm-profdata merge
22
23.. _profdata-merge:
24
25MERGE
26-----
27
28SYNOPSIS
29^^^^^^^^
30
31:program:`llvm-profdata merge` [*options*] [*filename...*]
32
33DESCRIPTION
34^^^^^^^^^^^
35
36:program:`llvm-profdata merge` takes several profile data files
37generated by PGO instrumentation and merges them together into a single
38indexed profile data file.
39
40By default profile data is merged without modification. This means that the
41relative importance of each input file is proportional to the number of samples
42or counts it contains. In general, the input from a longer training run will be
43interpreted as relatively more important than a shorter run. Depending on the
44nature of the training runs it may be useful to adjust the weight given to each
45input file by using the ``-weighted-input`` option.
46
47Profiles passed in via ``-weighted-input``, ``-input-files``, or via positional
48arguments are processed once for each time they are seen.
49
50
51OPTIONS
52^^^^^^^
53
54.. option:: -help
55
56 Print a summary of command line options.
57
58.. option:: -output=output, -o=output
59
60 Specify the output file name.  *Output* cannot be ``-`` as the resulting
61 indexed profile data can't be written to standard output.
62
63.. option:: -weighted-input=weight,filename
64
65 Specify an input file name along with a weight. The profile counts of the
66 supplied ``filename`` will be scaled (multiplied) by the supplied
67 ``weight``, where where ``weight`` is a decimal integer >= 1.
68 Input files specified without using this option are assigned a default
69 weight of 1. Examples are shown below.
70
71.. option:: -input-files=path, -f=path
72
73  Specify a file which contains a list of files to merge. The entries in this
74  file are newline-separated. Lines starting with '#' are skipped. Entries may
75  be of the form <filename> or <weight>,<filename>.
76
77.. option:: -remapping-file=path, -r=path
78
79  Specify a file which contains a remapping from symbol names in the input
80  profile to the symbol names that should be used in the output profile. The
81  file should consist of lines of the form ``<input-symbol> <output-symbol>``.
82  Blank lines and lines starting with ``#`` are skipped.
83
84  The :doc:`llvm-cxxmap <llvm-cxxmap>` tool can be used to generate the symbol
85  remapping file.
86
87.. option:: -instr (default)
88
89 Specify that the input profile is an instrumentation-based profile.
90
91.. option:: -sample
92
93 Specify that the input profile is a sample-based profile.
94
95 The format of the generated file can be generated in one of three ways:
96
97 .. option:: -binary (default)
98
99 Emit the profile using a binary encoding. For instrumentation-based profile
100 the output format is the indexed binary format.
101
102 .. option:: -text
103
104 Emit the profile in text mode. This option can also be used with both
105 sample-based and instrumentation-based profile. When this option is used
106 the profile will be dumped in the text format that is parsable by the profile
107 reader.
108
109 .. option:: -gcc
110
111 Emit the profile using GCC's gcov format (Not yet supported).
112
113.. option:: -sparse[=true|false]
114
115 Do not emit function records with 0 execution count. Can only be used in
116 conjunction with -instr. Defaults to false, since it can inhibit compiler
117 optimization during PGO.
118
119.. option:: -num-threads=N, -j=N
120
121 Use N threads to perform profile merging. When N=0, llvm-profdata auto-detects
122 an appropriate number of threads to use. This is the default.
123
124EXAMPLES
125^^^^^^^^
126Basic Usage
127+++++++++++
128Merge three profiles:
129
130::
131
132    llvm-profdata merge foo.profdata bar.profdata baz.profdata -output merged.profdata
133
134Weighted Input
135++++++++++++++
136The input file `foo.profdata` is especially important, multiply its counts by 10:
137
138::
139
140    llvm-profdata merge -weighted-input=10,foo.profdata bar.profdata baz.profdata -output merged.profdata
141
142Exactly equivalent to the previous invocation (explicit form; useful for programmatic invocation):
143
144::
145
146    llvm-profdata merge -weighted-input=10,foo.profdata -weighted-input=1,bar.profdata -weighted-input=1,baz.profdata -output merged.profdata
147
148.. program:: llvm-profdata show
149
150.. _profdata-show:
151
152SHOW
153----
154
155SYNOPSIS
156^^^^^^^^
157
158:program:`llvm-profdata show` [*options*] [*filename*]
159
160DESCRIPTION
161^^^^^^^^^^^
162
163:program:`llvm-profdata show` takes a profile data file and displays the
164information about the profile counters for this file and
165for any of the specified function(s).
166
167If *filename* is omitted or is ``-``, then **llvm-profdata show** reads its
168input from standard input.
169
170OPTIONS
171^^^^^^^
172
173.. option:: -all-functions
174
175 Print details for every function.
176
177.. option:: -counts
178
179 Print the counter values for the displayed functions.
180
181.. option:: -function=string
182
183 Print details for a function if the function's name contains the given string.
184
185.. option:: -help
186
187 Print a summary of command line options.
188
189.. option:: -output=output, -o=output
190
191 Specify the output file name.  If *output* is ``-`` or it isn't specified,
192 then the output is sent to standard output.
193
194.. option:: -instr (default)
195
196 Specify that the input profile is an instrumentation-based profile.
197
198.. option:: -text
199
200 Instruct the profile dumper to show profile counts in the text format of the
201 instrumentation-based profile data representation. By default, the profile
202 information is dumped in a more human readable form (also in text) with
203 annotations.
204
205.. option:: -topn=n
206
207 Instruct the profile dumper to show the top ``n`` functions with the
208 hottest basic blocks in the summary section. By default, the topn functions
209 are not dumped.
210
211.. option:: -sample
212
213 Specify that the input profile is a sample-based profile.
214
215.. option:: -memop-sizes
216
217 Show the profiled sizes of the memory intrinsic calls for shown functions.
218
219.. option:: -value-cutoff=n
220
221 Show only those functions whose max count values are greater or equal to ``n``.
222 By default, the value-cutoff is set to 0.
223
224.. option:: -list-below-cutoff
225
226 Only output names of functions whose max count value are below the cutoff
227 value.
228
229.. option:: -showcs
230 Only show context sensitive profile counts. The default is to filter all
231 context sensitive profile counts.
232
233EXIT STATUS
234-----------
235
236:program:`llvm-profdata` returns 1 if the command is omitted or is invalid,
237if it cannot read input files, or if there is a mismatch between their data.
238