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