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 //------------------------------------------------------------------
240 /// Find the best global data symbol visible from this context.
242 /// Symbol priority is:
243 /// - extern symbol in the current module if there is one
244 /// - non-extern symbol in the current module if there is one
245 /// - extern symbol in the target
246 /// - non-extern symbol in the target
247 /// It is an error if the highest-priority result is ambiguous.
250 /// The name of the symbol to search for.
252 /// @param[out] error
253 /// An error that will be populated with a message if there was an
254 /// ambiguous result. The error will not be populated if no result
258 /// The symbol that was found, or \b nullptr if none was found.
259 //------------------------------------------------------------------
260 const Symbol *FindBestGlobalDataSymbol(const ConstString &name, Status &error);
262 void GetDescription(Stream *s, lldb::DescriptionLevel level,
263 Target *target) const;
265 uint32_t GetResolvedMask() const;
267 lldb::LanguageType GetLanguage() const;
269 //------------------------------------------------------------------
270 /// Find a block that defines the function represented by this
273 /// If this symbol context points to a block that is an inlined
274 /// function, or is contained within an inlined function, the block
275 /// that defines the inlined function is returned.
277 /// If this symbol context has no block in it, or the block is not
278 /// itself an inlined function block or contained within one, we
279 /// return the top level function block.
281 /// This is a handy function to call when you want to get the block
282 /// whose variable list will include the arguments for the function
283 /// that is represented by this symbol context (whether the function
284 /// is an inline function or not).
287 /// The block object pointer that defines the function that is
288 /// represented by this symbol context object, nullptr otherwise.
289 //------------------------------------------------------------------
290 Block *GetFunctionBlock();
292 //------------------------------------------------------------------
293 /// If this symbol context represents a function that is a method,
294 /// return true and provide information about the method.
296 /// @param[out] language
297 /// If \b true is returned, the language for the method.
299 /// @param[out] is_instance_method
300 /// If \b true is returned, \b true if this is a instance method,
301 /// \b false if this is a static/class function.
303 /// @param[out] language_object_name
304 /// If \b true is returned, the name of the artificial variable
305 /// for the language ("this" for C++, "self" for ObjC).
308 /// \b True if this symbol context represents a function that
309 /// is a method of a class, \b false otherwise.
310 //------------------------------------------------------------------
311 bool GetFunctionMethodInfo(lldb::LanguageType &language,
312 bool &is_instance_method,
313 ConstString &language_object_name);
315 //------------------------------------------------------------------
316 /// Sorts the types in TypeMap according to SymbolContext
319 //------------------------------------------------------------------
320 void SortTypeList(TypeMap &type_map, TypeList &type_list) const;
322 //------------------------------------------------------------------
323 /// Find a name of the innermost function for the symbol context.
325 /// For instance, if the symbol context contains an inlined block,
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 ConstString GetFunctionName(
337 Mangled::NamePreference preference = Mangled::ePreferDemangled) const;
339 //------------------------------------------------------------------
340 /// Get the line entry that corresponds to the function.
342 /// If the symbol context contains an inlined block, the line entry
343 /// for the start address of the inlined function will be returned,
344 /// otherwise the line entry for the start address of the function
345 /// will be returned. This can be used after doing a
346 /// Module::FindFunctions(...) or ModuleList::FindFunctions(...)
347 /// call in order to get the correct line table information for
348 /// the symbol context.
349 /// it will return the inlined function name.
351 /// @param[in] prefer_mangled
352 /// if \btrue, then the mangled name will be returned if there
353 /// is one. Otherwise the unmangled name will be returned if it
357 /// The name of the function represented by this symbol context.
358 //------------------------------------------------------------------
359 LineEntry GetFunctionStartLineEntry() const;
361 //------------------------------------------------------------------
362 /// Find the block containing the inlined block that contains this block.
364 /// For instance, if the symbol context contains an inlined block,
365 /// it will return the inlined function name.
367 /// @param[in] curr_frame_pc
368 /// The address within the block of this object.
370 /// @param[out] next_frame_sc
371 /// A new symbol context that does what the title says it does.
373 /// @param[out] next_frame_addr
374 /// This is what you should report as the PC in \a next_frame_sc.
377 /// \b true if this SymbolContext specifies a block contained in an
378 /// inlined block. If this returns \b true, \a next_frame_sc and
379 /// \a next_frame_addr will be filled in correctly.
380 //------------------------------------------------------------------
381 bool GetParentOfInlinedScope(const Address &curr_frame_pc,
382 SymbolContext &next_frame_sc,
383 Address &inlined_frame_addr) const;
385 //------------------------------------------------------------------
387 //------------------------------------------------------------------
388 lldb::TargetSP target_sp; ///< The Target for a given query
389 lldb::ModuleSP module_sp; ///< The Module for a given query
390 CompileUnit *comp_unit; ///< The CompileUnit for a given query
391 Function *function; ///< The Function for a given query
392 Block *block; ///< The Block for a given query
393 LineEntry line_entry; ///< The LineEntry for a given query
394 Symbol *symbol; ///< The Symbol for a given query
395 Variable *variable; ///< The global variable matching the given query
398 class SymbolContextSpecifier {
400 typedef enum SpecificationType {
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
411 // This one produces a specifier that matches everything...
412 SymbolContextSpecifier(const lldb::TargetSP &target_sp);
414 ~SymbolContextSpecifier();
416 bool AddSpecification(const char *spec_string, SpecificationType type);
418 bool AddLineSpecification(uint32_t line_no, SpecificationType type);
422 bool SymbolContextMatches(SymbolContext &sc);
424 bool AddressMatches(lldb::addr_t addr);
426 void GetDescription(Stream *s, lldb::DescriptionLevel level) const;
429 lldb::TargetSP m_target_sp;
430 std::string m_module_spec;
431 lldb::ModuleSP m_module_sp;
432 std::unique_ptr<FileSpec> m_file_spec_ap;
435 std::string m_function_spec;
436 std::string m_class_name;
437 std::unique_ptr<AddressRange> m_address_range_ap;
438 uint32_t m_type; // Or'ed bits from SpecificationType
441 //----------------------------------------------------------------------
442 /// @class SymbolContextList SymbolContext.h "lldb/Symbol/SymbolContext.h"
443 /// @brief Defines a list of symbol context objects.
445 /// This class provides a common structure that can be used to contain
446 /// the result of a query that can contain a multiple results. Examples
447 /// of such queries include:
448 /// @li Looking up a function by name.
449 /// @li Finding all addresses for a specified file and line number.
450 //----------------------------------------------------------------------
451 class SymbolContextList {
453 //------------------------------------------------------------------
454 /// Default constructor.
456 /// Initialize with an empty list.
457 //------------------------------------------------------------------
460 //------------------------------------------------------------------
462 //------------------------------------------------------------------
463 ~SymbolContextList();
465 //------------------------------------------------------------------
466 /// Append a new symbol context to the list.
469 /// A symbol context to append to the list.
470 //------------------------------------------------------------------
471 void Append(const SymbolContext &sc);
473 void Append(const SymbolContextList &sc_list);
475 bool AppendIfUnique(const SymbolContext &sc, bool merge_symbol_into_function);
477 bool MergeSymbolContextIntoFunctionContext(const SymbolContext &symbol_sc,
478 uint32_t start_idx = 0,
479 uint32_t stop_idx = UINT32_MAX);
481 uint32_t AppendIfUnique(const SymbolContextList &sc_list,
482 bool merge_symbol_into_function);
484 //------------------------------------------------------------------
485 /// Clear the object's state.
487 /// Clears the symbol context list.
488 //------------------------------------------------------------------
491 //------------------------------------------------------------------
492 /// Dump a description of this object to a Stream.
494 /// Dump a description of the contents of each symbol context in
495 /// the list to the supplied stream \a s.
498 /// The stream to which to dump the object description.
499 //------------------------------------------------------------------
500 void Dump(Stream *s, Target *target) const;
502 //------------------------------------------------------------------
503 /// Get accessor for a symbol context at index \a idx.
505 /// Dump a description of the contents of each symbol context in
506 /// the list to the supplied stream \a s.
509 /// The zero based index into the symbol context list.
512 /// A reference to the symbol context to fill in.
515 /// Returns \b true if \a idx was a valid index into this
516 /// symbol context list and \a sc was filled in, \b false
518 //------------------------------------------------------------------
519 bool GetContextAtIndex(size_t idx, SymbolContext &sc) const;
521 //------------------------------------------------------------------
522 /// Direct reference accessor for a symbol context at index \a idx.
524 /// The index \a idx must be a valid index, no error checking will
525 /// be done to ensure that it is valid.
528 /// The zero based index into the symbol context list.
531 /// A const reference to the symbol context to fill in.
532 //------------------------------------------------------------------
533 SymbolContext &operator[](size_t idx) { return m_symbol_contexts[idx]; }
535 const SymbolContext &operator[](size_t idx) const {
536 return m_symbol_contexts[idx];
539 //------------------------------------------------------------------
540 /// Get accessor for the last symbol context in the list.
543 /// A reference to the symbol context to fill in.
546 /// Returns \b true if \a sc was filled in, \b false if the
548 //------------------------------------------------------------------
549 bool GetLastContext(SymbolContext &sc) const;
551 bool RemoveContextAtIndex(size_t idx);
553 //------------------------------------------------------------------
554 /// Get accessor for a symbol context list size.
557 /// Returns the number of symbol context objects in the list.
558 //------------------------------------------------------------------
559 uint32_t GetSize() const;
561 uint32_t NumLineEntriesWithLine(uint32_t line) const;
563 void GetDescription(Stream *s, lldb::DescriptionLevel level,
564 Target *target) const;
567 typedef std::vector<SymbolContext>
568 collection; ///< The collection type for the list.
570 //------------------------------------------------------------------
572 //------------------------------------------------------------------
573 collection m_symbol_contexts; ///< The list of symbol contexts.
576 typedef AdaptedIterable<collection, SymbolContext, vector_adapter>
577 SymbolContextIterable;
578 SymbolContextIterable SymbolContexts() {
579 return SymbolContextIterable(m_symbol_contexts);
583 bool operator==(const SymbolContext &lhs, const SymbolContext &rhs);
584 bool operator!=(const SymbolContext &lhs, const SymbolContext &rhs);
586 bool operator==(const SymbolContextList &lhs, const SymbolContextList &rhs);
587 bool operator!=(const SymbolContextList &lhs, const SymbolContextList &rhs);
589 } // namespace lldb_private
591 #endif // liblldb_SymbolContext_h_