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