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
47
48OPTIONS
49^^^^^^^
50
51.. option:: -help
52
53 Print a summary of command line options.
54
55.. option:: -output=output, -o=output
56
57 Specify the output file name.  *Output* cannot be ``-`` as the resulting
58 indexed profile data can't be written to standard output.
59
60.. option:: -weighted-input=weight,filename
61
62 Specify an input file name along with a weight. The profile counts of the
63 supplied ``filename`` will be scaled (multiplied) by the supplied
64 ``weight``, where where ``weight`` is a decimal integer >= 1.
65 Input files specified without using this option are assigned a default
66 weight of 1. Examples are shown below.
67
68.. option:: -instr (default)
69
70 Specify that the input profile is an instrumentation-based profile.
71
72.. option:: -sample
73
74 Specify that the input profile is a sample-based profile.
75
76 The format of the generated file can be generated in one of three ways:
77
78 .. option:: -binary (default)
79
80 Emit the profile using a binary encoding. For instrumentation-based profile
81 the output format is the indexed binary format.
82
83 .. option:: -text
84
85 Emit the profile in text mode. This option can also be used with both
86 sample-based and instrumentation-based profile. When this option is used
87 the profile will be dumped in the text format that is parsable by the profile
88 reader.
89
90 .. option:: -gcc
91
92 Emit the profile using GCC's gcov format (Not yet supported).
93
94 .. option:: -sparse[=true|false]
95
96 Do not emit function records with 0 execution count. Can only be used in
97 conjunction with -instr. Defaults to false, since it can inhibit compiler
98 optimization during PGO.
99
100EXAMPLES
101^^^^^^^^
102Basic Usage
103+++++++++++
104Merge three profiles:
105
106::
107
108    llvm-profdata merge foo.profdata bar.profdata baz.profdata -output merged.profdata
109
110Weighted Input
111++++++++++++++
112The input file `foo.profdata` is especially important, multiply its counts by 10:
113
114::
115
116    llvm-profdata merge -weighted-input=10,foo.profdata bar.profdata baz.profdata -output merged.profdata
117
118Exactly equivalent to the previous invocation (explicit form; useful for programmatic invocation):
119
120::
121
122    llvm-profdata merge -weighted-input=10,foo.profdata -weighted-input=1,bar.profdata -weighted-input=1,baz.profdata -output merged.profdata
123
124.. program:: llvm-profdata show
125
126.. _profdata-show:
127
128SHOW
129----
130
131SYNOPSIS
132^^^^^^^^
133
134:program:`llvm-profdata show` [*options*] [*filename*]
135
136DESCRIPTION
137^^^^^^^^^^^
138
139:program:`llvm-profdata show` takes a profile data file and displays the
140information about the profile counters for this file and
141for any of the specified function(s).
142
143If *filename* is omitted or is ``-``, then **llvm-profdata show** reads its
144input from standard input.
145
146OPTIONS
147^^^^^^^
148
149.. option:: -all-functions
150
151 Print details for every function.
152
153.. option:: -counts
154
155 Print the counter values for the displayed functions.
156
157.. option:: -function=string
158
159 Print details for a function if the function's name contains the given string.
160
161.. option:: -help
162
163 Print a summary of command line options.
164
165.. option:: -output=output, -o=output
166
167 Specify the output file name.  If *output* is ``-`` or it isn't specified,
168 then the output is sent to standard output.
169
170.. option:: -instr (default)
171
172 Specify that the input profile is an instrumentation-based profile.
173
174.. option:: -text
175
176 Instruct the profile dumper to show profile counts in the text format of the
177 instrumentation-based profile data representation. By default, the profile
178 information is dumped in a more human readable form (also in text) with
179 annotations.
180
181.. option:: -sample
182
183 Specify that the input profile is a sample-based profile.
184
185EXIT STATUS
186-----------
187
188:program:`llvm-profdata` returns 1 if the command is omitted or is invalid,
189if it cannot read input files, or if there is a mismatch between their data.
190