tools/dsymutil/DebugMap.h

   1 //===- tools/dsymutil/DebugMap.h - Generic debug map representation -------===//
   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 #ifndef LLVM_TOOLS_DSYMUTIL_DEBUGMAP_H
  22 #define LLVM_TOOLS_DSYMUTIL_DEBUGMAP_H
  23
  24 #include "llvm/ADT/StringMap.h"
  25 #include "llvm/Object/ObjectFile.h"
  26 #include "llvm/Support/ErrorOr.h"
  27 #include "llvm/Support/Format.h"
  28 #include "llvm/ADT/iterator_range.h"
  29 #include <vector>
  30
  31 namespace llvm {
  32 class raw_ostream;
  33
  34 namespace dsymutil {
  35 class DebugMapObject;
  36
  37 /// \brief The DebugMap object stores the list of object files to
  38 /// query for debug information along with the mapping between the
  39 /// symbols' addresses in the object file to their linked address in
  40 /// the linked binary.
  41 ///
  42 /// A DebugMap producer could look like this:
  43 /// DebugMap *DM = new DebugMap();
  44 /// for (const auto &Obj: LinkedObjects) {
  45 ///     DebugMapObject &DMO = DM->addDebugMapObject(Obj.getPath());
  46 ///     for (const auto &Sym: Obj.getLinkedSymbols())
  47 ///         DMO.addSymbol(Sym.getName(), Sym.getObjectFileAddress(),
  48 ///                       Sym.getBinaryAddress());
  49 /// }
  50 ///
  51 /// A DebugMap consumer can then use the map to link the debug
  52 /// information. For example something along the lines of:
  53 /// for (const auto &DMO: DM->objects()) {
  54 ///     auto Obj = createBinary(DMO.getObjectFilename());
  55 ///     for (auto &DIE: Obj.getDwarfDIEs()) {
  56 ///         if (SymbolMapping *Sym = DMO.lookup(DIE.getName()))
  57 ///             DIE.relocate(Sym->ObjectAddress, Sym->BinaryAddress);
  58 ///         else
  59 ///             DIE.discardSubtree();
  60 ///     }
  61 /// }
  62 class DebugMap {
  63   typedef std::vector<std::unique_ptr<DebugMapObject>> ObjectContainer;
  64   ObjectContainer Objects;
  65
  66 public:
  67   typedef ObjectContainer::const_iterator const_iterator;
  68
  69   iterator_range<const_iterator> objects() const {
  70     return make_range(begin(), end());
  71   }
  72
  73   const_iterator begin() const { return Objects.begin(); }
  74
  75   const_iterator end() const { return Objects.end(); }
  76
  77   /// This function adds an DebugMapObject to the list owned by this
  78   /// debug map.
  79   DebugMapObject &addDebugMapObject(StringRef ObjectFilePath);
  80
  81   void print(raw_ostream &OS) const;
  82
  83 #ifndef NDEBUG
  84   void dump() const;
  85 #endif
  86 };
  87
  88 /// \brief The DebugMapObject represents one object file described by
  89 /// the DebugMap. It contains a list of mappings between addresses in
  90 /// the object file and in the linked binary for all the linked atoms
  91 /// in this object file.
  92 class DebugMapObject {
  93 public:
  94   struct SymbolMapping {
  95     uint64_t ObjectAddress;
  96     uint64_t BinaryAddress;
  97     SymbolMapping(uint64_t ObjectAddress, uint64_t BinaryAddress)
  98         : ObjectAddress(ObjectAddress), BinaryAddress(BinaryAddress) {}
  99   };
 100
 101   /// \brief Adds a symbol mapping to this DebugMapObject.
 102   /// \returns false if the symbol was already registered. The request
 103   /// is discarded in this case.
 104   bool addSymbol(llvm::StringRef SymName, uint64_t ObjectAddress,
 105                  uint64_t LinkedAddress);
 106
 107   /// \brief Lookup a symbol mapping.
 108   /// \returns null if the symbol isn't found.
 109   const SymbolMapping *lookupSymbol(StringRef SymbolName) const;
 110
 111   llvm::StringRef getObjectFilename() const { return Filename; }
 112
 113   void print(raw_ostream &OS) const;
 114 #ifndef NDEBUG
 115   void dump() const;
 116 #endif
 117 private:
 118   friend class DebugMap;
 119   /// DebugMapObjects can only be constructed by the owning DebugMap.
 120   DebugMapObject(StringRef ObjectFilename);
 121
 122   std::string Filename;
 123   StringMap<SymbolMapping> Symbols;
 124 };
 125 }
 126 }
 127
 128 #endif // LLVM_TOOLS_DSYMUTIL_DEBUGMAP_H