[llvm-profdata] Add support for weighted merge of profile data (2nd try)

[oota-llvm.git] / docs / CommandGuide / llvm-profdata.rst

diff --git a/docs/CommandGuide/llvm-profdata.rst b/docs/CommandGuide/llvm-profdata.rst
index 210826a7babcd5a26059bb0261ae76fece5341e9..74fe4ee9d21941e56d7654a21c4da507b633052b 100644 (file)
--- a/docs/CommandGuide/llvm-profdata.rst
+++ b/docs/CommandGuide/llvm-profdata.rst
@@ -28,7 +28,7 @@ MERGE
 SYNOPSIS
 ^^^^^^^^
 
-:program:`llvm-profdata merge` [*options*] [*filenames...*]
+:program:`llvm-profdata merge` [*options*] [*filename...*]
 
 DESCRIPTION
 ^^^^^^^^^^^
@@ -37,6 +37,14 @@ DESCRIPTION
 generated by PGO instrumentation and merges them together into a single
 indexed profile data file.
 
+By default profile data is merged without modification. This means that the
+relative importance of each input file is proportional to the number of samples
+or counts it contains. In general, the input from a longer training run will be
+interpreted as relatively more important than a shorter run. Depending on the
+nature of the training runs it may be useful to adjust the weight given to each
+input file by using the ``-weighted-input`` option.
+
+
 OPTIONS
 ^^^^^^^
 
@@ -49,6 +57,13 @@ OPTIONS
  Specify the output file name.  *Output* cannot be ``-`` as the resulting
  indexed profile data can't be written to standard output.
 
+.. option:: -weighted-input=weight,filename
+
+ Specify an input file name along with a weight. The profile counts of the input
+ file will be scaled (multiplied) by the supplied ``weight``, where where ``weight``
+ is a decimal integer >= 1. Input files specified without using this option are
+ assigned a default weight of 1. Examples are shown below.
+
 .. option:: -instr (default)
 
  Specify that the input profile is an instrumentation-based profile.
@@ -75,6 +90,30 @@ OPTIONS
 
  Emit the profile using GCC's gcov format (Not yet supported).
 
+EXAMPLES
+^^^^^^^^
+Basic Usage
++++++++++++
+Merge three profiles:
+
+::
+
+    llvm-profdata merge foo.profdata bar.profdata baz.profdata -output merged.profdata
+
+Weighted Input
+++++++++++++++
+The input file `foo.profdata` is especially important, multiply its counts by 10:
+
+::
+
+    llvm-profdata merge -weighted-input=10,foo.profdata bar.profdata baz.profdata -output merged.profdata
+
+Exactly equivalent to the previous invocation (explicit form; useful for programmatic invocation):
+
+::
+
+    llvm-profdata merge -weighted-input=10,foo.profdata -weighted-input=1,bar.profdata -weighted-input=1,baz.profdata -output merged.profdata
+
 .. program:: llvm-profdata show
 
 .. _profdata-show: