contrib/llvm/tools/lldb/include/lldb/Symbol/Function.h

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