LLVM  7.0.0svn
DWARFDie.h
Go to the documentation of this file.
1 //===- DWARFDie.h -----------------------------------------------*- C++ -*-===//
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_DEBUGINFO_DWARFDIE_H
11 #define LLVM_DEBUGINFO_DWARFDIE_H
12 
13 #include "llvm/ADT/ArrayRef.h"
14 #include "llvm/ADT/Optional.h"
15 #include "llvm/ADT/iterator.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;
49  DWARFDie(DWARFUnit *Unit, const DWARFDebugInfoEntry * D) : U(Unit), Die(D) {}
50 
51  bool isValid() const { return U && Die; }
52  explicit operator bool() const { return isValid(); }
53  const DWARFDebugInfoEntry *getDebugInfoEntry() const { return Die; }
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.
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.
67  uint32_t getOffset() const {
68  assert(isValid() && "must check validity prior to calling");
69  return Die->getOffset();
70  }
71 
72  dwarf::Tag getTag() const {
73  auto AbbrevDecl = getAbbreviationDeclarationPtr();
74  if (AbbrevDecl)
75  return AbbrevDecl->getTag();
76  return dwarf::DW_TAG_null;
77  }
78 
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.
85  bool isNULL() const {
86  return getAbbreviationDeclarationPtr() == nullptr;
87  }
88 
89  /// Returns true if DIE represents a subprogram (not inlined).
90  bool isSubprogramDIE() const;
91 
92  /// Returns true if DIE represents a subprogram or an inlined subroutine.
93  bool isSubroutineDIE() const;
94 
95  /// Get the parent of this DIE object.
96  ///
97  /// \returns a valid DWARFDie instance if this object has a parent or an
98  /// invalid DWARFDie instance if it doesn't.
99  DWARFDie getParent() const;
100 
101  /// Get the sibling of this DIE object.
102  ///
103  /// \returns a valid DWARFDie instance if this object has a sibling or an
104  /// invalid DWARFDie instance if it doesn't.
105  DWARFDie getSibling() const;
106 
107  /// Get the previous sibling of this DIE object.
108  ///
109  /// \returns a valid DWARFDie instance if this object has a sibling or an
110  /// invalid DWARFDie instance if it doesn't.
112 
113  /// Get the first child of this DIE object.
114  ///
115  /// \returns a valid DWARFDie instance if this object has children or an
116  /// invalid DWARFDie instance if it doesn't.
117  DWARFDie getFirstChild() const;
118 
119  /// Get the last child of this DIE object.
120  ///
121  /// \returns a valid null DWARFDie instance if this object has children or an
122  /// invalid DWARFDie instance if it doesn't.
123  DWARFDie getLastChild() const;
124 
125  /// Dump the DIE and all of its attributes to the supplied stream.
126  ///
127  /// \param OS the stream to use for output.
128  /// \param indent the number of characters to indent each line that is output.
129  void dump(raw_ostream &OS, unsigned indent = 0,
130  DIDumpOptions DumpOpts = DIDumpOptions()) const;
131 
132 
133  /// Convenience zero-argument overload for debugging.
134  LLVM_DUMP_METHOD void dump() const;
135 
136  /// Extract the specified attribute from this DIE.
137  ///
138  /// Extract an attribute value from this DIE only. This call doesn't look
139  /// for the attribute value in any DW_AT_specification or
140  /// DW_AT_abstract_origin referenced DIEs.
141  ///
142  /// \param Attr the attribute to extract.
143  /// \returns an optional DWARFFormValue that will have the form value if the
144  /// attribute was successfully extracted.
146 
147  /// Extract the first value of any attribute in Attrs from this DIE.
148  ///
149  /// Extract the first attribute that matches from this DIE only. This call
150  /// doesn't look for the attribute value in any DW_AT_specification or
151  /// DW_AT_abstract_origin referenced DIEs. The attributes will be searched
152  /// linearly in the order they are specified within Attrs.
153  ///
154  /// \param Attrs an array of DWARF attribute to look for.
155  /// \returns an optional that has a valid DWARFFormValue for the first
156  /// matching attribute in Attrs, or None if none of the attributes in Attrs
157  /// exist in this DIE.
159 
160  /// Extract the first value of any attribute in Attrs from this DIE and
161  /// recurse into any DW_AT_specification or DW_AT_abstract_origin referenced
162  /// DIEs.
163  ///
164  /// \param Attrs an array of DWARF attribute to look for.
165  /// \returns an optional that has a valid DWARFFormValue for the first
166  /// matching attribute in Attrs, or None if none of the attributes in Attrs
167  /// exist in this DIE or in any DW_AT_specification or DW_AT_abstract_origin
168  /// DIEs.
171 
172  /// Extract the specified attribute from this DIE as the referenced DIE.
173  ///
174  /// Regardless of the reference type, return the correct DWARFDie instance if
175  /// the attribute exists. The returned DWARFDie object might be from another
176  /// DWARFUnit, but that is all encapsulated in the new DWARFDie object.
177  ///
178  /// Extract an attribute value from this DIE only. This call doesn't look
179  /// for the attribute value in any DW_AT_specification or
180  /// DW_AT_abstract_origin referenced DIEs.
181  ///
182  /// \param Attr the attribute to extract.
183  /// \returns a valid DWARFDie instance if the attribute exists, or an invalid
184  /// DWARFDie object if it doesn't.
186 
187  /// Extract the range base attribute from this DIE as absolute section offset.
188  ///
189  /// This is a utility function that checks for either the DW_AT_rnglists_base
190  /// or DW_AT_GNU_ranges_base attribute.
191  ///
192  /// \returns anm optional absolute section offset value for the attribute.
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  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.
223 
224  /// Get all address ranges for any DW_TAG_subprogram DIEs in this DIE or any
225  /// of its children.
226  ///
227  /// Get the hi/low PC range if both attributes are available or exrtracts the
228  /// non-contiguous address ranges from the DW_AT_ranges attribute for this DIE
229  /// and all children.
230  ///
231  /// \param Ranges the addres range vector to fill in.
233 
234  bool addressRangeContainsAddress(const uint64_t Address) const;
235 
236  /// If a DIE represents a subprogram (or inlined subroutine), returns its
237  /// mangled name (or short name, if mangled is missing). This name may be
238  /// fetched from specification or abstract origin for this subprogram.
239  /// Returns null if no name is found.
240  const char *getSubroutineName(DINameKind Kind) const;
241 
242  /// Return the DIE name resolving DW_AT_sepcification or DW_AT_abstract_origin
243  /// references if necessary. Returns null if no name is found.
244  const char *getName(DINameKind Kind) const;
245 
246  /// Returns the declaration line (start line) for a DIE, assuming it specifies
247  /// a subprogram. This may be fetched from specification or abstract origin
248  /// for this subprogram by resolving DW_AT_sepcification or
249  /// DW_AT_abstract_origin references if necessary.
250  uint64_t getDeclLine() const;
251 
252  /// Retrieves values of DW_AT_call_file, DW_AT_call_line and DW_AT_call_column
253  /// from DIE (or zeroes if they are missing). This function looks for
254  /// DW_AT_call attributes in this DIE only, it will not resolve the attribute
255  /// values in any DW_AT_specification or DW_AT_abstract_origin DIEs.
256  /// \param CallFile filled in with non-zero if successful, zero if there is no
257  /// DW_AT_call_file attribute in this DIE.
258  /// \param CallLine filled in with non-zero if successful, zero if there is no
259  /// DW_AT_call_line attribute in this DIE.
260  /// \param CallColumn filled in with non-zero if successful, zero if there is
261  /// no DW_AT_call_column attribute in this DIE.
262  /// \param CallDiscriminator filled in with non-zero if successful, zero if
263  /// there is no DW_AT_GNU_discriminator attribute in this DIE.
264  void getCallerFrame(uint32_t &CallFile, uint32_t &CallLine,
265  uint32_t &CallColumn, uint32_t &CallDiscriminator) const;
266 
267  class attribute_iterator;
268 
269  /// Get an iterator range to all attributes in the current DIE only.
270  ///
271  /// \returns an iterator range for the attributes of the current DIE.
273 
274  class iterator;
275 
276  iterator begin() const;
277  iterator end() const;
279 };
280 
282  public iterator_facade_base<attribute_iterator, std::forward_iterator_tag,
283  const DWARFAttribute> {
284  /// The DWARF DIE we are extracting attributes from.
285  DWARFDie Die;
286  /// The value vended to clients via the operator*() or operator->().
287  DWARFAttribute AttrValue;
288  /// The attribute index within the abbreviation declaration in Die.
289  uint32_t Index;
290 
291  /// Update the attribute index and attempt to read the attribute value. If the
292  /// attribute is able to be read, update AttrValue and the Index member
293  /// variable. If the attribute value is not able to be read, an appropriate
294  /// error will be set if the Err member variable is non-NULL and the iterator
295  /// will be set to the end value so iteration stops.
296  void updateForIndex(const DWARFAbbreviationDeclaration &AbbrDecl, uint32_t I);
297 
298 public:
299  attribute_iterator() = delete;
300  explicit attribute_iterator(DWARFDie D, bool End);
301 
302  attribute_iterator &operator++();
303  attribute_iterator &operator--();
304  explicit operator bool() const { return AttrValue.isValid(); }
305  const DWARFAttribute &operator*() const { return AttrValue; }
306  bool operator==(const attribute_iterator &X) const { return Index == X.Index; }
307 };
308 
309 inline bool operator==(const DWARFDie &LHS, const DWARFDie &RHS) {
310  return LHS.getDebugInfoEntry() == RHS.getDebugInfoEntry() &&
311  LHS.getDwarfUnit() == RHS.getDwarfUnit();
312 }
313 
314 inline bool operator!=(const DWARFDie &LHS, const DWARFDie &RHS) {
315  return !(LHS == RHS);
316 }
317 
318 inline bool operator<(const DWARFDie &LHS, const DWARFDie &RHS) {
319  return LHS.getOffset() < RHS.getOffset();
320 }
321 
323  : public iterator_facade_base<iterator, std::bidirectional_iterator_tag,
324  const DWARFDie> {
325  DWARFDie Die;
326 public:
327  iterator() = default;
328 
329  explicit iterator(DWARFDie D) : Die(D) {
330  }
331 
333  Die = Die.getSibling();
334  return *this;
335  }
336 
338  Die = Die.getPreviousSibling();
339  return *this;
340  }
341 
342  explicit operator bool() const { return Die.isValid(); }
343  const DWARFDie &operator*() const { return Die; }
344  bool operator==(const iterator &X) const { return Die == X.Die; }
345 };
346 
347 // These inline functions must follow the DWARFDie::iterator definition above
348 // as they use functions from that class.
350  return iterator(getFirstChild());
351 }
352 
354  return iterator(getLastChild());
355 }
356 
358  return make_range(begin(), end());
359 }
360 
361 } // end namespace llvm
362 
363 #endif // LLVM_DEBUGINFO_DWARFDIE_H
DWARFDie()=default
static GCMetadataPrinterRegistry::Add< ErlangGCPrinter > X("erlang", "erlang-compatible garbage collector")
bool operator==(const iterator &X) const
Definition: DWARFDie.h:344
DWARFUnit * getDwarfUnit() const
Definition: DWARFDie.h:54
bool isValid() const
Definition: DWARFDie.h:51
Compute iterated dominance frontiers using a linear time algorithm.
Definition: AllocatorList.h:24
#define LLVM_DUMP_METHOD
Mark debug helper function definitions like dump() that should not be stripped from debug builds...
Definition: Compiler.h:452
bool isSubprogramDIE() const
Returns true if DIE represents a subprogram (not inlined).
Definition: DWARFDie.cpp:284
bool addressRangeContainsAddress(const uint64_t Address) const
Definition: DWARFDie.cpp:425
Attribute
Attributes.
Definition: Dwarf.h:114
This provides a very simple, boring adaptor for a begin and end iterator into a range type...
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:409
const DWARFAbbreviationDeclaration * getAbbreviationDeclarationPtr() const
Get the abbreviation declaration for this DIE.
Definition: DWARFDie.h:59
DWARFDie getAttributeValueAsReferencedDie(dwarf::Attribute Attr) const
Extract the specified attribute from this DIE as the referenced DIE.
Definition: DWARFDie.cpp:351
DINameKind
A DINameKind is passed to name search methods to specify a preference regarding the type of name reso...
Definition: DIContext.h:114
bool operator==(const attribute_iterator &X) const
Definition: DWARFDie.h:306
iterator_range< iterator > children() const
Definition: DWARFDie.h:357
Optional< uint64_t > getRangesBaseAttribute() const
Extract the range base attribute from this DIE as absolute section offset.
Definition: DWARFDie.cpp:359
void getCallerFrame(uint32_t &CallFile, uint32_t &CallLine, uint32_t &CallColumn, uint32_t &CallDiscriminator) 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:463
Tagged union holding either a T or a Error.
Definition: CachePruning.h:23
const DWARFDebugInfoEntry * getDebugInfoEntry() const
Definition: DWARFDie.h:53
uint32_t getOffset() const
Get the absolute offset into the debug info or types section.
Definition: DWARFDie.h:67
Encapsulates a DWARF attribute value and all of the data required to describe the attribute value...
const DWARFDie & operator*() const
Definition: DWARFDie.h:343
bool hasChildren() const
Definition: DWARFDie.h:79
ArrayRef - Represent a constant reference to an array (0 or more elements consecutively in memory)...
Definition: APInt.h:33
bool getLowAndHighPC(uint64_t &LowPC, uint64_t &HighPC, uint64_t &SectionIndex) const
Retrieves DW_AT_low_pc and DW_AT_high_pc from CU.
Definition: DWARFDie.cpp:377
constexpr char Attrs[]
Key for Kernel::Metadata::mAttrs.
DWARFDie getSibling() const
Get the sibling of this DIE object.
Definition: DWARFDie.cpp:552
CRTP base class which implements the entire standard iterator facade in terms of a minimal subset of ...
Definition: iterator.h:68
uint64_t getDeclLine() const
Returns the declaration line (start line) for a DIE, assuming it specifies a subprogram.
Definition: DWARFDie.cpp:459
Container for dump options that control which debug information will be dumped.
Definition: DIContext.h:154
Utility class that carries the DWARF compile/type unit and the debug info entry in an object...
Definition: DWARFDie.h:43
DWARFDie getLastChild() const
Get the last child of this DIE object.
Definition: DWARFDie.cpp:570
bool isSubroutineDIE() const
Returns true if DIE represents a subprogram or an inlined subroutine.
Definition: DWARFDie.cpp:286
Optional< DWARFFormValue > findRecursively(ArrayRef< dwarf::Attribute > Attrs) const
Extract the first value of any attribute in Attrs from this DIE and recurse into any DW_AT_specificat...
Definition: DWARFDie.cpp:315
bool isNULL() const
Returns true for a valid DIE that terminates a sibling chain.
Definition: DWARFDie.h:85
iterator end() const
Definition: DWARFDie.h:353
iterator_range< T > make_range(T x, T y)
Convenience function for iterating over sub-ranges.
const DWARFAbbreviationDeclaration * getAbbreviationDeclarationPtr() const
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:444
DWARFDie getPreviousSibling() const
Get the previous sibling of this DIE object.
Definition: DWARFDie.cpp:558
static GCRegistry::Add< StatepointGC > D("statepoint-example", "an example strategy for statepoint")
iterator_range< attribute_iterator > attributes() const
Get an iterator range to all attributes in the current DIE only.
Definition: DWARFDie.cpp:576
A range adaptor for a pair of iterators.
This file contains constants used for implementing Dwarf debug support.
const DWARFAttribute & operator*() const
Definition: DWARFDie.h:305
bool operator!=(uint64_t V1, const APInt &V2)
Definition: APInt.h:1962
LLVM_DUMP_METHOD void dump() const
Convenience zero-argument overload for debugging.
Definition: DWARFDie.cpp:544
dwarf::Tag getTag() const
Definition: DWARFDie.h:72
#define I(x, y, z)
Definition: MD5.cpp:58
Expected< DWARFAddressRangesVector > getAddressRanges() const
Get the address ranges for this DIE.
Definition: DWARFDie.cpp:392
Optional< uint64_t > getHighPC(uint64_t LowPC) const
Get the DW_AT_high_pc attribute value as an address.
Definition: DWARFDie.cpp:363
iterator & operator++()
Definition: DWARFDie.h:332
const unsigned Kind
assert(ImpDefSCC.getReg()==AMDGPU::SCC &&ImpDefSCC.isDef())
bool isValid() const
bool operator<(int64_t V1, const APSInt &V2)
Definition: APSInt.h:326
Optional< DWARFFormValue > find(dwarf::Attribute Attr) const
Extract the specified attribute from this DIE.
Definition: DWARFDie.cpp:291
std::vector< DWARFAddressRange > DWARFAddressRangesVector
DWARFAddressRangesVector - represents a set of absolute address ranges.
DWARFDebugInfoEntry - A DIE with only the minimum required data.
DWARFDie getFirstChild() const
Get the first child of this DIE object.
Definition: DWARFDie.cpp:564
iterator(DWARFDie D)
Definition: DWARFDie.h:329
This class implements an extremely fast bulk output stream that can only output to a stream...
Definition: raw_ostream.h:46
bool operator==(uint64_t V1, const APInt &V2)
Definition: APInt.h:1960
iterator begin() const
Definition: DWARFDie.h:349
DWARFDie(DWARFUnit *Unit, const DWARFDebugInfoEntry *D)
Definition: DWARFDie.h:49
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:438
DWARFDie getParent() const
Get the parent of this DIE object.
Definition: DWARFDie.cpp:546
iterator & operator--()
Definition: DWARFDie.h:337