1 //===-- DWARFDie.h --------------------------------------------------------===//
3 // The LLVM Compiler Infrastructure
5 // This file is distributed under the University of Illinois Open Source
6 // License. See LICENSE.TXT for details.
8 //===----------------------------------------------------------------------===//
10 #ifndef LLVM_LIB_DEBUGINFO_DWARFDIE_H
11 #define LLVM_LIB_DEBUGINFO_DWARFDIE_H
13 #include "llvm/ADT/iterator.h"
14 #include "llvm/ADT/iterator_range.h"
15 #include "llvm/ADT/Optional.h"
16 #include "llvm/DebugInfo/DWARF/DWARFDebugInfoEntry.h"
21 class DWARFDebugInfoEntry;
24 //===----------------------------------------------------------------------===//
25 /// Utility class that carries the DWARF compile/type unit and the debug info
26 /// entry in an object.
28 /// When accessing information from a debug info entry we always need to DWARF
29 /// compile/type unit in order to extract the info correctly as some information
30 /// is relative to the compile/type unit. Prior to this class the DWARFUnit and
31 /// the DWARFDebugInfoEntry was passed around separately and there was the
32 /// possibility for error if the wrong DWARFUnit was used to extract a unit
33 /// relative offset. This class helps to ensure that this doesn't happen and
34 /// also simplifies the attribute extraction calls by not having to specify the
35 /// DWARFUnit for each call.
38 const DWARFDebugInfoEntry *Die;
40 DWARFDie() : U(nullptr), Die(nullptr) {}
41 DWARFDie(DWARFUnit *Unit, const DWARFDebugInfoEntry * D) : U(Unit), Die(D) {}
43 bool isValid() const { return U && Die; }
44 explicit operator bool() const { return isValid(); }
45 const DWARFDebugInfoEntry *getDebugInfoEntry() const { return Die; }
46 DWARFUnit *getDwarfUnit() const { return U; }
49 /// Get the abbreviation declaration for this DIE.
51 /// \returns the abbreviation declaration or NULL for null tags.
52 const DWARFAbbreviationDeclaration *getAbbreviationDeclarationPtr() const {
53 assert(isValid() && "must check validity prior to calling");
54 return Die->getAbbreviationDeclarationPtr();
57 /// Get the absolute offset into the debug info or types section.
59 /// \returns the DIE offset or -1U if invalid.
60 uint32_t getOffset() const {
61 assert(isValid() && "must check validity prior to calling");
62 return Die->getOffset();
65 dwarf::Tag getTag() const {
66 auto AbbrevDecl = getAbbreviationDeclarationPtr();
68 return AbbrevDecl->getTag();
69 return dwarf::DW_TAG_null;
72 bool hasChildren() const {
73 assert(isValid() && "must check validity prior to calling");
74 return Die->hasChildren();
77 /// Returns true for a valid DIE that terminates a sibling chain.
79 return getAbbreviationDeclarationPtr() == nullptr;
81 /// Returns true if DIE represents a subprogram (not inlined).
82 bool isSubprogramDIE() const;
84 /// Returns true if DIE represents a subprogram or an inlined subroutine.
85 bool isSubroutineDIE() const;
87 /// Get the parent of this DIE object.
89 /// \returns a valid DWARFDie instance if this object has a parent or an
90 /// invalid DWARFDie instance if it doesn't.
91 DWARFDie getParent() const;
93 /// Get the sibling of this DIE object.
95 /// \returns a valid DWARFDie instance if this object has a sibling or an
96 /// invalid DWARFDie instance if it doesn't.
97 DWARFDie getSibling() const;
99 /// Get the first child of this DIE object.
101 /// \returns a valid DWARFDie instance if this object has children or an
102 /// invalid DWARFDie instance if it doesn't.
103 DWARFDie getFirstChild() const {
104 if (isValid() && Die->hasChildren())
105 return DWARFDie(U, Die + 1);
109 /// Dump the DIE and all of its attributes to the supplied stream.
111 /// \param OS the stream to use for output.
112 /// \param recurseDepth the depth to recurse to when dumping this DIE and its
114 /// \param indent the number of characters to indent each line that is output.
115 void dump(raw_ostream &OS, unsigned recurseDepth, unsigned indent = 0) const;
117 /// Extract the specified attribute from this DIE.
119 /// Extract an attribute value from this DIE only. This call doesn't look
120 /// for the attribute value in any DW_AT_specification or
121 /// DW_AT_abstract_origin referenced DIEs.
123 /// \param Attr the attribute to extract.
124 /// \returns an optional DWARFFormValue that will have the form value if the
125 /// attribute was successfully extracted.
126 Optional<DWARFFormValue> getAttributeValue(dwarf::Attribute Attr) const;
128 /// Extract the specified attribute from this DIE as a C string.
130 /// Extract an attribute value from this DIE only. This call doesn't look
131 /// for the attribute value in any DW_AT_specification or
132 /// DW_AT_abstract_origin referenced DIEs.
134 /// \param Attr the attribute to extract.
135 /// \param FailValue the value to return if this DIE doesn't have this
137 /// \returns the NULL terminated C string value owned by the DWARF section
138 /// that contains the string or FailValue if the attribute doesn't exist or
139 /// if the attribute's form isn't a form that describes an string.
140 const char *getAttributeValueAsString(dwarf::Attribute Attr,
141 const char *FailValue) const;
143 /// Extract the specified attribute from this DIE as an address.
145 /// Extract an attribute value from this DIE only. This call doesn't look
146 /// for the attribute value in any DW_AT_specification or
147 /// DW_AT_abstract_origin referenced DIEs.
149 /// \param Attr the attribute to extract.
150 /// \param FailValue the value to return if this DIE doesn't have this
152 /// \returns the address value of the attribute or FailValue if the
153 /// attribute doesn't exist or if the attribute's form isn't a form that
154 /// describes an address.
155 uint64_t getAttributeValueAsAddress(dwarf::Attribute Attr,
156 uint64_t FailValue) const;
158 /// Extract the specified attribute from this DIE as an address.
160 /// Extract an attribute value from this DIE only. This call doesn't look
161 /// for the attribute value in any DW_AT_specification or
162 /// DW_AT_abstract_origin referenced DIEs.
164 /// \param Attr the attribute to extract.
165 /// \returns an optional value for the attribute.
166 Optional<uint64_t> getAttributeValueAsAddress(dwarf::Attribute Attr) const;
168 /// Extract the specified attribute from this DIE as a signed integer.
170 /// Extract an attribute value from this DIE only. This call doesn't look
171 /// for the attribute value in any DW_AT_specification or
172 /// DW_AT_abstract_origin referenced DIEs.
174 /// \param Attr the attribute to extract.
175 /// \param FailValue the value to return if this DIE doesn't have this
177 /// \returns the signed integer constant value of the attribute or FailValue
178 /// if the attribute doesn't exist or if the attribute's form isn't a form
179 /// that describes a signed integer.
180 int64_t getAttributeValueAsSignedConstant(dwarf::Attribute Attr,
181 int64_t FailValue) const;
183 /// Extract the specified attribute from this DIE as a signed integer.
185 /// Extract an attribute value from this DIE only. This call doesn't look
186 /// for the attribute value in any DW_AT_specification or
187 /// DW_AT_abstract_origin referenced DIEs.
189 /// \param Attr the attribute to extract.
190 /// \returns an optional value for the attribute.
192 getAttributeValueAsSignedConstant(dwarf::Attribute Attr) const;
194 /// Extract the specified attribute from this DIE as an unsigned integer.
196 /// Extract an attribute value from this DIE only. This call doesn't look
197 /// for the attribute value in any DW_AT_specification or
198 /// DW_AT_abstract_origin referenced DIEs.
200 /// \param Attr the attribute to extract.
201 /// \param FailValue the value to return if this DIE doesn't have this
203 /// \returns the unsigned integer constant value of the attribute or FailValue
204 /// if the attribute doesn't exist or if the attribute's form isn't a form
205 /// that describes an unsigned integer.
206 uint64_t getAttributeValueAsUnsignedConstant(dwarf::Attribute Attr,
207 uint64_t FailValue) const;
209 /// Extract the specified attribute from this DIE as an unsigned integer.
211 /// Extract an attribute value from this DIE only. This call doesn't look
212 /// for the attribute value in any DW_AT_specification or
213 /// DW_AT_abstract_origin referenced DIEs.
215 /// \param Attr the attribute to extract.
216 /// \returns an optional value for the attribute.
218 getAttributeValueAsUnsignedConstant(dwarf::Attribute Attr) const;
220 /// Extract the specified attribute from this DIE as absolute DIE Offset.
222 /// Extract an attribute value from this DIE only. This call doesn't look
223 /// for the attribute value in any DW_AT_specification or
224 /// DW_AT_abstract_origin referenced DIEs.
226 /// \param Attr the attribute to extract.
227 /// \param FailValue the value to return if this DIE doesn't have this
229 /// \returns the unsigned integer constant value of the attribute or FailValue
230 /// if the attribute doesn't exist or if the attribute's form isn't a form
231 /// that describes a reference.
232 uint64_t getAttributeValueAsReference(dwarf::Attribute Attr,
233 uint64_t FailValue) const;
235 /// Extract the specified attribute from this DIE as absolute DIE Offset.
237 /// Extract an attribute value from this DIE only. This call doesn't look
238 /// for the attribute value in any DW_AT_specification or
239 /// DW_AT_abstract_origin referenced DIEs.
241 /// \param Attr the attribute to extract.
242 /// \returns an optional value for the attribute.
243 Optional<uint64_t> getAttributeValueAsReference(dwarf::Attribute Attr) const;
245 /// Extract the specified attribute from this DIE as absolute section offset.
247 /// Extract an attribute value from this DIE only. This call doesn't look
248 /// for the attribute value in any DW_AT_specification or
249 /// DW_AT_abstract_origin referenced DIEs.
251 /// \param Attr the attribute to extract.
252 /// \param FailValue the value to return if this DIE doesn't have this
254 /// \returns the unsigned integer constant value of the attribute or FailValue
255 /// if the attribute doesn't exist or if the attribute's form isn't a form
256 /// that describes a section offset.
257 uint64_t getAttributeValueAsSectionOffset(dwarf::Attribute Attr,
258 uint64_t FailValue) const;
259 /// Extract the specified attribute from this DIE as absolute section offset.
261 /// Extract an attribute value from this DIE only. This call doesn't look
262 /// for the attribute value in any DW_AT_specification or
263 /// DW_AT_abstract_origin referenced DIEs.
265 /// \param Attr the attribute to extract.
266 /// \returns an optional value for the attribute.
268 getAttributeValueAsSectionOffset(dwarf::Attribute Attr) const;
270 /// Extract the specified attribute from this DIE as the referenced DIE.
272 /// Regardless of the reference type, return the correct DWARFDie instance if
273 /// the attribute exists. The returned DWARFDie object might be from another
274 /// DWARFUnit, but that is all encapsulated in the new DWARFDie object.
276 /// Extract an attribute value from this DIE only. This call doesn't look
277 /// for the attribute value in any DW_AT_specification or
278 /// DW_AT_abstract_origin referenced DIEs.
280 /// \param Attr the attribute to extract.
281 /// \returns a valid DWARFDie instance if the attribute exists, or an invalid
282 /// DWARFDie object if it doesn't.
283 DWARFDie getAttributeValueAsReferencedDie(dwarf::Attribute Attr) const;
285 /// Extract the range base attribute from this DIE as absolute section offset.
287 /// This is a utility function that checks for either the DW_AT_rnglists_base
288 /// or DW_AT_GNU_ranges_base attribute.
290 /// \returns anm optional absolute section offset value for the attribute.
291 Optional<uint64_t> getRangesBaseAttribute() const;
293 /// Get the DW_AT_high_pc attribute value as an address.
295 /// In DWARF version 4 and later the high PC can be encoded as an offset from
296 /// the DW_AT_low_pc. This function takes care of extracting the value as an
297 /// address or offset and adds it to the low PC if needed and returns the
298 /// value as an optional in case the DIE doesn't have a DW_AT_high_pc
301 /// \param LowPC the low PC that might be needed to calculate the high PC.
302 /// \returns an optional address value for the attribute.
303 Optional<uint64_t> getHighPC(uint64_t LowPC) const;
305 /// Retrieves DW_AT_low_pc and DW_AT_high_pc from CU.
306 /// Returns true if both attributes are present.
307 bool getLowAndHighPC(uint64_t &LowPC, uint64_t &HighPC) const;
309 /// Get the address ranges for this DIE.
311 /// Get the hi/low PC range if both attributes are available or exrtracts the
312 /// non-contiguous address ranges from the DW_AT_ranges attribute.
314 /// Extracts the range information from this DIE only. This call doesn't look
315 /// for the range in any DW_AT_specification or DW_AT_abstract_origin DIEs.
317 /// \returns a address range vector that might be empty if no address range
318 /// information is available.
319 DWARFAddressRangesVector getAddressRanges() const;
321 /// Get all address ranges for any DW_TAG_subprogram DIEs in this DIE or any
324 /// Get the hi/low PC range if both attributes are available or exrtracts the
325 /// non-contiguous address ranges from the DW_AT_ranges attribute for this DIE
326 /// and all children.
328 /// \param Ranges the addres range vector to fill in.
329 void collectChildrenAddressRanges(DWARFAddressRangesVector &Ranges) const;
331 bool addressRangeContainsAddress(const uint64_t Address) const;
333 /// If a DIE represents a subprogram (or inlined subroutine), returns its
334 /// mangled name (or short name, if mangled is missing). This name may be
335 /// fetched from specification or abstract origin for this subprogram.
336 /// Returns null if no name is found.
337 const char *getSubroutineName(DINameKind Kind) const;
339 /// Return the DIE name resolving DW_AT_sepcification or DW_AT_abstract_origin
340 /// references if necessary. Returns null if no name is found.
341 const char *getName(DINameKind Kind) const;
343 /// Retrieves values of DW_AT_call_file, DW_AT_call_line and DW_AT_call_column
344 /// from DIE (or zeroes if they are missing). This function looks for
345 /// DW_AT_call attributes in this DIE only, it will not resolve the attribute
346 /// values in any DW_AT_specification or DW_AT_abstract_origin DIEs.
347 /// \param CallFile filled in with non-zero if successful, zero if there is no
348 /// DW_AT_call_file attribute in this DIE.
349 /// \param CallLine filled in with non-zero if successful, zero if there is no
350 /// DW_AT_call_line attribute in this DIE.
351 /// \param CallColumn filled in with non-zero if successful, zero if there is
352 /// no DW_AT_call_column attribute in this DIE.
353 void getCallerFrame(uint32_t &CallFile, uint32_t &CallLine,
354 uint32_t &CallColumn) const;
356 /// Get inlined chain for a given address, rooted at the current DIE.
357 /// Returns empty chain if address is not contained in address range
360 getInlinedChainForAddress(const uint64_t Address,
361 SmallVectorImpl<DWARFDie> &InlinedChain) const;
365 iterator begin() const;
366 iterator end() const;
367 iterator_range<iterator> children() const;
371 inline bool operator==(const DWARFDie &LHS, const DWARFDie &RHS) {
372 return LHS.getDebugInfoEntry() == RHS.getDebugInfoEntry() &&
373 LHS.getDwarfUnit() == RHS.getDwarfUnit();
376 inline bool operator!=(const DWARFDie &LHS, const DWARFDie &RHS) {
377 return !(LHS == RHS);
380 class DWARFDie::iterator : public iterator_facade_base<iterator,
381 std::forward_iterator_tag,
385 if (Die && Die.isNULL())
389 iterator() = default;
390 explicit iterator(DWARFDie D) : Die(D) {
391 // If we start out with only a Null DIE then invalidate.
394 iterator &operator++() {
395 Die = Die.getSibling();
396 // Don't include the NULL die when iterating.
400 explicit operator bool() const { return Die.isValid(); }
401 const DWARFDie &operator*() const { return Die; }
402 bool operator==(const iterator &X) const { return Die == X.Die; }
405 // These inline functions must follow the DWARFDie::iterator definition above
406 // as they use functions from that class.
407 inline DWARFDie::iterator DWARFDie::begin() const {
408 return iterator(getFirstChild());
411 inline DWARFDie::iterator DWARFDie::end() const {
415 inline iterator_range<DWARFDie::iterator> DWARFDie::children() const {
416 return make_range(begin(), end());
419 } // end namespace llvm
421 #endif // LLVM_LIB_DEBUGINFO_DWARFDIE_H