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