contrib/llvm-project/lldb/include/lldb/Symbol/Function.h

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