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:: -instr (default)
78
79 Specify that the input profile is an instrumentation-based profile.
80
81.. option:: -sample
82
83 Specify that the input profile is a sample-based profile.
84
85 The format of the generated file can be generated in one of three ways:
86
87 .. option:: -binary (default)
88
89 Emit the profile using a binary encoding. For instrumentation-based profile
90 the output format is the indexed binary format.
91
92 .. option:: -text
93
94 Emit the profile in text mode. This option can also be used with both
95 sample-based and instrumentation-based profile. When this option is used
96 the profile will be dumped in the text format that is parsable by the profile
97 reader.
98
99 .. option:: -gcc
100
101 Emit the profile using GCC's gcov format (Not yet supported).
102
103.. option:: -sparse[=true|false]
104
105 Do not emit function records with 0 execution count. Can only be used in
106 conjunction with -instr. Defaults to false, since it can inhibit compiler
107 optimization during PGO.
108
109.. option:: -num-threads=N, -j=N
110
111 Use N threads to perform profile merging. When N=0, llvm-profdata auto-detects
112 an appropriate number of threads to use. This is the default.
113
114EXAMPLES
115^^^^^^^^
116Basic Usage
117+++++++++++
118Merge three profiles:
119
120::
121
122    llvm-profdata merge foo.profdata bar.profdata baz.profdata -output merged.profdata
123
124Weighted Input
125++++++++++++++
126The input file `foo.profdata` is especially important, multiply its counts by 10:
127
128::
129
130    llvm-profdata merge -weighted-input=10,foo.profdata bar.profdata baz.profdata -output merged.profdata
131
132Exactly equivalent to the previous invocation (explicit form; useful for programmatic invocation):
133
134::
135
136    llvm-profdata merge -weighted-input=10,foo.profdata -weighted-input=1,bar.profdata -weighted-input=1,baz.profdata -output merged.profdata
137
138.. program:: llvm-profdata show
139
140.. _profdata-show:
141
142SHOW
143----
144
145SYNOPSIS
146^^^^^^^^
147
148:program:`llvm-profdata show` [*options*] [*filename*]
149
150DESCRIPTION
151^^^^^^^^^^^
152
153:program:`llvm-profdata show` takes a profile data file and displays the
154information about the profile counters for this file and
155for any of the specified function(s).
156
157If *filename* is omitted or is ``-``, then **llvm-profdata show** reads its
158input from standard input.
159
160OPTIONS
161^^^^^^^
162
163.. option:: -all-functions
164
165 Print details for every function.
166
167.. option:: -counts
168
169 Print the counter values for the displayed functions.
170
171.. option:: -function=string
172
173 Print details for a function if the function's name contains the given string.
174
175.. option:: -help
176
177 Print a summary of command line options.
178
179.. option:: -output=output, -o=output
180
181 Specify the output file name.  If *output* is ``-`` or it isn't specified,
182 then the output is sent to standard output.
183
184.. option:: -instr (default)
185
186 Specify that the input profile is an instrumentation-based profile.
187
188.. option:: -text
189
190 Instruct the profile dumper to show profile counts in the text format of the
191 instrumentation-based profile data representation. By default, the profile
192 information is dumped in a more human readable form (also in text) with
193 annotations.
194
195.. option:: -topn=n
196
197 Instruct the profile dumper to show the top ``n`` functions with the
198 hottest basic blocks in the summary section. By default, the topn functions
199 are not dumped.
200
201.. option:: -sample
202
203 Specify that the input profile is a sample-based profile.
204
205.. option:: -memop-sizes
206
207 Show the profiled sizes of the memory intrinsic calls for shown functions.
208
209EXIT STATUS
210-----------
211
212:program:`llvm-profdata` returns 1 if the command is omitted or is invalid,
213if it cannot read input files, or if there is a mismatch between their data.
214