DWARFExpression.h revision 82f0746880b4a6b18bcf8666670140f5b4a56791 
1//===-- DWARFExpression.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#ifndef liblldb_DWARFExpression_h_
11#define liblldb_DWARFExpression_h_
12
13#include "lldb/lldb-private.h"
14#include "lldb/Core/ClangForward.h"
15#include "lldb/Core/Address.h"
16#include "lldb/Core/DataExtractor.h"
17#include "lldb/Core/Error.h"
18#include "lldb/Core/Scalar.h"
19
20class ClangExpressionVariable;
21class ClangExpressionVariableList;
22
23namespace lldb_private {
24
25class ClangExpressionDeclMap;
26
27//----------------------------------------------------------------------
28/// @class DWARFExpression DWARFExpression.h "lldb/Expression/DWARFExpression.h"
29/// @brief Encapsulates a DWARF location expression and interprets it.
30///
31/// DWARF location expressions are used in two ways by LLDB.  The first
32/// use is to find entities specified in the debug information, since
33/// their locations are specified in precisely this language.  The second
34/// is to interpret expressions without having to run the target in cases
35/// where the overhead from copying JIT-compiled code into the target is
36/// too high or where the target cannot be run.  This class encapsulates
37/// a single DWARF location expression or a location list and interprets
38/// it.
39//----------------------------------------------------------------------
40class DWARFExpression
41{
42public:
43    //------------------------------------------------------------------
44    /// Constructor
45    //------------------------------------------------------------------
46    DWARFExpression();
47
48    //------------------------------------------------------------------
49    /// Constructor
50    ///
51    /// @param[in] data
52    ///     A data extractor configured to read the DWARF location expression's
53    ///     bytecode.
54    ///
55    /// @param[in] data_offset
56    ///     The offset of the location expression in the extractor.
57    ///
58    /// @param[in] data_length
59    ///     The byte length of the location expression.
60    //------------------------------------------------------------------
61    DWARFExpression(const DataExtractor& data,
62                    uint32_t data_offset,
63                    uint32_t data_length);
64
65    //------------------------------------------------------------------
66    /// Copy constructor
67    //------------------------------------------------------------------
68    DWARFExpression(const DWARFExpression& rhs);
69
70    //------------------------------------------------------------------
71    /// Destructor
72    //------------------------------------------------------------------
73    virtual
74    ~DWARFExpression();
75
76    //------------------------------------------------------------------
77    /// Print the description of the expression to a stream
78    ///
79    /// @param[in] s
80    ///     The stream to print to.
81    ///
82    /// @param[in] level
83    ///     The level of verbosity to use.
84    ///
85    /// @param[in] location_list_base_addr
86    ///     If this is a location list based expression, this is the
87    ///     address of the object that owns it. NOTE: this value is
88    ///     different from the DWARF version of the location list base
89    ///     address which is compile unit relative. This base address
90    ///     is the address of the object that owns the location list.
91    //------------------------------------------------------------------
92    void
93    GetDescription (Stream *s,
94                    lldb::DescriptionLevel level,
95                    lldb::addr_t location_list_base_addr) const;
96
97    //------------------------------------------------------------------
98    /// Return true if the location expression contains data
99    //------------------------------------------------------------------
100    bool
101    IsValid() const;
102
103    //------------------------------------------------------------------
104    /// Return true if a location list was provided
105    //------------------------------------------------------------------
106    bool
107    IsLocationList() const;
108
109    //------------------------------------------------------------------
110    /// Search for a load address in the location list
111    ///
112    /// @param[in] process
113    ///     The process to use when resolving the load address
114    ///
115    /// @param[in] addr
116    ///     The address to resolve
117    ///
118    /// @return
119    ///     True if IsLocationList() is true and the address was found;
120    ///     false otherwise.
121    //------------------------------------------------------------------
122//    bool
123//    LocationListContainsLoadAddress (Process* process, const Address &addr) const;
124//
125    bool
126    LocationListContainsAddress (lldb::addr_t loclist_base_addr, lldb::addr_t addr) const;
127
128    //------------------------------------------------------------------
129    /// Make the expression parser read its location information from a
130    /// given data source.  Does not change the offset and length
131    ///
132    /// @param[in] data
133    ///     A data extractor configured to read the DWARF location expression's
134    ///     bytecode.
135    //------------------------------------------------------------------
136    void
137    SetOpcodeData(const DataExtractor& data);
138
139    //------------------------------------------------------------------
140    /// Make the expression parser read its location information from a
141    /// given data source
142    ///
143    /// @param[in] data
144    ///     A data extractor configured to read the DWARF location expression's
145    ///     bytecode.
146    ///
147    /// @param[in] data_offset
148    ///     The offset of the location expression in the extractor.
149    ///
150    /// @param[in] data_length
151    ///     The byte length of the location expression.
152    //------------------------------------------------------------------
153    void
154    SetOpcodeData(const DataExtractor& data, uint32_t data_offset, uint32_t data_length);
155
156    //------------------------------------------------------------------
157    /// Tells the expression that it refers to a location list.
158    ///
159    /// @param[in] slide
160    ///     This value should be a slide that is applied to any values
161    ///     in the location list data so the values become zero based
162    ///     offsets into the object that owns the location list. We need
163    ///     to make location lists relative to the objects that own them
164    ///     so we can relink addresses on the fly.
165    //------------------------------------------------------------------
166    void
167    SetLocationListSlide (lldb::addr_t slide);
168
169    //------------------------------------------------------------------
170    /// Return the call-frame-info style register kind
171    //------------------------------------------------------------------
172    int
173    GetRegisterKind ();
174
175    //------------------------------------------------------------------
176    /// Set the call-frame-info style register kind
177    ///
178    /// @param[in] reg_kind
179    ///     The register kind.
180    //------------------------------------------------------------------
181    void
182    SetRegisterKind (int reg_kind);
183
184    //------------------------------------------------------------------
185    /// Wrapper for the static evaluate function that accepts an
186    /// ExecutionContextScope instead of an ExecutionContext and uses
187    /// member variables to populate many operands
188    //------------------------------------------------------------------
189    bool
190    Evaluate (ExecutionContextScope *exe_scope,
191              clang::ASTContext *ast_context,
192              ClangExpressionVariableList *expr_locals,
193              ClangExpressionDeclMap *decl_map,
194              lldb::addr_t loclist_base_load_addr,
195              const Value* initial_value_ptr,
196              Value& result,
197              Error *error_ptr) const;
198
199    //------------------------------------------------------------------
200    /// Wrapper for the static evaluate function that uses member
201    /// variables to populate many operands
202    //------------------------------------------------------------------
203    bool
204    Evaluate (ExecutionContext *exe_ctx,
205              clang::ASTContext *ast_context,
206              ClangExpressionVariableList *expr_locals,
207              ClangExpressionDeclMap *decl_map,
208              RegisterContext *reg_ctx,
209              lldb::addr_t loclist_base_load_addr,
210              const Value* initial_value_ptr,
211              Value& result,
212              Error *error_ptr) const;
213
214    //------------------------------------------------------------------
215    /// Evaluate a DWARF location expression in a particular context
216    ///
217    /// @param[in] exe_ctx
218    ///     The execution context in which to evaluate the location
219    ///     expression.  The location expression may access the target's
220    ///     memory, especially if it comes from the expression parser.
221    ///
222    /// @param[in] ast_context
223    ///     The context in which to interpret types.
224    ///
225    /// @param[in] opcodes
226    ///     This is a static method so the opcodes need to be provided
227    ///     explicitly.
228    ///
229    /// @param[in] expr_locals
230    ///     If the location expression was produced by the expression parser,
231    ///     the list of local variables referenced by the DWARF expression.
232    ///     This list should already have been populated during parsing;
233    ///     the DWARF expression refers to variables by index.  Can be NULL if
234    ///     the location expression uses no locals.
235    ///
236    /// @param[in] decl_map
237    ///     If the location expression was produced by the expression parser,
238    ///     the list of external variables referenced by the location
239    ///     expression.  Can be NULL if the location expression uses no
240    ///     external variables.
241    ///
242    ///  @param[in] reg_ctx
243    ///     An optional parameter which provides a RegisterContext for use
244    ///     when evaluating the expression (i.e. for fetching register values).
245    ///     Normally this will come from the ExecutionContext's StackFrame but
246    ///     in the case where an expression needs to be evaluated while building
247    ///     the stack frame list, this short-cut is available.
248    ///
249    /// @param[in] offset
250    ///     The offset of the location expression in the data extractor.
251    ///
252    /// @param[in] length
253    ///     The length in bytes of the location expression.
254    ///
255    /// @param[in] reg_set
256    ///     The call-frame-info style register kind.
257    ///
258    /// @param[in] initial_value_ptr
259    ///     A value to put on top of the interpreter stack before evaluating
260    ///     the expression, if the expression is parametrized.  Can be NULL.
261    ///
262    /// @param[in] result
263    ///     A value into which the result of evaluating the expression is
264    ///     to be placed.
265    ///
266    /// @param[in] error_ptr
267    ///     If non-NULL, used to report errors in expression evaluation.
268    ///
269    /// @return
270    ///     True on success; false otherwise.  If error_ptr is non-NULL,
271    ///     details of the failure are provided through it.
272    //------------------------------------------------------------------
273    static bool
274    Evaluate (ExecutionContext *exe_ctx,
275              clang::ASTContext *ast_context,
276              ClangExpressionVariableList *expr_locals,
277              ClangExpressionDeclMap *decl_map,
278              RegisterContext *reg_ctx,
279              const DataExtractor& opcodes,
280              const uint32_t offset,
281              const uint32_t length,
282              const uint32_t reg_set,
283              const Value* initial_value_ptr,
284              Value& result,
285              Error *error_ptr);
286
287    //------------------------------------------------------------------
288    /// Loads a ClangExpressionVariableList into the object
289    ///
290    /// @param[in] locals
291    ///     If non-NULL, the list of locals used by this expression.
292    ///     See Evaluate().
293    //------------------------------------------------------------------
294    void
295    SetExpressionLocalVariableList (ClangExpressionVariableList *locals);
296
297    //------------------------------------------------------------------
298    /// Loads a ClangExpressionDeclMap into the object
299    ///
300    /// @param[in] locals
301    ///     If non-NULL, the list of external variables used by this
302    ///     expression.  See Evaluate().
303    //------------------------------------------------------------------
304    void
305    SetExpressionDeclMap (ClangExpressionDeclMap *decl_map);
306
307    bool
308    GetExpressionData (DataExtractor &data) const
309    {
310        data = m_data;
311        return data.GetByteSize() > 0;
312    }
313
314protected:
315    //------------------------------------------------------------------
316    /// Pretty-prints the location expression to a stream
317    ///
318    /// @param[in] stream
319    ///     The stream to use for pretty-printing.
320    ///
321    /// @param[in] offset
322    ///     The offset into the data buffer of the opcodes to be printed.
323    ///
324    /// @param[in] length
325    ///     The length in bytes of the opcodes to be printed.
326    ///
327    /// @param[in] level
328    ///     The level of detail to use in pretty-printing.
329    //------------------------------------------------------------------
330    void
331    DumpLocation(Stream *s,
332                 uint32_t offset,
333                 uint32_t length,
334                 lldb::DescriptionLevel level) const;
335
336    //------------------------------------------------------------------
337    /// Classes that inherit from DWARFExpression can see and modify these
338    //------------------------------------------------------------------
339
340    DataExtractor m_data;                       ///< A data extractor capable of reading opcode bytes
341    int m_reg_kind;                             ///< One of the defines that starts with LLDB_REGKIND_
342    lldb::addr_t m_loclist_slide;               ///< A value used to slide the location list offsets so that
343                                                ///< they are relative to the object that owns the location list
344                                                ///< (the function for frame base and variable location lists)
345
346};
347
348} // namespace lldb_private
349
350#endif  // liblldb_DWARFExpression_h_
351