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 "BinaryHolder.h"
25#include "RelocationMap.h"
26#include "llvm/ADT/DenseMap.h"
27#include "llvm/ADT/StringMap.h"
28#include "llvm/ADT/StringRef.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 "llvm/TargetParser/Triple.h"
35#include <chrono>
36#include <cstddef>
37#include <cstdint>
38#include <memory>
39#include <optional>
40#include <string>
41#include <utility>
42#include <vector>
43
44namespace llvm {
45
46class raw_ostream;
47
48namespace dsymutil {
49
50class DebugMapObject;
51class DebugMapObjectFilter;
52
53template <typename T> class DebugMapFilterBase {
54 using ObjectContainer = std::vector<std::unique_ptr<T>>;
55
56public:
57 using const_iterator = typename ObjectContainer::const_iterator;
58
59 const_iterator begin() const { return Objects.begin(); }
60
61 const_iterator end() const { return Objects.end(); }
62
63 iterator_range<const_iterator> objects() const {
64 return make_range(begin(), end());
65 }
66
67protected:
68 ObjectContainer Objects;
69};
70
71class DebugMapFilter : public DebugMapFilterBase<DebugMapObjectFilter> {
72public:
73 virtual ~DebugMapFilter() = default;
74
75private:
76 /// For YAML IO support.
77 ///@{
78 friend yaml::MappingTraits<std::unique_ptr<DebugMapFilter>>;
79 friend yaml::MappingTraits<DebugMapFilter>;
80
81 DebugMapFilter() = default;
82
83public:
84 DebugMapFilter(DebugMapFilter &&) = default;
85 DebugMapFilter &operator=(DebugMapFilter &&) = default;
86 ///@}
87};
88
89/// The DebugMap object stores the list of object files to query for debug
90/// information along with the mapping between the symbols' addresses in the
91/// object file to their linked address in the linked binary.
92///
93/// A DebugMap producer could look like this:
94/// DebugMap *DM = new DebugMap();
95/// for (const auto &Obj: LinkedObjects) {
96/// DebugMapObject &DMO = DM->addDebugMapObject(Obj.getPath());
97/// for (const auto &Sym: Obj.getLinkedSymbols())
98/// DMO.addSymbol(Sym.getName(), Sym.getObjectFileAddress(),
99/// Sym.getBinaryAddress());
100/// }
101///
102/// A DebugMap consumer can then use the map to link the debug
103/// information. For example something along the lines of:
104/// for (const auto &DMO: DM->objects()) {
105/// auto Obj = createBinary(DMO.getObjectFilename());
106/// for (auto &DIE: Obj.getDwarfDIEs()) {
107/// if (SymbolMapping *Sym = DMO.lookup(DIE.getName()))
108/// DIE.relocate(Sym->ObjectAddress, Sym->BinaryAddress);
109/// else
110/// DIE.discardSubtree();
111/// }
112/// }
113class DebugMap : public DebugMapFilterBase<DebugMapObject> {
114 Triple BinaryTriple;
115 std::string BinaryPath;
116 std::vector<uint8_t> BinaryUUID;
117
118 /// For YAML IO support.
119 ///@{
120 friend yaml::MappingTraits<std::unique_ptr<DebugMap>>;
121 friend yaml::MappingTraits<DebugMap>;
122
123 DebugMap() = default;
124 ///@}
125
126public:
127 DebugMap(const Triple &BinaryTriple, StringRef BinaryPath,
128 ArrayRef<uint8_t> BinaryUUID = ArrayRef<uint8_t>());
129
130 unsigned getNumberOfObjects() const { return Objects.size(); }
131
132 /// This function adds an DebugMapObject to the list owned by this
133 /// debug map.
134 DebugMapObject &
135 addDebugMapObject(StringRef ObjectFilePath,
136 sys::TimePoint<std::chrono::seconds> Timestamp,
137 uint8_t Type = llvm::MachO::N_OSO);
138
139 const Triple &getTriple() const { return BinaryTriple; }
140
141 ArrayRef<uint8_t> getUUID() const { return ArrayRef<uint8_t>(BinaryUUID); }
142
143 StringRef getBinaryPath() const { return BinaryPath; }
144
145 void print(raw_ostream &OS) const;
146
147#ifndef NDEBUG
148 void dump() const;
149#endif
150
151 /// Read a debug map for \a InputFile.
152 static ErrorOr<std::vector<std::unique_ptr<DebugMap>>>
153 parseYAMLDebugMap(BinaryHolder &BinHolder, StringRef InputFile,
154 StringRef PrependPath, bool Verbose);
155};
156
157class DebugMapObjectFilter {
158public:
159 virtual ~DebugMapObjectFilter() = default;
160 StringRef getObjectFilename() const { return Filename; }
161
162protected:
163 std::string Filename;
164
165private:
166 friend class DebugMapFilter;
167 friend class DebugMapObject;
168
169 DebugMapObjectFilter(StringRef ObjectFilename);
170
171 /// For YAMLIO support.
172 ///@{
173 friend yaml::MappingTraits<dsymutil::DebugMapObjectFilter>;
174 friend yaml::SequenceTraits<
175 std::vector<std::unique_ptr<DebugMapObjectFilter>>>;
176
177 DebugMapObjectFilter() = default;
178
179public:
180 DebugMapObjectFilter(DebugMapObjectFilter &&) = default;
181 DebugMapObjectFilter &operator=(DebugMapObjectFilter &&) = default;
182 ///@}
183};
184
185/// The DebugMapObject represents one object file described by the DebugMap. It
186/// contains a list of mappings between addresses in the object file and in the
187/// linked binary for all the linked atoms in this object file.
188class DebugMapObject : public DebugMapObjectFilter {
189public:
190 using YAMLSymbolMapping = std::pair<std::string, SymbolMapping>;
191 using DebugMapEntry = StringMapEntry<SymbolMapping>;
192
193 /// Adds a symbol mapping to this DebugMapObject.
194 /// \returns false if the symbol was already registered. The request
195 /// is discarded in this case.
196 bool addSymbol(StringRef SymName, std::optional<uint64_t> ObjectAddress,
197 uint64_t LinkedAddress, uint32_t Size);
198
199 /// Lookup a symbol mapping.
200 /// \returns null if the symbol isn't found.
201 const DebugMapEntry *lookupSymbol(StringRef SymbolName) const;
202
203 /// Lookup an object file address.
204 /// \returns null if the address isn't found.
205 const DebugMapEntry *lookupObjectAddress(uint64_t Address) const;
206
207 sys::TimePoint<std::chrono::seconds> getTimestamp() const {
208 return Timestamp;
209 }
210
211 uint8_t getType() const { return Type; }
212
213 iterator_range<StringMap<SymbolMapping>::const_iterator> symbols() const {
214 return make_range(x: Symbols.begin(), y: Symbols.end());
215 }
216
217 bool empty() const { return Symbols.empty(); }
218
219 void addWarning(StringRef Warning) {
220 Warnings.push_back(x: std::string(Warning));
221 }
222 const std::vector<std::string> &getWarnings() const { return Warnings; }
223
224 const std::optional<RelocationMap> &getRelocationMap() const {
225 return RelocMap;
226 }
227 void setRelocationMap(dsymutil::RelocationMap &RM);
228
229 const std::optional<std::string> &getInstallName() const {
230 return InstallName;
231 }
232 void setInstallName(StringRef IN);
233
234 void print(raw_ostream &OS) const;
235#ifndef NDEBUG
236 void dump() const;
237#endif
238
239private:
240 friend class DebugMap;
241
242 /// DebugMapObjects can only be constructed by the owning DebugMap.
243 DebugMapObject(StringRef ObjectFilename,
244 sys::TimePoint<std::chrono::seconds> Timestamp, uint8_t Type);
245
246 sys::TimePoint<std::chrono::seconds> Timestamp;
247 StringMap<struct SymbolMapping> Symbols;
248 DenseMap<uint64_t, DebugMapEntry *> AddressToMapping;
249 uint8_t Type;
250
251 std::optional<RelocationMap> RelocMap;
252 std::optional<std::string> InstallName;
253
254 std::vector<std::string> Warnings;
255
256 /// For YAMLIO support.
257 ///@{
258 friend yaml::MappingTraits<dsymutil::DebugMapObject>;
259 friend yaml::SequenceTraits<std::vector<std::unique_ptr<DebugMapObject>>>;
260
261 DebugMapObject() = default;
262
263public:
264 DebugMapObject(DebugMapObject &&) = default;
265 DebugMapObject &operator=(DebugMapObject &&) = default;
266 ///@}
267};
268
269} // end namespace dsymutil
270} // end namespace llvm
271
272LLVM_YAML_IS_SEQUENCE_VECTOR(llvm::dsymutil::DebugMapObject::YAMLSymbolMapping)
273
274namespace llvm {
275namespace yaml {
276
277using namespace llvm::dsymutil;
278
279template <> struct MappingTraits<std::pair<std::string, SymbolMapping>> {
280 static void mapping(IO &io, std::pair<std::string, SymbolMapping> &s);
281 static const bool flow = true;
282};
283
284template <> struct MappingTraits<dsymutil::DebugMapObject> {
285 struct YamlDMO;
286 static void mapping(IO &io, dsymutil::DebugMapObject &DMO);
287};
288
289template <>
290struct SequenceTraits<std::vector<std::unique_ptr<dsymutil::DebugMapObject>>> {
291 static size_t
292 size(IO &io, std::vector<std::unique_ptr<dsymutil::DebugMapObject>> &seq);
293 static dsymutil::DebugMapObject &
294 element(IO &, std::vector<std::unique_ptr<dsymutil::DebugMapObject>> &seq,
295 size_t index);
296};
297
298template <> struct MappingTraits<dsymutil::DebugMapObjectFilter> {
299 static void mapping(IO &io, dsymutil::DebugMapObjectFilter &DMO);
300};
301
302template <>
303struct SequenceTraits<
304 std::vector<std::unique_ptr<dsymutil::DebugMapObjectFilter>>> {
305 static size_t
306 size(IO &io,
307 std::vector<std::unique_ptr<dsymutil::DebugMapObjectFilter>> &seq);
308 static dsymutil::DebugMapObjectFilter &
309 element(IO &,
310 std::vector<std::unique_ptr<dsymutil::DebugMapObjectFilter>> &seq,
311 size_t index);
312};
313
314template <> struct MappingTraits<dsymutil::DebugMap> {
315 static void mapping(IO &io, dsymutil::DebugMap &DM);
316};
317
318template <> struct MappingTraits<std::unique_ptr<dsymutil::DebugMap>> {
319 static void mapping(IO &io, std::unique_ptr<dsymutil::DebugMap> &DM);
320};
321
322template <> struct MappingTraits<dsymutil::DebugMapFilter> {
323 static void mapping(IO &io, dsymutil::DebugMapFilter &DMF);
324};
325
326template <> struct MappingTraits<std::unique_ptr<dsymutil::DebugMapFilter>> {
327 static void mapping(IO &io, std::unique_ptr<dsymutil::DebugMapFilter> &DMF);
328};
329
330} // end namespace yaml
331} // end namespace llvm
332
333#endif // LLVM_TOOLS_DSYMUTIL_DEBUGMAP_H
334