contrib/llvm/include/llvm/DebugInfo/DWARF/DWARFDie.h

   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/iterator.h"
  15 #include "llvm/ADT/iterator_range.h"
  16 #include "llvm/ADT/Optional.h"
  17 #include "llvm/DebugInfo/DIContext.h"
  18 #include "llvm/DebugInfo/DWARF/DWARFAttribute.h"
  19 #include "llvm/DebugInfo/DWARF/DWARFDebugInfoEntry.h"
  20 #include "llvm/DebugInfo/DWARF/DWARFDebugRangeList.h"
  21 #include "llvm/Support/Dwarf.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.
  59   const DWARFAbbreviationDeclaration *getAbbreviationDeclarationPtr() const {
  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 first child of this DIE object.
 108   ///
 109   /// \returns a valid DWARFDie instance if this object has children or an
 110   /// invalid DWARFDie instance if it doesn't.
 111   DWARFDie getFirstChild() const {
 112     if (isValid() && Die->hasChildren())
 113       return DWARFDie(U, Die + 1);
 114     return DWARFDie();
 115   }
 116
 117   /// Dump the DIE and all of its attributes to the supplied stream.
 118   ///
 119   /// \param OS the stream to use for output.
 120   /// \param recurseDepth the depth to recurse to when dumping this DIE and its
 121   /// children.
 122   /// \param indent the number of characters to indent each line that is output.
 123   void dump(raw_ostream &OS, unsigned recurseDepth, unsigned indent = 0) const;
 124
 125   /// Extract the specified attribute from this DIE.
 126   ///
 127   /// Extract an attribute value from this DIE only. This call doesn't look
 128   /// for the attribute value in any DW_AT_specification or
 129   /// DW_AT_abstract_origin referenced DIEs.
 130   ///
 131   /// \param Attr the attribute to extract.
 132   /// \returns an optional DWARFFormValue that will have the form value if the
 133   /// attribute was successfully extracted.
 134   Optional<DWARFFormValue> find(dwarf::Attribute Attr) const;
 135
 136   /// Extract the first value of any attribute in Attrs from this DIE.
 137   ///
 138   /// Extract the first attribute that matches from this DIE only. This call
 139   /// doesn't look for the attribute value in any DW_AT_specification or
 140   /// DW_AT_abstract_origin referenced DIEs. The attributes will be searched
 141   /// linearly in the order they are specified within Attrs.
 142   ///
 143   /// \param Attrs an array of DWARF attribute to look for.
 144   /// \returns an optional that has a valid DWARFFormValue for the first
 145   /// matching attribute in Attrs, or None if none of the attributes in Attrs
 146   /// exist in this DIE.
 147   Optional<DWARFFormValue> find(ArrayRef<dwarf::Attribute> Attrs) const;
 148
 149   /// Extract the first value of any attribute in Attrs from this DIE and
 150   /// recurse into any DW_AT_specification or DW_AT_abstract_origin referenced
 151   /// DIEs.
 152   ///
 153   /// \param Attrs an array of DWARF attribute to look for.
 154   /// \returns an optional that has a valid DWARFFormValue for the first
 155   /// matching attribute in Attrs, or None if none of the attributes in Attrs
 156   /// exist in this DIE or in any DW_AT_specification or DW_AT_abstract_origin
 157   /// DIEs.
 158   Optional<DWARFFormValue>
 159   findRecursively(ArrayRef<dwarf::Attribute> Attrs) const;
 160
 161   /// Extract the specified attribute from this DIE as the referenced DIE.
 162   ///
 163   /// Regardless of the reference type, return the correct DWARFDie instance if
 164   /// the attribute exists. The returned DWARFDie object might be from another
 165   /// DWARFUnit, but that is all encapsulated in the new DWARFDie object.
 166   ///
 167   /// Extract an attribute value from this DIE only. This call doesn't look
 168   /// for the attribute value in any DW_AT_specification or
 169   /// DW_AT_abstract_origin referenced DIEs.
 170   ///
 171   /// \param Attr the attribute to extract.
 172   /// \returns a valid DWARFDie instance if the attribute exists, or an invalid
 173   /// DWARFDie object if it doesn't.
 174   DWARFDie getAttributeValueAsReferencedDie(dwarf::Attribute Attr) const;
 175
 176   /// Extract the range base attribute from this DIE as absolute section offset.
 177   ///
 178   /// This is a utility function that checks for either the DW_AT_rnglists_base
 179   /// or DW_AT_GNU_ranges_base attribute.
 180   ///
 181   /// \returns anm optional absolute section offset value for the attribute.
 182   Optional<uint64_t> getRangesBaseAttribute() const;
 183
 184   /// Get the DW_AT_high_pc attribute value as an address.
 185   ///
 186   /// In DWARF version 4 and later the high PC can be encoded as an offset from
 187   /// the DW_AT_low_pc. This function takes care of extracting the value as an
 188   /// address or offset and adds it to the low PC if needed and returns the
 189   /// value as an optional in case the DIE doesn't have a DW_AT_high_pc
 190   /// attribute.
 191   ///
 192   /// \param LowPC the low PC that might be needed to calculate the high PC.
 193   /// \returns an optional address value for the attribute.
 194   Optional<uint64_t> getHighPC(uint64_t LowPC) const;
 195
 196   /// Retrieves DW_AT_low_pc and DW_AT_high_pc from CU.
 197   /// Returns true if both attributes are present.
 198   bool getLowAndHighPC(uint64_t &LowPC, uint64_t &HighPC) const;
 199
 200   /// Get the address ranges for this DIE.
 201   ///
 202   /// Get the hi/low PC range if both attributes are available or exrtracts the
 203   /// non-contiguous address ranges from the DW_AT_ranges attribute.
 204   ///
 205   /// Extracts the range information from this DIE only. This call doesn't look
 206   /// for the range in any DW_AT_specification or DW_AT_abstract_origin DIEs.
 207   ///
 208   /// \returns a address range vector that might be empty if no address range
 209   /// information is available.
 210   DWARFAddressRangesVector getAddressRanges() const;
 211
 212   /// Get all address ranges for any DW_TAG_subprogram DIEs in this DIE or any
 213   /// of its children.
 214   ///
 215   /// Get the hi/low PC range if both attributes are available or exrtracts the
 216   /// non-contiguous address ranges from the DW_AT_ranges attribute for this DIE
 217   /// and all children.
 218   ///
 219   /// \param Ranges the addres range vector to fill in.
 220   void collectChildrenAddressRanges(DWARFAddressRangesVector &Ranges) const;
 221
 222   bool addressRangeContainsAddress(const uint64_t Address) const;
 223
 224   /// If a DIE represents a subprogram (or inlined subroutine), returns its
 225   /// mangled name (or short name, if mangled is missing). This name may be
 226   /// fetched from specification or abstract origin for this subprogram.
 227   /// Returns null if no name is found.
 228   const char *getSubroutineName(DINameKind Kind) const;
 229
 230   /// Return the DIE name resolving DW_AT_sepcification or DW_AT_abstract_origin
 231   /// references if necessary. Returns null if no name is found.
 232   const char *getName(DINameKind Kind) const;
 233
 234   /// Returns the declaration line (start line) for a DIE, assuming it specifies
 235   /// a subprogram. This may be fetched from specification or abstract origin
 236   /// for this subprogram by resolving DW_AT_sepcification or
 237   /// DW_AT_abstract_origin references if necessary.
 238   uint64_t getDeclLine() const;
 239
 240   /// Retrieves values of DW_AT_call_file, DW_AT_call_line and DW_AT_call_column
 241   /// from DIE (or zeroes if they are missing). This function looks for
 242   /// DW_AT_call attributes in this DIE only, it will not resolve the attribute
 243   /// values in any DW_AT_specification or DW_AT_abstract_origin DIEs.
 244   /// \param CallFile filled in with non-zero if successful, zero if there is no
 245   /// DW_AT_call_file attribute in this DIE.
 246   /// \param CallLine filled in with non-zero if successful, zero if there is no
 247   /// DW_AT_call_line attribute in this DIE.
 248   /// \param CallColumn filled in with non-zero if successful, zero if there is
 249   /// no DW_AT_call_column attribute in this DIE.
 250   /// \param CallDiscriminator filled in with non-zero if successful, zero if
 251   /// there is no DW_AT_GNU_discriminator attribute in this DIE.
 252   void getCallerFrame(uint32_t &CallFile, uint32_t &CallLine,
 253                       uint32_t &CallColumn, uint32_t &CallDiscriminator) const;
 254
 255   class attribute_iterator;
 256
 257   /// Get an iterator range to all attributes in the current DIE only.
 258   ///
 259   /// \returns an iterator range for the attributes of the current DIE.
 260   iterator_range<attribute_iterator> attributes() const;
 261
 262   class iterator;
 263
 264   iterator begin() const;
 265   iterator end() const;
 266   iterator_range<iterator> children() const;
 267 };
 268
 269 class DWARFDie::attribute_iterator :
 270     public iterator_facade_base<attribute_iterator, std::forward_iterator_tag,
 271                                 const DWARFAttribute> {
 272   /// The DWARF DIE we are extracting attributes from.
 273   DWARFDie Die;
 274   /// The value vended to clients via the operator*() or operator->().
 275   DWARFAttribute AttrValue;
 276   /// The attribute index within the abbreviation declaration in Die.
 277   uint32_t Index;
 278
 279   /// Update the attribute index and attempt to read the attribute value. If the
 280   /// attribute is able to be read, update AttrValue and the Index member
 281   /// variable. If the attribute value is not able to be read, an appropriate
 282   /// error will be set if the Err member variable is non-NULL and the iterator
 283   /// will be set to the end value so iteration stops.
 284   void updateForIndex(const DWARFAbbreviationDeclaration &AbbrDecl, uint32_t I);
 285
 286 public:
 287   attribute_iterator() = delete;
 288   explicit attribute_iterator(DWARFDie D, bool End);
 289
 290   attribute_iterator &operator++();
 291   explicit operator bool() const { return AttrValue.isValid(); }
 292   const DWARFAttribute &operator*() const { return AttrValue; }
 293   bool operator==(const attribute_iterator &X) const { return Index == X.Index; }
 294 };
 295
 296 inline bool operator==(const DWARFDie &LHS, const DWARFDie &RHS) {
 297   return LHS.getDebugInfoEntry() == RHS.getDebugInfoEntry() &&
 298       LHS.getDwarfUnit() == RHS.getDwarfUnit();
 299 }
 300
 301 inline bool operator!=(const DWARFDie &LHS, const DWARFDie &RHS) {
 302   return !(LHS == RHS);
 303 }
 304
 305 class DWARFDie::iterator : public iterator_facade_base<iterator,
 306                                                       std::forward_iterator_tag,
 307                                                       const DWARFDie> {
 308   DWARFDie Die;
 309   void skipNull() {
 310     if (Die && Die.isNULL())
 311       Die = DWARFDie();
 312   }
 313 public:
 314   iterator() = default;
 315
 316   explicit iterator(DWARFDie D) : Die(D) {
 317     // If we start out with only a Null DIE then invalidate.
 318     skipNull();
 319   }
 320
 321   iterator &operator++() {
 322     Die = Die.getSibling();
 323     // Don't include the NULL die when iterating.
 324     skipNull();
 325     return *this;
 326   }
 327
 328   explicit operator bool() const { return Die.isValid(); }
 329   const DWARFDie &operator*() const { return Die; }
 330   bool operator==(const iterator &X) const { return Die == X.Die; }
 331 };
 332
 333 // These inline functions must follow the DWARFDie::iterator definition above
 334 // as they use functions from that class.
 335 inline DWARFDie::iterator DWARFDie::begin() const {
 336   return iterator(getFirstChild());
 337 }
 338
 339 inline DWARFDie::iterator DWARFDie::end() const {
 340   return iterator();
 341 }
 342
 343 inline iterator_range<DWARFDie::iterator> DWARFDie::children() const {
 344   return make_range(begin(), end());
 345 }
 346
 347 } // end namespace llvm
 348
 349 #endif // LLVM_DEBUGINFO_DWARFDIE_H