1 //===-- SymbolContext.h -----------------------------------------*- C++ -*-===//
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
7 //===----------------------------------------------------------------------===//
9 #ifndef liblldb_SymbolContext_h_
10 #define liblldb_SymbolContext_h_
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"
22 namespace lldb_private {
24 class SymbolContextScope;
26 /// \class SymbolContext SymbolContext.h "lldb/Symbol/SymbolContext.h" Defines
27 /// a symbol context baton that can be handed other debug core functions.
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.
35 /// Default constructor.
37 /// Initialize all pointer members to nullptr and all struct members to
38 /// their default state.
41 /// Construct with an object that knows how to reconstruct its symbol
44 /// \param[in] sc_scope
45 /// A symbol context scope object that knows how to reconstruct
47 explicit SymbolContext(SymbolContextScope *sc_scope);
49 /// Construct with module, and optional compile unit, function, block, line
50 /// table, line entry and symbol.
52 /// Initialize all pointer to the specified values.
55 /// A Module pointer to the module for this context.
57 /// \param[in] comp_unit
58 /// A CompileUnit pointer to the compile unit for this context.
60 /// \param[in] function
61 /// A Function pointer to the function for this context.
64 /// A Block pointer to the deepest block for this context.
66 /// \param[in] line_entry
67 /// A LineEntry pointer to the line entry for this context.
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);
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);
87 /// Assignment operator.
89 /// Copies the address value from another SymbolContext object \a rhs into
93 /// A const SymbolContext object reference to copy.
96 /// A const SymbolContext object reference to \a this.
97 const SymbolContext &operator=(const SymbolContext &rhs);
99 /// Clear the object's state.
101 /// Resets all pointer members to nullptr, and clears any class objects to
102 /// their default state.
103 void Clear(bool clear_target);
105 /// Dump a description of this object to a Stream.
107 /// Dump a description of the contents of this object to the supplied stream
111 /// The stream to which to dump the object description.
112 void Dump(Stream *s, Target *target) const;
114 /// Dump the stop context in this object to a Stream.
116 /// Dump the best description of this object to the stream. The information
117 /// displayed depends on the amount and quality of the information in this
118 /// context. If a module, function, file and line number are available, they
119 /// will be dumped. If only a module and function or symbol name with offset
120 /// is available, that will be output. Else just the address at which the
121 /// target was stopped will be displayed.
124 /// The stream to which to dump the object description.
126 /// \param[in] so_addr
127 /// The resolved section offset address.
129 /// \param[in] show_fullpaths
130 /// When printing file paths (with the Module), whether the
131 /// base name of the Module should be printed or the full path.
133 /// \param[in] show_module
134 /// Whether the module name should be printed followed by a
135 /// grave accent "`" character.
137 /// \param[in] show_inlined_frames
138 /// If a given pc is in inlined function(s), whether the inlined
139 /// functions should be printed on separate lines in addition to
140 /// the concrete function containing the pc.
142 /// \param[in] show_function_arguments
143 /// If false, this method will try to elide the function argument
144 /// types when printing the function name. This may be ambiguous
145 /// for languages that have function overloading - but it may
146 /// make the "function name" too long to include all the argument
149 /// \param[in] show_function_name
150 /// Normally this should be true - the function/symbol name should
151 /// be printed. In disassembly formatting, where we want a format
152 /// like "<*+36>", this should be false and "*" will be printed
154 bool DumpStopContext(Stream *s, ExecutionContextScope *exe_scope,
155 const Address &so_addr, bool show_fullpaths,
156 bool show_module, bool show_inlined_frames,
157 bool show_function_arguments,
158 bool show_function_name) const;
160 /// Get the address range contained within a symbol context.
162 /// Address range priority is as follows:
163 /// - line_entry address range if line_entry is valid and
164 /// eSymbolContextLineEntry is set in \a scope
165 /// - block address range if block is not nullptr and eSymbolContextBlock
166 /// is set in \a scope
167 /// - function address range if function is not nullptr and
168 /// eSymbolContextFunction is set in \a scope
169 /// - symbol address range if symbol is not nullptr and
170 /// eSymbolContextSymbol is set in \a scope
173 /// A mask of symbol context bits telling this function which
174 /// address ranges it can use when trying to extract one from
175 /// the valid (non-nullptr) symbol context classes.
177 /// \param[in] range_idx
178 /// The address range index to grab. Since many functions and
179 /// blocks are not always contiguous, they may have more than
180 /// one address range.
182 /// \param[in] use_inline_block_range
183 /// If \a scope has the eSymbolContextBlock bit set, and there
184 /// is a valid block in the symbol context, return the block
185 /// address range for the containing inline function block, not
186 /// the deepest most block. This allows us to extract information
187 /// for the address range of the inlined function block, not
188 /// the deepest lexical block.
190 /// \param[out] range
191 /// An address range object that will be filled in if \b true
195 /// \b True if this symbol context contains items that describe
196 /// an address range, \b false otherwise.
197 bool GetAddressRange(uint32_t scope, uint32_t range_idx,
198 bool use_inline_block_range, AddressRange &range) const;
200 bool GetAddressRangeFromHereToEndLine(uint32_t end_line, AddressRange &range,
203 /// Find the best global data symbol visible from this context.
205 /// Symbol priority is:
206 /// - extern symbol in the current module if there is one
207 /// - non-extern symbol in the current module if there is one
208 /// - extern symbol in the target
209 /// - non-extern symbol in the target
210 /// It is an error if the highest-priority result is ambiguous.
213 /// The name of the symbol to search for.
215 /// \param[out] error
216 /// An error that will be populated with a message if there was an
217 /// ambiguous result. The error will not be populated if no result
221 /// The symbol that was found, or \b nullptr if none was found.
222 const Symbol *FindBestGlobalDataSymbol(ConstString name, Status &error);
224 void GetDescription(Stream *s, lldb::DescriptionLevel level,
225 Target *target) const;
227 uint32_t GetResolvedMask() const;
229 lldb::LanguageType GetLanguage() const;
231 /// Find a block that defines the function represented by this symbol
234 /// If this symbol context points to a block that is an inlined function, or
235 /// is contained within an inlined function, the block that defines the
236 /// inlined function is returned.
238 /// If this symbol context has no block in it, or the block is not itself an
239 /// inlined function block or contained within one, we return the top level
242 /// This is a handy function to call when you want to get the block whose
243 /// variable list will include the arguments for the function that is
244 /// represented by this symbol context (whether the function is an inline
245 /// function or not).
248 /// The block object pointer that defines the function that is
249 /// represented by this symbol context object, nullptr otherwise.
250 Block *GetFunctionBlock();
252 /// If this symbol context represents a function that is a method, return
253 /// true and provide information about the method.
255 /// \param[out] language
256 /// If \b true is returned, the language for the method.
258 /// \param[out] is_instance_method
259 /// If \b true is returned, \b true if this is a instance method,
260 /// \b false if this is a static/class function.
262 /// \param[out] language_object_name
263 /// If \b true is returned, the name of the artificial variable
264 /// for the language ("this" for C++, "self" for ObjC).
267 /// \b True if this symbol context represents a function that
268 /// is a method of a class, \b false otherwise.
269 bool GetFunctionMethodInfo(lldb::LanguageType &language,
270 bool &is_instance_method,
271 ConstString &language_object_name);
273 /// Sorts the types in TypeMap according to SymbolContext to TypeList
275 void SortTypeList(TypeMap &type_map, TypeList &type_list) const;
277 /// Find a name of the innermost function for the symbol context.
279 /// For instance, if the symbol context contains an inlined block, it will
280 /// return the inlined function name.
282 /// \param[in] prefer_mangled
283 /// if \btrue, then the mangled name will be returned if there
284 /// is one. Otherwise the unmangled name will be returned if it
288 /// The name of the function represented by this symbol context.
289 ConstString GetFunctionName(
290 Mangled::NamePreference preference = Mangled::ePreferDemangled) const;
292 /// Get the line entry that corresponds to the function.
294 /// If the symbol context contains an inlined block, the line entry for the
295 /// start address of the inlined function will be returned, otherwise the
296 /// line entry for the start address of the function will be returned. This
297 /// can be used after doing a Module::FindFunctions(...) or
298 /// ModuleList::FindFunctions(...) call in order to get the correct line
299 /// table information for the symbol context. it will return the inlined
302 /// \param[in] prefer_mangled
303 /// if \btrue, then the mangled name will be returned if there
304 /// is one. Otherwise the unmangled name will be returned if it
308 /// The name of the function represented by this symbol context.
309 LineEntry GetFunctionStartLineEntry() const;
311 /// Find the block containing the inlined block that contains this block.
313 /// For instance, if the symbol context contains an inlined block, it will
314 /// return the inlined function name.
316 /// \param[in] curr_frame_pc
317 /// The address within the block of this object.
319 /// \param[out] next_frame_sc
320 /// A new symbol context that does what the title says it does.
322 /// \param[out] next_frame_addr
323 /// This is what you should report as the PC in \a next_frame_sc.
326 /// \b true if this SymbolContext specifies a block contained in an
327 /// inlined block. If this returns \b true, \a next_frame_sc and
328 /// \a next_frame_addr will be filled in correctly.
329 bool GetParentOfInlinedScope(const Address &curr_frame_pc,
330 SymbolContext &next_frame_sc,
331 Address &inlined_frame_addr) const;
334 lldb::TargetSP target_sp; ///< The Target for a given query
335 lldb::ModuleSP module_sp; ///< The Module for a given query
336 CompileUnit *comp_unit; ///< The CompileUnit for a given query
337 Function *function; ///< The Function for a given query
338 Block *block; ///< The Block for a given query
339 LineEntry line_entry; ///< The LineEntry for a given query
340 Symbol *symbol; ///< The Symbol for a given query
341 Variable *variable; ///< The global variable matching the given query
344 class SymbolContextSpecifier {
346 enum SpecificationType {
347 eNothingSpecified = 0,
348 eModuleSpecified = 1 << 0,
349 eFileSpecified = 1 << 1,
350 eLineStartSpecified = 1 << 2,
351 eLineEndSpecified = 1 << 3,
352 eFunctionSpecified = 1 << 4,
353 eClassOrNamespaceSpecified = 1 << 5,
354 eAddressRangeSpecified = 1 << 6
357 // This one produces a specifier that matches everything...
358 SymbolContextSpecifier(const lldb::TargetSP &target_sp);
360 ~SymbolContextSpecifier();
362 bool AddSpecification(const char *spec_string, SpecificationType type);
364 bool AddLineSpecification(uint32_t line_no, SpecificationType type);
368 bool SymbolContextMatches(SymbolContext &sc);
370 bool AddressMatches(lldb::addr_t addr);
372 void GetDescription(Stream *s, lldb::DescriptionLevel level) const;
375 lldb::TargetSP m_target_sp;
376 std::string m_module_spec;
377 lldb::ModuleSP m_module_sp;
378 std::unique_ptr<FileSpec> m_file_spec_up;
381 std::string m_function_spec;
382 std::string m_class_name;
383 std::unique_ptr<AddressRange> m_address_range_up;
384 uint32_t m_type; // Or'ed bits from SpecificationType
387 /// \class SymbolContextList SymbolContext.h "lldb/Symbol/SymbolContext.h"
388 /// Defines a list of symbol context objects.
390 /// This class provides a common structure that can be used to contain the
391 /// result of a query that can contain a multiple results. Examples of such
393 /// \li Looking up a function by name.
394 /// \li Finding all addresses for a specified file and line number.
395 class SymbolContextList {
397 /// Default constructor.
399 /// Initialize with an empty list.
403 ~SymbolContextList();
405 /// Append a new symbol context to the list.
408 /// A symbol context to append to the list.
409 void Append(const SymbolContext &sc);
411 void Append(const SymbolContextList &sc_list);
413 bool AppendIfUnique(const SymbolContext &sc, bool merge_symbol_into_function);
415 uint32_t AppendIfUnique(const SymbolContextList &sc_list,
416 bool merge_symbol_into_function);
418 /// Clear the object's state.
420 /// Clears the symbol context list.
423 /// Dump a description of this object to a Stream.
425 /// Dump a description of the contents of each symbol context in the list to
426 /// the supplied stream \a s.
429 /// The stream to which to dump the object description.
430 void Dump(Stream *s, Target *target) const;
432 /// Get accessor for a symbol context at index \a idx.
434 /// Dump a description of the contents of each symbol context in the list to
435 /// the supplied stream \a s.
438 /// The zero based index into the symbol context list.
441 /// A reference to the symbol context to fill in.
444 /// Returns \b true if \a idx was a valid index into this
445 /// symbol context list and \a sc was filled in, \b false
447 bool GetContextAtIndex(size_t idx, SymbolContext &sc) const;
449 /// Direct reference accessor for a symbol context at index \a idx.
451 /// The index \a idx must be a valid index, no error checking will be done
452 /// to ensure that it is valid.
455 /// The zero based index into the symbol context list.
458 /// A const reference to the symbol context to fill in.
459 SymbolContext &operator[](size_t idx) { return m_symbol_contexts[idx]; }
461 const SymbolContext &operator[](size_t idx) const {
462 return m_symbol_contexts[idx];
465 bool RemoveContextAtIndex(size_t idx);
467 /// Get accessor for a symbol context list size.
470 /// Returns the number of symbol context objects in the list.
471 uint32_t GetSize() const;
473 uint32_t NumLineEntriesWithLine(uint32_t line) const;
475 void GetDescription(Stream *s, lldb::DescriptionLevel level,
476 Target *target) const;
479 typedef std::vector<SymbolContext>
480 collection; ///< The collection type for the list.
483 collection m_symbol_contexts; ///< The list of symbol contexts.
486 typedef AdaptedIterable<collection, SymbolContext, vector_adapter>
487 SymbolContextIterable;
488 SymbolContextIterable SymbolContexts() {
489 return SymbolContextIterable(m_symbol_contexts);
493 bool operator==(const SymbolContext &lhs, const SymbolContext &rhs);
494 bool operator!=(const SymbolContext &lhs, const SymbolContext &rhs);
496 bool operator==(const SymbolContextList &lhs, const SymbolContextList &rhs);
497 bool operator!=(const SymbolContextList &lhs, const SymbolContextList &rhs);
499 } // namespace lldb_private
501 #endif // liblldb_SymbolContext_h_