1 //===-- Function.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 liblldb_Function_h_ 11 #define liblldb_Function_h_ 12 13 #include "lldb/Core/AddressRange.h" 14 #include "lldb/Core/Mangled.h" 15 #include "lldb/Expression/DWARFExpression.h" 16 #include "lldb/Symbol/Block.h" 17 #include "lldb/Symbol/Declaration.h" 18 #include "lldb/Utility/UserID.h" 19 #include "llvm/ADT/ArrayRef.h" 20 21 namespace lldb_private { 22 23 //---------------------------------------------------------------------- 24 /// @class FunctionInfo Function.h "lldb/Symbol/Function.h" 25 /// A class that contains generic function information. 26 /// 27 /// This provides generic function information that gets reused between inline 28 /// functions and function types. 29 //---------------------------------------------------------------------- 30 class FunctionInfo { 31 public: 32 //------------------------------------------------------------------ 33 /// Construct with the function method name and optional declaration 34 /// information. 35 /// 36 /// @param[in] name 37 /// A C string name for the method name for this function. This 38 /// value should not be the mangled named, but the simple method 39 /// name. 40 /// 41 /// @param[in] decl_ptr 42 /// Optional declaration information that describes where the 43 /// function was declared. This can be NULL. 44 //------------------------------------------------------------------ 45 FunctionInfo(const char *name, const Declaration *decl_ptr); 46 47 //------------------------------------------------------------------ 48 /// Construct with the function method name and optional declaration 49 /// information. 50 /// 51 /// @param[in] name 52 /// A name for the method name for this function. This value 53 /// should not be the mangled named, but the simple method name. 54 /// 55 /// @param[in] decl_ptr 56 /// Optional declaration information that describes where the 57 /// function was declared. This can be NULL. 58 //------------------------------------------------------------------ 59 FunctionInfo(const ConstString &name, const Declaration *decl_ptr); 60 61 //------------------------------------------------------------------ 62 /// Destructor. 63 /// 64 /// The destructor is virtual since classes inherit from this class. 65 //------------------------------------------------------------------ 66 virtual ~FunctionInfo(); 67 68 //------------------------------------------------------------------ 69 /// Compare two function information objects. 70 /// 71 /// First compares the method names, and if equal, then compares the 72 /// declaration information. 73 /// 74 /// @param[in] lhs 75 /// The Left Hand Side const FunctionInfo object reference. 76 /// 77 /// @param[in] rhs 78 /// The Right Hand Side const FunctionInfo object reference. 79 /// 80 /// @return 81 /// @li -1 if lhs < rhs 82 /// @li 0 if lhs == rhs 83 /// @li 1 if lhs > rhs 84 //------------------------------------------------------------------ 85 static int Compare(const FunctionInfo &lhs, const FunctionInfo &rhs); 86 87 //------------------------------------------------------------------ 88 /// Dump a description of this object to a Stream. 89 /// 90 /// Dump a description of the contents of this object to the supplied stream 91 /// \a s. 92 /// 93 /// @param[in] s 94 /// The stream to which to dump the object description. 95 //------------------------------------------------------------------ 96 void Dump(Stream *s, bool show_fullpaths) const; 97 98 //------------------------------------------------------------------ 99 /// Get accessor for the declaration information. 100 /// 101 /// @return 102 /// A reference to the declaration object. 103 //------------------------------------------------------------------ 104 Declaration &GetDeclaration(); 105 106 //------------------------------------------------------------------ 107 /// Get const accessor for the declaration information. 108 /// 109 /// @return 110 /// A const reference to the declaration object. 111 //------------------------------------------------------------------ 112 const Declaration &GetDeclaration() const; 113 114 //------------------------------------------------------------------ 115 /// Get accessor for the method name. 116 /// 117 /// @return 118 /// A const reference to the method name object. 119 //------------------------------------------------------------------ 120 ConstString GetName() const; 121 122 //------------------------------------------------------------------ 123 /// Get the memory cost of this object. 124 /// 125 /// @return 126 /// The number of bytes that this object occupies in memory. 127 /// The returned value does not include the bytes for any 128 /// shared string values. 129 /// 130 /// @see ConstString::StaticMemorySize () 131 //------------------------------------------------------------------ 132 virtual size_t MemorySize() const; 133 134 protected: 135 //------------------------------------------------------------------ 136 // Member variables. 137 //------------------------------------------------------------------ 138 ConstString m_name; ///< Function method name (not a mangled name). 139 Declaration m_declaration; ///< Information describing where this function 140 ///information was defined. 141 }; 142 143 //---------------------------------------------------------------------- 144 /// @class InlineFunctionInfo Function.h "lldb/Symbol/Function.h" 145 /// A class that describes information for an inlined function. 146 //---------------------------------------------------------------------- 147 class InlineFunctionInfo : public FunctionInfo { 148 public: 149 //------------------------------------------------------------------ 150 /// Construct with the function method name, mangled name, and optional 151 /// declaration information. 152 /// 153 /// @param[in] name 154 /// A C string name for the method name for this function. This 155 /// value should not be the mangled named, but the simple method 156 /// name. 157 /// 158 /// @param[in] mangled 159 /// A C string name for the mangled name for this function. This 160 /// value can be NULL if there is no mangled information. 161 /// 162 /// @param[in] decl_ptr 163 /// Optional declaration information that describes where the 164 /// function was declared. This can be NULL. 165 /// 166 /// @param[in] call_decl_ptr 167 /// Optional calling location declaration information that 168 /// describes from where this inlined function was called. 169 //------------------------------------------------------------------ 170 InlineFunctionInfo(const char *name, const char *mangled, 171 const Declaration *decl_ptr, 172 const Declaration *call_decl_ptr); 173 174 //------------------------------------------------------------------ 175 /// Construct with the function method name, mangled name, and optional 176 /// declaration information. 177 /// 178 /// @param[in] name 179 /// A name for the method name for this function. This value 180 /// should not be the mangled named, but the simple method name. 181 /// 182 /// @param[in] mangled 183 /// A name for the mangled name for this function. This value 184 /// can be empty if there is no mangled information. 185 /// 186 /// @param[in] decl_ptr 187 /// Optional declaration information that describes where the 188 /// function was declared. This can be NULL. 189 /// 190 /// @param[in] call_decl_ptr 191 /// Optional calling location declaration information that 192 /// describes from where this inlined function was called. 193 //------------------------------------------------------------------ 194 InlineFunctionInfo(const ConstString &name, const Mangled &mangled, 195 const Declaration *decl_ptr, 196 const Declaration *call_decl_ptr); 197 198 //------------------------------------------------------------------ 199 /// Destructor. 200 //------------------------------------------------------------------ 201 ~InlineFunctionInfo() override; 202 203 //------------------------------------------------------------------ 204 /// Compare two inlined function information objects. 205 /// 206 /// First compares the FunctionInfo objects, and if equal, compares the 207 /// mangled names. 208 /// 209 /// @param[in] lhs 210 /// The Left Hand Side const InlineFunctionInfo object 211 /// reference. 212 /// 213 /// @param[in] rhs 214 /// The Right Hand Side const InlineFunctionInfo object 215 /// reference. 216 /// 217 /// @return 218 /// @li -1 if lhs < rhs 219 /// @li 0 if lhs == rhs 220 /// @li 1 if lhs > rhs 221 //------------------------------------------------------------------ 222 int Compare(const InlineFunctionInfo &lhs, const InlineFunctionInfo &rhs); 223 224 //------------------------------------------------------------------ 225 /// Dump a description of this object to a Stream. 226 /// 227 /// Dump a description of the contents of this object to the supplied stream 228 /// \a s. 229 /// 230 /// @param[in] s 231 /// The stream to which to dump the object description. 232 //------------------------------------------------------------------ 233 void Dump(Stream *s, bool show_fullpaths) const; 234 235 void DumpStopContext(Stream *s, lldb::LanguageType language) const; 236 237 ConstString GetName(lldb::LanguageType language) const; 238 239 ConstString GetDisplayName(lldb::LanguageType language) const; 240 241 //------------------------------------------------------------------ 242 /// Get accessor for the call site declaration information. 243 /// 244 /// @return 245 /// A reference to the declaration object. 246 //------------------------------------------------------------------ 247 Declaration &GetCallSite(); 248 249 //------------------------------------------------------------------ 250 /// Get const accessor for the call site declaration information. 251 /// 252 /// @return 253 /// A const reference to the declaration object. 254 //------------------------------------------------------------------ 255 const Declaration &GetCallSite() const; 256 257 //------------------------------------------------------------------ 258 /// Get accessor for the mangled name object. 259 /// 260 /// @return 261 /// A reference to the mangled name object. 262 //------------------------------------------------------------------ 263 Mangled &GetMangled(); 264 265 //------------------------------------------------------------------ 266 /// Get const accessor for the mangled name object. 267 /// 268 /// @return 269 /// A const reference to the mangled name object. 270 //------------------------------------------------------------------ 271 const Mangled &GetMangled() const; 272 273 //------------------------------------------------------------------ 274 /// Get the memory cost of this object. 275 /// 276 /// @return 277 /// The number of bytes that this object occupies in memory. 278 /// The returned value does not include the bytes for any 279 /// shared string values. 280 /// 281 /// @see ConstString::StaticMemorySize () 282 //------------------------------------------------------------------ 283 size_t MemorySize() const override; 284 285 private: 286 //------------------------------------------------------------------ 287 // Member variables. 288 //------------------------------------------------------------------ 289 Mangled m_mangled; ///< Mangled inlined function name (can be empty if there 290 ///is no mangled information). 291 Declaration m_call_decl; 292 }; 293 294 class Function; 295 296 //---------------------------------------------------------------------- 297 /// @class CallEdge Function.h "lldb/Symbol/Function.h" 298 /// 299 /// Represent a call made within a Function. This can be used to find a path 300 /// in the call graph between two functions. 301 //---------------------------------------------------------------------- 302 class CallEdge { 303 public: 304 /// Construct a call edge using a symbol name to identify the calling 305 /// function, and a return PC within the calling function to identify a 306 /// specific call site. 307 /// 308 /// TODO: A symbol name may not be globally unique. To disambiguate ODR 309 /// conflicts, it's necessary to determine the \c Target a call edge is 310 /// associated with before resolving it. 311 CallEdge(const char *symbol_name, lldb::addr_t return_pc); 312 313 CallEdge(CallEdge &&) = default; 314 CallEdge &operator=(CallEdge &&) = default; 315 316 /// Get the callee's definition. 317 /// 318 /// Note that this might lazily invoke the DWARF parser. 319 Function *GetCallee(ModuleList &images); 320 321 /// Get the load PC address of the instruction which executes after the call 322 /// returns. Returns LLDB_INVALID_ADDRESS iff this is a tail call. \p caller 323 /// is the Function containing this call, and \p target is the Target which 324 /// made the call. 325 lldb::addr_t GetReturnPCAddress(Function &caller, Target &target) const; 326 327 /// Like \ref GetReturnPCAddress, but returns an unslid function-local PC 328 /// offset. GetUnresolvedReturnPCAddress()329 lldb::addr_t GetUnresolvedReturnPCAddress() const { return return_pc; } 330 331 private: 332 void ParseSymbolFileAndResolve(ModuleList &images); 333 334 /// Either the callee's mangled name or its definition, discriminated by 335 /// \ref resolved. 336 union { 337 const char *symbol_name; 338 Function *def; 339 } lazy_callee; 340 341 /// An invalid address if this is a tail call. Otherwise, the function-local 342 /// PC offset. Adding this PC offset to the function's base load address 343 /// gives the return PC for the call. 344 lldb::addr_t return_pc; 345 346 /// Whether or not an attempt was made to find the callee's definition. 347 bool resolved; 348 349 DISALLOW_COPY_AND_ASSIGN(CallEdge); 350 }; 351 352 //---------------------------------------------------------------------- 353 /// @class Function Function.h "lldb/Symbol/Function.h" 354 /// A class that describes a function. 355 /// 356 /// Functions belong to CompileUnit objects (Function::m_comp_unit), have 357 /// unique user IDs (Function::UserID), know how to reconstruct their symbol 358 /// context (Function::SymbolContextScope), have a specific function type 359 /// (Function::m_type_uid), have a simple method name (FunctionInfo::m_name), 360 /// be declared at a specific location (FunctionInfo::m_declaration), possibly 361 /// have mangled names (Function::m_mangled), an optional return type 362 /// (Function::m_type), and contains lexical blocks (Function::m_blocks). 363 /// 364 /// The function information is split into a few pieces: 365 /// @li The concrete instance information 366 /// @li The abstract information 367 /// 368 /// The abstract information is found in the function type (Type) that 369 /// describes a function information, return type and parameter types. 370 /// 371 /// The concrete information is the address range information and specific 372 /// locations for an instance of this function. 373 //---------------------------------------------------------------------- 374 class Function : public UserID, public SymbolContextScope { 375 public: 376 //------------------------------------------------------------------ 377 /// Construct with a compile unit, function UID, function type UID, optional 378 /// mangled name, function type, and a section offset based address range. 379 /// 380 /// @param[in] comp_unit 381 /// The compile unit to which this function belongs. 382 /// 383 /// @param[in] func_uid 384 /// The UID for this function. This value is provided by the 385 /// SymbolFile plug-in and can be any value that allows 386 /// the plug-in to quickly find and parse more detailed 387 /// information when and if more information is needed. 388 /// 389 /// @param[in] func_type_uid 390 /// The type UID for the function Type to allow for lazy type 391 /// parsing from the debug information. 392 /// 393 /// @param[in] mangled 394 /// The optional mangled name for this function. If empty, there 395 /// is no mangled information. 396 /// 397 /// @param[in] func_type 398 /// The optional function type. If NULL, the function type will 399 /// be parsed on demand when accessed using the 400 /// Function::GetType() function by asking the SymbolFile 401 /// plug-in to get the type for \a func_type_uid. 402 /// 403 /// @param[in] range 404 /// The section offset based address for this function. 405 //------------------------------------------------------------------ 406 Function(CompileUnit *comp_unit, lldb::user_id_t func_uid, 407 lldb::user_id_t func_type_uid, const Mangled &mangled, 408 Type *func_type, const AddressRange &range); 409 410 //------------------------------------------------------------------ 411 /// Destructor. 412 //------------------------------------------------------------------ 413 ~Function() override; 414 415 //------------------------------------------------------------------ 416 /// @copydoc SymbolContextScope::CalculateSymbolContext(SymbolContext*) 417 /// 418 /// @see SymbolContextScope 419 //------------------------------------------------------------------ 420 void CalculateSymbolContext(SymbolContext *sc) override; 421 422 lldb::ModuleSP CalculateSymbolContextModule() override; 423 424 CompileUnit *CalculateSymbolContextCompileUnit() override; 425 426 Function *CalculateSymbolContextFunction() override; 427 GetAddressRange()428 const AddressRange &GetAddressRange() { return m_range; } 429 430 lldb::LanguageType GetLanguage() const; 431 //------------------------------------------------------------------ 432 /// Find the file and line number of the source location of the start of the 433 /// function. This will use the declaration if present and fall back on the 434 /// line table if that fails. So there may NOT be a line table entry for 435 /// this source file/line combo. 436 /// 437 /// @param[out] source_file 438 /// The source file. 439 /// 440 /// @param[out] line_no 441 /// The line number. 442 //------------------------------------------------------------------ 443 void GetStartLineSourceInfo(FileSpec &source_file, uint32_t &line_no); 444 445 //------------------------------------------------------------------ 446 /// Find the file and line number of the source location of the end of the 447 /// function. 448 /// 449 /// 450 /// @param[out] source_file 451 /// The source file. 452 /// 453 /// @param[out] line_no 454 /// The line number. 455 //------------------------------------------------------------------ 456 void GetEndLineSourceInfo(FileSpec &source_file, uint32_t &line_no); 457 458 //------------------------------------------------------------------ 459 /// Get the outgoing call edges from this function, sorted by their return 460 /// PC addresses (in increasing order). 461 //------------------------------------------------------------------ 462 llvm::MutableArrayRef<CallEdge> GetCallEdges(); 463 464 //------------------------------------------------------------------ 465 /// Get the outgoing tail-calling edges from this function. If none exist, 466 /// return None. 467 //------------------------------------------------------------------ 468 llvm::MutableArrayRef<CallEdge> GetTailCallingEdges(); 469 470 //------------------------------------------------------------------ 471 /// Get accessor for the block list. 472 /// 473 /// @return 474 /// The block list object that describes all lexical blocks 475 /// in the function. 476 /// 477 /// @see BlockList 478 //------------------------------------------------------------------ 479 Block &GetBlock(bool can_create); 480 481 //------------------------------------------------------------------ 482 /// Get accessor for the compile unit that owns this function. 483 /// 484 /// @return 485 /// A compile unit object pointer. 486 //------------------------------------------------------------------ 487 CompileUnit *GetCompileUnit(); 488 489 //------------------------------------------------------------------ 490 /// Get const accessor for the compile unit that owns this function. 491 /// 492 /// @return 493 /// A const compile unit object pointer. 494 //------------------------------------------------------------------ 495 const CompileUnit *GetCompileUnit() const; 496 497 void GetDescription(Stream *s, lldb::DescriptionLevel level, Target *target); 498 499 //------------------------------------------------------------------ 500 /// Get accessor for the frame base location. 501 /// 502 /// @return 503 /// A location expression that describes the function frame 504 /// base. 505 //------------------------------------------------------------------ GetFrameBaseExpression()506 DWARFExpression &GetFrameBaseExpression() { return m_frame_base; } 507 508 //------------------------------------------------------------------ 509 /// Get const accessor for the frame base location. 510 /// 511 /// @return 512 /// A const compile unit object pointer. 513 //------------------------------------------------------------------ GetFrameBaseExpression()514 const DWARFExpression &GetFrameBaseExpression() const { return m_frame_base; } 515 516 ConstString GetName() const; 517 518 ConstString GetNameNoArguments() const; 519 520 ConstString GetDisplayName() const; 521 GetMangled()522 const Mangled &GetMangled() const { return m_mangled; } 523 524 //------------------------------------------------------------------ 525 /// Get the DeclContext for this function, if available. 526 /// 527 /// @return 528 /// The DeclContext, or NULL if none exists. 529 //------------------------------------------------------------------ 530 CompilerDeclContext GetDeclContext(); 531 532 //------------------------------------------------------------------ 533 /// Get accessor for the type that describes the function return value type, 534 /// and parameter types. 535 /// 536 /// @return 537 /// A type object pointer. 538 //------------------------------------------------------------------ 539 Type *GetType(); 540 541 //------------------------------------------------------------------ 542 /// Get const accessor for the type that describes the function return value 543 /// type, and parameter types. 544 /// 545 /// @return 546 /// A const type object pointer. 547 //------------------------------------------------------------------ 548 const Type *GetType() const; 549 550 CompilerType GetCompilerType(); 551 552 //------------------------------------------------------------------ 553 /// Get the size of the prologue instructions for this function. The 554 /// "prologue" instructions include any instructions given line number 0 555 /// immediately following the prologue end. 556 /// 557 /// @return 558 /// The size of the prologue. 559 //------------------------------------------------------------------ 560 uint32_t GetPrologueByteSize(); 561 562 //------------------------------------------------------------------ 563 /// Dump a description of this object to a Stream. 564 /// 565 /// Dump a description of the contents of this object to the supplied stream 566 /// \a s. 567 /// 568 /// @param[in] s 569 /// The stream to which to dump the object description. 570 /// 571 /// @param[in] show_context 572 /// If \b true, variables will dump their symbol context 573 /// information. 574 //------------------------------------------------------------------ 575 void Dump(Stream *s, bool show_context) const; 576 577 //------------------------------------------------------------------ 578 /// @copydoc SymbolContextScope::DumpSymbolContext(Stream*) 579 /// 580 /// @see SymbolContextScope 581 //------------------------------------------------------------------ 582 void DumpSymbolContext(Stream *s) override; 583 584 //------------------------------------------------------------------ 585 /// Get the memory cost of this object. 586 /// 587 /// @return 588 /// The number of bytes that this object occupies in memory. 589 /// The returned value does not include the bytes for any 590 /// shared string values. 591 /// 592 /// @see ConstString::StaticMemorySize () 593 //------------------------------------------------------------------ 594 size_t MemorySize() const; 595 596 //------------------------------------------------------------------ 597 /// Get whether compiler optimizations were enabled for this function 598 /// 599 /// The debug information may provide information about whether this 600 /// function was compiled with optimization or not. In this case, 601 /// "optimized" means that the debug experience may be difficult for the 602 /// user to understand. Variables may not be available when the developer 603 /// would expect them, stepping through the source lines in the function may 604 /// appear strange, etc. 605 /// 606 /// @return 607 /// Returns 'true' if this function was compiled with 608 /// optimization. 'false' indicates that either the optimization 609 /// is unknown, or this function was built without optimization. 610 //------------------------------------------------------------------ 611 bool GetIsOptimized(); 612 613 //------------------------------------------------------------------ 614 /// Get whether this function represents a 'top-level' function 615 /// 616 /// The concept of a top-level function is language-specific, mostly meant 617 /// to represent the notion of scripting-style code that has global 618 /// visibility of the variables/symbols/functions/... defined within the 619 /// containing file/module 620 /// 621 /// If stopped in a top-level function, LLDB will expose global variables 622 /// as-if locals in the 'frame variable' command 623 /// 624 /// @return 625 /// Returns 'true' if this function is a top-level function, 626 /// 'false' otherwise. 627 //------------------------------------------------------------------ 628 bool IsTopLevelFunction(); 629 630 lldb::DisassemblerSP GetInstructions(const ExecutionContext &exe_ctx, 631 const char *flavor, 632 bool prefer_file_cache); 633 634 bool GetDisassembly(const ExecutionContext &exe_ctx, const char *flavor, 635 bool prefer_file_cache, Stream &strm); 636 637 protected: 638 enum { 639 flagsCalculatedPrologueSize = 640 (1 << 0) ///< Have we already tried to calculate the prologue size? 641 }; 642 643 //------------------------------------------------------------------ 644 // Member variables. 645 //------------------------------------------------------------------ 646 CompileUnit *m_comp_unit; ///< The compile unit that owns this function. 647 lldb::user_id_t 648 m_type_uid; ///< The user ID of for the prototype Type for this function. 649 Type *m_type; ///< The function prototype type for this function that include 650 ///the function info (FunctionInfo), return type and parameters. 651 Mangled m_mangled; ///< The mangled function name if any, if empty, there is 652 ///no mangled information. 653 Block m_block; ///< All lexical blocks contained in this function. 654 AddressRange m_range; ///< The function address range that covers the widest 655 ///range needed to contain all blocks 656 DWARFExpression m_frame_base; ///< The frame base expression for variables 657 ///that are relative to the frame pointer. 658 Flags m_flags; 659 uint32_t 660 m_prologue_byte_size; ///< Compute the prologue size once and cache it 661 662 bool m_call_edges_resolved = false; ///< Whether call site info has been 663 /// parsed. 664 std::vector<CallEdge> m_call_edges; ///< Outgoing call edges. 665 private: 666 DISALLOW_COPY_AND_ASSIGN(Function); 667 }; 668 669 } // namespace lldb_private 670 671 #endif // liblldb_Function_h_ 672