1 //===-- SymbolContext.h -----------------------------------------*- C++ -*-===//
3 // The LLVM Compiler Infrastructure
5 // This file is distributed under the University of Illinois Open Source
6 // License. See LICENSE.TXT for details.
8 //===----------------------------------------------------------------------===//
10 #ifndef liblldb_SymbolContext_h_
11 #define liblldb_SymbolContext_h_
19 // Other libraries and framework 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"
27 namespace lldb_private {
29 class SymbolContextScope;
31 //----------------------------------------------------------------------
32 /// @class SymbolContext SymbolContext.h "lldb/Symbol/SymbolContext.h"
33 /// @brief Defines a symbol context baton that can be handed other debug
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
40 /// @li Looking up a load address.
41 //----------------------------------------------------------------------
44 //------------------------------------------------------------------
45 /// Default constructor.
47 /// Initialize all pointer members to nullptr and all struct members
48 /// to their default state.
49 //------------------------------------------------------------------
52 //------------------------------------------------------------------
53 /// Construct with an object that knows how to reconstruct its
56 /// @param[in] sc_scope
57 /// A symbol context scope object that knows how to reconstruct
59 //------------------------------------------------------------------
60 explicit SymbolContext(SymbolContextScope *sc_scope);
62 //------------------------------------------------------------------
63 /// Construct with module, and optional compile unit, function,
64 /// block, line table, line entry and symbol.
66 /// Initialize all pointer to the specified values.
69 /// A Module pointer to the module for this context.
71 /// @param[in] comp_unit
72 /// A CompileUnit pointer to the compile unit for this context.
74 /// @param[in] function
75 /// A Function pointer to the function for this context.
78 /// A Block pointer to the deepest block for this context.
80 /// @param[in] line_entry
81 /// A LineEntry pointer to the line entry for this context.
84 /// A Symbol pointer to the symbol for this context.
85 //------------------------------------------------------------------
86 explicit SymbolContext(const lldb::TargetSP &target_sp,
87 const lldb::ModuleSP &module_sp,
88 CompileUnit *comp_unit = nullptr,
89 Function *function = nullptr, Block *block = nullptr,
90 LineEntry *line_entry = nullptr,
91 Symbol *symbol = nullptr);
93 // This version sets the target to a NULL TargetSP if you don't know it.
94 explicit SymbolContext(const lldb::ModuleSP &module_sp,
95 CompileUnit *comp_unit = nullptr,
96 Function *function = nullptr, Block *block = nullptr,
97 LineEntry *line_entry = nullptr,
98 Symbol *symbol = nullptr);
100 //------------------------------------------------------------------
103 /// Makes a copy of the another SymbolContext object \a rhs.
106 /// A const SymbolContext object reference to copy.
107 //------------------------------------------------------------------
108 SymbolContext(const SymbolContext &rhs);
112 //------------------------------------------------------------------
113 /// Assignment operator.
115 /// Copies the address value from another SymbolContext object \a
116 /// rhs into \a this object.
119 /// A const SymbolContext object reference to copy.
122 /// A const SymbolContext object reference to \a this.
123 //------------------------------------------------------------------
124 const SymbolContext &operator=(const SymbolContext &rhs);
126 //------------------------------------------------------------------
127 /// Clear the object's state.
129 /// Resets all pointer members to nullptr, and clears any class objects
130 /// to their default state.
131 //------------------------------------------------------------------
132 void Clear(bool clear_target);
134 //------------------------------------------------------------------
135 /// Dump a description of this object to a Stream.
137 /// Dump a description of the contents of this object to the
138 /// supplied stream \a s.
141 /// The stream to which to dump the object description.
142 //------------------------------------------------------------------
143 void Dump(Stream *s, Target *target) const;
145 //------------------------------------------------------------------
146 /// Dump the stop context in this object to a Stream.
148 /// Dump the best description of this object to the stream. The
149 /// information displayed depends on the amount and quality of the
150 /// information in this context. If a module, function, file and
151 /// line number are available, they will be dumped. If only a
152 /// module and function or symbol name with offset is available,
153 /// that will be output. Else just the address at which the target
154 /// was stopped will be displayed.
157 /// The stream to which to dump the object description.
159 /// @param[in] so_addr
160 /// The resolved section offset address.
162 /// @param[in] show_fullpaths
163 /// When printing file paths (with the Module), whether the
164 /// base name of the Module should be printed or the full path.
166 /// @param[in] show_module
167 /// Whether the module name should be printed followed by a
168 /// grave accent "`" character.
170 /// @param[in] show_inlined_frames
171 /// If a given pc is in inlined function(s), whether the inlined
172 /// functions should be printed on separate lines in addition to
173 /// the concrete function containing the pc.
175 /// @param[in] show_function_arguments
176 /// If false, this method will try to elide the function argument
177 /// types when printing the function name. This may be ambiguous
178 /// for languages that have function overloading - but it may
179 /// make the "function name" too long to include all the argument
182 /// @param[in] show_function_name
183 /// Normally this should be true - the function/symbol name should
184 /// be printed. In disassembly formatting, where we want a format
185 /// like "<*+36>", this should be false and "*" will be printed
187 //------------------------------------------------------------------
188 bool DumpStopContext(Stream *s, ExecutionContextScope *exe_scope,
189 const Address &so_addr, bool show_fullpaths,
190 bool show_module, bool show_inlined_frames,
191 bool show_function_arguments,
192 bool show_function_name) const;
194 //------------------------------------------------------------------
195 /// Get the address range contained within a symbol context.
197 /// Address range priority is as follows:
198 /// - line_entry address range if line_entry is valid and
199 /// eSymbolContextLineEntry is set in \a scope
200 /// - block address range if block is not nullptr and eSymbolContextBlock
201 /// is set in \a scope
202 /// - function address range if function is not nullptr and
203 /// eSymbolContextFunction is set in \a scope
204 /// - symbol address range if symbol is not nullptr and
205 /// eSymbolContextSymbol is set in \a scope
208 /// A mask of symbol context bits telling this function which
209 /// address ranges it can use when trying to extract one from
210 /// the valid (non-nullptr) symbol context classes.
212 /// @param[in] range_idx
213 /// The address range index to grab. Since many functions and
214 /// blocks are not always contiguous, they may have more than
215 /// one address range.
217 /// @param[in] use_inline_block_range
218 /// If \a scope has the eSymbolContextBlock bit set, and there
219 /// is a valid block in the symbol context, return the block
220 /// address range for the containing inline function block, not
221 /// the deepest most block. This allows us to extract information
222 /// for the address range of the inlined function block, not
223 /// the deepest lexical block.
225 /// @param[out] range
226 /// An address range object that will be filled in if \b true
230 /// \b True if this symbol context contains items that describe
231 /// an address range, \b false otherwise.
232 //------------------------------------------------------------------
233 bool GetAddressRange(uint32_t scope, uint32_t range_idx,
234 bool use_inline_block_range, AddressRange &range) const;
236 bool GetAddressRangeFromHereToEndLine(uint32_t end_line, AddressRange &range,
239 void GetDescription(Stream *s, lldb::DescriptionLevel level,
240 Target *target) const;
242 uint32_t GetResolvedMask() const;
244 lldb::LanguageType GetLanguage() const;
246 //------------------------------------------------------------------
247 /// Find a block that defines the function represented by this
250 /// If this symbol context points to a block that is an inlined
251 /// function, or is contained within an inlined function, the block
252 /// that defines the inlined function is returned.
254 /// If this symbol context has no block in it, or the block is not
255 /// itself an inlined function block or contained within one, we
256 /// return the top level function block.
258 /// This is a handy function to call when you want to get the block
259 /// whose variable list will include the arguments for the function
260 /// that is represented by this symbol context (whether the function
261 /// is an inline function or not).
264 /// The block object pointer that defines the function that is
265 /// represented by this symbol context object, nullptr otherwise.
266 //------------------------------------------------------------------
267 Block *GetFunctionBlock();
269 //------------------------------------------------------------------
270 /// If this symbol context represents a function that is a method,
271 /// return true and provide information about the method.
273 /// @param[out] language
274 /// If \b true is returned, the language for the method.
276 /// @param[out] is_instance_method
277 /// If \b true is returned, \b true if this is a instance method,
278 /// \b false if this is a static/class function.
280 /// @param[out] language_object_name
281 /// If \b true is returned, the name of the artificial variable
282 /// for the language ("this" for C++, "self" for ObjC).
285 /// \b True if this symbol context represents a function that
286 /// is a method of a class, \b false otherwise.
287 //------------------------------------------------------------------
288 bool GetFunctionMethodInfo(lldb::LanguageType &language,
289 bool &is_instance_method,
290 ConstString &language_object_name);
292 //------------------------------------------------------------------
293 /// Sorts the types in TypeMap according to SymbolContext
296 //------------------------------------------------------------------
297 void SortTypeList(TypeMap &type_map, TypeList &type_list) const;
299 //------------------------------------------------------------------
300 /// Find a name of the innermost function for the symbol context.
302 /// For instance, if the symbol context contains an inlined block,
303 /// it will return the inlined function name.
305 /// @param[in] prefer_mangled
306 /// if \btrue, then the mangled name will be returned if there
307 /// is one. Otherwise the unmangled name will be returned if it
311 /// The name of the function represented by this symbol context.
312 //------------------------------------------------------------------
313 ConstString GetFunctionName(
314 Mangled::NamePreference preference = Mangled::ePreferDemangled) const;
316 //------------------------------------------------------------------
317 /// Get the line entry that corresponds to the function.
319 /// If the symbol context contains an inlined block, the line entry
320 /// for the start address of the inlined function will be returned,
321 /// otherwise the line entry for the start address of the function
322 /// will be returned. This can be used after doing a
323 /// Module::FindFunctions(...) or ModuleList::FindFunctions(...)
324 /// call in order to get the correct line table information for
325 /// the symbol context.
326 /// it will return the inlined function name.
328 /// @param[in] prefer_mangled
329 /// if \btrue, then the mangled name will be returned if there
330 /// is one. Otherwise the unmangled name will be returned if it
334 /// The name of the function represented by this symbol context.
335 //------------------------------------------------------------------
336 LineEntry GetFunctionStartLineEntry() const;
338 //------------------------------------------------------------------
339 /// Find the block containing the inlined block that contains this block.
341 /// For instance, if the symbol context contains an inlined block,
342 /// it will return the inlined function name.
344 /// @param[in] curr_frame_pc
345 /// The address within the block of this object.
347 /// @param[out] next_frame_sc
348 /// A new symbol context that does what the title says it does.
350 /// @param[out] next_frame_addr
351 /// This is what you should report as the PC in \a next_frame_sc.
354 /// \b true if this SymbolContext specifies a block contained in an
355 /// inlined block. If this returns \b true, \a next_frame_sc and
356 /// \a next_frame_addr will be filled in correctly.
357 //------------------------------------------------------------------
358 bool GetParentOfInlinedScope(const Address &curr_frame_pc,
359 SymbolContext &next_frame_sc,
360 Address &inlined_frame_addr) const;
362 //------------------------------------------------------------------
364 //------------------------------------------------------------------
365 lldb::TargetSP target_sp; ///< The Target for a given query
366 lldb::ModuleSP module_sp; ///< The Module for a given query
367 CompileUnit *comp_unit; ///< The CompileUnit for a given query
368 Function *function; ///< The Function for a given query
369 Block *block; ///< The Block for a given query
370 LineEntry line_entry; ///< The LineEntry for a given query
371 Symbol *symbol; ///< The Symbol for a given query
372 Variable *variable; ///< The global variable matching the given query
375 class SymbolContextSpecifier {
377 typedef enum SpecificationType {
378 eNothingSpecified = 0,
379 eModuleSpecified = 1 << 0,
380 eFileSpecified = 1 << 1,
381 eLineStartSpecified = 1 << 2,
382 eLineEndSpecified = 1 << 3,
383 eFunctionSpecified = 1 << 4,
384 eClassOrNamespaceSpecified = 1 << 5,
385 eAddressRangeSpecified = 1 << 6
388 // This one produces a specifier that matches everything...
389 SymbolContextSpecifier(const lldb::TargetSP &target_sp);
391 ~SymbolContextSpecifier();
393 bool AddSpecification(const char *spec_string, SpecificationType type);
395 bool AddLineSpecification(uint32_t line_no, SpecificationType type);
399 bool SymbolContextMatches(SymbolContext &sc);
401 bool AddressMatches(lldb::addr_t addr);
403 void GetDescription(Stream *s, lldb::DescriptionLevel level) const;
406 lldb::TargetSP m_target_sp;
407 std::string m_module_spec;
408 lldb::ModuleSP m_module_sp;
409 std::unique_ptr<FileSpec> m_file_spec_ap;
412 std::string m_function_spec;
413 std::string m_class_name;
414 std::unique_ptr<AddressRange> m_address_range_ap;
415 uint32_t m_type; // Or'ed bits from SpecificationType
418 //----------------------------------------------------------------------
419 /// @class SymbolContextList SymbolContext.h "lldb/Symbol/SymbolContext.h"
420 /// @brief Defines a list of symbol context objects.
422 /// This class provides a common structure that can be used to contain
423 /// the result of a query that can contain a multiple results. Examples
424 /// of such queries include:
425 /// @li Looking up a function by name.
426 /// @li Finding all addresses for a specified file and line number.
427 //----------------------------------------------------------------------
428 class SymbolContextList {
430 //------------------------------------------------------------------
431 /// Default constructor.
433 /// Initialize with an empty list.
434 //------------------------------------------------------------------
437 //------------------------------------------------------------------
439 //------------------------------------------------------------------
440 ~SymbolContextList();
442 //------------------------------------------------------------------
443 /// Append a new symbol context to the list.
446 /// A symbol context to append to the list.
447 //------------------------------------------------------------------
448 void Append(const SymbolContext &sc);
450 void Append(const SymbolContextList &sc_list);
452 bool AppendIfUnique(const SymbolContext &sc, bool merge_symbol_into_function);
454 bool MergeSymbolContextIntoFunctionContext(const SymbolContext &symbol_sc,
455 uint32_t start_idx = 0,
456 uint32_t stop_idx = UINT32_MAX);
458 uint32_t AppendIfUnique(const SymbolContextList &sc_list,
459 bool merge_symbol_into_function);
461 //------------------------------------------------------------------
462 /// Clear the object's state.
464 /// Clears the symbol context list.
465 //------------------------------------------------------------------
468 //------------------------------------------------------------------
469 /// Dump a description of this object to a Stream.
471 /// Dump a description of the contents of each symbol context in
472 /// the list to the supplied stream \a s.
475 /// The stream to which to dump the object description.
476 //------------------------------------------------------------------
477 void Dump(Stream *s, Target *target) const;
479 //------------------------------------------------------------------
480 /// Get accessor for a symbol context at index \a idx.
482 /// Dump a description of the contents of each symbol context in
483 /// the list to the supplied stream \a s.
486 /// The zero based index into the symbol context list.
489 /// A reference to the symbol context to fill in.
492 /// Returns \b true if \a idx was a valid index into this
493 /// symbol context list and \a sc was filled in, \b false
495 //------------------------------------------------------------------
496 bool GetContextAtIndex(size_t idx, SymbolContext &sc) const;
498 //------------------------------------------------------------------
499 /// Direct reference accessor for a symbol context at index \a idx.
501 /// The index \a idx must be a valid index, no error checking will
502 /// be done to ensure that it is valid.
505 /// The zero based index into the symbol context list.
508 /// A const reference to the symbol context to fill in.
509 //------------------------------------------------------------------
510 SymbolContext &operator[](size_t idx) { return m_symbol_contexts[idx]; }
512 const SymbolContext &operator[](size_t idx) const {
513 return m_symbol_contexts[idx];
516 //------------------------------------------------------------------
517 /// Get accessor for the last symbol context in the list.
520 /// A reference to the symbol context to fill in.
523 /// Returns \b true if \a sc was filled in, \b false if the
525 //------------------------------------------------------------------
526 bool GetLastContext(SymbolContext &sc) const;
528 bool RemoveContextAtIndex(size_t idx);
530 //------------------------------------------------------------------
531 /// Get accessor for a symbol context list size.
534 /// Returns the number of symbol context objects in the list.
535 //------------------------------------------------------------------
536 uint32_t GetSize() const;
538 uint32_t NumLineEntriesWithLine(uint32_t line) const;
540 void GetDescription(Stream *s, lldb::DescriptionLevel level,
541 Target *target) const;
544 typedef std::vector<SymbolContext>
545 collection; ///< The collection type for the list.
547 //------------------------------------------------------------------
549 //------------------------------------------------------------------
550 collection m_symbol_contexts; ///< The list of symbol contexts.
553 typedef AdaptedIterable<collection, SymbolContext, vector_adapter>
554 SymbolContextIterable;
555 SymbolContextIterable SymbolContexts() {
556 return SymbolContextIterable(m_symbol_contexts);
560 bool operator==(const SymbolContext &lhs, const SymbolContext &rhs);
561 bool operator!=(const SymbolContext &lhs, const SymbolContext &rhs);
563 bool operator==(const SymbolContextList &lhs, const SymbolContextList &rhs);
564 bool operator!=(const SymbolContextList &lhs, const SymbolContextList &rhs);
566 } // namespace lldb_private
568 #endif // liblldb_SymbolContext_h_