1llvm-profdata - Profile data tool 2================================= 3 4.. program:: llvm-profdata 5 6SYNOPSIS 7-------- 8 9:program:`llvm-profdata` *command* [*args...*] 10 11DESCRIPTION 12----------- 13 14The :program:`llvm-profdata` tool is a small utility for working with profile 15data files. 16 17COMMANDS 18-------- 19 20* :ref:`merge <profdata-merge>` 21* :ref:`show <profdata-show>` 22* :ref:`overlap <profdata-overlap>` 23 24.. program:: llvm-profdata merge 25 26.. _profdata-merge: 27 28MERGE 29----- 30 31SYNOPSIS 32^^^^^^^^ 33 34:program:`llvm-profdata merge` [*options*] [*filename...*] 35 36DESCRIPTION 37^^^^^^^^^^^ 38 39:program:`llvm-profdata merge` takes several profile data files 40generated by PGO instrumentation and merges them together into a single 41indexed profile data file. 42 43By default profile data is merged without modification. This means that the 44relative importance of each input file is proportional to the number of samples 45or counts it contains. In general, the input from a longer training run will be 46interpreted as relatively more important than a shorter run. Depending on the 47nature of the training runs it may be useful to adjust the weight given to each 48input file by using the ``-weighted-input`` option. 49 50Profiles passed in via ``-weighted-input``, ``-input-files``, or via positional 51arguments are processed once for each time they are seen. 52 53 54OPTIONS 55^^^^^^^ 56 57.. option:: -help 58 59 Print a summary of command line options. 60 61.. option:: -output=output, -o=output 62 63 Specify the output file name. *Output* cannot be ``-`` as the resulting 64 indexed profile data can't be written to standard output. 65 66.. option:: -weighted-input=weight,filename 67 68 Specify an input file name along with a weight. The profile counts of the 69 supplied ``filename`` will be scaled (multiplied) by the supplied 70 ``weight``, where ``weight`` is a decimal integer >= 1. 71 Input files specified without using this option are assigned a default 72 weight of 1. Examples are shown below. 73 74.. option:: -input-files=path, -f=path 75 76 Specify a file which contains a list of files to merge. The entries in this 77 file are newline-separated. Lines starting with '#' are skipped. Entries may 78 be of the form <filename> or <weight>,<filename>. 79 80.. option:: -remapping-file=path, -r=path 81 82 Specify a file which contains a remapping from symbol names in the input 83 profile to the symbol names that should be used in the output profile. The 84 file should consist of lines of the form ``<input-symbol> <output-symbol>``. 85 Blank lines and lines starting with ``#`` are skipped. 86 87 The :doc:`llvm-cxxmap <llvm-cxxmap>` tool can be used to generate the symbol 88 remapping file. 89 90.. option:: -instr (default) 91 92 Specify that the input profile is an instrumentation-based profile. 93 94.. option:: -sample 95 96 Specify that the input profile is a sample-based profile. 97 98 The format of the generated file can be generated in one of three ways: 99 100 .. option:: -binary (default) 101 102 Emit the profile using a binary encoding. For instrumentation-based profile 103 the output format is the indexed binary format. 104 105 .. option:: -extbinary 106 107 Emit the profile using an extensible binary encoding. This option can only 108 be used with sample-based profile. The extensible binary encoding can be 109 more compact with compression enabled and can be loaded faster than the 110 default binary encoding. 111 112 .. option:: -text 113 114 Emit the profile in text mode. This option can also be used with both 115 sample-based and instrumentation-based profile. When this option is used 116 the profile will be dumped in the text format that is parsable by the profile 117 reader. 118 119 .. option:: -gcc 120 121 Emit the profile using GCC's gcov format (Not yet supported). 122 123.. option:: -sparse[=true|false] 124 125 Do not emit function records with 0 execution count. Can only be used in 126 conjunction with -instr. Defaults to false, since it can inhibit compiler 127 optimization during PGO. 128 129.. option:: -num-threads=N, -j=N 130 131 Use N threads to perform profile merging. When N=0, llvm-profdata auto-detects 132 an appropriate number of threads to use. This is the default. 133 134.. option:: -failure-mode=[any|all] 135 136 Set the failure mode. There are two options: 'any' causes the merge command to 137 fail if any profiles are invalid, and 'all' causes the merge command to fail 138 only if all profiles are invalid. If 'all' is set, information from any 139 invalid profiles is excluded from the final merged product. The default 140 failure mode is 'any'. 141 142.. option:: -prof-sym-list=path 143 144 Specify a file which contains a list of symbols to generate profile symbol 145 list in the profile. This option can only be used with sample-based profile 146 in extbinary format. The entries in this file are newline-separated. 147 148.. option:: -compress-all-sections=[true|false] 149 150 Compress all sections when writing the profile. This option can only be used 151 with sample-based profile in extbinary format. 152 153.. option:: -use-md5=[true|false] 154 155 Use MD5 to represent string in name table when writing the profile. 156 This option can only be used with sample-based profile in extbinary format. 157 158.. option:: -gen-partial-profile=[true|false] 159 160 Mark the profile to be a partial profile which only provides partial profile 161 coverage for the optimized target. This option can only be used with 162 sample-based profile in extbinary format. 163 164EXAMPLES 165^^^^^^^^ 166Basic Usage 167+++++++++++ 168Merge three profiles: 169 170:: 171 172 llvm-profdata merge foo.profdata bar.profdata baz.profdata -output merged.profdata 173 174Weighted Input 175++++++++++++++ 176The input file `foo.profdata` is especially important, multiply its counts by 10: 177 178:: 179 180 llvm-profdata merge -weighted-input=10,foo.profdata bar.profdata baz.profdata -output merged.profdata 181 182Exactly equivalent to the previous invocation (explicit form; useful for programmatic invocation): 183 184:: 185 186 llvm-profdata merge -weighted-input=10,foo.profdata -weighted-input=1,bar.profdata -weighted-input=1,baz.profdata -output merged.profdata 187 188.. program:: llvm-profdata show 189 190.. _profdata-show: 191 192SHOW 193---- 194 195SYNOPSIS 196^^^^^^^^ 197 198:program:`llvm-profdata show` [*options*] [*filename*] 199 200DESCRIPTION 201^^^^^^^^^^^ 202 203:program:`llvm-profdata show` takes a profile data file and displays the 204information about the profile counters for this file and 205for any of the specified function(s). 206 207If *filename* is omitted or is ``-``, then **llvm-profdata show** reads its 208input from standard input. 209 210OPTIONS 211^^^^^^^ 212 213.. option:: -all-functions 214 215 Print details for every function. 216 217.. option:: -counts 218 219 Print the counter values for the displayed functions. 220 221.. option:: -function=string 222 223 Print details for a function if the function's name contains the given string. 224 225.. option:: -help 226 227 Print a summary of command line options. 228 229.. option:: -output=output, -o=output 230 231 Specify the output file name. If *output* is ``-`` or it isn't specified, 232 then the output is sent to standard output. 233 234.. option:: -instr (default) 235 236 Specify that the input profile is an instrumentation-based profile. 237 238.. option:: -text 239 240 Instruct the profile dumper to show profile counts in the text format of the 241 instrumentation-based profile data representation. By default, the profile 242 information is dumped in a more human readable form (also in text) with 243 annotations. 244 245.. option:: -topn=n 246 247 Instruct the profile dumper to show the top ``n`` functions with the 248 hottest basic blocks in the summary section. By default, the topn functions 249 are not dumped. 250 251.. option:: -sample 252 253 Specify that the input profile is a sample-based profile. 254 255.. option:: -memop-sizes 256 257 Show the profiled sizes of the memory intrinsic calls for shown functions. 258 259.. option:: -value-cutoff=n 260 261 Show only those functions whose max count values are greater or equal to ``n``. 262 By default, the value-cutoff is set to 0. 263 264.. option:: -list-below-cutoff 265 266 Only output names of functions whose max count value are below the cutoff 267 value. 268 269.. option:: -showcs 270 271 Only show context sensitive profile counts. The default is to filter all 272 context sensitive profile counts. 273 274.. option:: -show-prof-sym-list=[true|false] 275 276 Show profile symbol list if it exists in the profile. This option is only 277 meaningful for sample-based profile in extbinary format. 278 279.. option:: -show-sec-info-only=[true|false] 280 281 Show basic information about each section in the profile. This option is 282 only meaningful for sample-based profile in extbinary format. 283 284.. program:: llvm-profdata overlap 285 286.. _profdata-overlap: 287 288OVERLAP 289------- 290 291SYNOPSIS 292^^^^^^^^ 293 294:program:`llvm-profdata overlap` [*options*] [*base profile file*] [*test profile file*] 295 296DESCRIPTION 297^^^^^^^^^^^ 298 299:program:`llvm-profdata overlap` takes two profile data files and displays the 300*overlap* of counter distribution between the whole files and between any of the 301specified functions. 302 303In this command, *overlap* is defined as follows: 304Suppose *base profile file* has the following counts: 305{c1_1, c1_2, ..., c1_n, c1_u_1, c2_u_2, ..., c2_u_s}, 306and *test profile file* has 307{c2_1, c2_2, ..., c2_n, c2_v_1, c2_v_2, ..., c2_v_t}. 308Here c{1|2}_i (i = 1 .. n) are matched counters and c1_u_i (i = 1 .. s) and 309c2_v_i (i = 1 .. v) are unmatched counters (or counters only existing in) 310*base profile file* and *test profile file*, respectively. 311Let sum_1 = c1_1 + c1_2 + ... + c1_n + c1_u_1 + c2_u_2 + ... + c2_u_s, and 312sum_2 = c2_1 + c2_2 + ... + c2_n + c2_v_1 + c2_v_2 + ... + c2_v_t. 313*overlap* = min(c1_1/sum_1, c2_1/sum_2) + min(c1_2/sum_1, c2_2/sum_2) + ... 314+ min(c1_n/sum_1, c2_n/sum_2). 315 316The result overlap distribution is a percentage number, ranging from 0.0% to 317100.0%, where 0.0% means there is no overlap and 100.0% means a perfect 318overlap. 319 320Here is an example, if *base profile file* has counts of {400, 600}, and 321*test profile file* has matched counts of {60000, 40000}. The *overlap* is 80%. 322 323OPTIONS 324^^^^^^^ 325 326.. option:: -function=string 327 328 Print details for a function if the function's name contains the given string. 329 330.. option:: -help 331 332 Print a summary of command line options. 333 334.. option:: -o=output or -o output 335 336 Specify the output file name. If *output* is ``-`` or it isn't specified, 337 then the output is sent to standard output. 338 339.. option:: -value-cutoff=n 340 341 Show only those functions whose max count values are greater or equal to ``n``. 342 By default, the value-cutoff is set to max of unsigned long long. 343 344.. option:: -cs 345 346 Only show overlap for the context sensitive profile counts. The default is to show 347 non-context sensitive profile counts. 348 349EXIT STATUS 350----------- 351 352:program:`llvm-profdata` returns 1 if the command is omitted or is invalid, 353if it cannot read input files, or if there is a mismatch between their data. 354