include/llvm/Support/SymbolRemappingReader.h

   1 //===- SymbolRemappingReader.h - Read symbol remapping file -----*- C++ -*-===//
   2 //
   3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
   4 // See https://llvm.org/LICENSE.txt for license information.
   5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
   6 //
   7 //===----------------------------------------------------------------------===//
   8 //
   9 // This file contains definitions needed for reading and applying symbol
  10 // remapping files.
  11 //
  12 // Support is provided only for the Itanium C++ name mangling scheme for now.
  13 //
  14 // NOTE: If you are making changes to this file format, please remember
  15 //       to document them in the Clang documentation at
  16 //       tools/clang/docs/UsersManual.rst.
  17 //
  18 // File format
  19 // -----------
  20 //
  21 // The symbol remappings are written as an ASCII text file. Blank lines and
  22 // lines starting with a # are ignored. All other lines specify a kind of
  23 // mangled name fragment, along with two fragments of that kind that should
  24 // be treated as equivalent, separated by spaces.
  25 //
  26 // See http://itanium-cxx-abi.github.io/cxx-abi/abi.html#mangling for a
  27 // description of the Itanium name mangling scheme.
  28 //
  29 // The accepted fragment kinds are:
  30 //
  31 //  * name  A <name>, such as 6foobar or St3__1
  32 //  * type  A <type>, such as Ss or N4llvm9StringRefE
  33 //  * encoding  An <encoding> (a complete mangling without the leading _Z)
  34 //
  35 // For example:
  36 //
  37 // # Ignore int / long differences to treat symbols from 32-bit and 64-bit
  38 // # builds with differing size_t / ptrdiff_t / intptr_t as equivalent.
  39 // type i l
  40 // type j m
  41 //
  42 // # Ignore differences between libc++ and libstdc++, and between libstdc++'s
  43 // # C++98 and C++11 ABIs.
  44 // name 3std St3__1
  45 // name 3std St7__cxx11
  46 //
  47 // # Remap a function overload to a specialization of a template (including
  48 // # any local symbols declared within it).
  49 // encoding N2NS1fEi N2NS1fIiEEvT_
  50 //
  51 // # Substitutions must be remapped separately from namespace 'std' for now.
  52 // name Sa NSt3__19allocatorE
  53 // name Sb NSt3__112basic_stringE
  54 // type Ss NSt3__112basic_stringIcSt11char_traitsIcESaE
  55 // # ...
  56 //
  57 //===----------------------------------------------------------------------===//
  58
  59 #ifndef LLVM_SUPPORT_SYMBOLREMAPPINGREADER_H
  60 #define LLVM_SUPPORT_SYMBOLREMAPPINGREADER_H
  61
  62 #include "llvm/ADT/StringRef.h"
  63 #include "llvm/Support/Error.h"
  64 #include "llvm/Support/ItaniumManglingCanonicalizer.h"
  65 #include "llvm/Support/MemoryBuffer.h"
  66
  67 namespace llvm {
  68
  69 class SymbolRemappingParseError : public ErrorInfo<SymbolRemappingParseError> {
  70 public:
  71   SymbolRemappingParseError(StringRef File, int64_t Line, Twine Message)
  72       : File(File), Line(Line), Message(Message.str()) {}
  73
  74   void log(llvm::raw_ostream &OS) const override {
  75     OS << File << ':' << Line << ": " << Message;
  76   }
  77   std::error_code convertToErrorCode() const override {
  78     return llvm::inconvertibleErrorCode();
  79   }
  80
  81   StringRef getFileName() const { return File; }
  82   int64_t getLineNum() const { return Line; }
  83   StringRef getMessage() const { return Message; }
  84
  85   static char ID;
  86
  87 private:
  88   std::string File;
  89   int64_t Line;
  90   std::string Message;
  91 };
  92
  93 /// Reader for symbol remapping files.
  94 ///
  95 /// Remaps the symbol names in profile data to match those in the program
  96 /// according to a set of rules specified in a given file.
  97 class SymbolRemappingReader {
  98 public:
  99   /// Read remappings from the given buffer, which must live as long as
 100   /// the remapper.
 101   Error read(MemoryBuffer &B);
 102
 103   /// A Key represents an equivalence class of symbol names.
 104   using Key = uintptr_t;
 105
 106   /// Construct a key for the given symbol, or return an existing one if an
 107   /// equivalent name has already been inserted. The symbol name must live
 108   /// as long as the remapper.
 109   ///
 110   /// The result will be Key() if the name cannot be remapped (typically
 111   /// because it is not a valid mangled name).
 112   Key insert(StringRef FunctionName) {
 113     return Canonicalizer.canonicalize(FunctionName);
 114   }
 115
 116   /// Map the given symbol name into the key for the corresponding equivalence
 117   /// class.
 118   ///
 119   /// The result will typically be Key() if no equivalent symbol has been
 120   /// inserted, but this is not guaranteed: a Key different from all keys ever
 121   /// returned by \c insert may be returned instead.
 122   Key lookup(StringRef FunctionName) {
 123     return Canonicalizer.lookup(FunctionName);
 124   }
 125
 126 private:
 127   ItaniumManglingCanonicalizer Canonicalizer;
 128 };
 129
 130 } // end namespace llvm
 131
 132 #endif // LLVM_SUPPORT_SYMBOLREMAPPINGREADER_H