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
  48 OPTIONS
  49 ^^^^^^^
  50
  51 .. option:: -help
  52
  53  Print a summary of command line options.
  54
  55 .. option:: -output=output, -o=output
  56
  57  Specify the output file name.  *Output* cannot be ``-`` as the resulting
  58  indexed profile data can't be written to standard output.
  59
  60 .. option:: -weighted-input=weight,filename
  61
  62  Specify an input file name along with a weight. The profile counts of the input
  63  file will be scaled (multiplied) by the supplied ``weight``, where where ``weight``
  64  is a decimal integer >= 1. Input files specified without using this option are
  65  assigned a default weight of 1. Examples are shown below.
  66
  67 .. option:: -instr (default)
  68
  69  Specify that the input profile is an instrumentation-based profile.
  70
  71 .. option:: -sample
  72
  73  Specify that the input profile is a sample-based profile.
  74
  75  The format of the generated file can be generated in one of three ways:
  76
  77  .. option:: -binary (default)
  78
  79  Emit the profile using a binary encoding. For instrumentation-based profile
  80  the output format is the indexed binary format.
  81
  82  .. option:: -text
  83
  84  Emit the profile in text mode. This option can also be used with both
  85  sample-based and instrumentation-based profile. When this option is used
  86  the profile will be dumped in the text format that is parsable by the profile
  87  reader.
  88
  89  .. option:: -gcc
  90
  91  Emit the profile using GCC's gcov format (Not yet supported).
  92
  93 EXAMPLES
  94 ^^^^^^^^
  95 Basic Usage
  96 +++++++++++
  97 Merge three profiles:
  98
  99 ::
 100
 101     llvm-profdata merge foo.profdata bar.profdata baz.profdata -output merged.profdata
 102
 103 Weighted Input
 104 ++++++++++++++
 105 The input file `foo.profdata` is especially important, multiply its counts by 10:
 106
 107 ::
 108
 109     llvm-profdata merge -weighted-input=10,foo.profdata bar.profdata baz.profdata -output merged.profdata
 110
 111 Exactly equivalent to the previous invocation (explicit form; useful for programmatic invocation):
 112
 113 ::
 114
 115     llvm-profdata merge -weighted-input=10,foo.profdata -weighted-input=1,bar.profdata -weighted-input=1,baz.profdata -output merged.profdata
 116
 117 .. program:: llvm-profdata show
 118
 119 .. _profdata-show:
 120
 121 SHOW
 122 ----
 123
 124 SYNOPSIS
 125 ^^^^^^^^
 126
 127 :program:`llvm-profdata show` [*options*] [*filename*]
 128
 129 DESCRIPTION
 130 ^^^^^^^^^^^
 131
 132 :program:`llvm-profdata show` takes a profile data file and displays the
 133 information about the profile counters for this file and
 134 for any of the specified function(s).
 135
 136 If *filename* is omitted or is ``-``, then **llvm-profdata show** reads its
 137 input from standard input.
 138
 139 OPTIONS
 140 ^^^^^^^
 141
 142 .. option:: -all-functions
 143
 144  Print details for every function.
 145
 146 .. option:: -counts
 147
 148  Print the counter values for the displayed functions.
 149
 150 .. option:: -function=string
 151
 152  Print details for a function if the function's name contains the given string.
 153
 154 .. option:: -help
 155
 156  Print a summary of command line options.
 157
 158 .. option:: -output=output, -o=output
 159
 160  Specify the output file name.  If *output* is ``-`` or it isn't specified,
 161  then the output is sent to standard output.
 162
 163 .. option:: -instr (default)
 164
 165  Specify that the input profile is an instrumentation-based profile.
 166
 167 .. option:: -text
 168
 169  Instruct the profile dumper to show profile counts in the text format of the
 170  instrumentation-based profile data representation. By default, the profile
 171  information is dumped in a more human readable form (also in text) with
 172  annotations.
 173
 174 .. option:: -sample
 175
 176  Specify that the input profile is a sample-based profile.
 177
 178 EXIT STATUS
 179 -----------
 180
 181 :program:`llvm-profdata` returns 1 if the command is omitted or is invalid,
 182 if it cannot read input files, or if there is a mismatch between their data.