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