1LLVM-PROFDATA(1) LLVM LLVM-PROFDATA(1)
2
6 llvm-profdata - Profile data tool
7
9 llvm-profdata command [args...]
10
12 The llvm-profdata tool is a small utility for working with profile data
13 files.
14
16 • merge
17 • show
19 • overlap
21
23 SYNOPSIS
24 llvm-profdata merge [options] [filename...]
25 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 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 Profiles passed in via -weighted-input, -input-files, or via positional
40 arguments are processed once for each time they are seen.
41 OPTIONS
43 -help Print a summary of command line options.
44 -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 -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 -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 -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 The llvm-cxxmap tool can be used to generate the symbol remap‐
70 ping file.
71 -instr (default)
73 Specify that the input profile is an instrumentation-based pro‐
74 file.
75 -sample
77 Specify that the input profile is a sample-based profile.
78 The format of the generated file can be generated in one of
80 three ways:
81 -binary (default)
83 Emit the profile using a binary encoding. For instrumenta‐
85 tion-based profile the output format is the indexed binary for‐
86 mat.
87 -text
89 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 -gcc
96 Emit the profile using GCC's gcov format (Not yet supported).
98 -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 -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 -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 EXAMPLES
118 Basic Usage
119 Merge three profiles:
120 llvm-profdata merge foo.profdata bar.profdata baz.profdata -output merged.profdata
122 Weighted Input
124 The input file foo.profdata is especially important, multiply its
125 counts by 10:
126 llvm-profdata merge -weighted-input=10,foo.profdata bar.profdata baz.profdata -output merged.profdata
128 Exactly equivalent to the previous invocation (explicit form; useful
130 for programmatic invocation):
131 llvm-profdata merge -weighted-input=10,foo.profdata -weighted-input=1,bar.profdata -weighted-input=1,baz.profdata -output merged.profdata
133
135 SYNOPSIS
136 llvm-profdata show [options] [filename]
137 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 If filename is omitted or is -, then llvm-profdata show reads its input
144 from standard input.
145 OPTIONS
147 -all-functions
148 Print details for every function.
149 -counts
151 Print the counter values for the displayed functions.
152 -function=string
154 Print details for a function if the function's name contains the
155 given string.
156 -help Print a summary of command line options.
158 -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 -instr (default)
164 Specify that the input profile is an instrumentation-based pro‐
165 file.
166 -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 -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 -sample
178 Specify that the input profile is a sample-based profile.
179 -memop-sizes
181 Show the profiled sizes of the memory intrinsic calls for shown
182 functions.
183 -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 -list-below-cutoff
189 Only output names of functions whose max count value are below
190 the cutoff value.
191 -showcs
193 Only show context sensitive profile counts. The default is to
194 filter all context sensitive profile counts.
195
197 SYNOPSIS
198 llvm-profdata overlap [options] [base profile file] [test profile file]
199 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 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 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 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 OPTIONS
225 -function=string
226 Print details for a function if the function's name contains the
227 given string.
228 -help Print a summary of command line options.
230 -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 -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 -cs Only show overlap for the context sensitive profile counts. The
241 default is to show non-context sensitive profile counts.
242
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
248 Maintained by the LLVM Team (https://llvm.org/).
249
251 2003-2021, LLVM Project
25210 2021-07-22 LLVM-PROFDATA(1)