tools/dsymutil/DebugMap.h

   1 //=- tools/dsymutil/DebugMap.h - Generic debug map representation -*- C++ -*-=//
   2 //
   3 //                             The LLVM Linker
   4 //
   5 // This file is distributed under the University of Illinois Open Source
   6 // License. See LICENSE.TXT for details.
   7 //
   8 //===----------------------------------------------------------------------===//
   9 //
  10 /// \file
  11 ///
  12 /// This file contains the class declaration of the DebugMap
  13 /// entity. A DebugMap lists all the object files linked together to
  14 /// produce an executable along with the linked address of all the
  15 /// atoms used in these object files.
  16 /// The DebugMap is an input to the DwarfLinker class that will
  17 /// extract the Dwarf debug information from the referenced object
  18 /// files and link their usefull debug info together.
  19 //
  20 //===----------------------------------------------------------------------===//
  21
  22 #ifndef LLVM_TOOLS_DSYMUTIL_DEBUGMAP_H
  23 #define LLVM_TOOLS_DSYMUTIL_DEBUGMAP_H
  24
  25 #include "llvm/ADT/DenseMap.h"
  26 #include "llvm/ADT/Optional.h"
  27 #include "llvm/ADT/StringMap.h"
  28 #include "llvm/ADT/StringRef.h"
  29 #include "llvm/ADT/Triple.h"
  30 #include "llvm/ADT/iterator_range.h"
  31 #include "llvm/Support/Chrono.h"
  32 #include "llvm/Support/ErrorOr.h"
  33 #include "llvm/Support/YAMLTraits.h"
  34 #include <chrono>
  35 #include <cstddef>
  36 #include <cstdint>
  37 #include <memory>
  38 #include <string>
  39 #include <utility>
  40 #include <vector>
  41
  42 namespace llvm {
  43
  44 class raw_ostream;
  45
  46 namespace dsymutil {
  47
  48 class DebugMapObject;
  49
  50 /// \brief The DebugMap object stores the list of object files to
  51 /// query for debug information along with the mapping between the
  52 /// symbols' addresses in the object file to their linked address in
  53 /// the linked binary.
  54 ///
  55 /// A DebugMap producer could look like this:
  56 /// DebugMap *DM = new DebugMap();
  57 /// for (const auto &Obj: LinkedObjects) {
  58 ///     DebugMapObject &DMO = DM->addDebugMapObject(Obj.getPath());
  59 ///     for (const auto &Sym: Obj.getLinkedSymbols())
  60 ///         DMO.addSymbol(Sym.getName(), Sym.getObjectFileAddress(),
  61 ///                       Sym.getBinaryAddress());
  62 /// }
  63 ///
  64 /// A DebugMap consumer can then use the map to link the debug
  65 /// information. For example something along the lines of:
  66 /// for (const auto &DMO: DM->objects()) {
  67 ///     auto Obj = createBinary(DMO.getObjectFilename());
  68 ///     for (auto &DIE: Obj.getDwarfDIEs()) {
  69 ///         if (SymbolMapping *Sym = DMO.lookup(DIE.getName()))
  70 ///             DIE.relocate(Sym->ObjectAddress, Sym->BinaryAddress);
  71 ///         else
  72 ///             DIE.discardSubtree();
  73 ///     }
  74 /// }
  75 class DebugMap {
  76   Triple BinaryTriple;
  77   std::string BinaryPath;
  78
  79   using ObjectContainer = std::vector<std::unique_ptr<DebugMapObject>>;
  80
  81   ObjectContainer Objects;
  82
  83   /// For YAML IO support.
  84   ///@{
  85   friend yaml::MappingTraits<std::unique_ptr<DebugMap>>;
  86   friend yaml::MappingTraits<DebugMap>;
  87
  88   DebugMap() = default;
  89   ///@}
  90
  91 public:
  92   DebugMap(const Triple &BinaryTriple, StringRef BinaryPath)
  93       : BinaryTriple(BinaryTriple), BinaryPath(BinaryPath) {}
  94
  95   using const_iterator = ObjectContainer::const_iterator;
  96
  97   iterator_range<const_iterator> objects() const {
  98     return make_range(begin(), end());
  99   }
 100
 101   const_iterator begin() const { return Objects.begin(); }
 102
 103   const_iterator end() const { return Objects.end(); }
 104
 105   /// This function adds an DebugMapObject to the list owned by this
 106   /// debug map.
 107   DebugMapObject &
 108   addDebugMapObject(StringRef ObjectFilePath,
 109                     sys::TimePoint<std::chrono::seconds> Timestamp,
 110                     uint8_t Type);
 111
 112   const Triple &getTriple() const { return BinaryTriple; }
 113
 114   StringRef getBinaryPath() const { return BinaryPath; }
 115
 116   void print(raw_ostream &OS) const;
 117
 118 #ifndef NDEBUG
 119   void dump() const;
 120 #endif
 121
 122   /// Read a debug map for \a InputFile.
 123   static ErrorOr<std::vector<std::unique_ptr<DebugMap>>>
 124   parseYAMLDebugMap(StringRef InputFile, StringRef PrependPath, bool Verbose);
 125 };
 126
 127 /// \brief The DebugMapObject represents one object file described by
 128 /// the DebugMap. It contains a list of mappings between addresses in
 129 /// the object file and in the linked binary for all the linked atoms
 130 /// in this object file.
 131 class DebugMapObject {
 132 public:
 133   struct SymbolMapping {
 134     Optional<yaml::Hex64> ObjectAddress;
 135     yaml::Hex64 BinaryAddress;
 136     yaml::Hex32 Size;
 137
 138     SymbolMapping(Optional<uint64_t> ObjectAddr, uint64_t BinaryAddress,
 139                   uint32_t Size)
 140         : BinaryAddress(BinaryAddress), Size(Size) {
 141       if (ObjectAddr)
 142         ObjectAddress = *ObjectAddr;
 143     }
 144
 145     /// For YAML IO support
 146     SymbolMapping() = default;
 147   };
 148
 149   using YAMLSymbolMapping = std::pair<std::string, SymbolMapping>;
 150   using DebugMapEntry = StringMapEntry<SymbolMapping>;
 151
 152   /// \brief Adds a symbol mapping to this DebugMapObject.
 153   /// \returns false if the symbol was already registered. The request
 154   /// is discarded in this case.
 155   bool addSymbol(StringRef SymName, Optional<uint64_t> ObjectAddress,
 156                  uint64_t LinkedAddress, uint32_t Size);
 157
 158   /// \brief Lookup a symbol mapping.
 159   /// \returns null if the symbol isn't found.
 160   const DebugMapEntry *lookupSymbol(StringRef SymbolName) const;
 161
 162   /// \brief Lookup an objectfile address.
 163   /// \returns null if the address isn't found.
 164   const DebugMapEntry *lookupObjectAddress(uint64_t Address) const;
 165
 166   StringRef getObjectFilename() const { return Filename; }
 167
 168   sys::TimePoint<std::chrono::seconds> getTimestamp() const {
 169     return Timestamp;
 170   }
 171
 172   uint8_t getType() const { return Type; }
 173
 174   iterator_range<StringMap<SymbolMapping>::const_iterator> symbols() const {
 175     return make_range(Symbols.begin(), Symbols.end());
 176   }
 177
 178   void print(raw_ostream &OS) const;
 179 #ifndef NDEBUG
 180   void dump() const;
 181 #endif
 182
 183 private:
 184   friend class DebugMap;
 185
 186   /// DebugMapObjects can only be constructed by the owning DebugMap.
 187   DebugMapObject(StringRef ObjectFilename,
 188                  sys::TimePoint<std::chrono::seconds> Timestamp, uint8_t Type);
 189
 190   std::string Filename;
 191   sys::TimePoint<std::chrono::seconds> Timestamp;
 192   StringMap<SymbolMapping> Symbols;
 193   DenseMap<uint64_t, DebugMapEntry *> AddressToMapping;
 194   uint8_t Type;
 195
 196   /// For YAMLIO support.
 197   ///@{
 198   friend yaml::MappingTraits<dsymutil::DebugMapObject>;
 199   friend yaml::SequenceTraits<std::vector<std::unique_ptr<DebugMapObject>>>;
 200
 201   DebugMapObject() = default;
 202
 203 public:
 204   DebugMapObject(DebugMapObject &&) = default;
 205   DebugMapObject &operator=(DebugMapObject &&) = default;
 206   ///@}
 207 };
 208
 209 } // end namespace dsymutil
 210
 211 } // end namespace llvm
 212
 213 LLVM_YAML_IS_SEQUENCE_VECTOR(llvm::dsymutil::DebugMapObject::YAMLSymbolMapping)
 214
 215 namespace llvm {
 216 namespace yaml {
 217
 218 using namespace llvm::dsymutil;
 219
 220 template <>
 221 struct MappingTraits<std::pair<std::string, DebugMapObject::SymbolMapping>> {
 222   static void mapping(IO &io,
 223                       std::pair<std::string, DebugMapObject::SymbolMapping> &s);
 224   static const bool flow = true;
 225 };
 226
 227 template <> struct MappingTraits<dsymutil::DebugMapObject> {
 228   struct YamlDMO;
 229   static void mapping(IO &io, dsymutil::DebugMapObject &DMO);
 230 };
 231
 232 template <> struct ScalarTraits<Triple> {
 233   static void output(const Triple &val, void *, raw_ostream &out);
 234   static StringRef input(StringRef scalar, void *, Triple &value);
 235   static QuotingType mustQuote(StringRef) { return QuotingType::Single; }
 236 };
 237
 238 template <>
 239 struct SequenceTraits<std::vector<std::unique_ptr<dsymutil::DebugMapObject>>> {
 240   static size_t
 241   size(IO &io, std::vector<std::unique_ptr<dsymutil::DebugMapObject>> &seq);
 242   static dsymutil::DebugMapObject &
 243   element(IO &, std::vector<std::unique_ptr<dsymutil::DebugMapObject>> &seq,
 244           size_t index);
 245 };
 246
 247 template <> struct MappingTraits<dsymutil::DebugMap> {
 248   static void mapping(IO &io, dsymutil::DebugMap &DM);
 249 };
 250
 251 template <> struct MappingTraits<std::unique_ptr<dsymutil::DebugMap>> {
 252   static void mapping(IO &io, std::unique_ptr<dsymutil::DebugMap> &DM);
 253 };
 254
 255 } // end namespace yaml
 256 } // end namespace llvm
 257
 258 #endif // LLVM_TOOLS_DSYMUTIL_DEBUGMAP_H