docs/CommandGuide/llvm-profdata.rst

   1 llvm-profdata - Profile data tool
   2 =================================
   3
   4 .. program:: llvm-profdata
   5
   6 SYNOPSIS
   7 --------
   8
   9 :program:`llvm-profdata` *command* [*args...*]
  10
  11 DESCRIPTION
  12 -----------
  13
  14 The :program:`llvm-profdata` tool is a small utility for working with profile
  15 data files.
  16
  17 COMMANDS
  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
  28 MERGE
  29 -----
  30
  31 SYNOPSIS
  32 ^^^^^^^^
  33
  34 :program:`llvm-profdata merge` [*options*] [*filename...*]
  35
  36 DESCRIPTION
  37 ^^^^^^^^^^^
  38
  39 :program:`llvm-profdata merge` takes several profile data files
  40 generated by PGO instrumentation and merges them together into a single
  41 indexed profile data file.
  42
  43 By default profile data is merged without modification. This means that the
  44 relative importance of each input file is proportional to the number of samples
  45 or counts it contains. In general, the input from a longer training run will be
  46 interpreted as relatively more important than a shorter run. Depending on the
  47 nature of the training runs it may be useful to adjust the weight given to each
  48 input file by using the ``-weighted-input`` option.
  49
  50 Profiles passed in via ``-weighted-input``, ``-input-files``, or via positional
  51 arguments are processed once for each time they are seen.
  52
  53
  54 OPTIONS
  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 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:: -text
 106
 107  Emit the profile in text mode. This option can also be used with both
 108  sample-based and instrumentation-based profile. When this option is used
 109  the profile will be dumped in the text format that is parsable by the profile
 110  reader.
 111
 112  .. option:: -gcc
 113
 114  Emit the profile using GCC's gcov format (Not yet supported).
 115
 116 .. option:: -sparse[=true|false]
 117
 118  Do not emit function records with 0 execution count. Can only be used in
 119  conjunction with -instr. Defaults to false, since it can inhibit compiler
 120  optimization during PGO.
 121
 122 .. option:: -num-threads=N, -j=N
 123
 124  Use N threads to perform profile merging. When N=0, llvm-profdata auto-detects
 125  an appropriate number of threads to use. This is the default.
 126
 127 EXAMPLES
 128 ^^^^^^^^
 129 Basic Usage
 130 +++++++++++
 131 Merge three profiles:
 132
 133 ::
 134
 135     llvm-profdata merge foo.profdata bar.profdata baz.profdata -output merged.profdata
 136
 137 Weighted Input
 138 ++++++++++++++
 139 The input file `foo.profdata` is especially important, multiply its counts by 10:
 140
 141 ::
 142
 143     llvm-profdata merge -weighted-input=10,foo.profdata bar.profdata baz.profdata -output merged.profdata
 144
 145 Exactly equivalent to the previous invocation (explicit form; useful for programmatic invocation):
 146
 147 ::
 148
 149     llvm-profdata merge -weighted-input=10,foo.profdata -weighted-input=1,bar.profdata -weighted-input=1,baz.profdata -output merged.profdata
 150
 151 .. program:: llvm-profdata show
 152
 153 .. _profdata-show:
 154
 155 SHOW
 156 ----
 157
 158 SYNOPSIS
 159 ^^^^^^^^
 160
 161 :program:`llvm-profdata show` [*options*] [*filename*]
 162
 163 DESCRIPTION
 164 ^^^^^^^^^^^
 165
 166 :program:`llvm-profdata show` takes a profile data file and displays the
 167 information about the profile counters for this file and
 168 for any of the specified function(s).
 169
 170 If *filename* is omitted or is ``-``, then **llvm-profdata show** reads its
 171 input from standard input.
 172
 173 OPTIONS
 174 ^^^^^^^
 175
 176 .. option:: -all-functions
 177
 178  Print details for every function.
 179
 180 .. option:: -counts
 181
 182  Print the counter values for the displayed functions.
 183
 184 .. option:: -function=string
 185
 186  Print details for a function if the function's name contains the given string.
 187
 188 .. option:: -help
 189
 190  Print a summary of command line options.
 191
 192 .. option:: -output=output, -o=output
 193
 194  Specify the output file name.  If *output* is ``-`` or it isn't specified,
 195  then the output is sent to standard output.
 196
 197 .. option:: -instr (default)
 198
 199  Specify that the input profile is an instrumentation-based profile.
 200
 201 .. option:: -text
 202
 203  Instruct the profile dumper to show profile counts in the text format of the
 204  instrumentation-based profile data representation. By default, the profile
 205  information is dumped in a more human readable form (also in text) with
 206  annotations.
 207
 208 .. option:: -topn=n
 209
 210  Instruct the profile dumper to show the top ``n`` functions with the
 211  hottest basic blocks in the summary section. By default, the topn functions
 212  are not dumped.
 213
 214 .. option:: -sample
 215
 216  Specify that the input profile is a sample-based profile.
 217
 218 .. option:: -memop-sizes
 219
 220  Show the profiled sizes of the memory intrinsic calls for shown functions.
 221
 222 .. option:: -value-cutoff=n
 223
 224  Show only those functions whose max count values are greater or equal to ``n``.
 225  By default, the value-cutoff is set to 0.
 226
 227 .. option:: -list-below-cutoff
 228
 229  Only output names of functions whose max count value are below the cutoff
 230  value.
 231
 232 .. option:: -showcs
 233
 234  Only show context sensitive profile counts. The default is to filter all
 235  context sensitive profile counts.
 236
 237 .. program:: llvm-profdata overlap
 238
 239 .. _profdata-overlap:
 240
 241 OVERLAP
 242 -------
 243
 244 SYNOPSIS
 245 ^^^^^^^^
 246
 247 :program:`llvm-profdata overlap` [*options*] [*base profile file*] [*test profile file*]
 248
 249 DESCRIPTION
 250 ^^^^^^^^^^^
 251
 252 :program:`llvm-profdata overlap` takes two profile data files and displays the
 253 *overlap* of counter distribution between the whole files and between any of the
 254 specified functions.
 255
 256 In this command, *overlap* is defined as follows:
 257 Suppose *base profile file* has the following counts:
 258 {c1_1, c1_2, ..., c1_n, c1_u_1, c2_u_2, ..., c2_u_s},
 259 and *test profile file* has
 260 {c2_1, c2_2, ..., c2_n, c2_v_1, c2_v_2, ..., c2_v_t}.
 261 Here c{1|2}_i (i = 1 .. n) are matched counters and c1_u_i (i = 1 .. s) and
 262 c2_v_i (i = 1 .. v) are unmatched counters (or counters only existing in)
 263 *base profile file* and *test profile file*, respectively.
 264 Let sum_1 = c1_1 + c1_2 +  ... + c1_n +  c1_u_1 + c2_u_2 + ... + c2_u_s, and
 265 sum_2 = c2_1 + c2_2 + ... + c2_n + c2_v_1 + c2_v_2 + ... + c2_v_t.
 266 *overlap* = min(c1_1/sum_1, c2_1/sum_2) + min(c1_2/sum_1, c2_2/sum_2) + ...
 267 + min(c1_n/sum_1, c2_n/sum_2).
 268
 269 The result overlap distribution is a percentage number, ranging from 0.0% to
 270 100.0%, where 0.0% means there is no overlap and 100.0% means a perfect
 271 overlap.
 272
 273 Here is an example, if *base profile file* has counts of {400, 600}, and
 274 *test profile file* has matched counts of {60000, 40000}. The *overlap* is 80%.
 275
 276 OPTIONS
 277 ^^^^^^^
 278
 279 .. option:: -function=string
 280
 281  Print details for a function if the function's name contains the given string.
 282
 283 .. option:: -help
 284
 285  Print a summary of command line options.
 286
 287 .. option:: -o=output or -o output
 288
 289  Specify the output file name.  If *output* is ``-`` or it isn't specified,
 290  then the output is sent to standard output.
 291
 292 .. option:: -value-cutoff=n
 293
 294  Show only those functions whose max count values are greater or equal to ``n``.
 295  By default, the value-cutoff is set to max of unsigned long long.
 296
 297 .. option:: -cs
 298
 299  Only show overlap for the context sensitive profile counts. The default is to show
 300  non-context sensitive profile counts.
 301
 302 EXIT STATUS
 303 -----------
 304
 305 :program:`llvm-profdata` returns 1 if the command is omitted or is invalid,
 306 if it cannot read input files, or if there is a mismatch between their data.