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