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