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

source code of llvm/include/llvm/DebugInfo/DWARF/DWARFDie.h