1 //===- DWARFDie.h -----------------------------------------------*- 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 #ifndef LLVM_DEBUGINFO_DWARFDIE_H
10 #define LLVM_DEBUGINFO_DWARFDIE_H
11
12 #include "llvm/ADT/ArrayRef.h"
13 #include "llvm/ADT/Optional.h"
14 #include "llvm/ADT/iterator.h"
15 #include "llvm/ADT/iterator_range.h"
16 #include "llvm/BinaryFormat/Dwarf.h"
17 #include "llvm/DebugInfo/DIContext.h"
18 #include "llvm/DebugInfo/DWARF/DWARFAddressRange.h"
19 #include "llvm/DebugInfo/DWARF/DWARFAttribute.h"
20 #include "llvm/DebugInfo/DWARF/DWARFDebugInfoEntry.h"
21 #include "llvm/DebugInfo/DWARF/DWARFDebugLoc.h"
22 #include <cassert>
23 #include <cstdint>
24 #include <iterator>
25
26 namespace llvm {
27
28 class DWARFUnit;
29 class raw_ostream;
30
31 //===----------------------------------------------------------------------===//
32 /// Utility class that carries the DWARF compile/type unit and the debug info
33 /// entry in an object.
34 ///
35 /// When accessing information from a debug info entry we always need to DWARF
36 /// compile/type unit in order to extract the info correctly as some information
37 /// is relative to the compile/type unit. Prior to this class the DWARFUnit and
38 /// the DWARFDebugInfoEntry was passed around separately and there was the
39 /// possibility for error if the wrong DWARFUnit was used to extract a unit
40 /// relative offset. This class helps to ensure that this doesn't happen and
41 /// also simplifies the attribute extraction calls by not having to specify the
42 /// DWARFUnit for each call.
43 class DWARFDie {
44 DWARFUnit *U = nullptr;
45 const DWARFDebugInfoEntry *Die = nullptr;
46
47 public:
48 DWARFDie() = default;
DWARFDie(DWARFUnit * Unit,const DWARFDebugInfoEntry * D)49 DWARFDie(DWARFUnit *Unit, const DWARFDebugInfoEntry *D) : U(Unit), Die(D) {}
50
isValid()51 bool isValid() const { return U && Die; }
52 explicit operator bool() const { return isValid(); }
getDebugInfoEntry()53 const DWARFDebugInfoEntry *getDebugInfoEntry() const { return Die; }
getDwarfUnit()54 DWARFUnit *getDwarfUnit() const { return U; }
55
56 /// Get the abbreviation declaration for this DIE.
57 ///
58 /// \returns the abbreviation declaration or NULL for null tags.
getAbbreviationDeclarationPtr()59 const DWARFAbbreviationDeclaration *getAbbreviationDeclarationPtr() const {
60 assert(isValid() && "must check validity prior to calling");
61 return Die->getAbbreviationDeclarationPtr();
62 }
63
64 /// Get the absolute offset into the debug info or types section.
65 ///
66 /// \returns the DIE offset or -1U if invalid.
getOffset()67 uint64_t getOffset() const {
68 assert(isValid() && "must check validity prior to calling");
69 return Die->getOffset();
70 }
71
getTag()72 dwarf::Tag getTag() const {
73 auto AbbrevDecl = getAbbreviationDeclarationPtr();
74 if (AbbrevDecl)
75 return AbbrevDecl->getTag();
76 return dwarf::DW_TAG_null;
77 }
78
hasChildren()79 bool hasChildren() const {
80 assert(isValid() && "must check validity prior to calling");
81 return Die->hasChildren();
82 }
83
84 /// Returns true for a valid DIE that terminates a sibling chain.
isNULL()85 bool isNULL() const { return getAbbreviationDeclarationPtr() == nullptr; }
86
87 /// Returns true if DIE represents a subprogram (not inlined).
88 bool isSubprogramDIE() const;
89
90 /// Returns true if DIE represents a subprogram or an inlined subroutine.
91 bool isSubroutineDIE() const;
92
93 /// Get the parent of this DIE object.
94 ///
95 /// \returns a valid DWARFDie instance if this object has a parent or an
96 /// invalid DWARFDie instance if it doesn't.
97 DWARFDie getParent() const;
98
99 /// Get the sibling of this DIE object.
100 ///
101 /// \returns a valid DWARFDie instance if this object has a sibling or an
102 /// invalid DWARFDie instance if it doesn't.
103 DWARFDie getSibling() const;
104
105 /// Get the previous sibling of this DIE object.
106 ///
107 /// \returns a valid DWARFDie instance if this object has a sibling or an
108 /// invalid DWARFDie instance if it doesn't.
109 DWARFDie getPreviousSibling() const;
110
111 /// Get the first child of this DIE object.
112 ///
113 /// \returns a valid DWARFDie instance if this object has children or an
114 /// invalid DWARFDie instance if it doesn't.
115 DWARFDie getFirstChild() const;
116
117 /// Get the last child of this DIE object.
118 ///
119 /// \returns a valid null DWARFDie instance if this object has children or an
120 /// invalid DWARFDie instance if it doesn't.
121 DWARFDie getLastChild() const;
122
123 /// Dump the DIE and all of its attributes to the supplied stream.
124 ///
125 /// \param OS the stream to use for output.
126 /// \param indent the number of characters to indent each line that is output.
127 void dump(raw_ostream &OS, unsigned indent = 0,
128 DIDumpOptions DumpOpts = DIDumpOptions()) const;
129
130 /// Convenience zero-argument overload for debugging.
131 LLVM_DUMP_METHOD void dump() const;
132
133 /// Extract the specified attribute from this DIE.
134 ///
135 /// Extract an attribute value from this DIE only. This call doesn't look
136 /// for the attribute value in any DW_AT_specification or
137 /// DW_AT_abstract_origin referenced DIEs.
138 ///
139 /// \param Attr the attribute to extract.
140 /// \returns an optional DWARFFormValue that will have the form value if the
141 /// attribute was successfully extracted.
142 Optional<DWARFFormValue> find(dwarf::Attribute Attr) const;
143
144 /// Extract the first value of any attribute in Attrs from this DIE.
145 ///
146 /// Extract the first attribute that matches from this DIE only. This call
147 /// doesn't look for the attribute value in any DW_AT_specification or
148 /// DW_AT_abstract_origin referenced DIEs. The attributes will be searched
149 /// linearly in the order they are specified within Attrs.
150 ///
151 /// \param Attrs an array of DWARF attribute to look for.
152 /// \returns an optional that has a valid DWARFFormValue for the first
153 /// matching attribute in Attrs, or None if none of the attributes in Attrs
154 /// exist in this DIE.
155 Optional<DWARFFormValue> find(ArrayRef<dwarf::Attribute> Attrs) const;
156
157 /// Extract the first value of any attribute in Attrs from this DIE and
158 /// recurse into any DW_AT_specification or DW_AT_abstract_origin referenced
159 /// DIEs.
160 ///
161 /// \param Attrs an array of DWARF attribute to look for.
162 /// \returns an optional that has a valid DWARFFormValue for the first
163 /// matching attribute in Attrs, or None if none of the attributes in Attrs
164 /// exist in this DIE or in any DW_AT_specification or DW_AT_abstract_origin
165 /// DIEs.
166 Optional<DWARFFormValue>
167 findRecursively(ArrayRef<dwarf::Attribute> Attrs) const;
168
169 /// Extract the specified attribute from this DIE as the referenced DIE.
170 ///
171 /// Regardless of the reference type, return the correct DWARFDie instance if
172 /// the attribute exists. The returned DWARFDie object might be from another
173 /// DWARFUnit, but that is all encapsulated in the new DWARFDie object.
174 ///
175 /// Extract an attribute value from this DIE only. This call doesn't look
176 /// for the attribute value in any DW_AT_specification or
177 /// DW_AT_abstract_origin referenced DIEs.
178 ///
179 /// \param Attr the attribute to extract.
180 /// \returns a valid DWARFDie instance if the attribute exists, or an invalid
181 /// DWARFDie object if it doesn't.
182 DWARFDie getAttributeValueAsReferencedDie(dwarf::Attribute Attr) const;
183 DWARFDie getAttributeValueAsReferencedDie(const DWARFFormValue &V) const;
184
185 /// Extract the range base attribute from this DIE as absolute section offset.
186 ///
187 /// This is a utility function that checks for either the DW_AT_rnglists_base
188 /// or DW_AT_GNU_ranges_base attribute.
189 ///
190 /// \returns anm optional absolute section offset value for the attribute.
191 Optional<uint64_t> getRangesBaseAttribute() const;
192 Optional<uint64_t> getLocBaseAttribute() const;
193
194 /// Get the DW_AT_high_pc attribute value as an address.
195 ///
196 /// In DWARF version 4 and later the high PC can be encoded as an offset from
197 /// the DW_AT_low_pc. This function takes care of extracting the value as an
198 /// address or offset and adds it to the low PC if needed and returns the
199 /// value as an optional in case the DIE doesn't have a DW_AT_high_pc
200 /// attribute.
201 ///
202 /// \param LowPC the low PC that might be needed to calculate the high PC.
203 /// \returns an optional address value for the attribute.
204 Optional<uint64_t> getHighPC(uint64_t LowPC) const;
205
206 /// Retrieves DW_AT_low_pc and DW_AT_high_pc from CU.
207 /// Returns true if both attributes are present.
208 bool getLowAndHighPC(uint64_t &LowPC, uint64_t &HighPC,
209 uint64_t &SectionIndex) const;
210
211 /// Get the address ranges for this DIE.
212 ///
213 /// Get the hi/low PC range if both attributes are available or exrtracts the
214 /// non-contiguous address ranges from the DW_AT_ranges attribute.
215 ///
216 /// Extracts the range information from this DIE only. This call doesn't look
217 /// for the range in any DW_AT_specification or DW_AT_abstract_origin DIEs.
218 ///
219 /// \returns a address range vector that might be empty if no address range
220 /// information is available.
221 Expected<DWARFAddressRangesVector> getAddressRanges() const;
222
223 /// Get all address ranges for any DW_TAG_subprogram DIEs in this DIE or any
224 /// of its children.
225 ///
226 /// Get the hi/low PC range if both attributes are available or exrtracts the
227 /// non-contiguous address ranges from the DW_AT_ranges attribute for this DIE
228 /// and all children.
229 ///
230 /// \param Ranges the addres range vector to fill in.
231 void collectChildrenAddressRanges(DWARFAddressRangesVector &Ranges) const;
232
233 bool addressRangeContainsAddress(const uint64_t Address) const;
234
235 Expected<DWARFLocationExpressionsVector>
236 getLocations(dwarf::Attribute Attr) const;
237
238 /// If a DIE represents a subprogram (or inlined subroutine), returns its
239 /// mangled name (or short name, if mangled is missing). This name may be
240 /// fetched from specification or abstract origin for this subprogram.
241 /// Returns null if no name is found.
242 const char *getSubroutineName(DINameKind Kind) const;
243
244 /// Return the DIE name resolving DW_AT_sepcification or DW_AT_abstract_origin
245 /// references if necessary. Returns null if no name is found.
246 const char *getName(DINameKind Kind) const;
247
248 /// Returns the declaration line (start line) for a DIE, assuming it specifies
249 /// a subprogram. This may be fetched from specification or abstract origin
250 /// for this subprogram by resolving DW_AT_sepcification or
251 /// DW_AT_abstract_origin references if necessary.
252 uint64_t getDeclLine() const;
253
254 /// Retrieves values of DW_AT_call_file, DW_AT_call_line and DW_AT_call_column
255 /// from DIE (or zeroes if they are missing). This function looks for
256 /// DW_AT_call attributes in this DIE only, it will not resolve the attribute
257 /// values in any DW_AT_specification or DW_AT_abstract_origin DIEs.
258 /// \param CallFile filled in with non-zero if successful, zero if there is no
259 /// DW_AT_call_file attribute in this DIE.
260 /// \param CallLine filled in with non-zero if successful, zero if there is no
261 /// DW_AT_call_line attribute in this DIE.
262 /// \param CallColumn filled in with non-zero if successful, zero if there is
263 /// no DW_AT_call_column attribute in this DIE.
264 /// \param CallDiscriminator filled in with non-zero if successful, zero if
265 /// there is no DW_AT_GNU_discriminator attribute in this DIE.
266 void getCallerFrame(uint32_t &CallFile, uint32_t &CallLine,
267 uint32_t &CallColumn, uint32_t &CallDiscriminator) const;
268
269 class attribute_iterator;
270
271 /// Get an iterator range to all attributes in the current DIE only.
272 ///
273 /// \returns an iterator range for the attributes of the current DIE.
274 iterator_range<attribute_iterator> attributes() const;
275
276 class iterator;
277
278 iterator begin() const;
279 iterator end() const;
280
281 std::reverse_iterator<iterator> rbegin() const;
282 std::reverse_iterator<iterator> rend() const;
283
284 iterator_range<iterator> children() const;
285 };
286
287 class DWARFDie::attribute_iterator
288 : public iterator_facade_base<attribute_iterator, std::forward_iterator_tag,
289 const DWARFAttribute> {
290 /// The DWARF DIE we are extracting attributes from.
291 DWARFDie Die;
292 /// The value vended to clients via the operator*() or operator->().
293 DWARFAttribute AttrValue;
294 /// The attribute index within the abbreviation declaration in Die.
295 uint32_t Index;
296
297 friend bool operator==(const attribute_iterator &LHS,
298 const attribute_iterator &RHS);
299
300 /// Update the attribute index and attempt to read the attribute value. If the
301 /// attribute is able to be read, update AttrValue and the Index member
302 /// variable. If the attribute value is not able to be read, an appropriate
303 /// error will be set if the Err member variable is non-NULL and the iterator
304 /// will be set to the end value so iteration stops.
305 void updateForIndex(const DWARFAbbreviationDeclaration &AbbrDecl, uint32_t I);
306
307 public:
308 attribute_iterator() = delete;
309 explicit attribute_iterator(DWARFDie D, bool End);
310
311 attribute_iterator &operator++();
312 attribute_iterator &operator--();
313 explicit operator bool() const { return AttrValue.isValid(); }
314 const DWARFAttribute &operator*() const { return AttrValue; }
315 };
316
317 inline bool operator==(const DWARFDie::attribute_iterator &LHS,
318 const DWARFDie::attribute_iterator &RHS) {
319 return LHS.Index == RHS.Index;
320 }
321
322 inline bool operator!=(const DWARFDie::attribute_iterator &LHS,
323 const DWARFDie::attribute_iterator &RHS) {
324 return !(LHS == RHS);
325 }
326
327 inline bool operator==(const DWARFDie &LHS, const DWARFDie &RHS) {
328 return LHS.getDebugInfoEntry() == RHS.getDebugInfoEntry() &&
329 LHS.getDwarfUnit() == RHS.getDwarfUnit();
330 }
331
332 inline bool operator!=(const DWARFDie &LHS, const DWARFDie &RHS) {
333 return !(LHS == RHS);
334 }
335
336 inline bool operator<(const DWARFDie &LHS, const DWARFDie &RHS) {
337 return LHS.getOffset() < RHS.getOffset();
338 }
339
340 class DWARFDie::iterator
341 : public iterator_facade_base<iterator, std::bidirectional_iterator_tag,
342 const DWARFDie> {
343 DWARFDie Die;
344
345 friend std::reverse_iterator<llvm::DWARFDie::iterator>;
346 friend bool operator==(const DWARFDie::iterator &LHS,
347 const DWARFDie::iterator &RHS);
348
349 public:
350 iterator() = default;
351
iterator(DWARFDie D)352 explicit iterator(DWARFDie D) : Die(D) {}
353
354 iterator &operator++() {
355 Die = Die.getSibling();
356 return *this;
357 }
358
359 iterator &operator--() {
360 Die = Die.getPreviousSibling();
361 return *this;
362 }
363
364 const DWARFDie &operator*() const { return Die; }
365 };
366
367 inline bool operator==(const DWARFDie::iterator &LHS,
368 const DWARFDie::iterator &RHS) {
369 return LHS.Die == RHS.Die;
370 }
371
372 inline bool operator!=(const DWARFDie::iterator &LHS,
373 const DWARFDie::iterator &RHS) {
374 return !(LHS == RHS);
375 }
376
377 // These inline functions must follow the DWARFDie::iterator definition above
378 // as they use functions from that class.
begin()379 inline DWARFDie::iterator DWARFDie::begin() const {
380 return iterator(getFirstChild());
381 }
382
end()383 inline DWARFDie::iterator DWARFDie::end() const {
384 return iterator(getLastChild());
385 }
386
children()387 inline iterator_range<DWARFDie::iterator> DWARFDie::children() const {
388 return make_range(begin(), end());
389 }
390
391 } // end namespace llvm
392
393 namespace std {
394
395 template <>
396 class reverse_iterator<llvm::DWARFDie::iterator>
397 : public llvm::iterator_facade_base<
398 reverse_iterator<llvm::DWARFDie::iterator>,
399 bidirectional_iterator_tag, const llvm::DWARFDie> {
400
401 private:
402 llvm::DWARFDie Die;
403 bool AtEnd;
404
405 public:
reverse_iterator(llvm::DWARFDie::iterator It)406 reverse_iterator(llvm::DWARFDie::iterator It)
407 : Die(It.Die), AtEnd(!It.Die.getPreviousSibling()) {
408 if (!AtEnd)
409 Die = Die.getPreviousSibling();
410 }
411
base()412 llvm::DWARFDie::iterator base() const {
413 return llvm::DWARFDie::iterator(AtEnd ? Die : Die.getSibling());
414 }
415
416 reverse_iterator<llvm::DWARFDie::iterator> &operator++() {
417 assert(!AtEnd && "Incrementing rend");
418 llvm::DWARFDie D = Die.getPreviousSibling();
419 if (D)
420 Die = D;
421 else
422 AtEnd = true;
423 return *this;
424 }
425
426 reverse_iterator<llvm::DWARFDie::iterator> &operator--() {
427 if (AtEnd) {
428 AtEnd = false;
429 return *this;
430 }
431 Die = Die.getSibling();
432 assert(!Die.isNULL() && "Decrementing rbegin");
433 return *this;
434 }
435
436 const llvm::DWARFDie &operator*() const {
437 assert(Die.isValid());
438 return Die;
439 }
440
441 // FIXME: We should be able to specify the equals operator as a friend, but
442 // that causes the compiler to think the operator overload is ambiguous
443 // with the friend declaration and the actual definition as candidates.
equals(const reverse_iterator<llvm::DWARFDie::iterator> & RHS)444 bool equals(const reverse_iterator<llvm::DWARFDie::iterator> &RHS) const {
445 return Die == RHS.Die && AtEnd == RHS.AtEnd;
446 }
447 };
448
449 } // namespace std
450
451 namespace llvm {
452
453 inline bool operator==(const std::reverse_iterator<DWARFDie::iterator> &LHS,
454 const std::reverse_iterator<DWARFDie::iterator> &RHS) {
455 return LHS.equals(RHS);
456 }
457
458 inline bool operator!=(const std::reverse_iterator<DWARFDie::iterator> &LHS,
459 const std::reverse_iterator<DWARFDie::iterator> &RHS) {
460 return !(LHS == RHS);
461 }
462
rbegin()463 inline std::reverse_iterator<DWARFDie::iterator> DWARFDie::rbegin() const {
464 return llvm::make_reverse_iterator(end());
465 }
466
rend()467 inline std::reverse_iterator<DWARFDie::iterator> DWARFDie::rend() const {
468 return llvm::make_reverse_iterator(begin());
469 }
470
471 } // end namespace llvm
472
473 #endif // LLVM_DEBUGINFO_DWARFDIE_H
474