SymbolContext.h revision eea264007bc5fb42c8f3239726a9d28ae42e1b7b 
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/Symbol/LineEntry.h"
19
20namespace lldb_private {
21
22class SymbolContextScope;
23//----------------------------------------------------------------------
24/// @class SymbolContext SymbolContext.h "lldb/Symbol/SymbolContext.h"
25/// @brief Defines a symbol context baton that can be handed other debug
26/// core functions.
27///
28/// Many debugger functions require a context when doing lookups. This
29/// class provides a common structure that can be used as the result
30/// of a query that can contain a single result. Examples of such
31/// queries include
32///     @li Looking up a load address.
33//----------------------------------------------------------------------
34class SymbolContext
35{
36public:
37
38    //------------------------------------------------------------------
39    /// Default constructor.
40    ///
41    /// Initialize all pointer members to NULL and all struct members
42    /// to their default state.
43    //------------------------------------------------------------------
44    SymbolContext ();
45
46    //------------------------------------------------------------------
47    /// Construct with an object that knows how to reconstruct its
48    /// symbol context.
49    ///
50    /// @param[in] sc_scope
51    ///     A symbol context scope object that knows how to reconstruct
52    ///     it's context.
53    //------------------------------------------------------------------
54    explicit
55    SymbolContext (SymbolContextScope *sc_scope);
56
57    //------------------------------------------------------------------
58    /// Construct with module, and optional compile unit, function,
59    /// block, line table, line entry and symbol.
60    ///
61    /// Initialize all pointer to the specified values.
62    ///
63    /// @param[in] module
64    ///     A Module pointer to the module for this context.
65    ///
66    /// @param[in] comp_unit
67    ///     A CompileUnit pointer to the compile unit for this context.
68    ///
69    /// @param[in] function
70    ///     A Function pointer to the function for this context.
71    ///
72    /// @param[in] block
73    ///     A Block pointer to the deepest block for this context.
74    ///
75    /// @param[in] line_entry
76    ///     A LineEntry pointer to the line entry for this context.
77    ///
78    /// @param[in] symbol
79    ///     A Symbol pointer to the symbol for this context.
80    //------------------------------------------------------------------
81    explicit
82    SymbolContext (const lldb::TargetSP &target_sp,
83                   const lldb::ModuleSP &module_sp,
84                   CompileUnit *comp_unit = NULL,
85                   Function *function = NULL,
86                   Block *block = NULL,
87                   LineEntry *line_entry = NULL,
88                   Symbol *symbol = NULL);
89
90    // This version sets the target to a NULL TargetSP if you don't know it.
91    explicit
92    SymbolContext (const lldb::ModuleSP &module_sp,
93                   CompileUnit *comp_unit = NULL,
94                   Function *function = NULL,
95                   Block *block = NULL,
96                   LineEntry *line_entry = NULL,
97                   Symbol *symbol = NULL);
98
99    //------------------------------------------------------------------
100    /// Copy constructor
101    ///
102    /// Makes a copy of the another SymbolContext object \a rhs.
103    ///
104    /// @param[in] rhs
105    ///     A const SymbolContext object reference to copy.
106    //------------------------------------------------------------------
107    SymbolContext (const SymbolContext& rhs);
108
109    //------------------------------------------------------------------
110    /// Assignment operator.
111    ///
112    /// Copies the address value from another SymbolContext object \a
113    /// rhs into \a this object.
114    ///
115    /// @param[in] rhs
116    ///     A const SymbolContext object reference to copy.
117    ///
118    /// @return
119    ///     A const SymbolContext object reference to \a this.
120    //------------------------------------------------------------------
121    const SymbolContext&
122    operator= (const SymbolContext& rhs);
123
124    //------------------------------------------------------------------
125    /// Clear the object's state.
126    ///
127    /// Resets all pointer members to NULL, and clears any class objects
128    /// to their default state.
129    //------------------------------------------------------------------
130    void
131    Clear ();
132
133    //------------------------------------------------------------------
134    /// Dump a description of this object to a Stream.
135    ///
136    /// Dump a description of the contents of this object to the
137    /// supplied stream \a s.
138    ///
139    /// @param[in] s
140    ///     The stream to which to dump the object descripton.
141    //------------------------------------------------------------------
142    void
143    Dump (Stream *s, Target *target) const;
144
145    //------------------------------------------------------------------
146    /// Dump the stop context in this object to a Stream.
147    ///
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 ouput. Else just the address at which the target
154    /// was stopped will be displayed.
155    ///
156    /// @param[in] s
157    ///     The stream to which to dump the object descripton.
158    ///
159    /// @param[in] so_addr
160    ///     The resolved section offset address.
161    //------------------------------------------------------------------
162    void
163    DumpStopContext (Stream *s,
164                     ExecutionContextScope *exe_scope,
165                     const Address &so_addr,
166                     bool show_fullpaths,
167                     bool show_module,
168                     bool show_inlined_frames) const;
169
170    //------------------------------------------------------------------
171    /// Get the address range contained within a symbol context.
172    ///
173    /// Address range priority is as follows:
174    ///     - line_entry address range if line_entry is valid
175    ///     - function address range if function is not NULL
176    ///     - symbol address range if symbol is not NULL
177    ///
178    /// @param[out] range
179    ///     An address range object that will be filled in if \b true
180    ///     is returned.
181    ///
182    /// @return
183    ///     \b True if this symbol context contains items that describe
184    ///     an address range, \b false otherwise.
185    //------------------------------------------------------------------
186    bool
187    GetAddressRange (uint32_t scope, AddressRange &range) const;
188
189
190    void
191    GetDescription(Stream *s,
192                   lldb::DescriptionLevel level,
193                   Target *target) const;
194
195    uint32_t
196    GetResolvedMask () const;
197
198
199    //------------------------------------------------------------------
200    /// Find a function matching the given name, working out from this
201    /// symbol context.
202    ///
203    /// @return
204    ///     The number of symbol contexts found.
205    //------------------------------------------------------------------
206    size_t
207    FindFunctionsByName (const ConstString &name,
208                         bool append,
209                         SymbolContextList &sc_list) const;
210
211    //------------------------------------------------------------------
212    /// Find a variable matching the given name, working out from this
213    /// symbol context.
214    ///
215    /// @return
216    ///     A shared pointer to the variable found.
217    //------------------------------------------------------------------
218    lldb::VariableSP
219    FindVariableByName (const char *name) const;
220
221    //------------------------------------------------------------------
222    /// Find a type matching the given name, working out from this
223    /// symbol context.
224    ///
225    /// @return
226    ///     A shared pointer to the variable found.
227    //------------------------------------------------------------------
228    lldb::TypeSP
229    FindTypeByName (const ConstString &name) const;
230
231    //------------------------------------------------------------------
232    // Member variables
233    //------------------------------------------------------------------
234    lldb::TargetSP  target_sp;  ///< The Target for a given query
235    lldb::ModuleSP  module_sp;  ///< The Module for a given query
236    CompileUnit *   comp_unit;  ///< The CompileUnit for a given query
237    Function *      function;   ///< The Function for a given query
238    Block *         block;      ///< The Block for a given query
239    LineEntry       line_entry; ///< The LineEntry for a given query
240    Symbol *        symbol;     ///< The Symbol for a given query
241};
242
243//----------------------------------------------------------------------
244/// @class SymbolContextList SymbolContext.h "lldb/Symbol/SymbolContext.h"
245/// @brief Defines a list of symbol context objects.
246///
247/// This class provides a common structure that can be used to contain
248/// the result of a query that can contain a multiple results. Examples
249/// of such queries include:
250///     @li Looking up a function by name.
251///     @li Finding all addressses for a specified file and line number.
252//----------------------------------------------------------------------
253class SymbolContextList
254{
255public:
256    //------------------------------------------------------------------
257    /// Default constructor.
258    ///
259    /// Initialize with an empty list.
260    //------------------------------------------------------------------
261    SymbolContextList ();
262
263    //------------------------------------------------------------------
264    /// Destructor.
265    //------------------------------------------------------------------
266    ~SymbolContextList ();
267
268    //------------------------------------------------------------------
269    /// Append a new symbol context to the list.
270    ///
271    /// @param[in] sc
272    ///     A symbol context to append to the list.
273    //------------------------------------------------------------------
274    void
275    Append(const SymbolContext& sc);
276
277    //------------------------------------------------------------------
278    /// Clear the object's state.
279    ///
280    /// Clears the symbol context list.
281    //------------------------------------------------------------------
282    void
283    Clear();
284
285    //------------------------------------------------------------------
286    /// Dump a description of this object to a Stream.
287    ///
288    /// Dump a description of the contents of each symbol context in
289    /// the list to the supplied stream \a s.
290    ///
291    /// @param[in] s
292    ///     The stream to which to dump the object descripton.
293    //------------------------------------------------------------------
294    void
295    Dump(Stream *s, Target *target) const;
296
297    //------------------------------------------------------------------
298    /// Get accessor for a symbol context at index \a idx.
299    ///
300    /// Dump a description of the contents of each symbol context in
301    /// the list to the supplied stream \a s.
302    ///
303    /// @param[in] idx
304    ///     The zero based index into the symbol context list.
305    ///
306    /// @param[out] sc
307    ///     A reference to the symbol context to fill in.
308    ///
309    /// @return
310    ///     Returns \b true if \a idx was a valid index into this
311    ///     symbol context list and \a sc was filled in, \b false
312    ///     otherwise.
313    //------------------------------------------------------------------
314    bool
315    GetContextAtIndex(uint32_t idx, SymbolContext& sc) const;
316
317    bool
318    RemoveContextAtIndex (uint32_t idx);
319    //------------------------------------------------------------------
320    /// Get accessor for a symbol context list size.
321    ///
322    /// @return
323    ///     Returns the number of symbol context objects in the list.
324    //------------------------------------------------------------------
325    uint32_t
326    GetSize() const;
327
328protected:
329    typedef std::vector<SymbolContext> collection; ///< The collection type for the list.
330
331    //------------------------------------------------------------------
332    // Member variables.
333    //------------------------------------------------------------------
334    collection m_symbol_contexts; ///< The list of symbol contexts.
335};
336
337bool operator== (const SymbolContext& lhs, const SymbolContext& rhs);
338bool operator!= (const SymbolContext& lhs, const SymbolContext& rhs);
339
340} // namespace lldb_private
341
342#endif  // liblldb_SymbolContext_h_
343