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 void getCallerFrame(uint32_t &CallFile, uint32_t &CallLine, 251 uint32_t &CallColumn) const; 252 253 /// Get inlined chain for a given address, rooted at the current DIE. 254 /// Returns empty chain if address is not contained in address range 255 /// of current DIE. 256 void 257 getInlinedChainForAddress(const uint64_t Address, 258 SmallVectorImpl<DWARFDie> &InlinedChain) const; 259 260 class attribute_iterator; 261 262 /// Get an iterator range to all attributes in the current DIE only. 263 /// 264 /// \returns an iterator range for the attributes of the current DIE. 265 iterator_range<attribute_iterator> attributes() const; 266 267 class iterator; 268 269 iterator begin() const; 270 iterator end() const; 271 iterator_range<iterator> children() const; 272 }; 273 274 class DWARFDie::attribute_iterator : 275 public iterator_facade_base<attribute_iterator, std::forward_iterator_tag, 276 const DWARFAttribute> { 277 /// The DWARF DIE we are extracting attributes from. 278 DWARFDie Die; 279 /// The value vended to clients via the operator*() or operator->(). 280 DWARFAttribute AttrValue; 281 /// The attribute index within the abbreviation declaration in Die. 282 uint32_t Index; 283 284 /// Update the attribute index and attempt to read the attribute value. If the 285 /// attribute is able to be read, update AttrValue and the Index member 286 /// variable. If the attribute value is not able to be read, an appropriate 287 /// error will be set if the Err member variable is non-NULL and the iterator 288 /// will be set to the end value so iteration stops. 289 void updateForIndex(const DWARFAbbreviationDeclaration &AbbrDecl, uint32_t I); 290 291 public: 292 attribute_iterator() = delete; 293 explicit attribute_iterator(DWARFDie D, bool End); 294 295 attribute_iterator &operator++(); 296 explicit operator bool() const { return AttrValue.isValid(); } 297 const DWARFAttribute &operator*() const { return AttrValue; } 298 bool operator==(const attribute_iterator &X) const { return Index == X.Index; } 299 }; 300 301 inline bool operator==(const DWARFDie &LHS, const DWARFDie &RHS) { 302 return LHS.getDebugInfoEntry() == RHS.getDebugInfoEntry() && 303 LHS.getDwarfUnit() == RHS.getDwarfUnit(); 304 } 305 306 inline bool operator!=(const DWARFDie &LHS, const DWARFDie &RHS) { 307 return !(LHS == RHS); 308 } 309 310 class DWARFDie::iterator : public iterator_facade_base<iterator, 311 std::forward_iterator_tag, 312 const DWARFDie> { 313 DWARFDie Die; 314 void skipNull() { 315 if (Die && Die.isNULL()) 316 Die = DWARFDie(); 317 } 318 public: 319 iterator() = default; 320 321 explicit iterator(DWARFDie D) : Die(D) { 322 // If we start out with only a Null DIE then invalidate. 323 skipNull(); 324 } 325 326 iterator &operator++() { 327 Die = Die.getSibling(); 328 // Don't include the NULL die when iterating. 329 skipNull(); 330 return *this; 331 } 332 333 explicit operator bool() const { return Die.isValid(); } 334 const DWARFDie &operator*() const { return Die; } 335 bool operator==(const iterator &X) const { return Die == X.Die; } 336 }; 337 338 // These inline functions must follow the DWARFDie::iterator definition above 339 // as they use functions from that class. 340 inline DWARFDie::iterator DWARFDie::begin() const { 341 return iterator(getFirstChild()); 342 } 343 344 inline DWARFDie::iterator DWARFDie::end() const { 345 return iterator(); 346 } 347 348 inline iterator_range<DWARFDie::iterator> DWARFDie::children() const { 349 return make_range(begin(), end()); 350 } 351 352 } // end namespace llvm 353 354 #endif // LLVM_DEBUGINFO_DWARFDIE_H 355