3 files changed, 221 insertions, 26 deletions
diff --git a/docs/CommandGuide/FileCheck.rst b/docs/CommandGuide/FileCheck.rst
index af01503..f48bf47 100644
--- a/docs/CommandGuide/FileCheck.rst
+++ b/docs/CommandGuide/FileCheck.rst
@@ -185,6 +185,31 @@ For example, something like this works as you'd expect:
 newline between it and the previous directive.  A "``CHECK-NEXT:``" cannot be
 the first directive in a file.
 
+The "CHECK-SAME:" directive
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Sometimes you want to match lines and would like to verify that matches happen
+on the same line as the previous match.  In this case, you can use "``CHECK:``"
+and "``CHECK-SAME:``" directives to specify this.  If you specified a custom
+check prefix, just use "``<PREFIX>-SAME:``".
+
+"``CHECK-SAME:``" is particularly powerful in conjunction with "``CHECK-NOT:``"
+(described below).
+
+For example, the following works like you'd expect:
+
+.. code-block:: llvm
+
+   !0 = !MDLocation(line: 5, scope: !1, inlinedAt: !2)
+
+   ; CHECK:       !MDLocation(line: 5,
+   ; CHECK-NOT:               column:
+   ; CHECK-SAME:              scope: ![[SCOPE:[0-9]+]]
+
+"``CHECK-SAME:``" directives reject the input if there are any newlines between
+it and the previous directive.  A "``CHECK-SAME:``" cannot be the first
+directive in a file.
+
 The "CHECK-NOT:" directive
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -339,7 +364,7 @@ simply uniquely match a single line in the file being verified.
 FileCheck Pattern Matching Syntax
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The "``CHECK:``" and "``CHECK-NOT:``" directives both take a pattern to match.
+All FileCheck directives take a pattern to match.
 For most uses of FileCheck, fixed string matching is perfectly sufficient.  For
 some things, a more flexible form of matching is desired.  To support this,
 FileCheck allows you to specify regular expressions in matching strings,
diff --git a/docs/CommandGuide/llvm-cov.rst b/docs/CommandGuide/llvm-cov.rst
index e0b2fe9..dff3375 100644
--- a/docs/CommandGuide/llvm-cov.rst
+++ b/docs/CommandGuide/llvm-cov.rst
@@ -4,18 +4,49 @@ llvm-cov - emit coverage information
 SYNOPSIS
 --------
 
-:program:`llvm-cov` [options] SOURCEFILE
+:program:`llvm-cov` *command* [*args...*]
 
 DESCRIPTION
 -----------
 
-The :program:`llvm-cov` tool reads code coverage data files and displays the
-coverage information for a specified source file. It is compatible with the
-``gcov`` tool from version 4.2 of ``GCC`` and may also be compatible with
-some later versions of ``gcov``.
+The :program:`llvm-cov` tool shows code coverage information for
+programs that are instrumented to emit profile data. It can be used to
+work with ``gcov``\-style coverage or with ``clang``\'s instrumentation
+based profiling.
 
-To use llvm-cov, you must first build an instrumented version of your
-application that collects coverage data as it runs. Compile with the
+If the program is invoked with a base name of ``gcov``, it will behave as if
+the :program:`llvm-cov gcov` command were called. Otherwise, a command should
+be provided.
+
+COMMANDS
+--------
+
+* :ref:`gcov <llvm-cov-gcov>`
+* :ref:`show <llvm-cov-show>`
+* :ref:`report <llvm-cov-report>`
+
+.. program:: llvm-cov gcov
+
+.. _llvm-cov-gcov:
+
+GCOV COMMAND
+------------
+
+SYNOPSIS
+^^^^^^^^
+
+:program:`llvm-cov gcov` [*options*] *SOURCEFILE*
+
+DESCRIPTION
+^^^^^^^^^^^
+
+The :program:`llvm-cov gcov` tool reads code coverage data files and displays
+the coverage information for a specified source file. It is compatible with the
+``gcov`` tool from version 4.2 of ``GCC`` and may also be compatible with some
+later versions of ``gcov``.
+
+To use :program:`llvm-cov gcov`, you must first build an instrumented version
+of your application that collects coverage data as it runs. Compile with the
 ``-fprofile-arcs`` and ``-ftest-coverage`` options to add the
 instrumentation. (Alternatively, you can use the ``--coverage`` option, which
 includes both of those other options.) You should compile with debugging
@@ -39,24 +70,23 @@ directories, the prefix from the ``GCOV_PREFIX`` variable is added. These
 environment variables allow you to run the instrumented program on a machine
 where the original object file directories are not accessible, but you will
 then need to copy the ``.gcda`` files back to the object file directories
-where llvm-cov expects to find them.
+where :program:`llvm-cov gcov` expects to find them.
 
-Once you have generated the coverage data files, run llvm-cov for each main
-source file where you want to examine the coverage results. This should be run
-from the same directory where you previously ran the compiler. The results for
-the specified source file are written to a file named by appending a ``.gcov``
-suffix. A separate output file is also created for each file included by the
-main source file, also with a ``.gcov`` suffix added.
+Once you have generated the coverage data files, run :program:`llvm-cov gcov`
+for each main source file where you want to examine the coverage results. This
+should be run from the same directory where you previously ran the
+compiler. The results for the specified source file are written to a file named
+by appending a ``.gcov`` suffix. A separate output file is also created for
+each file included by the main source file, also with a ``.gcov`` suffix added.
 
-The basic content of an llvm-cov output file is a copy of the source file with
+The basic content of an ``.gcov`` output file is a copy of the source file with
 an execution count and line number prepended to every line. The execution
 count is shown as ``-`` if a line does not contain any executable code. If
 a line contains code but that code was never executed, the count is displayed
 as ``#####``.
 
-
 OPTIONS
--------
+^^^^^^^
 
 .. option:: -a, --all-blocks
 
@@ -66,7 +96,7 @@ OPTIONS
 
 .. option:: -b, --branch-probabilities
 
- Display conditional branch probabilities and a summary of branch information. 
+ Display conditional branch probabilities and a summary of branch information.
 
 .. option:: -c, --branch-counts
 
@@ -120,8 +150,148 @@ OPTIONS
  Display the version of llvm-cov.
 
 EXIT STATUS
------------
+^^^^^^^^^^^
+
+:program:`llvm-cov gcov` returns 1 if it cannot read input files.  Otherwise,
+it exits with zero.
+
+
+.. program:: llvm-cov show
+
+.. _llvm-cov-show:
+
+SHOW COMMAND
+------------
+
+SYNOPSIS
+^^^^^^^^
+
+:program:`llvm-cov show` [*options*] -instr-profile *PROFILE* *BIN* [*SOURCES*]
+
+DESCRIPTION
+^^^^^^^^^^^
+
+The :program:`llvm-cov show` command shows line by line coverage of a binary
+*BIN* using the profile data *PROFILE*. It can optionally be filtered to only
+show the coverage for the files listed in *SOURCES*.
+
+To use :program:`llvm-cov show`, you need a program that's compiled with
+instrumentation to emit profile and coverage data. To build such a program with
+``clang`` use the ``-fprofile-instr-generate`` and ``-fcoverage-mapping``
+flags. If linking with the ``clang`` driver, pass ``-fprofile-instr-generate``
+to the link stage to make sure the necessary runtime libraries are linked in.
+
+The coverage information is stored in the built executable or library itself,
+and this is what you should pass to :program:`llvm-cov show` as the *BIN*
+argument. The profile data is generated by running this instrumented program
+normally. When the program exits it will write out a raw profile file,
+typically called ``default.profraw``, which can be converted to a format that
+is suitable for the *PROFILE* argument using the :program:`llvm-profdata merge`
+tool.
+
+OPTIONS
+^^^^^^^
+
+.. option:: -show-line-counts
+
+ Show the execution counts for each line. This is enabled by default, unless
+ another ``-show`` option is used.
+
+.. option:: -show-expansions
+
+ Expand inclusions, such as preprocessor macros or textual inclusions, inline
+ in the display of the source file.
+
+.. option:: -show-instantiations
+
+ For source regions that are instantiated multiple times, such as templates in
+ ``C++``, show each instantiation separately as well as the combined summary.
+
+.. option:: -show-regions
+
+ Show the execution counts for each region by displaying a caret that points to
+ the character where the region starts.
+
+.. option:: -show-line-counts-or-regions
+
+ Show the execution counts for each line if there is only one region on the
+ line, but show the individual regions if there are multiple on the line.
+
+.. option:: -use-color[=VALUE]
+
+ Enable or disable color output. By default this is autodetected.
+
+.. option:: -arch=<name>
+
+ If the covered binary is a universal binary, select the architecture to use
+ when looking up the coverage map. Errors out if the supplied architecture is
+ not found in the universal binary, or if used on a non-universal binary of
+ a different architecture.
+
+.. option:: -name=<NAME>
+
+ Show code coverage only for functions with the given name.
+
+.. option:: -name-regex=<PATTERN>
+
+ Show code coverage only for functions that match the given regular expression.
+
+.. option:: -line-coverage-gt=<N>
+
+ Show code coverage only for functions with line coverage greater than the
+ given threshold.
+
+.. option:: -line-coverage-lt=<N>
+
+ Show code coverage only for functions with line coverage less than the given
+ threshold.
+
+.. option:: -region-coverage-gt=<N>
+
+ Show code coverage only for functions with region coverage greater than the
+ given threshold.
+
+.. option:: -region-coverage-lt=<N>
+
+ Show code coverage only for functions with region coverage less than the given
+ threshold.
+
+.. program:: llvm-cov report
+
+.. _llvm-cov-report:
+
+REPORT COMMAND
+--------------
+
+SYNOPSIS
+^^^^^^^^
+
+:program:`llvm-cov report` [*options*] -instr-profile *PROFILE* *BIN* [*SOURCES*]
+
+DESCRIPTION
+^^^^^^^^^^^
+
+The :program:`llvm-cov report` command displays a summary of the coverage of a
+binary *BIN* using the profile data *PROFILE*. It can optionally be filtered to
+only show the coverage for the files listed in *SOURCES*.
+
+If no source files are provided, a summary line is printed for each file in the
+coverage data. If any files are provided, summaries are shown for each function
+in the listed files instead.
+
+For information on compiling programs for coverage and generating profile data,
+see :ref:`llvm-cov-show`.
+
+OPTIONS
+^^^^^^^
+
+.. option:: -use-color[=VALUE]
+
+ Enable or disable color output. By default this is autodetected.
 
-:program:`llvm-cov` returns 1 if it cannot read input files.  Otherwise, it
-exits with zero.
+.. option:: -arch=<name>
 
+ If the covered binary is a universal binary, select the architecture to use
+ when looking up the coverage map. Errors out if the supplied architecture is
+ not found in the universal binary, or if used on a non-universal binary of
+ a different architecture.
diff --git a/docs/CommandGuide/llvm-profdata.rst b/docs/CommandGuide/llvm-profdata.rst
index 0762e2c..45f7073 100644
--- a/docs/CommandGuide/llvm-profdata.rst
+++ b/docs/CommandGuide/llvm-profdata.rst
@@ -15,12 +15,12 @@ data files.
 COMMANDS
 --------
 
-* `merge <profdata_merge_>`_
-* `show <profdata_show_>`_
+* :ref:`merge <profdata-merge>`
+* :ref:`show <profdata-show>`
 
 .. program:: llvm-profdata merge
 
-.. _profdata_merge:
+.. _profdata-merge:
 
 MERGE
 -----
@@ -51,7 +51,7 @@ OPTIONS
 
 .. program:: llvm-profdata show
 
-.. _profdata_show:
+.. _profdata-show:
 
 SHOW
 ----