Add flag to llvm-profdata to allow symbols in profile data to be remapped, and

add a tool to generate symbol remapping files.

Summary:
The new tool llvm-cxxmap builds a symbol mapping table from a file containing
a description of partial equivalences to apply to mangled names and files
containing old and new symbol tables.

Reviewers: davidxl

Subscribers: mgorny, llvm-commits

Differential Revision: https://reviews.llvm.org/D51470

llvm-svn: 342168

3 files changed, 102 insertions, 0 deletions

diff --git a/llvm/docs/CommandGuide/index.rst b/llvm/docs/CommandGuide/index.rst
index fca5a42608c..9108ae6a96b 100644
--- a/llvm/docs/CommandGuide/index.rst
+++ b/llvm/docs/CommandGuide/index.rst
@@ -25,6 +25,7 @@ Basic Commands
    llvm-nm
    llvm-objdump
    llvm-config
+   llvm-cxxmap
    llvm-diff
    llvm-cov
    llvm-profdata
diff --git a/llvm/docs/CommandGuide/llvm-cxxmap.rst b/llvm/docs/CommandGuide/llvm-cxxmap.rst
new file mode 100644
index 00000000000..7293f60b55d
--- /dev/null
+++ b/llvm/docs/CommandGuide/llvm-cxxmap.rst
@@ -0,0 +1,91 @@
+llvm-cxxmap - Mangled name remapping tool
+=========================================
+
+SYNOPSIS
+--------
+
+:program:`llvm-cxxmap` [*options*] *symbol-file-1* *symbol-file-2*
+
+DESCRIPTION
+-----------
+
+The :program:`llvm-cxxmap` tool performs fuzzy matching of C++ mangled names,
+based on a file describing name components that should be considered equivalent.
+
+The symbol files should contain a list of C++ mangled names (one per line).
+Blank lines and lines starting with ``#`` are ignored. The output is a list
+of pairs of equivalent symbols, one per line, of the form
+
+.. code-block:: none
+
+  <symbol-1> <symbol-2>
+
+where ``<symbol-1>`` is a symbol from *symbol-file-1* and ``<symbol-2>`` is
+a symbol from *symbol-file-2*. Mappings for which the two symbols are identical
+are omitted.
+
+OPTIONS
+-------
+
+.. program:: llvm-cxxmap
+
+.. option:: -remapping-file=file, -r=file
+
+ Specify a file containing a list of equivalence rules that should be used
+ to determine whether two symbols are equivalent. Required.
+ See :ref:`remapping-file`.
+
+.. option:: -output=file, -o=file
+
+ Specify a file to write the list of matched names to. If unspecified, the
+ list will be written to stdout.
+
+.. option:: -Wambiguous
+
+ Produce a warning if there are multiple equivalent (but distinct) symbols in
+ *symbol-file-2*.
+
+.. option:: -Wincomplete
+
+ Produce a warning if *symbol-file-1* contains a symbol for which there is no
+ equivalent symbol in *symbol-file-2*.
+
+.. _remapping-file:
+
+REMAPPING FILE
+--------------
+
+The remapping file is a text file containing lines of the form
+
+.. code-block:: none
+
+  fragmentkind fragment1 fragment2
+
+where ``fragmentkind`` is one of ``name``, ``type``, or ``encoding``,
+indicating whether the following mangled name fragments are
+<`name <http://itanium-cxx-abi.github.io/cxx-abi/abi.html#mangle.name>`_>s,
+<`type <http://itanium-cxx-abi.github.io/cxx-abi/abi.html#mangle.type>`_>s, or
+<`encoding <http://itanium-cxx-abi.github.io/cxx-abi/abi.html#mangle.encoding>`_>s,
+respectively.
+Blank lines and lines starting with ``#`` are ignored.
+
+For convenience, built-in <substitution>s such as ``St`` and ``Ss``
+are accepted as <name>s (even though they technically are not <name>s).
+
+For example, to specify that ``absl::string_view`` and ``std::string_view``
+should be treated as equivalent, the following remapping file could be used:
+
+.. code-block:: none
+
+  # absl::string_view is considered equivalent to std::string_view
+  type N4absl11string_viewE St17basic_string_viewIcSt11char_traitsIcEE
+
+  # std:: might be std::__1:: in libc++ or std::__cxx11:: in libstdc++
+  name St St3__1
+  name St St7__cxx11
+
+.. note::
+
+  Symbol remapping is currently only supported for C++ mangled names
+  following the Itanium C++ ABI mangling scheme. This covers all C++ targets
+  supported by Clang other than Windows targets.
diff --git a/llvm/docs/CommandGuide/llvm-profdata.rst b/llvm/docs/CommandGuide/llvm-profdata.rst
index 5b6330b5dc4..96c91e309d7 100644
--- a/llvm/docs/CommandGuide/llvm-profdata.rst
+++ b/llvm/docs/CommandGuide/llvm-profdata.rst
@@ -74,6 +74,16 @@ OPTIONS
   file are newline-separated. Lines starting with '#' are skipped. Entries may
   be of the form <filename> or <weight>,<filename>.
 
+.. option:: -remapping-file=path, -r=path
+
+  Specify a file which contains a remapping from symbol names in the input
+  profile to the symbol names that should be used in the output profile. The
+  file should consist of lines of the form ``<input-symbol> <output-symbol>``.
+  Blank lines and lines starting with ``#`` are skipped.
+
+  The :doc:`llvm-cxxmap <llvm-cxxmap>` tool can be used to generate the symbol
+  remapping file.
+
 .. option:: -instr (default)
 
  Specify that the input profile is an instrumentation-based profile.