1 //===- DWARFDie.h -----------------------------------------------*- C++ -*-===// 2 // 3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions. 4 // See https://llvm.org/LICENSE.txt for license information. 5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception 6 // 7 //===----------------------------------------------------------------------===// 8 9 #ifndef LLVM_DEBUGINFO_DWARF_DWARFDIE_H 10 #define LLVM_DEBUGINFO_DWARF_DWARFDIE_H 11 12 #include "llvm/ADT/ArrayRef.h" 13 #include "llvm/ADT/Optional.h" 14 #include "llvm/ADT/iterator.h" 15 #include "llvm/ADT/iterator_range.h" 16 #include "llvm/BinaryFormat/Dwarf.h" 17 #include "llvm/DebugInfo/DIContext.h" 18 #include "llvm/DebugInfo/DWARF/DWARFAddressRange.h" 19 #include "llvm/DebugInfo/DWARF/DWARFAttribute.h" 20 #include "llvm/DebugInfo/DWARF/DWARFDebugInfoEntry.h" 21 #include "llvm/DebugInfo/DWARF/DWARFDebugLoc.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 uint64_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 { return getAbbreviationDeclarationPtr() == nullptr; } 86 87 /// Returns true if DIE represents a subprogram (not inlined). 88 bool isSubprogramDIE() const; 89 90 /// Returns true if DIE represents a subprogram or an inlined subroutine. 91 bool isSubroutineDIE() const; 92 93 /// Get the parent of this DIE object. 94 /// 95 /// \returns a valid DWARFDie instance if this object has a parent or an 96 /// invalid DWARFDie instance if it doesn't. 97 DWARFDie getParent() const; 98 99 /// Get the sibling of this DIE object. 100 /// 101 /// \returns a valid DWARFDie instance if this object has a sibling or an 102 /// invalid DWARFDie instance if it doesn't. 103 DWARFDie getSibling() const; 104 105 /// Get the previous sibling of this DIE object. 106 /// 107 /// \returns a valid DWARFDie instance if this object has a sibling or an 108 /// invalid DWARFDie instance if it doesn't. 109 DWARFDie getPreviousSibling() const; 110 111 /// Get the first child of this DIE object. 112 /// 113 /// \returns a valid DWARFDie instance if this object has children or an 114 /// invalid DWARFDie instance if it doesn't. 115 DWARFDie getFirstChild() const; 116 117 /// Get the last child of this DIE object. 118 /// 119 /// \returns a valid null DWARFDie instance if this object has children or an 120 /// invalid DWARFDie instance if it doesn't. 121 DWARFDie getLastChild() const; 122 123 /// Dump the DIE and all of its attributes to the supplied stream. 124 /// 125 /// \param OS the stream to use for output. 126 /// \param indent the number of characters to indent each line that is output. 127 void dump(raw_ostream &OS, unsigned indent = 0, 128 DIDumpOptions DumpOpts = DIDumpOptions()) const; 129 130 /// Convenience zero-argument overload for debugging. 131 LLVM_DUMP_METHOD void dump() const; 132 133 /// Extract the specified attribute from this DIE. 134 /// 135 /// Extract an attribute value from this DIE only. This call doesn't look 136 /// for the attribute value in any DW_AT_specification or 137 /// DW_AT_abstract_origin referenced DIEs. 138 /// 139 /// \param Attr the attribute to extract. 140 /// \returns an optional DWARFFormValue that will have the form value if the 141 /// attribute was successfully extracted. 142 Optional<DWARFFormValue> find(dwarf::Attribute Attr) const; 143 144 /// Extract the first value of any attribute in Attrs from this DIE. 145 /// 146 /// Extract the first attribute that matches from this DIE only. This call 147 /// doesn't look for the attribute value in any DW_AT_specification or 148 /// DW_AT_abstract_origin referenced DIEs. The attributes will be searched 149 /// linearly in the order they are specified within Attrs. 150 /// 151 /// \param Attrs an array of DWARF attribute to look for. 152 /// \returns an optional that has a valid DWARFFormValue for the first 153 /// matching attribute in Attrs, or None if none of the attributes in Attrs 154 /// exist in this DIE. 155 Optional<DWARFFormValue> find(ArrayRef<dwarf::Attribute> Attrs) const; 156 157 /// Extract the first value of any attribute in Attrs from this DIE and 158 /// recurse into any DW_AT_specification or DW_AT_abstract_origin referenced 159 /// DIEs. 160 /// 161 /// \param Attrs an array of DWARF attribute to look for. 162 /// \returns an optional that has a valid DWARFFormValue for the first 163 /// matching attribute in Attrs, or None if none of the attributes in Attrs 164 /// exist in this DIE or in any DW_AT_specification or DW_AT_abstract_origin 165 /// DIEs. 166 Optional<DWARFFormValue> 167 findRecursively(ArrayRef<dwarf::Attribute> Attrs) const; 168 169 /// Extract the specified attribute from this DIE as the referenced DIE. 170 /// 171 /// Regardless of the reference type, return the correct DWARFDie instance if 172 /// the attribute exists. The returned DWARFDie object might be from another 173 /// DWARFUnit, but that is all encapsulated in the new DWARFDie object. 174 /// 175 /// Extract an attribute value from this DIE only. This call doesn't look 176 /// for the attribute value in any DW_AT_specification or 177 /// DW_AT_abstract_origin referenced DIEs. 178 /// 179 /// \param Attr the attribute to extract. 180 /// \returns a valid DWARFDie instance if the attribute exists, or an invalid 181 /// DWARFDie object if it doesn't. 182 DWARFDie getAttributeValueAsReferencedDie(dwarf::Attribute Attr) const; 183 DWARFDie getAttributeValueAsReferencedDie(const DWARFFormValue &V) const; 184 185 DWARFDie resolveTypeUnitReference() const; 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. 193 Optional<uint64_t> getRangesBaseAttribute() const; 194 Optional<uint64_t> getLocBaseAttribute() const; 195 196 /// Get the DW_AT_high_pc attribute value as an address. 197 /// 198 /// In DWARF version 4 and later the high PC can be encoded as an offset from 199 /// the DW_AT_low_pc. This function takes care of extracting the value as an 200 /// address or offset and adds it to the low PC if needed and returns the 201 /// value as an optional in case the DIE doesn't have a DW_AT_high_pc 202 /// attribute. 203 /// 204 /// \param LowPC the low PC that might be needed to calculate the high PC. 205 /// \returns an optional address value for the attribute. 206 Optional<uint64_t> getHighPC(uint64_t LowPC) const; 207 208 /// Retrieves DW_AT_low_pc and DW_AT_high_pc from CU. 209 /// Returns true if both attributes are present. 210 bool getLowAndHighPC(uint64_t &LowPC, uint64_t &HighPC, 211 uint64_t &SectionIndex) const; 212 213 /// Get the address ranges for this DIE. 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. 217 /// 218 /// Extracts the range information from this DIE only. This call doesn't look 219 /// for the range in any DW_AT_specification or DW_AT_abstract_origin DIEs. 220 /// 221 /// \returns a address range vector that might be empty if no address range 222 /// information is available. 223 Expected<DWARFAddressRangesVector> getAddressRanges() const; 224 225 bool addressRangeContainsAddress(const uint64_t Address) const; 226 227 Expected<DWARFLocationExpressionsVector> 228 getLocations(dwarf::Attribute Attr) const; 229 230 /// If a DIE represents a subprogram (or inlined subroutine), returns its 231 /// mangled name (or short name, if mangled is missing). This name may be 232 /// fetched from specification or abstract origin for this subprogram. 233 /// Returns null if no name is found. 234 const char *getSubroutineName(DINameKind Kind) const; 235 236 /// Return the DIE name resolving DW_AT_specification or DW_AT_abstract_origin 237 /// references if necessary. For the LinkageName case it additionaly searches 238 /// for ShortName if LinkageName is not found. 239 /// Returns null if no name is found. 240 const char *getName(DINameKind Kind) const; 241 void getFullName(raw_string_ostream &, 242 std::string *OriginalFullName = nullptr) const; 243 244 /// Return the DIE short name resolving DW_AT_specification or 245 /// DW_AT_abstract_origin references if necessary. Returns null if no name 246 /// is found. 247 const char *getShortName() const; 248 249 /// Return the DIE linkage name resolving DW_AT_specification or 250 /// DW_AT_abstract_origin references if necessary. Returns null if no name 251 /// is found. 252 const char *getLinkageName() const; 253 254 /// Returns the declaration line (start line) for a DIE, assuming it specifies 255 /// a subprogram. This may be fetched from specification or abstract origin 256 /// for this subprogram by resolving DW_AT_sepcification or 257 /// DW_AT_abstract_origin references if necessary. 258 uint64_t getDeclLine() const; 259 std::string getDeclFile(DILineInfoSpecifier::FileLineInfoKind Kind) const; 260 261 /// Retrieves values of DW_AT_call_file, DW_AT_call_line and DW_AT_call_column 262 /// from DIE (or zeroes if they are missing). This function looks for 263 /// DW_AT_call attributes in this DIE only, it will not resolve the attribute 264 /// values in any DW_AT_specification or DW_AT_abstract_origin DIEs. 265 /// \param CallFile filled in with non-zero if successful, zero if there is no 266 /// DW_AT_call_file attribute in this DIE. 267 /// \param CallLine filled in with non-zero if successful, zero if there is no 268 /// DW_AT_call_line attribute in this DIE. 269 /// \param CallColumn filled in with non-zero if successful, zero if there is 270 /// no DW_AT_call_column attribute in this DIE. 271 /// \param CallDiscriminator filled in with non-zero if successful, zero if 272 /// there is no DW_AT_GNU_discriminator attribute in this DIE. 273 void getCallerFrame(uint32_t &CallFile, uint32_t &CallLine, 274 uint32_t &CallColumn, uint32_t &CallDiscriminator) const; 275 276 class attribute_iterator; 277 278 /// Get an iterator range to all attributes in the current DIE only. 279 /// 280 /// \returns an iterator range for the attributes of the current DIE. 281 iterator_range<attribute_iterator> attributes() const; 282 283 class iterator; 284 285 iterator begin() const; 286 iterator end() const; 287 288 std::reverse_iterator<iterator> rbegin() const; 289 std::reverse_iterator<iterator> rend() const; 290 291 iterator_range<iterator> children() const; 292 }; 293 294 class DWARFDie::attribute_iterator 295 : public iterator_facade_base<attribute_iterator, std::forward_iterator_tag, 296 const DWARFAttribute> { 297 /// The DWARF DIE we are extracting attributes from. 298 DWARFDie Die; 299 /// The value vended to clients via the operator*() or operator->(). 300 DWARFAttribute AttrValue; 301 /// The attribute index within the abbreviation declaration in Die. 302 uint32_t Index; 303 304 friend bool operator==(const attribute_iterator &LHS, 305 const attribute_iterator &RHS); 306 307 /// Update the attribute index and attempt to read the attribute value. If the 308 /// attribute is able to be read, update AttrValue and the Index member 309 /// variable. If the attribute value is not able to be read, an appropriate 310 /// error will be set if the Err member variable is non-NULL and the iterator 311 /// will be set to the end value so iteration stops. 312 void updateForIndex(const DWARFAbbreviationDeclaration &AbbrDecl, uint32_t I); 313 314 public: 315 attribute_iterator() = delete; 316 explicit attribute_iterator(DWARFDie D, bool End); 317 318 attribute_iterator &operator++(); 319 attribute_iterator &operator--(); 320 explicit operator bool() const { return AttrValue.isValid(); } 321 const DWARFAttribute &operator*() const { return AttrValue; } 322 }; 323 324 inline bool operator==(const DWARFDie::attribute_iterator &LHS, 325 const DWARFDie::attribute_iterator &RHS) { 326 return LHS.Index == RHS.Index; 327 } 328 329 inline bool operator!=(const DWARFDie::attribute_iterator &LHS, 330 const DWARFDie::attribute_iterator &RHS) { 331 return !(LHS == RHS); 332 } 333 334 inline bool operator==(const DWARFDie &LHS, const DWARFDie &RHS) { 335 return LHS.getDebugInfoEntry() == RHS.getDebugInfoEntry() && 336 LHS.getDwarfUnit() == RHS.getDwarfUnit(); 337 } 338 339 inline bool operator!=(const DWARFDie &LHS, const DWARFDie &RHS) { 340 return !(LHS == RHS); 341 } 342 343 inline bool operator<(const DWARFDie &LHS, const DWARFDie &RHS) { 344 return LHS.getOffset() < RHS.getOffset(); 345 } 346 347 class DWARFDie::iterator 348 : public iterator_facade_base<iterator, std::bidirectional_iterator_tag, 349 const DWARFDie> { 350 DWARFDie Die; 351 352 friend std::reverse_iterator<llvm::DWARFDie::iterator>; 353 friend bool operator==(const DWARFDie::iterator &LHS, 354 const DWARFDie::iterator &RHS); 355 356 public: 357 iterator() = default; 358 359 explicit iterator(DWARFDie D) : Die(D) {} 360 361 iterator &operator++() { 362 Die = Die.getSibling(); 363 return *this; 364 } 365 366 iterator &operator--() { 367 Die = Die.getPreviousSibling(); 368 return *this; 369 } 370 371 const DWARFDie &operator*() const { return Die; } 372 }; 373 374 inline bool operator==(const DWARFDie::iterator &LHS, 375 const DWARFDie::iterator &RHS) { 376 return LHS.Die == RHS.Die; 377 } 378 379 // These inline functions must follow the DWARFDie::iterator definition above 380 // as they use functions from that class. 381 inline DWARFDie::iterator DWARFDie::begin() const { 382 return iterator(getFirstChild()); 383 } 384 385 inline DWARFDie::iterator DWARFDie::end() const { 386 return iterator(getLastChild()); 387 } 388 389 inline iterator_range<DWARFDie::iterator> DWARFDie::children() const { 390 return make_range(begin(), end()); 391 } 392 393 } // end namespace llvm 394 395 namespace std { 396 397 template <> 398 class reverse_iterator<llvm::DWARFDie::iterator> 399 : public llvm::iterator_facade_base< 400 reverse_iterator<llvm::DWARFDie::iterator>, 401 bidirectional_iterator_tag, const llvm::DWARFDie> { 402 403 private: 404 llvm::DWARFDie Die; 405 bool AtEnd; 406 407 public: 408 reverse_iterator(llvm::DWARFDie::iterator It) 409 : Die(It.Die), AtEnd(!It.Die.getPreviousSibling()) { 410 if (!AtEnd) 411 Die = Die.getPreviousSibling(); 412 } 413 414 llvm::DWARFDie::iterator base() const { 415 return llvm::DWARFDie::iterator(AtEnd ? Die : Die.getSibling()); 416 } 417 418 reverse_iterator<llvm::DWARFDie::iterator> &operator++() { 419 assert(!AtEnd && "Incrementing rend"); 420 llvm::DWARFDie D = Die.getPreviousSibling(); 421 if (D) 422 Die = D; 423 else 424 AtEnd = true; 425 return *this; 426 } 427 428 reverse_iterator<llvm::DWARFDie::iterator> &operator--() { 429 if (AtEnd) { 430 AtEnd = false; 431 return *this; 432 } 433 Die = Die.getSibling(); 434 assert(!Die.isNULL() && "Decrementing rbegin"); 435 return *this; 436 } 437 438 const llvm::DWARFDie &operator*() const { 439 assert(Die.isValid()); 440 return Die; 441 } 442 443 // FIXME: We should be able to specify the equals operator as a friend, but 444 // that causes the compiler to think the operator overload is ambiguous 445 // with the friend declaration and the actual definition as candidates. 446 bool equals(const reverse_iterator<llvm::DWARFDie::iterator> &RHS) const { 447 return Die == RHS.Die && AtEnd == RHS.AtEnd; 448 } 449 }; 450 451 } // namespace std 452 453 namespace llvm { 454 455 inline bool operator==(const std::reverse_iterator<DWARFDie::iterator> &LHS, 456 const std::reverse_iterator<DWARFDie::iterator> &RHS) { 457 return LHS.equals(RHS); 458 } 459 460 inline bool operator!=(const std::reverse_iterator<DWARFDie::iterator> &LHS, 461 const std::reverse_iterator<DWARFDie::iterator> &RHS) { 462 return !(LHS == RHS); 463 } 464 465 inline std::reverse_iterator<DWARFDie::iterator> DWARFDie::rbegin() const { 466 return std::make_reverse_iterator(end()); 467 } 468 469 inline std::reverse_iterator<DWARFDie::iterator> DWARFDie::rend() const { 470 return std::make_reverse_iterator(begin()); 471 } 472 473 void dumpTypeQualifiedName(const DWARFDie &DIE, raw_ostream &OS); 474 void dumpTypeUnqualifiedName(const DWARFDie &DIE, raw_ostream &OS, 475 std::string *OriginalFullName = nullptr); 476 477 } // end namespace llvm 478 479 #endif // LLVM_DEBUGINFO_DWARF_DWARFDIE_H 480