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