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 DSYMUTIL_DEBUGMAP_H
  22 #define 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
  33 class raw_ostream;
  34
  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 {
  64   typedef std::vector<std::unique_ptr<DebugMapObject>> ObjectContainer;
  65   ObjectContainer Objects;
  66
  67 public:
  68   typedef ObjectContainer::const_iterator const_iterator;
  69
  70   iterator_range<const_iterator> objects() const {
  71     return make_range(begin(), end());
  72   }
  73
  74   const_iterator begin() const {
  75     return Objects.begin();
  76   }
  77
  78   const_iterator end() const {
  79     return Objects.end();
  80   }
  81
  82   /// This function adds an DebugMapObject to the list owned by this
  83   /// debug map.
  84   DebugMapObject& addDebugMapObject(StringRef ObjectFilePath);
  85
  86   void print(raw_ostream& OS) const;
  87
  88 #ifndef NDEBUG
  89   void dump() const;
  90 #endif
  91 };
  92
  93 /// \brief The DebugMapObject represents one object file described by
  94 /// the DebugMap. It contains a list of mappings between addresses in
  95 /// the object file and in the linked binary for all the linked atoms
  96 /// in this object file.
  97 class DebugMapObject {
  98 public:
  99   struct SymbolMapping {
 100     uint64_t ObjectAddress;
 101     uint64_t BinaryAddress;
 102   };
 103
 104   /// \brief Adds a symbol mapping to this DebugMapObject.
 105   /// \returns false if the symbol was already registered. The request
 106   /// is discarded in this case.
 107   bool addSymbol(llvm::StringRef SymName, uint64_t ObjectAddress,
 108                  uint64_t LinkedAddress);
 109
 110   /// \bried Lookup a symbol mapping.
 111   /// \returns null if the symbol isn't found.
 112   const SymbolMapping *lookupSymbol(StringRef SymbolName) const;
 113
 114   llvm::StringRef getObjectFilename() const { return Filename; }
 115
 116   void print(raw_ostream& OS) const;
 117 #ifndef NDEBUG
 118   void dump() const;
 119 #endif
 120 private:
 121   friend class DebugMap;
 122   /// DebugMapObjects can only be constructed by the owning DebugMap.
 123   DebugMapObject(StringRef ObjectFilename);
 124
 125   std::string Filename;
 126   StringMap<SymbolMapping> Symbols;
 127 };
 128
 129 }
 130
 131 #endif // DSYMUTIL_DEBUGMAP_H