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