include/llvm/DebugInfo/DWARF/DWARFDie.h

   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"
  14 #include "llvm/ADT/iterator_range.h"
  15 #include "llvm/ADT/Optional.h"
  16 #include "llvm/DebugInfo/DWARF/DWARFDebugInfoEntry.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.
  52   const DWARFAbbreviationDeclaration *getAbbreviationDeclarationPtr() const {
  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.
 103   DWARFDie getFirstChild() const {
 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.
 126   Optional<DWARFFormValue> getAttributeValue(dwarf::Attribute Attr) const;
 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.
 140   const char *getAttributeValueAsString(dwarf::Attribute Attr,
 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.
 151   Optional<uint64_t> getAttributeValueAsAddress(dwarf::Attribute Attr) const;
 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.
 161   Optional<int64_t>
 162   getAttributeValueAsSignedConstant(dwarf::Attribute Attr) const;
 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.
 172   Optional<uint64_t>
 173   getAttributeValueAsUnsignedConstant(dwarf::Attribute Attr) const;
 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.
 183   Optional<uint64_t> getAttributeValueAsReference(dwarf::Attribute Attr) const;
 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.
 193   Optional<uint64_t>
 194   getAttributeValueAsSectionOffset(dwarf::Attribute Attr) const;
 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.
 209   DWARFDie getAttributeValueAsReferencedDie(dwarf::Attribute Attr) const;
 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.
 217   Optional<uint64_t> getRangesBaseAttribute() const;
 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.
 245   DWARFAddressRangesVector getAddressRanges() const;
 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.
 255   void collectChildrenAddressRanges(DWARFAddressRangesVector &Ranges) const;
 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;
 293   iterator_range<iterator> children() 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   }
 320   iterator &operator++() {
 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.
 333 inline DWARFDie::iterator DWARFDie::begin() const {
 334   return iterator(getFirstChild());
 335 }
 336
 337 inline DWARFDie::iterator DWARFDie::end() const {
 338   return iterator();
 339 }
 340
 341 inline iterator_range<DWARFDie::iterator> DWARFDie::children() const {
 342   return make_range(begin(), end());
 343 }
 344
 345 } // end namespace llvm
 346
 347 #endif  // LLVM_LIB_DEBUGINFO_DWARFDIE_H