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/Core/Address.h"
14 #include "lldb/Core/Disassembler.h"
15 #include "lldb/Utility/DataExtractor.h"
16 #include "lldb/Utility/Scalar.h"
17 #include "lldb/Utility/Status.h"
18 #include "lldb/lldb-private.h"
23 namespace lldb_private {
25 //----------------------------------------------------------------------
26 /// @class DWARFExpression DWARFExpression.h
27 /// "lldb/Expression/DWARFExpression.h" Encapsulates a DWARF location
28 /// expression and interprets it.
30 /// DWARF location expressions are used in two ways by LLDB. The first
31 /// use is to find entities specified in the debug information, since their
32 /// locations are specified in precisely this language. The second is to
33 /// interpret expressions without having to run the target in cases where the
34 /// overhead from copying JIT-compiled code into the target is too high or
35 /// where the target cannot be run. This class encapsulates a single DWARF
36 /// location expression or a location list and interprets it.
37 //----------------------------------------------------------------------
38 class DWARFExpression {
40 enum LocationListFormat : uint8_t {
41 NonLocationList, // Not a location list
42 RegularLocationList, // Location list format used in non-split dwarf files
43 SplitDwarfLocationList, // Location list format used in pre-DWARF v5 split
44 // dwarf files (.debug_loc.dwo)
45 LocLists, // Location list format used in DWARF v5
46 // (.debug_loclists/.debug_loclists.dwo).
49 //------------------------------------------------------------------
51 //------------------------------------------------------------------
52 explicit DWARFExpression(DWARFUnit *dwarf_cu);
54 //------------------------------------------------------------------
58 /// A data extractor configured to read the DWARF location expression's
61 /// @param[in] data_offset
62 /// The offset of the location expression in the extractor.
64 /// @param[in] data_length
65 /// The byte length of the location expression.
66 //------------------------------------------------------------------
67 DWARFExpression(lldb::ModuleSP module, const DataExtractor &data,
68 DWARFUnit *dwarf_cu, lldb::offset_t data_offset,
69 lldb::offset_t data_length);
71 //------------------------------------------------------------------
73 //------------------------------------------------------------------
74 DWARFExpression(const DWARFExpression &rhs);
76 //------------------------------------------------------------------
78 //------------------------------------------------------------------
79 virtual ~DWARFExpression();
81 //------------------------------------------------------------------
82 /// Print the description of the expression to a stream
85 /// The stream to print to.
88 /// The level of verbosity to use.
90 /// @param[in] location_list_base_addr
91 /// If this is a location list based expression, this is the
92 /// address of the object that owns it. NOTE: this value is
93 /// different from the DWARF version of the location list base
94 /// address which is compile unit relative. This base address
95 /// is the address of the object that owns the location list.
98 /// An optional ABI plug-in that can be used to resolve register
100 //------------------------------------------------------------------
101 void GetDescription(Stream *s, lldb::DescriptionLevel level,
102 lldb::addr_t location_list_base_addr, ABI *abi) const;
104 //------------------------------------------------------------------
105 /// Return true if the location expression contains data
106 //------------------------------------------------------------------
107 bool IsValid() const;
109 //------------------------------------------------------------------
110 /// Return true if a location list was provided
111 //------------------------------------------------------------------
112 bool IsLocationList() const;
114 //------------------------------------------------------------------
115 /// Search for a load address in the location list
117 /// @param[in] process
118 /// The process to use when resolving the load address
121 /// The address to resolve
124 /// True if IsLocationList() is true and the address was found;
126 //------------------------------------------------------------------
128 // LocationListContainsLoadAddress (Process* process, const Address &addr)
131 bool LocationListContainsAddress(lldb::addr_t loclist_base_addr,
132 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 file_addr.
137 /// If file_addr is LLDB_INVALID_ADDRESS, the this function will return true
138 /// if the variable there is any DW_OP_addr in a location that (yet still is
139 /// NOT a location list). This helps us detect if a variable is a global or
140 /// static variable since there is no other indication from DWARF debug
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 //------------------------------------------------------------------
155 lldb::addr_t GetLocation_DW_OP_addr(uint32_t op_addr_idx, bool &error) const;
157 bool Update_DW_OP_addr(lldb::addr_t file_addr);
159 void SetModule(const lldb::ModuleSP &module) { m_module_wp = module; }
161 bool ContainsThreadLocalStorage() const;
163 bool LinkThreadLocalStorage(
164 lldb::ModuleSP new_module_sp,
165 std::function<lldb::addr_t(lldb::addr_t file_addr)> const
166 &link_address_callback);
168 //------------------------------------------------------------------
169 /// Make the expression parser read its location information from a given
170 /// data source. Does not change the offset and length
173 /// A data extractor configured to read the DWARF location expression's
175 //------------------------------------------------------------------
176 void SetOpcodeData(const DataExtractor &data);
178 //------------------------------------------------------------------
179 /// Make the expression parser read its location information from a given
182 /// @param[in] module_sp
183 /// The module that defines the DWARF expression.
186 /// A data extractor configured to read the DWARF location expression's
189 /// @param[in] data_offset
190 /// The offset of the location expression in the extractor.
192 /// @param[in] data_length
193 /// The byte length of the location expression.
194 //------------------------------------------------------------------
195 void SetOpcodeData(lldb::ModuleSP module_sp, const DataExtractor &data,
196 lldb::offset_t data_offset, lldb::offset_t data_length);
198 //------------------------------------------------------------------
199 /// Copy the DWARF location expression into a local buffer.
201 /// It is a good idea to copy the data so we don't keep the entire object
202 /// file worth of data around just for a few bytes of location expression.
203 /// LLDB typically will mmap the entire contents of debug information files,
204 /// and if we use SetOpcodeData, it will get a shared reference to all of
205 /// this data for the and cause the object file to have to stay around. Even
206 /// worse, a very very large ".a" that contains one or more .o files could
207 /// end up being referenced. Location lists are typically small so even
208 /// though we are copying the data, it shouldn't amount to that much for the
209 /// variables we end up parsing.
211 /// @param[in] module_sp
212 /// The module that defines the DWARF expression.
215 /// A data extractor configured to read and copy the DWARF
216 /// location expression's bytecode.
218 /// @param[in] data_offset
219 /// The offset of the location expression in the extractor.
221 /// @param[in] data_length
222 /// The byte length of the location expression.
223 //------------------------------------------------------------------
224 void CopyOpcodeData(lldb::ModuleSP module_sp, const DataExtractor &data,
225 lldb::offset_t data_offset, lldb::offset_t data_length);
227 void CopyOpcodeData(const void *data, lldb::offset_t data_length,
228 lldb::ByteOrder byte_order, uint8_t addr_byte_size);
230 void CopyOpcodeData(uint64_t const_value,
231 lldb::offset_t const_value_byte_size,
232 uint8_t addr_byte_size);
234 //------------------------------------------------------------------
235 /// Tells the expression that it refers to a location list.
238 /// This value should be a slide that is applied to any values
239 /// in the location list data so the values become zero based
240 /// offsets into the object that owns the location list. We need
241 /// to make location lists relative to the objects that own them
242 /// so we can relink addresses on the fly.
243 //------------------------------------------------------------------
244 void SetLocationListSlide(lldb::addr_t slide);
246 //------------------------------------------------------------------
247 /// Return the call-frame-info style register kind
248 //------------------------------------------------------------------
249 int GetRegisterKind();
251 //------------------------------------------------------------------
252 /// Set the call-frame-info style register kind
254 /// @param[in] reg_kind
255 /// The register kind.
256 //------------------------------------------------------------------
257 void SetRegisterKind(lldb::RegisterKind reg_kind);
259 //------------------------------------------------------------------
260 /// Wrapper for the static evaluate function that accepts an
261 /// ExecutionContextScope instead of an ExecutionContext and uses member
262 /// variables to populate many operands
263 //------------------------------------------------------------------
264 bool Evaluate(ExecutionContextScope *exe_scope,
265 lldb::addr_t loclist_base_load_addr,
266 const Value *initial_value_ptr, const Value *object_address_ptr,
267 Value &result, Status *error_ptr) const;
269 //------------------------------------------------------------------
270 /// Wrapper for the static evaluate function that uses member variables to
271 /// populate many operands
272 //------------------------------------------------------------------
273 bool Evaluate(ExecutionContext *exe_ctx, RegisterContext *reg_ctx,
274 lldb::addr_t loclist_base_load_addr,
275 const Value *initial_value_ptr, const Value *object_address_ptr,
276 Value &result, Status *error_ptr) const;
278 //------------------------------------------------------------------
279 /// Evaluate a DWARF location expression in a particular context
281 /// @param[in] exe_ctx
282 /// The execution context in which to evaluate the location
283 /// expression. The location expression may access the target's
284 /// memory, especially if it comes from the expression parser.
286 /// @param[in] opcode_ctx
287 /// The module which defined the expression.
289 /// @param[in] opcodes
290 /// This is a static method so the opcodes need to be provided
293 /// @param[in] expr_locals
294 /// If the location expression was produced by the expression parser,
295 /// the list of local variables referenced by the DWARF expression.
296 /// This list should already have been populated during parsing;
297 /// the DWARF expression refers to variables by index. Can be NULL if
298 /// the location expression uses no locals.
300 /// @param[in] decl_map
301 /// If the location expression was produced by the expression parser,
302 /// the list of external variables referenced by the location
303 /// expression. Can be NULL if the location expression uses no
304 /// external variables.
306 /// @param[in] reg_ctx
307 /// An optional parameter which provides a RegisterContext for use
308 /// when evaluating the expression (i.e. for fetching register values).
309 /// Normally this will come from the ExecutionContext's StackFrame but
310 /// in the case where an expression needs to be evaluated while building
311 /// the stack frame list, this short-cut is available.
313 /// @param[in] offset
314 /// The offset of the location expression in the data extractor.
316 /// @param[in] length
317 /// The length in bytes of the location expression.
319 /// @param[in] reg_set
320 /// The call-frame-info style register kind.
322 /// @param[in] initial_value_ptr
323 /// A value to put on top of the interpreter stack before evaluating
324 /// the expression, if the expression is parametrized. Can be NULL.
326 /// @param[in] result
327 /// A value into which the result of evaluating the expression is
330 /// @param[in] error_ptr
331 /// If non-NULL, used to report errors in expression evaluation.
334 /// True on success; false otherwise. If error_ptr is non-NULL,
335 /// details of the failure are provided through it.
336 //------------------------------------------------------------------
337 static bool Evaluate(ExecutionContext *exe_ctx, RegisterContext *reg_ctx,
338 lldb::ModuleSP opcode_ctx, const DataExtractor &opcodes,
339 DWARFUnit *dwarf_cu, const lldb::offset_t offset,
340 const lldb::offset_t length,
341 const lldb::RegisterKind reg_set,
342 const Value *initial_value_ptr,
343 const Value *object_address_ptr, Value &result,
346 bool GetExpressionData(DataExtractor &data) const {
348 return data.GetByteSize() > 0;
351 bool DumpLocationForAddress(Stream *s, lldb::DescriptionLevel level,
352 lldb::addr_t loclist_base_load_addr,
353 lldb::addr_t address, ABI *abi);
355 static size_t LocationListSize(const DWARFUnit *dwarf_cu,
356 const DataExtractor &debug_loc_data,
357 lldb::offset_t offset);
359 static bool PrintDWARFExpression(Stream &s, const DataExtractor &data,
360 int address_size, int dwarf_ref_size,
361 bool location_expression);
363 static void PrintDWARFLocationList(Stream &s, const DWARFUnit *cu,
364 const DataExtractor &debug_loc_data,
365 lldb::offset_t offset);
367 bool MatchesOperand(StackFrame &frame, const Instruction::Operand &op);
370 //------------------------------------------------------------------
371 /// Pretty-prints the location expression to a stream
373 /// @param[in] stream
374 /// The stream to use for pretty-printing.
376 /// @param[in] offset
377 /// The offset into the data buffer of the opcodes to be printed.
379 /// @param[in] length
380 /// The length in bytes of the opcodes to be printed.
383 /// The level of detail to use in pretty-printing.
386 /// An optional ABI plug-in that can be used to resolve register
388 //------------------------------------------------------------------
389 void DumpLocation(Stream *s, lldb::offset_t offset, lldb::offset_t length,
390 lldb::DescriptionLevel level, ABI *abi) const;
392 bool GetLocation(lldb::addr_t base_addr, lldb::addr_t pc,
393 lldb::offset_t &offset, lldb::offset_t &len);
395 static bool AddressRangeForLocationListEntry(
396 const DWARFUnit *dwarf_cu, const DataExtractor &debug_loc_data,
397 lldb::offset_t *offset_ptr, lldb::addr_t &low_pc, lldb::addr_t &high_pc);
399 bool GetOpAndEndOffsets(StackFrame &frame, lldb::offset_t &op_offset,
400 lldb::offset_t &end_offset);
402 //------------------------------------------------------------------
403 /// Classes that inherit from DWARFExpression can see and modify these
404 //------------------------------------------------------------------
406 lldb::ModuleWP m_module_wp; ///< Module which defined this expression.
407 DataExtractor m_data; ///< A data extractor capable of reading opcode bytes
408 DWARFUnit *m_dwarf_cu; ///< The DWARF compile unit this expression
409 ///belongs to. It is used
410 ///< to evaluate values indexing into the .debug_addr section (e.g.
411 ///< DW_OP_GNU_addr_index, DW_OP_GNU_const_index)
413 m_reg_kind; ///< One of the defines that starts with LLDB_REGKIND_
414 lldb::addr_t m_loclist_slide; ///< A value used to slide the location list
416 ///< they are relative to the object that owns the location list
417 ///< (the function for frame base and variable location lists)
420 } // namespace lldb_private
422 #endif // liblldb_DWARFExpression_h_