1 //===-- DWARFExpression.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_DWARFExpression_h_
11 #define liblldb_DWARFExpression_h_
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"
20 namespace lldb_private {
22 class ClangExpressionVariable;
23 class ClangExpressionVariableList;
25 class ClangExpressionDeclMap;
27 //----------------------------------------------------------------------
28 /// @class DWARFExpression DWARFExpression.h "lldb/Expression/DWARFExpression.h"
29 /// @brief Encapsulates a DWARF location expression and interprets it.
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
39 //----------------------------------------------------------------------
43 //------------------------------------------------------------------
45 //------------------------------------------------------------------
48 //------------------------------------------------------------------
52 /// A data extractor configured to read the DWARF location expression's
55 /// @param[in] data_offset
56 /// The offset of the location expression in the extractor.
58 /// @param[in] data_length
59 /// The byte length of the location expression.
60 //------------------------------------------------------------------
61 DWARFExpression(lldb::ModuleSP module,
62 const DataExtractor& data,
63 lldb::offset_t data_offset,
64 lldb::offset_t data_length);
66 //------------------------------------------------------------------
68 //------------------------------------------------------------------
69 DWARFExpression(const DWARFExpression& rhs);
71 //------------------------------------------------------------------
73 //------------------------------------------------------------------
77 //------------------------------------------------------------------
78 /// Print the description of the expression to a stream
81 /// The stream to print to.
84 /// The level of verbosity to use.
86 /// @param[in] location_list_base_addr
87 /// If this is a location list based expression, this is the
88 /// address of the object that owns it. NOTE: this value is
89 /// different from the DWARF version of the location list base
90 /// address which is compile unit relative. This base address
91 /// is the address of the object that owns the location list.
94 /// An optional ABI plug-in that can be used to resolve register
96 //------------------------------------------------------------------
98 GetDescription (Stream *s,
99 lldb::DescriptionLevel level,
100 lldb::addr_t location_list_base_addr,
103 //------------------------------------------------------------------
104 /// Return true if the location expression contains data
105 //------------------------------------------------------------------
109 //------------------------------------------------------------------
110 /// Return true if a location list was provided
111 //------------------------------------------------------------------
113 IsLocationList() const;
115 //------------------------------------------------------------------
116 /// Search for a load address in the location list
118 /// @param[in] process
119 /// The process to use when resolving the load address
122 /// The address to resolve
125 /// True if IsLocationList() is true and the address was found;
127 //------------------------------------------------------------------
129 // LocationListContainsLoadAddress (Process* process, const Address &addr) const;
132 LocationListContainsAddress (lldb::addr_t loclist_base_addr, lldb::addr_t addr) const;
134 //------------------------------------------------------------------
135 /// If a location is not a location list, return true if the location
136 /// contains a DW_OP_addr () opcode in the stream that matches \a
137 /// file_addr. If file_addr is LLDB_INVALID_ADDRESS, the this
138 /// function will return true if the variable there is any DW_OP_addr
139 /// in a location that (yet still is NOT a location list). This helps
140 /// us detect if a variable is a global or static variable since
141 /// there is no other indication from DWARF debug info.
143 /// @param[in] op_addr_idx
144 /// The DW_OP_addr index to retrieve in case there is more than
145 /// one DW_OP_addr opcode in the location byte stream.
147 /// @param[out] error
148 /// If the location stream contains unknown DW_OP opcodes or the
149 /// data is missing, \a error will be set to \b true.
152 /// LLDB_INVALID_ADDRESS if the location doesn't contain a
153 /// DW_OP_addr for \a op_addr_idx, otherwise a valid file address
154 //------------------------------------------------------------------
156 GetLocation_DW_OP_addr (uint32_t op_addr_idx, bool &error) const;
159 Update_DW_OP_addr (lldb::addr_t file_addr);
161 //------------------------------------------------------------------
162 /// Make the expression parser read its location information from a
163 /// given data source. Does not change the offset and length
166 /// A data extractor configured to read the DWARF location expression's
168 //------------------------------------------------------------------
170 SetOpcodeData(const DataExtractor& data);
172 //------------------------------------------------------------------
173 /// Make the expression parser read its location information from a
174 /// given data source
176 /// @param[in] module_sp
177 /// The module that defines the DWARF expression.
180 /// A data extractor configured to read the DWARF location expression's
183 /// @param[in] data_offset
184 /// The offset of the location expression in the extractor.
186 /// @param[in] data_length
187 /// The byte length of the location expression.
188 //------------------------------------------------------------------
190 SetOpcodeData(lldb::ModuleSP module_sp, const DataExtractor& data, lldb::offset_t data_offset, lldb::offset_t data_length);
192 //------------------------------------------------------------------
193 /// Copy the DWARF location expression into a local buffer.
195 /// It is a good idea to copy the data so we don't keep the entire
196 /// object file worth of data around just for a few bytes of location
197 /// expression. LLDB typically will mmap the entire contents of debug
198 /// information files, and if we use SetOpcodeData, it will get a
199 /// shared reference to all of this data for the and cause the object
200 /// file to have to stay around. Even worse, a very very large ".a"
201 /// that contains one or more .o files could end up being referenced.
202 /// Location lists are typically small so even though we are copying
203 /// the data, it shouldn't amount to that much for the variables we
206 /// @param[in] module_sp
207 /// The module that defines the DWARF expression.
210 /// A data extractor configured to read and copy the DWARF
211 /// location expression's bytecode.
213 /// @param[in] data_offset
214 /// The offset of the location expression in the extractor.
216 /// @param[in] data_length
217 /// The byte length of the location expression.
218 //------------------------------------------------------------------
220 CopyOpcodeData (lldb::ModuleSP module_sp,
221 const DataExtractor& data,
222 lldb::offset_t data_offset,
223 lldb::offset_t data_length);
226 CopyOpcodeData (const void *data,
227 lldb::offset_t data_length,
228 lldb::ByteOrder byte_order,
229 uint8_t addr_byte_size);
232 CopyOpcodeData (uint64_t const_value,
233 lldb::offset_t const_value_byte_size,
234 uint8_t addr_byte_size);
237 //------------------------------------------------------------------
238 /// Tells the expression that it refers to a location list.
241 /// This value should be a slide that is applied to any values
242 /// in the location list data so the values become zero based
243 /// offsets into the object that owns the location list. We need
244 /// to make location lists relative to the objects that own them
245 /// so we can relink addresses on the fly.
246 //------------------------------------------------------------------
248 SetLocationListSlide (lldb::addr_t slide);
250 //------------------------------------------------------------------
251 /// Return the call-frame-info style register kind
252 //------------------------------------------------------------------
256 //------------------------------------------------------------------
257 /// Set the call-frame-info style register kind
259 /// @param[in] reg_kind
260 /// The register kind.
261 //------------------------------------------------------------------
263 SetRegisterKind (lldb::RegisterKind reg_kind);
265 //------------------------------------------------------------------
266 /// Wrapper for the static evaluate function that accepts an
267 /// ExecutionContextScope instead of an ExecutionContext and uses
268 /// member variables to populate many operands
269 //------------------------------------------------------------------
271 Evaluate (ExecutionContextScope *exe_scope,
272 ClangExpressionVariableList *expr_locals,
273 ClangExpressionDeclMap *decl_map,
274 lldb::addr_t loclist_base_load_addr,
275 const Value* initial_value_ptr,
277 Error *error_ptr) const;
279 //------------------------------------------------------------------
280 /// Wrapper for the static evaluate function that uses member
281 /// variables to populate many operands
282 //------------------------------------------------------------------
284 Evaluate (ExecutionContext *exe_ctx,
285 ClangExpressionVariableList *expr_locals,
286 ClangExpressionDeclMap *decl_map,
287 RegisterContext *reg_ctx,
288 lldb::addr_t loclist_base_load_addr,
289 const Value* initial_value_ptr,
291 Error *error_ptr) const;
293 //------------------------------------------------------------------
294 /// Evaluate a DWARF location expression in a particular context
296 /// @param[in] exe_ctx
297 /// The execution context in which to evaluate the location
298 /// expression. The location expression may access the target's
299 /// memory, especially if it comes from the expression parser.
301 /// @param[in] opcode_ctx
302 /// The module which defined the expression.
304 /// @param[in] opcodes
305 /// This is a static method so the opcodes need to be provided
308 /// @param[in] expr_locals
309 /// If the location expression was produced by the expression parser,
310 /// the list of local variables referenced by the DWARF expression.
311 /// This list should already have been populated during parsing;
312 /// the DWARF expression refers to variables by index. Can be NULL if
313 /// the location expression uses no locals.
315 /// @param[in] decl_map
316 /// If the location expression was produced by the expression parser,
317 /// the list of external variables referenced by the location
318 /// expression. Can be NULL if the location expression uses no
319 /// external variables.
321 /// @param[in] reg_ctx
322 /// An optional parameter which provides a RegisterContext for use
323 /// when evaluating the expression (i.e. for fetching register values).
324 /// Normally this will come from the ExecutionContext's StackFrame but
325 /// in the case where an expression needs to be evaluated while building
326 /// the stack frame list, this short-cut is available.
328 /// @param[in] offset
329 /// The offset of the location expression in the data extractor.
331 /// @param[in] length
332 /// The length in bytes of the location expression.
334 /// @param[in] reg_set
335 /// The call-frame-info style register kind.
337 /// @param[in] initial_value_ptr
338 /// A value to put on top of the interpreter stack before evaluating
339 /// the expression, if the expression is parametrized. Can be NULL.
341 /// @param[in] result
342 /// A value into which the result of evaluating the expression is
345 /// @param[in] error_ptr
346 /// If non-NULL, used to report errors in expression evaluation.
349 /// True on success; false otherwise. If error_ptr is non-NULL,
350 /// details of the failure are provided through it.
351 //------------------------------------------------------------------
353 Evaluate (ExecutionContext *exe_ctx,
354 ClangExpressionVariableList *expr_locals,
355 ClangExpressionDeclMap *decl_map,
356 RegisterContext *reg_ctx,
357 lldb::ModuleSP opcode_ctx,
358 const DataExtractor& opcodes,
359 const lldb::offset_t offset,
360 const lldb::offset_t length,
361 const lldb::RegisterKind reg_set,
362 const Value* initial_value_ptr,
366 //------------------------------------------------------------------
367 /// Loads a ClangExpressionVariableList into the object
369 /// @param[in] locals
370 /// If non-NULL, the list of locals used by this expression.
372 //------------------------------------------------------------------
374 SetExpressionLocalVariableList (ClangExpressionVariableList *locals);
376 //------------------------------------------------------------------
377 /// Loads a ClangExpressionDeclMap into the object
379 /// @param[in] locals
380 /// If non-NULL, the list of external variables used by this
381 /// expression. See Evaluate().
382 //------------------------------------------------------------------
384 SetExpressionDeclMap (ClangExpressionDeclMap *decl_map);
387 GetExpressionData (DataExtractor &data) const
390 return data.GetByteSize() > 0;
394 DumpLocationForAddress (Stream *s,
395 lldb::DescriptionLevel level,
396 lldb::addr_t loclist_base_load_addr,
397 lldb::addr_t address,
401 //------------------------------------------------------------------
402 /// Pretty-prints the location expression to a stream
404 /// @param[in] stream
405 /// The stream to use for pretty-printing.
407 /// @param[in] offset
408 /// The offset into the data buffer of the opcodes to be printed.
410 /// @param[in] length
411 /// The length in bytes of the opcodes to be printed.
414 /// The level of detail to use in pretty-printing.
417 /// An optional ABI plug-in that can be used to resolve register
419 //------------------------------------------------------------------
421 DumpLocation(Stream *s,
422 lldb::offset_t offset,
423 lldb::offset_t length,
424 lldb::DescriptionLevel level,
428 GetLocation (lldb::addr_t base_addr,
430 lldb::offset_t &offset,
431 lldb::offset_t &len);
433 //------------------------------------------------------------------
434 /// Classes that inherit from DWARFExpression can see and modify these
435 //------------------------------------------------------------------
437 lldb::ModuleWP m_module_wp; ///< Module which defined this expression.
438 DataExtractor m_data; ///< A data extractor capable of reading opcode bytes
439 lldb::RegisterKind m_reg_kind; ///< One of the defines that starts with LLDB_REGKIND_
440 lldb::addr_t m_loclist_slide; ///< A value used to slide the location list offsets so that
441 ///< they are relative to the object that owns the location list
442 ///< (the function for frame base and variable location lists)
446 } // namespace lldb_private
448 #endif // liblldb_DWARFExpression_h_