DWARFExpression.h revision 178710cd4307f3d44dc76ebd70fc7daf7ebe17c5 
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              lldb::addr_t loclist_base_load_addr,
193              const Value* initial_value_ptr,
194              Value& result,
195              Error *error_ptr) const;
196
197    //------------------------------------------------------------------
198    /// Wrapper for the static evaluate function that uses member
199    /// variables to populate many operands
200    //------------------------------------------------------------------
201    bool
202    Evaluate (ExecutionContext *exe_ctx,
203              clang::ASTContext *ast_context,
204              lldb::addr_t loclist_base_load_addr,
205              const Value* initial_value_ptr,
206              Value& result,
207              Error *error_ptr) const;
208
209    //------------------------------------------------------------------
210    /// Evaluate a DWARF location expression in a particular context
211    ///
212    /// @param[in] exe_ctx
213    ///     The execution context in which to evaluate the location
214    ///     expression.  The location expression may access the target's
215    ///     memory, especially if it comes from the expression parser.
216    ///
217    /// @param[in] ast_context
218    ///     The context in which to interpret types.
219    ///
220    /// @param[in] opcodes
221    ///     This is a static method so the opcodes need to be provided
222    ///     explicitly.
223    ///
224    /// @param[in] expr_locals
225    ///     If the location expression was produced by the expression parser,
226    ///     the list of local variables referenced by the DWARF expression.
227    ///     This list should already have been populated during parsing;
228    ///     the DWARF expression refers to variables by index.  Can be NULL if
229    ///     the location expression uses no locals.
230    ///
231    /// @param[in] decl_map
232    ///     If the location expression was produced by the expression parser,
233    ///     the list of external variables referenced by the location
234    ///     expression.  Can be NULL if the location expression uses no
235    ///     external variables.
236    ///
237    /// @param[in] offset
238    ///     The offset of the location expression in the data extractor.
239    ///
240    /// @param[in] length
241    ///     The length in bytes of the location expression.
242    ///
243    /// @param[in] reg_set
244    ///     The call-frame-info style register kind.
245    ///
246    /// @param[in] initial_value_ptr
247    ///     A value to put on top of the interpreter stack before evaluating
248    ///     the expression, if the expression is parametrized.  Can be NULL.
249    ///
250    /// @param[in] result
251    ///     A value into which the result of evaluating the expression is
252    ///     to be placed.
253    ///
254    /// @param[in] error_ptr
255    ///     If non-NULL, used to report errors in expression evaluation.
256    ///
257    /// @return
258    ///     True on success; false otherwise.  If error_ptr is non-NULL,
259    ///     details of the failure are provided through it.
260    //------------------------------------------------------------------
261    static bool
262    Evaluate (ExecutionContext *exe_ctx,
263              clang::ASTContext *ast_context,
264              const DataExtractor& opcodes,
265              ClangExpressionVariableList *expr_locals,
266              ClangExpressionDeclMap *decl_map,
267              const uint32_t offset,
268              const uint32_t length,
269              const uint32_t reg_set,
270              const Value* initial_value_ptr,
271              Value& result,
272              Error *error_ptr);
273
274    //------------------------------------------------------------------
275    /// Loads a ClangExpressionVariableList into the object
276    ///
277    /// @param[in] locals
278    ///     If non-NULL, the list of locals used by this expression.
279    ///     See Evaluate().
280    //------------------------------------------------------------------
281    void
282    SetExpressionLocalVariableList (ClangExpressionVariableList *locals);
283
284    //------------------------------------------------------------------
285    /// Loads a ClangExpressionDeclMap into the object
286    ///
287    /// @param[in] locals
288    ///     If non-NULL, the list of external variables used by this
289    ///     expression.  See Evaluate().
290    //------------------------------------------------------------------
291    void
292    SetExpressionDeclMap (ClangExpressionDeclMap *decl_map);
293
294protected:
295    //------------------------------------------------------------------
296    /// Pretty-prints the location expression to a stream
297    ///
298    /// @param[in] stream
299    ///     The stream to use for pretty-printing.
300    ///
301    /// @param[in] offset
302    ///     The offset into the data buffer of the opcodes to be printed.
303    ///
304    /// @param[in] length
305    ///     The length in bytes of the opcodes to be printed.
306    ///
307    /// @param[in] level
308    ///     The level of detail to use in pretty-printing.
309    //------------------------------------------------------------------
310    void
311    DumpLocation(Stream *s,
312                 uint32_t offset,
313                 uint32_t length,
314                 lldb::DescriptionLevel level) const;
315
316    //------------------------------------------------------------------
317    /// Classes that inherit from DWARFExpression can see and modify these
318    //------------------------------------------------------------------
319
320    DataExtractor m_data;                       ///< A data extractor capable of reading opcode bytes
321    int m_reg_kind;                             ///< One of the defines that starts with LLDB_REGKIND_
322    lldb::addr_t m_loclist_slide;               ///< A value used to slide the location list offsets so that
323                                                ///< they are relative to the object that owns the location list
324                                                ///< (the function for frame base and variable location lists)
325    ClangExpressionVariableList *m_expr_locals; ///< The locals used by this expression.  See Evaluate()
326    ClangExpressionDeclMap *m_decl_map;         ///< The external variables used by this expression.  See Evaluate()
327};
328
329} // namespace lldb_private
330
331#endif  // liblldb_DWARFExpression_h_
332