docs/CommandGuide/llvm-profdata.rst

   1 llvm-profdata - Profile data tool
   2 =================================
   3
   4 SYNOPSIS
   5 --------
   6
   7 :program:`llvm-profdata` *command* [*args...*]
   8
   9 DESCRIPTION
  10 -----------
  11
  12 The :program:`llvm-profdata` tool is a small utility for working with profile
  13 data files.
  14
  15 COMMANDS
  16 --------
  17
  18 * :ref:`merge <profdata-merge>`
  19 * :ref:`show <profdata-show>`
  20
  21 .. program:: llvm-profdata merge
  22
  23 .. _profdata-merge:
  24
  25 MERGE
  26 -----
  27
  28 SYNOPSIS
  29 ^^^^^^^^
  30
  31 :program:`llvm-profdata merge` [*options*] [*filename...*]
  32
  33 DESCRIPTION
  34 ^^^^^^^^^^^
  35
  36 :program:`llvm-profdata merge` takes several profile data files
  37 generated by PGO instrumentation and merges them together into a single
  38 indexed profile data file.
  39
  40 By default profile data is merged without modification. This means that the
  41 relative importance of each input file is proportional to the number of samples
  42 or counts it contains. In general, the input from a longer training run will be
  43 interpreted as relatively more important than a shorter run. Depending on the
  44 nature of the training runs it may be useful to adjust the weight given to each
  45 input file by using the ``-weighted-input`` option.
  46
  47 Profiles passed in via ``-weighted-input``, ``-input-files``, or via positional
  48 arguments are processed once for each time they are seen.
  49
  50
  51 OPTIONS
  52 ^^^^^^^
  53
  54 .. option:: -help
  55
  56  Print a summary of command line options.
  57
  58 .. option:: -output=output, -o=output
  59
  60  Specify the output file name.  *Output* cannot be ``-`` as the resulting
  61  indexed profile data can't be written to standard output.
  62
  63 .. option:: -weighted-input=weight,filename
  64
  65  Specify an input file name along with a weight. The profile counts of the
  66  supplied ``filename`` will be scaled (multiplied) by the supplied
  67  ``weight``, where where ``weight`` is a decimal integer >= 1.
  68  Input files specified without using this option are assigned a default
  69  weight of 1. Examples are shown below.
  70
  71 .. option:: -input-files=path, -f=path
  72
  73   Specify a file which contains a list of files to merge. The entries in this
  74   file are newline-separated. Lines starting with '#' are skipped. Entries may
  75   be of the form <filename> or <weight>,<filename>.
  76
  77 .. option:: -remapping-file=path, -r=path
  78
  79   Specify a file which contains a remapping from symbol names in the input
  80   profile to the symbol names that should be used in the output profile. The
  81   file should consist of lines of the form ``<input-symbol> <output-symbol>``.
  82   Blank lines and lines starting with ``#`` are skipped.
  83
  84   The :doc:`llvm-cxxmap <llvm-cxxmap>` tool can be used to generate the symbol
  85   remapping file.
  86
  87 .. option:: -instr (default)
  88
  89  Specify that the input profile is an instrumentation-based profile.
  90
  91 .. option:: -sample
  92
  93  Specify that the input profile is a sample-based profile.
  94
  95  The format of the generated file can be generated in one of three ways:
  96
  97  .. option:: -binary (default)
  98
  99  Emit the profile using a binary encoding. For instrumentation-based profile
 100  the output format is the indexed binary format.
 101
 102  .. option:: -text
 103
 104  Emit the profile in text mode. This option can also be used with both
 105  sample-based and instrumentation-based profile. When this option is used
 106  the profile will be dumped in the text format that is parsable by the profile
 107  reader.
 108
 109  .. option:: -gcc
 110
 111  Emit the profile using GCC's gcov format (Not yet supported).
 112
 113 .. option:: -sparse[=true|false]
 114
 115  Do not emit function records with 0 execution count. Can only be used in
 116  conjunction with -instr. Defaults to false, since it can inhibit compiler
 117  optimization during PGO.
 118
 119 .. option:: -num-threads=N, -j=N
 120
 121  Use N threads to perform profile merging. When N=0, llvm-profdata auto-detects
 122  an appropriate number of threads to use. This is the default.
 123
 124 EXAMPLES
 125 ^^^^^^^^
 126 Basic Usage
 127 +++++++++++
 128 Merge three profiles:
 129
 130 ::
 131
 132     llvm-profdata merge foo.profdata bar.profdata baz.profdata -output merged.profdata
 133
 134 Weighted Input
 135 ++++++++++++++
 136 The input file `foo.profdata` is especially important, multiply its counts by 10:
 137
 138 ::
 139
 140     llvm-profdata merge -weighted-input=10,foo.profdata bar.profdata baz.profdata -output merged.profdata
 141
 142 Exactly equivalent to the previous invocation (explicit form; useful for programmatic invocation):
 143
 144 ::
 145
 146     llvm-profdata merge -weighted-input=10,foo.profdata -weighted-input=1,bar.profdata -weighted-input=1,baz.profdata -output merged.profdata
 147
 148 .. program:: llvm-profdata show
 149
 150 .. _profdata-show:
 151
 152 SHOW
 153 ----
 154
 155 SYNOPSIS
 156 ^^^^^^^^
 157
 158 :program:`llvm-profdata show` [*options*] [*filename*]
 159
 160 DESCRIPTION
 161 ^^^^^^^^^^^
 162
 163 :program:`llvm-profdata show` takes a profile data file and displays the
 164 information about the profile counters for this file and
 165 for any of the specified function(s).
 166
 167 If *filename* is omitted or is ``-``, then **llvm-profdata show** reads its
 168 input from standard input.
 169
 170 OPTIONS
 171 ^^^^^^^
 172
 173 .. option:: -all-functions
 174
 175  Print details for every function.
 176
 177 .. option:: -counts
 178
 179  Print the counter values for the displayed functions.
 180
 181 .. option:: -function=string
 182
 183  Print details for a function if the function's name contains the given string.
 184
 185 .. option:: -help
 186
 187  Print a summary of command line options.
 188
 189 .. option:: -output=output, -o=output
 190
 191  Specify the output file name.  If *output* is ``-`` or it isn't specified,
 192  then the output is sent to standard output.
 193
 194 .. option:: -instr (default)
 195
 196  Specify that the input profile is an instrumentation-based profile.
 197
 198 .. option:: -text
 199
 200  Instruct the profile dumper to show profile counts in the text format of the
 201  instrumentation-based profile data representation. By default, the profile
 202  information is dumped in a more human readable form (also in text) with
 203  annotations.
 204
 205 .. option:: -topn=n
 206
 207  Instruct the profile dumper to show the top ``n`` functions with the
 208  hottest basic blocks in the summary section. By default, the topn functions
 209  are not dumped.
 210
 211 .. option:: -sample
 212
 213  Specify that the input profile is a sample-based profile.
 214
 215 .. option:: -memop-sizes
 216
 217  Show the profiled sizes of the memory intrinsic calls for shown functions.
 218
 219 EXIT STATUS
 220 -----------
 221
 222 :program:`llvm-profdata` returns 1 if the command is omitted or is invalid,
 223 if it cannot read input files, or if there is a mismatch between their data.