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

   1 //===-- SymbolContext.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
  11 #ifndef liblldb_SymbolContext_h_
  12 #define liblldb_SymbolContext_h_
  13
  14 #include <vector>
  15
  16 #include "lldb/lldb-private.h"
  17 #include "lldb/Core/Address.h"
  18 #include "lldb/Core/Mangled.h"
  19 #include "lldb/Symbol/ClangASTType.h"
  20 #include "lldb/Symbol/LineEntry.h"
  21
  22 namespace lldb_private {
  23
  24 class SymbolContextScope;
  25 //----------------------------------------------------------------------
  26 /// @class SymbolContext SymbolContext.h "lldb/Symbol/SymbolContext.h"
  27 /// @brief Defines a symbol context baton that can be handed other debug
  28 /// core functions.
  29 ///
  30 /// Many debugger functions require a context when doing lookups. This
  31 /// class provides a common structure that can be used as the result
  32 /// of a query that can contain a single result. Examples of such
  33 /// queries include
  34 ///     @li Looking up a load address.
  35 //----------------------------------------------------------------------
  36 class SymbolContext
  37 {
  38 public:
  39
  40     //------------------------------------------------------------------
  41     /// Default constructor.
  42     ///
  43     /// Initialize all pointer members to NULL and all struct members
  44     /// to their default state.
  45     //------------------------------------------------------------------
  46     SymbolContext ();
  47
  48     //------------------------------------------------------------------
  49     /// Construct with an object that knows how to reconstruct its
  50     /// symbol context.
  51     ///
  52     /// @param[in] sc_scope
  53     ///     A symbol context scope object that knows how to reconstruct
  54     ///     it's context.
  55     //------------------------------------------------------------------
  56     explicit
  57     SymbolContext (SymbolContextScope *sc_scope);
  58
  59     //------------------------------------------------------------------
  60     /// Construct with module, and optional compile unit, function,
  61     /// block, line table, line entry and symbol.
  62     ///
  63     /// Initialize all pointer to the specified values.
  64     ///
  65     /// @param[in] module
  66     ///     A Module pointer to the module for this context.
  67     ///
  68     /// @param[in] comp_unit
  69     ///     A CompileUnit pointer to the compile unit for this context.
  70     ///
  71     /// @param[in] function
  72     ///     A Function pointer to the function for this context.
  73     ///
  74     /// @param[in] block
  75     ///     A Block pointer to the deepest block for this context.
  76     ///
  77     /// @param[in] line_entry
  78     ///     A LineEntry pointer to the line entry for this context.
  79     ///
  80     /// @param[in] symbol
  81     ///     A Symbol pointer to the symbol for this context.
  82     //------------------------------------------------------------------
  83     explicit
  84     SymbolContext (const lldb::TargetSP &target_sp,
  85                    const lldb::ModuleSP &module_sp,
  86                    CompileUnit *comp_unit = NULL,
  87                    Function *function = NULL,
  88                    Block *block = NULL,
  89                    LineEntry *line_entry = NULL,
  90                    Symbol *symbol = NULL);
  91
  92     // This version sets the target to a NULL TargetSP if you don't know it.
  93     explicit
  94     SymbolContext (const lldb::ModuleSP &module_sp,
  95                    CompileUnit *comp_unit = NULL,
  96                    Function *function = NULL,
  97                    Block *block = NULL,
  98                    LineEntry *line_entry = NULL,
  99                    Symbol *symbol = NULL);
 100
 101     ~SymbolContext ();
 102     //------------------------------------------------------------------
 103     /// Copy constructor
 104     ///
 105     /// Makes a copy of the another SymbolContext object \a rhs.
 106     ///
 107     /// @param[in] rhs
 108     ///     A const SymbolContext object reference to copy.
 109     //------------------------------------------------------------------
 110     SymbolContext (const SymbolContext& rhs);
 111
 112     //------------------------------------------------------------------
 113     /// Assignment operator.
 114     ///
 115     /// Copies the address value from another SymbolContext object \a
 116     /// rhs into \a this object.
 117     ///
 118     /// @param[in] rhs
 119     ///     A const SymbolContext object reference to copy.
 120     ///
 121     /// @return
 122     ///     A const SymbolContext object reference to \a this.
 123     //------------------------------------------------------------------
 124     const SymbolContext&
 125     operator= (const SymbolContext& rhs);
 126
 127     //------------------------------------------------------------------
 128     /// Clear the object's state.
 129     ///
 130     /// Resets all pointer members to NULL, and clears any class objects
 131     /// to their default state.
 132     //------------------------------------------------------------------
 133     void
 134     Clear (bool clear_target);
 135
 136     //------------------------------------------------------------------
 137     /// Dump a description of this object to a Stream.
 138     ///
 139     /// Dump a description of the contents of this object to the
 140     /// supplied stream \a s.
 141     ///
 142     /// @param[in] s
 143     ///     The stream to which to dump the object descripton.
 144     //------------------------------------------------------------------
 145     void
 146     Dump (Stream *s, Target *target) const;
 147
 148     //------------------------------------------------------------------
 149     /// Dump the stop context in this object to a Stream.
 150     ///
 151     /// Dump the best description of this object to the stream. The
 152     /// information displayed depends on the amount and quality of the
 153     /// information in this context. If a module, function, file and
 154     /// line number are available, they will be dumped. If only a
 155     /// module and function or symbol name with offset is available,
 156     /// that will be output. Else just the address at which the target
 157     /// was stopped will be displayed.
 158     ///
 159     /// @param[in] s
 160     ///     The stream to which to dump the object descripton.
 161     ///
 162     /// @param[in] so_addr
 163     ///     The resolved section offset address.
 164     //------------------------------------------------------------------
 165     bool
 166     DumpStopContext (Stream *s,
 167                      ExecutionContextScope *exe_scope,
 168                      const Address &so_addr,
 169                      bool show_fullpaths,
 170                      bool show_module,
 171                      bool show_inlined_frames) const;
 172
 173     //------------------------------------------------------------------
 174     /// Get the address range contained within a symbol context.
 175     ///
 176     /// Address range priority is as follows:
 177     ///     - line_entry address range if line_entry is valid and eSymbolContextLineEntry is set in \a scope
 178     ///     - block address range if block is not NULL and eSymbolContextBlock is set in \a scope
 179     ///     - function address range if function is not NULL and eSymbolContextFunction is set in \a scope
 180     ///     - symbol address range if symbol is not NULL and eSymbolContextSymbol is set in \a scope
 181     ///
 182     /// @param[in] scope
 183     ///     A mask of symbol context bits telling this function which
 184     ///     address ranges it can use when trying to extract one from
 185     ///     the valid (non-NULL) symbol context classes.
 186     ///
 187     /// @param[in] range_idx
 188     ///     The address range index to grab. Since many functions and
 189     ///     blocks are not always contiguous, they may have more than
 190     ///     one address range.
 191     ///
 192     /// @param[in] use_inline_block_range
 193     ///     If \a scope has the eSymbolContextBlock bit set, and there
 194     ///     is a valid block in the symbol context, return the block
 195     ///     address range for the containing inline function block, not
 196     ///     the deepest most block. This allows us to extract information
 197     ///     for the address range of the inlined function block, not
 198     ///     the deepest lexical block.
 199     ///
 200     /// @param[out] range
 201     ///     An address range object that will be filled in if \b true
 202     ///     is returned.
 203     ///
 204     /// @return
 205     ///     \b True if this symbol context contains items that describe
 206     ///     an address range, \b false otherwise.
 207     //------------------------------------------------------------------
 208     bool
 209     GetAddressRange (uint32_t scope,
 210                      uint32_t range_idx,
 211                      bool use_inline_block_range,
 212                      AddressRange &range) const;
 213
 214
 215     void
 216     GetDescription(Stream *s,
 217                    lldb::DescriptionLevel level,
 218                    Target *target) const;
 219
 220     uint32_t
 221     GetResolvedMask () const;
 222
 223
 224     //------------------------------------------------------------------
 225     /// Find a block that defines the function represented by this
 226     /// symbol context.
 227     ///
 228     /// If this symbol context points to a block that is an inlined
 229     /// function, or is contained within an inlined function, the block
 230     /// that defines the inlined function is returned.
 231     ///
 232     /// If this symbol context has no block in it, or the block is not
 233     /// itself an inlined function block or contained within one, we
 234     /// return the top level function block.
 235     ///
 236     /// This is a handy function to call when you want to get the block
 237     /// whose variable list will include the arguments for the function
 238     /// that is represented by this symbol context (whether the function
 239     /// is an inline function or not).
 240     ///
 241     /// @return
 242     ///     The block object pointer that defines the function that is
 243     ///     represented by this symbol context object, NULL otherwise.
 244     //------------------------------------------------------------------
 245     Block *
 246     GetFunctionBlock ();
 247
 248
 249     //------------------------------------------------------------------
 250     /// If this symbol context represents a function that is a method,
 251     /// return true and provide information about the method.
 252     ///
 253     /// @param[out] language
 254     ///     If \b true is returned, the language for the method.
 255     ///
 256     /// @param[out] is_instance_method
 257     ///     If \b true is returned, \b true if this is a instance method,
 258     ///     \b false if this is a static/class function.
 259     ///
 260     /// @param[out] language_object_name
 261     ///     If \b true is returned, the name of the artificial variable
 262     ///     for the language ("this" for C++, "self" for ObjC).
 263     ///
 264     /// @return
 265     ///     \b True if this symbol context represents a function that
 266     ///     is a method of a class, \b false otherwise.
 267     //------------------------------------------------------------------
 268     bool
 269     GetFunctionMethodInfo (lldb::LanguageType &language,
 270                            bool &is_instance_method,
 271                            ConstString &language_object_name);
 272
 273     //------------------------------------------------------------------
 274     /// Find a name of the innermost function for the symbol context.
 275     ///
 276     /// For instance, if the symbol context contains an inlined block,
 277     /// it will return the inlined function name.
 278     ///
 279     /// @param[in] prefer_mangled
 280     ///    if \btrue, then the mangled name will be returned if there
 281     ///    is one.  Otherwise the unmangled name will be returned if it
 282     ///    is available.
 283     ///
 284     /// @return
 285     ///     The name of the function represented by this symbol context.
 286     //------------------------------------------------------------------
 287     ConstString
 288     GetFunctionName (Mangled::NamePreference preference = Mangled::ePreferDemangled) const;
 289
 290
 291     //------------------------------------------------------------------
 292     /// Get the line entry that corresponds to the function.
 293     ///
 294     /// If the symbol context contains an inlined block, the line entry
 295     /// for the start address of the inlined function will be returned,
 296     /// otherwise the line entry for the start address of the function
 297     /// will be returned. This can be used after doing a
 298     /// Module::FindFunctions(...) or ModuleList::FindFunctions(...)
 299     /// call in order to get the correct line table information for
 300     /// the symbol context.
 301     /// it will return the inlined function name.
 302     ///
 303     /// @param[in] prefer_mangled
 304     ///    if \btrue, then the mangled name will be returned if there
 305     ///    is one.  Otherwise the unmangled name will be returned if it
 306     ///    is available.
 307     ///
 308     /// @return
 309     ///     The name of the function represented by this symbol context.
 310     //------------------------------------------------------------------
 311     LineEntry
 312     GetFunctionStartLineEntry () const;
 313
 314     //------------------------------------------------------------------
 315     /// Find the block containing the inlined block that contains this block.
 316     ///
 317     /// For instance, if the symbol context contains an inlined block,
 318     /// it will return the inlined function name.
 319     ///
 320     /// @param[in] curr_frame_pc
 321     ///    The address within the block of this object.
 322     ///
 323     /// @param[out] next_frame_sc
 324     ///     A new symbol context that does what the title says it does.
 325     ///
 326     /// @param[out] next_frame_addr
 327     ///     This is what you should report as the PC in \a next_frame_sc.
 328     ///
 329     /// @return
 330     ///     \b true if this SymbolContext specifies a block contained in an
 331     ///     inlined block.  If this returns \b true, \a next_frame_sc and
 332     ///     \a next_frame_addr will be filled in correctly.
 333     //------------------------------------------------------------------
 334     bool
 335     GetParentOfInlinedScope (const Address &curr_frame_pc,
 336                              SymbolContext &next_frame_sc,
 337                              Address &inlined_frame_addr) const;
 338
 339     //------------------------------------------------------------------
 340     // Member variables
 341     //------------------------------------------------------------------
 342     lldb::TargetSP  target_sp;  ///< The Target for a given query
 343     lldb::ModuleSP  module_sp;  ///< The Module for a given query
 344     CompileUnit *   comp_unit;  ///< The CompileUnit for a given query
 345     Function *      function;   ///< The Function for a given query
 346     Block *         block;      ///< The Block for a given query
 347     LineEntry       line_entry; ///< The LineEntry for a given query
 348     Symbol *        symbol;     ///< The Symbol for a given query
 349 };
 350
 351
 352 class SymbolContextSpecifier
 353 {
 354 public:
 355     typedef enum SpecificationType
 356     {
 357         eNothingSpecified          = 0,
 358         eModuleSpecified           = 1 << 0,
 359         eFileSpecified             = 1 << 1,
 360         eLineStartSpecified        = 1 << 2,
 361         eLineEndSpecified          = 1 << 3,
 362         eFunctionSpecified         = 1 << 4,
 363         eClassOrNamespaceSpecified = 1 << 5,
 364         eAddressRangeSpecified     = 1 << 6
 365     } SpecificationType;
 366
 367     // This one produces a specifier that matches everything...
 368     SymbolContextSpecifier (const lldb::TargetSP& target_sp);
 369
 370     ~SymbolContextSpecifier();
 371
 372     bool
 373     AddSpecification (const char *spec_string, SpecificationType type);
 374
 375     bool
 376     AddLineSpecification (uint32_t line_no, SpecificationType type);
 377
 378     void
 379     Clear();
 380
 381     bool
 382     SymbolContextMatches(SymbolContext &sc);
 383
 384     bool
 385     AddressMatches(lldb::addr_t addr);
 386
 387     void
 388     GetDescription (Stream *s, lldb::DescriptionLevel level) const;
 389
 390 private:
 391     lldb::TargetSP                 m_target_sp;
 392     std::string                    m_module_spec;
 393     lldb::ModuleSP                 m_module_sp;
 394     std::unique_ptr<FileSpec>       m_file_spec_ap;
 395     size_t                         m_start_line;
 396     size_t                         m_end_line;
 397     std::string                    m_function_spec;
 398     std::string                    m_class_name;
 399     std::unique_ptr<AddressRange>   m_address_range_ap;
 400     uint32_t                       m_type; // Or'ed bits from SpecificationType
 401
 402 };
 403
 404 //----------------------------------------------------------------------
 405 /// @class SymbolContextList SymbolContext.h "lldb/Symbol/SymbolContext.h"
 406 /// @brief Defines a list of symbol context objects.
 407 ///
 408 /// This class provides a common structure that can be used to contain
 409 /// the result of a query that can contain a multiple results. Examples
 410 /// of such queries include:
 411 ///     @li Looking up a function by name.
 412 ///     @li Finding all addressses for a specified file and line number.
 413 //----------------------------------------------------------------------
 414 class SymbolContextList
 415 {
 416 public:
 417     //------------------------------------------------------------------
 418     /// Default constructor.
 419     ///
 420     /// Initialize with an empty list.
 421     //------------------------------------------------------------------
 422     SymbolContextList ();
 423
 424     //------------------------------------------------------------------
 425     /// Destructor.
 426     //------------------------------------------------------------------
 427     ~SymbolContextList ();
 428
 429     //------------------------------------------------------------------
 430     /// Append a new symbol context to the list.
 431     ///
 432     /// @param[in] sc
 433     ///     A symbol context to append to the list.
 434     //------------------------------------------------------------------
 435     void
 436     Append (const SymbolContext& sc);
 437
 438     void
 439     Append (const SymbolContextList& sc_list);
 440
 441     bool
 442     AppendIfUnique (const SymbolContext& sc,
 443                     bool merge_symbol_into_function);
 444
 445     bool
 446     MergeSymbolContextIntoFunctionContext (const SymbolContext& symbol_sc,
 447                                            uint32_t start_idx = 0,
 448                                            uint32_t stop_idx = UINT32_MAX);
 449
 450     uint32_t
 451     AppendIfUnique (const SymbolContextList& sc_list,
 452                     bool merge_symbol_into_function);
 453     //------------------------------------------------------------------
 454     /// Clear the object's state.
 455     ///
 456     /// Clears the symbol context list.
 457     //------------------------------------------------------------------
 458     void
 459     Clear();
 460
 461     //------------------------------------------------------------------
 462     /// Dump a description of this object to a Stream.
 463     ///
 464     /// Dump a description of the contents of each symbol context in
 465     /// the list to the supplied stream \a s.
 466     ///
 467     /// @param[in] s
 468     ///     The stream to which to dump the object descripton.
 469     //------------------------------------------------------------------
 470     void
 471     Dump(Stream *s, Target *target) const;
 472
 473     //------------------------------------------------------------------
 474     /// Get accessor for a symbol context at index \a idx.
 475     ///
 476     /// Dump a description of the contents of each symbol context in
 477     /// the list to the supplied stream \a s.
 478     ///
 479     /// @param[in] idx
 480     ///     The zero based index into the symbol context list.
 481     ///
 482     /// @param[out] sc
 483     ///     A reference to the symbol context to fill in.
 484     ///
 485     /// @return
 486     ///     Returns \b true if \a idx was a valid index into this
 487     ///     symbol context list and \a sc was filled in, \b false
 488     ///     otherwise.
 489     //------------------------------------------------------------------
 490     bool
 491     GetContextAtIndex(size_t idx, SymbolContext& sc) const;
 492
 493     //------------------------------------------------------------------
 494     /// Direct reference accessor for a symbol context at index \a idx.
 495     ///
 496     /// The index \a idx must be a valid index, no error checking will
 497     /// be done to ensure that it is valid.
 498     ///
 499     /// @param[in] idx
 500     ///     The zero based index into the symbol context list.
 501     ///
 502     /// @return
 503     ///     A const reference to the symbol context to fill in.
 504     //------------------------------------------------------------------
 505     SymbolContext&
 506     operator [] (size_t idx)
 507     {
 508         return m_symbol_contexts[idx];
 509     }
 510
 511     const SymbolContext&
 512     operator [] (size_t idx) const
 513     {
 514         return m_symbol_contexts[idx];
 515     }
 516
 517     //------------------------------------------------------------------
 518     /// Get accessor for the last symbol context in the list.
 519     ///
 520     /// @param[out] sc
 521     ///     A reference to the symbol context to fill in.
 522     ///
 523     /// @return
 524     ///     Returns \b true if \a sc was filled in, \b false if the
 525     ///     list is empty.
 526     //------------------------------------------------------------------
 527     bool
 528     GetLastContext(SymbolContext& sc) const;
 529
 530     bool
 531     RemoveContextAtIndex (size_t idx);
 532     //------------------------------------------------------------------
 533     /// Get accessor for a symbol context list size.
 534     ///
 535     /// @return
 536     ///     Returns the number of symbol context objects in the list.
 537     //------------------------------------------------------------------
 538     uint32_t
 539     GetSize() const;
 540
 541     uint32_t
 542     NumLineEntriesWithLine (uint32_t line) const;
 543
 544     void
 545     GetDescription(Stream *s,
 546                    lldb::DescriptionLevel level,
 547                    Target *target) const;
 548
 549 protected:
 550     typedef std::vector<SymbolContext> collection; ///< The collection type for the list.
 551
 552     //------------------------------------------------------------------
 553     // Member variables.
 554     //------------------------------------------------------------------
 555     collection m_symbol_contexts; ///< The list of symbol contexts.
 556 };
 557
 558 bool operator== (const SymbolContext& lhs, const SymbolContext& rhs);
 559 bool operator!= (const SymbolContext& lhs, const SymbolContext& rhs);
 560
 561 bool operator== (const SymbolContextList& lhs, const SymbolContextList& rhs);
 562 bool operator!= (const SymbolContextList& lhs, const SymbolContextList& rhs);
 563
 564 } // namespace lldb_private
 565
 566 #endif  // liblldb_SymbolContext_h_