1 //=- tools/dsymutil/DebugMap.h - Generic debug map representation -*- C++ -*-=//
2 //
3 //                     The LLVM Compiler Infrastructure
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/Object/MachO.h"
32 #include "llvm/Support/Chrono.h"
33 #include "llvm/Support/ErrorOr.h"
34 #include "llvm/Support/YAMLTraits.h"
35 #include <chrono>
36 #include <cstddef>
37 #include <cstdint>
38 #include <memory>
39 #include <string>
40 #include <utility>
41 #include <vector>
42 
43 namespace llvm {
44 
45 class raw_ostream;
46 
47 namespace dsymutil {
48 
49 class DebugMapObject;
50 
51 /// The DebugMap object stores the list of object files to query for debug
52 /// information along with the mapping between the symbols' addresses in the
53 /// object file to their linked address in 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   std::vector<uint8_t> BinaryUUID;
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            ArrayRef<uint8_t> BinaryUUID = ArrayRef<uint8_t>())
94       : BinaryTriple(BinaryTriple), BinaryPath(BinaryPath),
95         BinaryUUID(BinaryUUID.begin(), BinaryUUID.end()) {}
96 
97   using const_iterator = ObjectContainer::const_iterator;
98 
99   iterator_range<const_iterator> objects() const {
100     return make_range(begin(), end());
101   }
102 
103   const_iterator begin() const { return Objects.begin(); }
104 
105   const_iterator end() const { return Objects.end(); }
106 
107   unsigned getNumberOfObjects() const { return Objects.size(); }
108 
109   /// This function adds an DebugMapObject to the list owned by this
110   /// debug map.
111   DebugMapObject &
112   addDebugMapObject(StringRef ObjectFilePath,
113                     sys::TimePoint<std::chrono::seconds> Timestamp,
114                     uint8_t Type = llvm::MachO::N_OSO);
115 
116   const Triple &getTriple() const { return BinaryTriple; }
117 
118   const ArrayRef<uint8_t> getUUID() const {
119     return ArrayRef<uint8_t>(BinaryUUID);
120   }
121 
122   StringRef getBinaryPath() const { return BinaryPath; }
123 
124   void print(raw_ostream &OS) const;
125 
126 #ifndef NDEBUG
127   void dump() const;
128 #endif
129 
130   /// Read a debug map for \a InputFile.
131   static ErrorOr<std::vector<std::unique_ptr<DebugMap>>>
132   parseYAMLDebugMap(StringRef InputFile, StringRef PrependPath, bool Verbose);
133 };
134 
135 /// The DebugMapObject represents one object file described by the DebugMap. It
136 /// contains a list of mappings between addresses in the object file and in the
137 /// linked binary for all the linked atoms in this object file.
138 class DebugMapObject {
139 public:
140   struct SymbolMapping {
141     Optional<yaml::Hex64> ObjectAddress;
142     yaml::Hex64 BinaryAddress;
143     yaml::Hex32 Size;
144 
145     SymbolMapping(Optional<uint64_t> ObjectAddr, uint64_t BinaryAddress,
146                   uint32_t Size)
147         : BinaryAddress(BinaryAddress), Size(Size) {
148       if (ObjectAddr)
149         ObjectAddress = *ObjectAddr;
150     }
151 
152     /// For YAML IO support
153     SymbolMapping() = default;
154   };
155 
156   using YAMLSymbolMapping = std::pair<std::string, SymbolMapping>;
157   using DebugMapEntry = StringMapEntry<SymbolMapping>;
158 
159   /// Adds a symbol mapping to this DebugMapObject.
160   /// \returns false if the symbol was already registered. The request
161   /// is discarded in this case.
162   bool addSymbol(StringRef SymName, Optional<uint64_t> ObjectAddress,
163                  uint64_t LinkedAddress, uint32_t Size);
164 
165   /// Lookup a symbol mapping.
166   /// \returns null if the symbol isn't found.
167   const DebugMapEntry *lookupSymbol(StringRef SymbolName) const;
168 
169   /// Lookup an object file address.
170   /// \returns null if the address isn't found.
171   const DebugMapEntry *lookupObjectAddress(uint64_t Address) const;
172 
173   StringRef getObjectFilename() const { return Filename; }
174 
175   sys::TimePoint<std::chrono::seconds> getTimestamp() const {
176     return Timestamp;
177   }
178 
179   uint8_t getType() const { return Type; }
180 
181   iterator_range<StringMap<SymbolMapping>::const_iterator> symbols() const {
182     return make_range(Symbols.begin(), Symbols.end());
183   }
184 
185   bool empty() const { return Symbols.empty(); }
186 
187   void addWarning(StringRef Warning) { Warnings.push_back(Warning); }
188   const std::vector<std::string> &getWarnings() const { return Warnings; }
189 
190   void print(raw_ostream &OS) const;
191 #ifndef NDEBUG
192   void dump() const;
193 #endif
194 
195 private:
196   friend class DebugMap;
197 
198   /// DebugMapObjects can only be constructed by the owning DebugMap.
199   DebugMapObject(StringRef ObjectFilename,
200                  sys::TimePoint<std::chrono::seconds> Timestamp, uint8_t Type);
201 
202   std::string Filename;
203   sys::TimePoint<std::chrono::seconds> Timestamp;
204   StringMap<SymbolMapping> Symbols;
205   DenseMap<uint64_t, DebugMapEntry *> AddressToMapping;
206   uint8_t Type;
207 
208   std::vector<std::string> Warnings;
209 
210   /// For YAMLIO support.
211   ///@{
212   friend yaml::MappingTraits<dsymutil::DebugMapObject>;
213   friend yaml::SequenceTraits<std::vector<std::unique_ptr<DebugMapObject>>>;
214 
215   DebugMapObject() = default;
216 
217 public:
218   DebugMapObject(DebugMapObject &&) = default;
219   DebugMapObject &operator=(DebugMapObject &&) = default;
220   ///@}
221 };
222 
223 } // end namespace dsymutil
224 } // end namespace llvm
225 
226 LLVM_YAML_IS_SEQUENCE_VECTOR(llvm::dsymutil::DebugMapObject::YAMLSymbolMapping)
227 
228 namespace llvm {
229 namespace yaml {
230 
231 using namespace llvm::dsymutil;
232 
233 template <>
234 struct MappingTraits<std::pair<std::string, DebugMapObject::SymbolMapping>> {
235   static void mapping(IO &io,
236                       std::pair<std::string, DebugMapObject::SymbolMapping> &s);
237   static const bool flow = true;
238 };
239 
240 template <> struct MappingTraits<dsymutil::DebugMapObject> {
241   struct YamlDMO;
242   static void mapping(IO &io, dsymutil::DebugMapObject &DMO);
243 };
244 
245 template <> struct ScalarTraits<Triple> {
246   static void output(const Triple &val, void *, raw_ostream &out);
247   static StringRef input(StringRef scalar, void *, Triple &value);
248   static QuotingType mustQuote(StringRef) { return QuotingType::Single; }
249 };
250 
251 template <>
252 struct SequenceTraits<std::vector<std::unique_ptr<dsymutil::DebugMapObject>>> {
253   static size_t
254   size(IO &io, std::vector<std::unique_ptr<dsymutil::DebugMapObject>> &seq);
255   static dsymutil::DebugMapObject &
256   element(IO &, std::vector<std::unique_ptr<dsymutil::DebugMapObject>> &seq,
257           size_t index);
258 };
259 
260 template <> struct MappingTraits<dsymutil::DebugMap> {
261   static void mapping(IO &io, dsymutil::DebugMap &DM);
262 };
263 
264 template <> struct MappingTraits<std::unique_ptr<dsymutil::DebugMap>> {
265   static void mapping(IO &io, std::unique_ptr<dsymutil::DebugMap> &DM);
266 };
267 
268 } // end namespace yaml
269 } // end namespace llvm
270 
271 #endif // LLVM_TOOLS_DSYMUTIL_DEBUGMAP_H
272