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* :ref:`order <profdata-order>` 24 25.. program:: llvm-profdata merge 26 27.. _profdata-merge: 28 29MERGE 30----- 31 32SYNOPSIS 33^^^^^^^^ 34 35:program:`llvm-profdata merge` [*options*] [*filename...*] 36 37DESCRIPTION 38^^^^^^^^^^^ 39 40:program:`llvm-profdata merge` takes several profile data files 41generated by PGO instrumentation and merges them together into a single 42indexed profile data file. 43 44By default profile data is merged without modification. This means that the 45relative importance of each input file is proportional to the number of samples 46or counts it contains. In general, the input from a longer training run will be 47interpreted as relatively more important than a shorter run. Depending on the 48nature of the training runs it may be useful to adjust the weight given to each 49input file by using the ``-weighted-input`` option. 50 51Profiles passed in via ``-weighted-input``, ``-input-files``, or via positional 52arguments are processed once for each time they are seen. 53 54 55OPTIONS 56^^^^^^^ 57 58.. option:: --help 59 60 Print a summary of command line options. 61 62.. option:: --output=<output>, -o 63 64 Specify the output file name. *Output* cannot be ``-`` as the resulting 65 indexed profile data can't be written to standard output. 66 67.. option:: --weighted-input=<weight,filename> 68 69 Specify an input file name along with a weight. The profile counts of the 70 supplied ``filename`` will be scaled (multiplied) by the supplied 71 ``weight``, where ``weight`` is a decimal integer >= 1. 72 Input files specified without using this option are assigned a default 73 weight of 1. Examples are shown below. 74 75.. option:: --input-files=<path>, -f 76 77 Specify a file which contains a list of files to merge. The entries in this 78 file are newline-separated. Lines starting with '#' are skipped. Entries may 79 be of the form <filename> or <weight>,<filename>. 80 81.. option:: --remapping-file=<path>, -r 82 83 Specify a file which contains a remapping from symbol names in the input 84 profile to the symbol names that should be used in the output profile. The 85 file should consist of lines of the form ``<input-symbol> <output-symbol>``. 86 Blank lines and lines starting with ``#`` are skipped. 87 88 The :doc:`llvm-cxxmap <llvm-cxxmap>` tool can be used to generate the symbol 89 remapping file. 90 91.. option:: --instr (default) 92 93 Specify that the input profile is an instrumentation-based profile. 94 95.. option:: --sample 96 97 Specify that the input profile is a sample-based profile. 98 99 The format of the generated file can be generated in one of three ways: 100 101 .. option:: --binary (default) 102 103 Emit the profile using a binary encoding. For instrumentation-based profile 104 the output format is the indexed binary format. 105 106 .. option:: --extbinary 107 108 Emit the profile using an extensible binary encoding. This option can only 109 be used with sample-based profile. The extensible binary encoding can be 110 more compact with compression enabled and can be loaded faster than the 111 default binary encoding. 112 113 .. option:: --text 114 115 Emit the profile in text mode. This option can also be used with both 116 sample-based and instrumentation-based profile. When this option is used 117 the profile will be dumped in the text format that is parsable by the profile 118 reader. 119 120 .. option:: --gcc 121 122 Emit the profile using GCC's gcov format (Not yet supported). 123 124.. option:: --sparse[=true|false] 125 126 Do not emit function records with 0 execution count. Can only be used in 127 conjunction with -instr. Defaults to false, since it can inhibit compiler 128 optimization during PGO. 129 130.. option:: --num-threads=<N>, -j 131 132 Use N threads to perform profile merging. When N=0, llvm-profdata auto-detects 133 an appropriate number of threads to use. This is the default. 134 135.. option:: --failure-mode=[any|all] 136 137 Set the failure mode. There are two options: 'any' causes the merge command to 138 fail if any profiles are invalid, and 'all' causes the merge command to fail 139 only if all profiles are invalid. If 'all' is set, information from any 140 invalid profiles is excluded from the final merged product. The default 141 failure mode is 'any'. 142 143.. option:: --prof-sym-list=<path> 144 145 Specify a file which contains a list of symbols to generate profile symbol 146 list in the profile. This option can only be used with sample-based profile 147 in extbinary format. The entries in this file are newline-separated. 148 149.. option:: --compress-all-sections=[true|false] 150 151 Compress all sections when writing the profile. This option can only be used 152 with sample-based profile in extbinary format. 153 154.. option:: --use-md5=[true|false] 155 156 Use MD5 to represent string in name table when writing the profile. 157 This option can only be used with sample-based profile in extbinary format. 158 159.. option:: --gen-partial-profile=[true|false] 160 161 Mark the profile to be a partial profile which only provides partial profile 162 coverage for the optimized target. This option can only be used with 163 sample-based profile in extbinary format. 164 165.. option:: --split-layout=[true|false] 166 167 Split the profile data section to two with one containing sample profiles with 168 inlined functions and the other not. This option can only be used with 169 sample-based profile in extbinary format. 170 171.. option:: --convert-sample-profile-layout=[nest|flat] 172 173 Convert the merged profile into a profile with a new layout. Supported 174 layout are ``nest`` (Nested profile, the input should be CS flat profile) and 175 ``flat`` (Profile with nested inlinees flattened out). 176 177.. option:: --supplement-instr-with-sample=<file> 178 179 Supplement an instrumentation profile with sample profile. The sample profile 180 is the input of the flag. Output will be in instrumentation format (only works 181 with -instr). 182 183.. option:: --zero-counter-threshold=<float> 184 185 For the function which is cold in instr profile but hot in sample profile, if 186 the ratio of the number of zero counters divided by the total number of 187 counters is above the threshold, the profile of the function will be regarded 188 as being harmful for performance and will be dropped. 189 190.. option:: --instr-prof-cold-threshold=<int> 191 192 User specified cold threshold for instr profile which will override the cold 193 threshold got from profile summary. 194 195.. option:: --suppl-min-size-threshold=<int> 196 197 If the size of a function is smaller than the threshold, assume it can be 198 inlined by PGO early inliner and it will not be adjusted based on sample 199 profile. 200 201.. option:: --debug-info=<path> 202 203 Specify the executable or ``.dSYM`` that contains debug info for the raw profile. 204 When ``--debug-info-correlate`` or ``--profile-correlate=debug-info`` was used 205 for instrumentation, use this option to correlate the raw profile. 206 207.. option:: --binary-file=<path> 208 209 Specify the executable that contains profile data and profile name sections for 210 the raw profile. When ``-profile-correlate=binary`` was used for 211 instrumentation, use this option to correlate the raw profile. 212 213.. option:: --debuginfod 214 215 Use debuginfod to find the associated executables that contain profile data and 216 name sections for the raw profiles to correlate them. 217 When -profile-correlate=binary was used for instrumentation, this option can be 218 used for correlation. 219 220.. option:: --debug-file-directory=<dir> 221 222 Use provided local directories to search for executables that contain profile 223 data and name sections for the raw profiles to correlate them. 224 When -profile-correlate=binary was used for instrumentation, this option can be 225 used for correlation. 226 227.. option:: --correlate=<kind> 228 229 Specify the correlation kind (debug_info or binary) to use when -debuginfod or 230 -debug-file-directory=<dir> option is provided. 231 232.. option:: --temporal-profile-trace-reservoir-size 233 234 The maximum number of temporal profile traces to be stored in the output 235 profile. If more traces are added, we will use reservoir sampling to select 236 which traces to keep. Note that changing this value between different merge 237 invocations on the same indexed profile could result in sample bias. The 238 default value is 100. 239 240.. option:: --temporal-profile-max-trace-length 241 242 The maximum number of functions in a single temporal profile trace. Longer 243 traces will be truncated. The default value is 1000. 244 245.. option:: --function=<string> 246 247 Only keep functions matching the regex in the output, all others are erased 248 from the profile. 249 250.. option:: --no-function=<string> 251 252 Remove functions matching the regex from the profile. If both --function and 253 --no-function are specified and a function matches both, it is removed. 254 255EXAMPLES 256^^^^^^^^ 257Basic Usage 258+++++++++++ 259Merge three profiles: 260 261:: 262 263 llvm-profdata merge foo.profdata bar.profdata baz.profdata -output merged.profdata 264 265Weighted Input 266++++++++++++++ 267The input file ``foo.profdata`` is especially important, multiply its counts by 10: 268 269:: 270 271 llvm-profdata merge --weighted-input=10,foo.profdata bar.profdata baz.profdata --output merged.profdata 272 273Exactly equivalent to the previous invocation (explicit form; useful for programmatic invocation): 274 275:: 276 277 llvm-profdata merge --weighted-input=10,foo.profdata --weighted-input=1,bar.profdata --weighted-input=1,baz.profdata --output merged.profdata 278 279.. program:: llvm-profdata show 280 281.. _profdata-show: 282 283SHOW 284---- 285 286SYNOPSIS 287^^^^^^^^ 288 289:program:`llvm-profdata show` [*options*] [*filename*] 290 291DESCRIPTION 292^^^^^^^^^^^ 293 294:program:`llvm-profdata show` takes a profile data file and displays the 295information about the profile counters for this file and 296for any of the specified function(s). 297 298If *filename* is omitted or is ``-``, then **llvm-profdata show** reads its 299input from standard input. 300 301OPTIONS 302^^^^^^^ 303 304.. option:: --all-functions 305 306 Print details for every function. 307 308.. option:: --binary-ids 309 310 Print embedded binary ids in a profile. 311 312.. option:: --counts 313 314 Print the counter values for the displayed functions. 315 316.. option:: --show-format=<text|json|yaml> 317 318 Emit output in the selected format if supported by the provided profile type. 319 320.. option:: --function=<string> 321 322 Print details for a function if the function's name contains the given string. 323 324.. option:: --help 325 326 Print a summary of command line options. 327 328.. option:: --output=<output>, -o 329 330 Specify the output file name. If *output* is ``-`` or it isn't specified, 331 then the output is sent to standard output. 332 333.. option:: --instr (default) 334 335 Specify that the input profile is an instrumentation-based profile. 336 337.. option:: --text 338 339 Instruct the profile dumper to show profile counts in the text format of the 340 instrumentation-based profile data representation. By default, the profile 341 information is dumped in a more human readable form (also in text) with 342 annotations. 343 344.. option:: --topn=<n> 345 346 Instruct the profile dumper to show the top ``n`` functions with the 347 hottest basic blocks in the summary section. By default, the topn functions 348 are not dumped. 349 350.. option:: --sample 351 352 Specify that the input profile is a sample-based profile. 353 354.. option:: --memop-sizes 355 356 Show the profiled sizes of the memory intrinsic calls for shown functions. 357 358.. option:: --value-cutoff=<n> 359 360 Show only those functions whose max count values are greater or equal to ``n``. 361 By default, the value-cutoff is set to 0. 362 363.. option:: --list-below-cutoff 364 365 Only output names of functions whose max count value are below the cutoff 366 value. 367 368.. option:: --profile-version 369 370 Print profile version. 371 372.. option:: --showcs 373 374 Only show context sensitive profile counts. The default is to filter all 375 context sensitive profile counts. 376 377.. option:: --show-prof-sym-list=[true|false] 378 379 Show profile symbol list if it exists in the profile. This option is only 380 meaningful for sample-based profile in extbinary format. 381 382.. option:: --show-sec-info-only=[true|false] 383 384 Show basic information about each section in the profile. This option is 385 only meaningful for sample-based profile in extbinary format. 386 387.. option:: --debug-info=<path> 388 389 Specify the executable or ``.dSYM`` that contains debug info for the raw profile. 390 When ``--debug-info-correlate`` or ``--profile-correlate=debug-info`` was used 391 for instrumentation, use this option to show the correlated functions from the 392 raw profile. 393 394.. option:: --covered 395 396 Show only the functions that have been executed, i.e., functions with non-zero 397 counts. 398 399.. program:: llvm-profdata overlap 400 401.. _profdata-overlap: 402 403OVERLAP 404------- 405 406SYNOPSIS 407^^^^^^^^ 408 409:program:`llvm-profdata overlap` [*options*] [*base profile file*] [*test profile file*] 410 411DESCRIPTION 412^^^^^^^^^^^ 413 414:program:`llvm-profdata overlap` takes two profile data files and displays the 415*overlap* of counter distribution between the whole files and between any of the 416specified functions. 417 418In this command, *overlap* is defined as follows: 419Suppose *base profile file* has the following counts: 420{c1_1, c1_2, ..., c1_n, c1_u_1, c2_u_2, ..., c2_u_s}, 421and *test profile file* has 422{c2_1, c2_2, ..., c2_n, c2_v_1, c2_v_2, ..., c2_v_t}. 423Here c{1|2}_i (i = 1 .. n) are matched counters and c1_u_i (i = 1 .. s) and 424c2_v_i (i = 1 .. v) are unmatched counters (or counters only existing in) 425*base profile file* and *test profile file*, respectively. 426Let sum_1 = c1_1 + c1_2 + ... + c1_n + c1_u_1 + c2_u_2 + ... + c2_u_s, and 427sum_2 = c2_1 + c2_2 + ... + c2_n + c2_v_1 + c2_v_2 + ... + c2_v_t. 428*overlap* = min(c1_1/sum_1, c2_1/sum_2) + min(c1_2/sum_1, c2_2/sum_2) + ... 429+ min(c1_n/sum_1, c2_n/sum_2). 430 431The result overlap distribution is a percentage number, ranging from 0.0% to 432100.0%, where 0.0% means there is no overlap and 100.0% means a perfect 433overlap. 434 435Here is an example, if *base profile file* has counts of {400, 600}, and 436*test profile file* has matched counts of {60000, 40000}. The *overlap* is 80%. 437 438OPTIONS 439^^^^^^^ 440 441.. option:: --function=<string> 442 443 Print details for a function if the function's name contains the given string. 444 445.. option:: --help 446 447 Print a summary of command line options. 448 449.. option:: --output=<output>, -o 450 451 Specify the output file name. If *output* is ``-`` or it isn't specified, 452 then the output is sent to standard output. 453 454.. option:: --value-cutoff=<n> 455 456 Show only those functions whose max count values are greater or equal to ``n``. 457 By default, the value-cutoff is set to max of unsigned long long. 458 459.. option:: --cs 460 461 Only show overlap for the context sensitive profile counts. The default is to show 462 non-context sensitive profile counts. 463 464.. program:: llvm-profdata order 465 466.. _profdata-order: 467 468ORDER 469------- 470 471SYNOPSIS 472^^^^^^^^ 473 474:program:`llvm-profdata order` [*options*] [*filename*] 475 476DESCRIPTION 477^^^^^^^^^^^ 478 479:program:`llvm-profdata order` uses temporal profiling traces from a profile and 480finds a function order that reduces the number of page faults for those traces. 481This output can be directly passed to ``lld`` via ``--symbol-ordering-file=`` 482for ELF or ``-order-file`` for Mach-O. If the traces found in the profile are 483representative of the real world, then this order should improve startup 484performance. 485 486OPTIONS 487^^^^^^^ 488 489.. option:: --help 490 491 Print a summary of command line options. 492 493.. option:: --output=<output>, -o 494 495 Specify the output file name. If *output* is ``-`` or it isn't specified, 496 then the output is sent to standard output. 497 498EXIT STATUS 499----------- 500 501:program:`llvm-profdata` returns 1 if the command is omitted or is invalid, 502if it cannot read input files, or if there is a mismatch between their data. 503