1 //=- tools/dsymutil/DebugMap.h - Generic debug map representation -*- C++ -*-=//
5 // This file is distributed under the University of Illinois Open Source
6 // License. See LICENSE.TXT for details.
8 //===----------------------------------------------------------------------===//
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.
20 //===----------------------------------------------------------------------===//
22 #ifndef LLVM_TOOLS_DSYMUTIL_DEBUGMAP_H
23 #define LLVM_TOOLS_DSYMUTIL_DEBUGMAP_H
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"
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.
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());
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);
72 /// DIE.discardSubtree();
77 std::string BinaryPath;
79 using ObjectContainer = std::vector<std::unique_ptr<DebugMapObject>>;
81 ObjectContainer Objects;
83 /// For YAML IO support.
85 friend yaml::MappingTraits<std::unique_ptr<DebugMap>>;
86 friend yaml::MappingTraits<DebugMap>;
92 DebugMap(const Triple &BinaryTriple, StringRef BinaryPath)
93 : BinaryTriple(BinaryTriple), BinaryPath(BinaryPath) {}
95 using const_iterator = ObjectContainer::const_iterator;
97 iterator_range<const_iterator> objects() const {
98 return make_range(begin(), end());
101 const_iterator begin() const { return Objects.begin(); }
103 const_iterator end() const { return Objects.end(); }
105 unsigned getNumberOfObjects() const { return Objects.size(); }
107 /// This function adds an DebugMapObject to the list owned by this
110 addDebugMapObject(StringRef ObjectFilePath,
111 sys::TimePoint<std::chrono::seconds> Timestamp,
112 uint8_t Type = llvm::MachO::N_OSO);
114 const Triple &getTriple() const { return BinaryTriple; }
116 StringRef getBinaryPath() const { return BinaryPath; }
118 void print(raw_ostream &OS) const;
124 /// Read a debug map for \a InputFile.
125 static ErrorOr<std::vector<std::unique_ptr<DebugMap>>>
126 parseYAMLDebugMap(StringRef InputFile, StringRef PrependPath, bool Verbose);
129 /// The DebugMapObject represents one object file described by the DebugMap. It
130 /// contains a list of mappings between addresses in the object file and in the
131 /// linked binary for all the linked atoms in this object file.
132 class DebugMapObject {
134 struct SymbolMapping {
135 Optional<yaml::Hex64> ObjectAddress;
136 yaml::Hex64 BinaryAddress;
139 SymbolMapping(Optional<uint64_t> ObjectAddr, uint64_t BinaryAddress,
141 : BinaryAddress(BinaryAddress), Size(Size) {
143 ObjectAddress = *ObjectAddr;
146 /// For YAML IO support
147 SymbolMapping() = default;
150 using YAMLSymbolMapping = std::pair<std::string, SymbolMapping>;
151 using DebugMapEntry = StringMapEntry<SymbolMapping>;
153 /// Adds a symbol mapping to this DebugMapObject.
154 /// \returns false if the symbol was already registered. The request
155 /// is discarded in this case.
156 bool addSymbol(StringRef SymName, Optional<uint64_t> ObjectAddress,
157 uint64_t LinkedAddress, uint32_t Size);
159 /// Lookup a symbol mapping.
160 /// \returns null if the symbol isn't found.
161 const DebugMapEntry *lookupSymbol(StringRef SymbolName) const;
163 /// Lookup an object file address.
164 /// \returns null if the address isn't found.
165 const DebugMapEntry *lookupObjectAddress(uint64_t Address) const;
167 StringRef getObjectFilename() const { return Filename; }
169 sys::TimePoint<std::chrono::seconds> getTimestamp() const {
173 uint8_t getType() const { return Type; }
175 iterator_range<StringMap<SymbolMapping>::const_iterator> symbols() const {
176 return make_range(Symbols.begin(), Symbols.end());
179 void print(raw_ostream &OS) const;
185 friend class DebugMap;
187 /// DebugMapObjects can only be constructed by the owning DebugMap.
188 DebugMapObject(StringRef ObjectFilename,
189 sys::TimePoint<std::chrono::seconds> Timestamp, uint8_t Type);
191 std::string Filename;
192 sys::TimePoint<std::chrono::seconds> Timestamp;
193 StringMap<SymbolMapping> Symbols;
194 DenseMap<uint64_t, DebugMapEntry *> AddressToMapping;
197 /// For YAMLIO support.
199 friend yaml::MappingTraits<dsymutil::DebugMapObject>;
200 friend yaml::SequenceTraits<std::vector<std::unique_ptr<DebugMapObject>>>;
202 DebugMapObject() = default;
205 DebugMapObject(DebugMapObject &&) = default;
206 DebugMapObject &operator=(DebugMapObject &&) = default;
210 } // end namespace dsymutil
211 } // end namespace llvm
213 LLVM_YAML_IS_SEQUENCE_VECTOR(llvm::dsymutil::DebugMapObject::YAMLSymbolMapping)
218 using namespace llvm::dsymutil;
221 struct MappingTraits<std::pair<std::string, DebugMapObject::SymbolMapping>> {
222 static void mapping(IO &io,
223 std::pair<std::string, DebugMapObject::SymbolMapping> &s);
224 static const bool flow = true;
227 template <> struct MappingTraits<dsymutil::DebugMapObject> {
229 static void mapping(IO &io, dsymutil::DebugMapObject &DMO);
232 template <> struct ScalarTraits<Triple> {
233 static void output(const Triple &val, void *, raw_ostream &out);
234 static StringRef input(StringRef scalar, void *, Triple &value);
235 static QuotingType mustQuote(StringRef) { return QuotingType::Single; }
239 struct SequenceTraits<std::vector<std::unique_ptr<dsymutil::DebugMapObject>>> {
241 size(IO &io, std::vector<std::unique_ptr<dsymutil::DebugMapObject>> &seq);
242 static dsymutil::DebugMapObject &
243 element(IO &, std::vector<std::unique_ptr<dsymutil::DebugMapObject>> &seq,
247 template <> struct MappingTraits<dsymutil::DebugMap> {
248 static void mapping(IO &io, dsymutil::DebugMap &DM);
251 template <> struct MappingTraits<std::unique_ptr<dsymutil::DebugMap>> {
252 static void mapping(IO &io, std::unique_ptr<dsymutil::DebugMap> &DM);
255 } // end namespace yaml
256 } // end namespace llvm
258 #endif // LLVM_TOOLS_DSYMUTIL_DEBUGMAP_H