LLVM  4.0.0
DWARFDie.h
Go to the documentation of this file.
1 //===-- DWARFDie.h --------------------------------------------------------===//
2 //
3 // The LLVM Compiler Infrastructure
4 //
5 // This file is distributed under the University of Illinois Open Source
6 // License. See LICENSE.TXT for details.
7 //
8 //===----------------------------------------------------------------------===//
9 
10 #ifndef LLVM_LIB_DEBUGINFO_DWARFDIE_H
11 #define LLVM_LIB_DEBUGINFO_DWARFDIE_H
12 
13 #include "llvm/ADT/iterator.h"
15 #include "llvm/ADT/Optional.h"
17 
18 namespace llvm {
19 
20 class DWARFUnit;
21 class DWARFDebugInfoEntry;
22 class raw_ostream;
23 
24 //===----------------------------------------------------------------------===//
25 /// Utility class that carries the DWARF compile/type unit and the debug info
26 /// entry in an object.
27 ///
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.
36 class DWARFDie {
37  DWARFUnit *U;
38  const DWARFDebugInfoEntry *Die;
39 public:
40  DWARFDie() : U(nullptr), Die(nullptr) {}
41  DWARFDie(DWARFUnit *Unit, const DWARFDebugInfoEntry * D) : U(Unit), Die(D) {}
42 
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; }
47 
48 
49  /// Get the abbreviation declaration for this DIE.
50  ///
51  /// \returns the abbreviation declaration or NULL for null tags.
53  assert(isValid() && "must check validity prior to calling");
54  return Die->getAbbreviationDeclarationPtr();
55  }
56 
57  /// Get the absolute offset into the debug info or types section.
58  ///
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();
63  }
64 
65  dwarf::Tag getTag() const {
66  auto AbbrevDecl = getAbbreviationDeclarationPtr();
67  if (AbbrevDecl)
68  return AbbrevDecl->getTag();
69  return dwarf::DW_TAG_null;
70  }
71 
72  bool hasChildren() const {
73  assert(isValid() && "must check validity prior to calling");
74  return Die->hasChildren();
75  }
76 
77  /// Returns true for a valid DIE that terminates a sibling chain.
78  bool isNULL() const {
79  return getAbbreviationDeclarationPtr() == nullptr;
80  }
81  /// Returns true if DIE represents a subprogram (not inlined).
82  bool isSubprogramDIE() const;
83 
84  /// Returns true if DIE represents a subprogram or an inlined subroutine.
85  bool isSubroutineDIE() const;
86 
87  /// Get the parent of this DIE object.
88  ///
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;
92 
93  /// Get the sibling of this DIE object.
94  ///
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;
98 
99  /// Get the first child of this DIE object.
100  ///
101  /// \returns a valid DWARFDie instance if this object has children or an
102  /// invalid DWARFDie instance if it doesn't.
104  if (isValid() && Die->hasChildren())
105  return DWARFDie(U, Die + 1);
106  return DWARFDie();
107  }
108 
109  /// Dump the DIE and all of its attributes to the supplied stream.
110  ///
111  /// \param OS the stream to use for output.
112  /// \param recurseDepth the depth to recurse to when dumping this DIE and its
113  /// children.
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;
116 
117  /// Extract the specified attribute from this DIE.
118  ///
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.
122  ///
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.
127 
128  /// Extract the specified attribute from this DIE as a C string.
129  ///
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.
133  ///
134  /// \param Attr the attribute to extract.
135  /// \param FailValue the value to return if this DIE doesn't have this
136  /// attribute.
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.
141  const char *FailValue) const;
142 
143  /// Extract the specified attribute from this DIE as an address.
144  ///
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.
148  ///
149  /// \param Attr the attribute to extract.
150  /// \returns an optional value for the attribute.
152 
153  /// Extract the specified attribute from this DIE as a signed integer.
154  ///
155  /// Extract an attribute value from this DIE only. This call doesn't look
156  /// for the attribute value in any DW_AT_specification or
157  /// DW_AT_abstract_origin referenced DIEs.
158  ///
159  /// \param Attr the attribute to extract.
160  /// \returns an optional value for the attribute.
163 
164  /// Extract the specified attribute from this DIE as an unsigned integer.
165  ///
166  /// Extract an attribute value from this DIE only. This call doesn't look
167  /// for the attribute value in any DW_AT_specification or
168  /// DW_AT_abstract_origin referenced DIEs.
169  ///
170  /// \param Attr the attribute to extract.
171  /// \returns an optional value for the attribute.
174 
175  /// Extract the specified attribute from this DIE as absolute DIE Offset.
176  ///
177  /// Extract an attribute value from this DIE only. This call doesn't look
178  /// for the attribute value in any DW_AT_specification or
179  /// DW_AT_abstract_origin referenced DIEs.
180  ///
181  /// \param Attr the attribute to extract.
182  /// \returns an optional value for the attribute.
184 
185  /// Extract the specified attribute from this DIE as absolute section offset.
186  ///
187  /// Extract an attribute value from this DIE only. This call doesn't look
188  /// for the attribute value in any DW_AT_specification or
189  /// DW_AT_abstract_origin referenced DIEs.
190  ///
191  /// \param Attr the attribute to extract.
192  /// \returns an optional value for the attribute.
195 
196  /// Extract the specified attribute from this DIE as the referenced DIE.
197  ///
198  /// Regardless of the reference type, return the correct DWARFDie instance if
199  /// the attribute exists. The returned DWARFDie object might be from another
200  /// DWARFUnit, but that is all encapsulated in the new DWARFDie object.
201  ///
202  /// Extract an attribute value from this DIE only. This call doesn't look
203  /// for the attribute value in any DW_AT_specification or
204  /// DW_AT_abstract_origin referenced DIEs.
205  ///
206  /// \param Attr the attribute to extract.
207  /// \returns a valid DWARFDie instance if the attribute exists, or an invalid
208  /// DWARFDie object if it doesn't.
210 
211  /// Extract the range base attribute from this DIE as absolute section offset.
212  ///
213  /// This is a utility function that checks for either the DW_AT_rnglists_base
214  /// or DW_AT_GNU_ranges_base attribute.
215  ///
216  /// \returns anm optional absolute section offset value for the attribute.
218 
219  /// Get the DW_AT_high_pc attribute value as an address.
220  ///
221  /// In DWARF version 4 and later the high PC can be encoded as an offset from
222  /// the DW_AT_low_pc. This function takes care of extracting the value as an
223  /// address or offset and adds it to the low PC if needed and returns the
224  /// value as an optional in case the DIE doesn't have a DW_AT_high_pc
225  /// attribute.
226  ///
227  /// \param LowPC the low PC that might be needed to calculate the high PC.
228  /// \returns an optional address value for the attribute.
229  Optional<uint64_t> getHighPC(uint64_t LowPC) const;
230 
231  /// Retrieves DW_AT_low_pc and DW_AT_high_pc from CU.
232  /// Returns true if both attributes are present.
233  bool getLowAndHighPC(uint64_t &LowPC, uint64_t &HighPC) const;
234 
235  /// Get the address ranges for this DIE.
236  ///
237  /// Get the hi/low PC range if both attributes are available or exrtracts the
238  /// non-contiguous address ranges from the DW_AT_ranges attribute.
239  ///
240  /// Extracts the range information from this DIE only. This call doesn't look
241  /// for the range in any DW_AT_specification or DW_AT_abstract_origin DIEs.
242  ///
243  /// \returns a address range vector that might be empty if no address range
244  /// information is available.
246 
247  /// Get all address ranges for any DW_TAG_subprogram DIEs in this DIE or any
248  /// of its children.
249  ///
250  /// Get the hi/low PC range if both attributes are available or exrtracts the
251  /// non-contiguous address ranges from the DW_AT_ranges attribute for this DIE
252  /// and all children.
253  ///
254  /// \param Ranges the addres range vector to fill in.
256 
257  bool addressRangeContainsAddress(const uint64_t Address) const;
258 
259  /// If a DIE represents a subprogram (or inlined subroutine), returns its
260  /// mangled name (or short name, if mangled is missing). This name may be
261  /// fetched from specification or abstract origin for this subprogram.
262  /// Returns null if no name is found.
263  const char *getSubroutineName(DINameKind Kind) const;
264 
265  /// Return the DIE name resolving DW_AT_sepcification or DW_AT_abstract_origin
266  /// references if necessary. Returns null if no name is found.
267  const char *getName(DINameKind Kind) const;
268 
269  /// Retrieves values of DW_AT_call_file, DW_AT_call_line and DW_AT_call_column
270  /// from DIE (or zeroes if they are missing). This function looks for
271  /// DW_AT_call attributes in this DIE only, it will not resolve the attribute
272  /// values in any DW_AT_specification or DW_AT_abstract_origin DIEs.
273  /// \param CallFile filled in with non-zero if successful, zero if there is no
274  /// DW_AT_call_file attribute in this DIE.
275  /// \param CallLine filled in with non-zero if successful, zero if there is no
276  /// DW_AT_call_line attribute in this DIE.
277  /// \param CallColumn filled in with non-zero if successful, zero if there is
278  /// no DW_AT_call_column attribute in this DIE.
279  void getCallerFrame(uint32_t &CallFile, uint32_t &CallLine,
280  uint32_t &CallColumn) const;
281 
282  /// Get inlined chain for a given address, rooted at the current DIE.
283  /// Returns empty chain if address is not contained in address range
284  /// of current DIE.
285  void
286  getInlinedChainForAddress(const uint64_t Address,
287  SmallVectorImpl<DWARFDie> &InlinedChain) const;
288 
289  class iterator;
290 
291  iterator begin() const;
292  iterator end() const;
294 };
295 
296 
297 inline bool operator==(const DWARFDie &LHS, const DWARFDie &RHS) {
298  return LHS.getDebugInfoEntry() == RHS.getDebugInfoEntry() &&
299  LHS.getDwarfUnit() == RHS.getDwarfUnit();
300 }
301 
302 inline bool operator!=(const DWARFDie &LHS, const DWARFDie &RHS) {
303  return !(LHS == RHS);
304 }
305 
306 class DWARFDie::iterator : public iterator_facade_base<iterator,
307  std::forward_iterator_tag,
308  const DWARFDie> {
309  DWARFDie Die;
310  void skipNull() {
311  if (Die && Die.isNULL())
312  Die = DWARFDie();
313  }
314 public:
315  iterator() = default;
316  explicit iterator(DWARFDie D) : Die(D) {
317  // If we start out with only a Null DIE then invalidate.
318  skipNull();
319  }
321  Die = Die.getSibling();
322  // Don't include the NULL die when iterating.
323  skipNull();
324  return *this;
325  }
326  explicit operator bool() const { return Die.isValid(); }
327  const DWARFDie &operator*() const { return Die; }
328  bool operator==(const iterator &X) const { return Die == X.Die; }
329 };
330 
331 // These inline functions must follow the DWARFDie::iterator definition above
332 // as they use functions from that class.
334  return iterator(getFirstChild());
335 }
336 
338  return iterator();
339 }
340 
342  return make_range(begin(), end());
343 }
344 
345 } // end namespace llvm
346 
347 #endif // LLVM_LIB_DEBUGINFO_DWARFDIE_H
const DWARFDie & operator*() const
Definition: DWARFDie.h:327
Optional< int64_t > getAttributeValueAsSignedConstant(dwarf::Attribute Attr) const
Extract the specified attribute from this DIE as a signed integer.
Definition: DWARFDie.cpp:163
DWARFDie getAttributeValueAsReferencedDie(dwarf::Attribute Attr) const
Extract the specified attribute from this DIE as the referenced DIE.
Definition: DWARFDie.cpp:192
DWARFAddressRangesVector getAddressRanges() const
Get the address ranges for this DIE.
Definition: DWARFDie.cpp:237
Optional< uint64_t > getHighPC(uint64_t LowPC) const
Get the DW_AT_high_pc attribute value as an address.
Definition: DWARFDie.cpp:210
std::vector< std::pair< uint64_t, uint64_t > > DWARFAddressRangesVector
DWARFAddressRangesVector - represents a set of absolute address ranges.
Optional< DWARFFormValue > getAttributeValue(dwarf::Attribute Attr) const
Extract the specified attribute from this DIE.
Definition: DWARFDie.cpp:137
Attribute
Attributes.
Definition: Dwarf.h:94
This provides a very simple, boring adaptor for a begin and end iterator into a range type...
void getCallerFrame(uint32_t &CallFile, uint32_t &CallLine, uint32_t &CallColumn) const
Retrieves values of DW_AT_call_file, DW_AT_call_line and DW_AT_call_column from DIE (or zeroes if the...
Definition: DWARFDie.cpp:308
void collectChildrenAddressRanges(DWARFAddressRangesVector &Ranges) const
Get all address ranges for any DW_TAG_subprogram DIEs in this DIE or any of its children.
Definition: DWARFDie.cpp:256
bool getLowAndHighPC(uint64_t &LowPC, uint64_t &HighPC) const
Retrieves DW_AT_low_pc and DW_AT_high_pc from CU.
Definition: DWARFDie.cpp:224
const DWARFDebugInfoEntry * getDebugInfoEntry() const
Definition: DWARFDie.h:45
DINameKind
A DINameKind is passed to name search methods to specify a preference regarding the type of name reso...
Definition: DIContext.h:97
bool isValid() const
Definition: DWARFDie.h:43
bool addressRangeContainsAddress(const uint64_t Address) const
Definition: DWARFDie.cpp:268
const char * getSubroutineName(DINameKind Kind) const
If a DIE represents a subprogram (or inlined subroutine), returns its mangled name (or short name...
Definition: DWARFDie.cpp:277
Optional< uint64_t > getAttributeValueAsAddress(dwarf::Attribute Attr) const
Extract the specified attribute from this DIE as an address.
Definition: DWARFDie.cpp:156
uint32_t getOffset() const
Get the absolute offset into the debug info or types section.
Definition: DWARFDie.h:60
This class consists of common code factored out of the SmallVector class to reduce code duplication b...
Definition: APFloat.h:32
static GCRegistry::Add< StatepointGC > D("statepoint-example","an example strategy for statepoint")
const char * getAttributeValueAsString(dwarf::Attribute Attr, const char *FailValue) const
Extract the specified attribute from this DIE as a C string.
Definition: DWARFDie.cpp:146
CRTP base class which implements the entire standard iterator facade in terms of a minimal subset of ...
Definition: iterator.h:65
DWARFDie getParent() const
Get the parent of this DIE object.
Definition: DWARFDie.cpp:391
Optional< uint64_t > getAttributeValueAsSectionOffset(dwarf::Attribute Attr) const
Extract the specified attribute from this DIE as absolute section offset.
Definition: DWARFDie.cpp:184
DWARFDie getSibling() const
Get the sibling of this DIE object.
Definition: DWARFDie.cpp:397
DWARFUnit * getDwarfUnit() const
Definition: DWARFDie.h:46
Utility class that carries the DWARF compile/type unit and the debug info entry in an object...
Definition: DWARFDie.h:36
iterator end() const
Definition: DWARFDie.h:337
void getInlinedChainForAddress(const uint64_t Address, SmallVectorImpl< DWARFDie > &InlinedChain) const
Get inlined chain for a given address, rooted at the current DIE.
Definition: DWARFDie.cpp:365
iterator_range< iterator > children() const
Definition: DWARFDie.h:341
static GCMetadataPrinterRegistry::Add< ErlangGCPrinter > X("erlang","erlang-compatible garbage collector")
Optional< uint64_t > getAttributeValueAsUnsignedConstant(dwarf::Attribute Attr) const
Extract the specified attribute from this DIE as an unsigned integer.
Definition: DWARFDie.cpp:170
bool operator==(const iterator &X) const
Definition: DWARFDie.h:328
bool hasChildren() const
Definition: DWARFDie.h:72
void dump(raw_ostream &OS, unsigned recurseDepth, unsigned indent=0) const
Dump the DIE and all of its attributes to the supplied stream.
Definition: DWARFDie.cpp:316
DWARFDie getFirstChild() const
Get the first child of this DIE object.
Definition: DWARFDie.h:103
const DWARFAbbreviationDeclaration * getAbbreviationDeclarationPtr() const
Get the abbreviation declaration for this DIE.
Definition: DWARFDie.h:52
iterator_range< T > make_range(T x, T y)
Convenience function for iterating over sub-ranges.
const char * getName(DINameKind Kind) const
Return the DIE name resolving DW_AT_sepcification or DW_AT_abstract_origin references if necessary...
Definition: DWARFDie.cpp:284
Optional< uint64_t > getAttributeValueAsReference(dwarf::Attribute Attr) const
Extract the specified attribute from this DIE as absolute DIE Offset.
Definition: DWARFDie.cpp:177
A range adaptor for a pair of iterators.
iterator begin() const
Definition: DWARFDie.h:333
Optional< uint64_t > getRangesBaseAttribute() const
Extract the range base attribute from this DIE as absolute section offset.
Definition: DWARFDie.cpp:203
bool isSubroutineDIE() const
Returns true if DIE represents a subprogram or an inlined subroutine.
Definition: DWARFDie.cpp:131
bool operator!=(uint64_t V1, const APInt &V2)
Definition: APInt.h:1724
bool isSubprogramDIE() const
Returns true if DIE represents a subprogram (not inlined).
Definition: DWARFDie.cpp:127
const DWARFAbbreviationDeclaration * getAbbreviationDeclarationPtr() const
iterator & operator++()
Definition: DWARFDie.h:320
std::vector< uint8_t > Unit
Definition: FuzzerDefs.h:71
const unsigned Kind
assert(ImpDefSCC.getReg()==AMDGPU::SCC &&ImpDefSCC.isDef())
dwarf::Tag getTag() const
Definition: DWARFDie.h:65
DWARFDebugInfoEntry - A DIE with only the minimum required data.
iterator(DWARFDie D)
Definition: DWARFDie.h:316
This class implements an extremely fast bulk output stream that can only output to a stream...
Definition: raw_ostream.h:44
bool operator==(uint64_t V1, const APInt &V2)
Definition: APInt.h:1722
DWARFDie(DWARFUnit *Unit, const DWARFDebugInfoEntry *D)
Definition: DWARFDie.h:41
bool isNULL() const
Returns true for a valid DIE that terminates a sibling chain.
Definition: DWARFDie.h:78