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