1 //===-- StackFrame.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_StackFrame_h_
11 #define liblldb_StackFrame_h_
15 // Other libraries and framework includes
17 #include "lldb/Core/Error.h"
18 #include "lldb/Core/Flags.h"
19 #include "lldb/Core/Scalar.h"
20 #include "lldb/Core/StreamString.h"
21 #include "lldb/Core/UserID.h"
22 #include "lldb/Core/ValueObjectList.h"
23 #include "lldb/Symbol/SymbolContext.h"
24 #include "lldb/Target/ExecutionContextScope.h"
25 #include "lldb/Target/StackID.h"
27 namespace lldb_private {
29 /// @class StackFrame StackFrame.h "lldb/Target/StackFrame.h"
31 /// @brief This base class provides an interface to stack frames.
33 /// StackFrames may have a Canonical Frame Address (CFA) or not.
34 /// A frame may have a plain pc value or it may have a pc value + stop_id
35 /// to indicate a specific point in the debug session so the correct section
36 /// load list is used for symbolication.
38 /// Local variables may be available, or not. A register context may be
39 /// available, or not.
42 public ExecutionContextScope,
43 public std::enable_shared_from_this<StackFrame>
46 enum ExpressionPathOption
48 eExpressionPathOptionCheckPtrVsMember = (1u << 0),
49 eExpressionPathOptionsNoFragileObjcIvar = (1u << 1),
50 eExpressionPathOptionsNoSyntheticChildren = (1u << 2),
51 eExpressionPathOptionsNoSyntheticArrayRange = (1u << 3),
52 eExpressionPathOptionsAllowDirectIVarAccess = (1u << 4)
55 //------------------------------------------------------------------
56 /// Construct a StackFrame object without supplying a RegisterContextSP.
58 /// This is the one constructor that doesn't take a RegisterContext
59 /// parameter. This ctor may be called when creating a history StackFrame;
60 /// these are used if we've collected a stack trace of pc addresses at
61 /// some point in the past. We may only have pc values. We may have pc
62 /// values and the stop_id when the stack trace was recorded. We may have a
63 /// CFA, or more likely, we won't.
65 /// @param [in] thread_sp
66 /// The Thread that this frame belongs to.
68 /// @param [in] frame_idx
69 /// This StackFrame's frame index number in the Thread. If inlined stack
70 /// frames are being created, this may differ from the concrete_frame_idx
71 /// which is the frame index without any inlined stack frames.
73 /// @param [in] concrete_frame_idx
74 /// The StackFrame's frame index number in the Thread without any inlined
75 /// stack frames being included in the index.
78 /// The Canonical Frame Address (this terminology from DWARF) for this
79 /// stack frame. The CFA for a stack frame does not change over the
80 /// span of the stack frame's existence. It is often the value of the
81 /// caller's stack pointer before the call instruction into this frame's
82 /// function. It is usually not the same as the frame pointer register's
85 /// @param [in] cfa_is_valid
86 /// A history stack frame may not have a CFA value collected. We want to
87 /// distinguish between "no CFA available" and a CFA of
88 /// LLDB_INVALID_ADDRESS.
91 /// The current pc value of this stack frame.
93 /// @param [in] stop_id
94 /// The stop_id which should be used when looking up symbols for the pc value,
95 /// if appropriate. This argument is ignored if stop_id_is_valid is false.
97 /// @param [in] stop_id_is_valid
98 /// If the stop_id argument provided is not needed for this StackFrame, this
99 /// should be false. If this is a history stack frame and we know the stop_id
100 /// when the pc value was collected, that stop_id should be provided and this
103 /// @param [in] is_history_frame
104 /// If this is a historical stack frame -- possibly without CFA or registers or
105 /// local variables -- then this should be set to true.
107 /// @param [in] sc_ptr
108 /// Optionally seed the StackFrame with the SymbolContext information that has
109 /// already been discovered.
110 //------------------------------------------------------------------
111 StackFrame (const lldb::ThreadSP &thread_sp,
112 lldb::user_id_t frame_idx,
113 lldb::user_id_t concrete_frame_idx,
118 bool stop_id_is_valid,
119 bool is_history_frame,
120 const SymbolContext *sc_ptr);
122 StackFrame (const lldb::ThreadSP &thread_sp,
123 lldb::user_id_t frame_idx,
124 lldb::user_id_t concrete_frame_idx,
125 const lldb::RegisterContextSP ®_context_sp,
128 const SymbolContext *sc_ptr);
130 StackFrame (const lldb::ThreadSP &thread_sp,
131 lldb::user_id_t frame_idx,
132 lldb::user_id_t concrete_frame_idx,
133 const lldb::RegisterContextSP ®_context_sp,
136 const SymbolContext *sc_ptr);
138 virtual ~StackFrame ();
143 return m_thread_wp.lock();
149 //------------------------------------------------------------------
150 /// Get an Address for the current pc value in this StackFrame.
152 /// May not be the same as the actual PC value for inlined stack frames.
155 /// The Address object set to the current PC value.
156 //------------------------------------------------------------------
158 GetFrameCodeAddress();
160 //------------------------------------------------------------------
161 /// Change the pc value for a given thread.
163 /// Change the current pc value for the frame on this thread.
166 /// The load address that the pc will be set to.
169 /// true if the pc was changed. false if this failed -- possibly
170 /// because this frame is not a live StackFrame.
171 //------------------------------------------------------------------
173 ChangePC (lldb::addr_t pc);
175 //------------------------------------------------------------------
176 /// Provide a SymbolContext for this StackFrame's current pc value.
178 /// The StackFrame maintains this SymbolContext and adds additional information
179 /// to it on an as-needed basis. This helps to avoid different functions
180 /// looking up symbolic information for a given pc value multple times.
182 /// @params [in] resolve_scope
183 /// Flags from the SymbolContextItem enumerated type which specify what
184 /// type of symbol context is needed by this caller.
187 /// A SymbolContext reference which includes the types of information
188 /// requested by resolve_scope, if they are available.
189 //------------------------------------------------------------------
191 GetSymbolContext (uint32_t resolve_scope);
193 //------------------------------------------------------------------
194 /// Return the Canonical Frame Address (DWARF term) for this frame.
196 /// The CFA is typically the value of the stack pointer register before
197 /// the call invocation is made. It will not change during the lifetime
198 /// of a stack frame. It is often not the same thing as the frame pointer
201 /// Live StackFrames will always have a CFA but other types of frames may
202 /// not be able to supply one.
204 /// @param [out] value
205 /// The address of the CFA for this frame, if available.
207 /// @param [out] error_ptr
208 /// If there is an error determining the CFA address, this may contain a
209 /// string explaining the failure.
212 /// Returns true if the CFA value was successfully set in value. Some
213 /// frames may be unable to provide this value; they will return false.
214 //------------------------------------------------------------------
216 GetFrameBaseValue(Scalar &value, Error *error_ptr);
218 //------------------------------------------------------------------
219 /// Get the current lexical scope block for this StackFrame, if possible.
221 /// If debug information is available for this stack frame, return a
222 /// pointer to the innermost lexical Block that the frame is currently
226 /// A pointer to the current Block. NULL is returned if this can
228 //------------------------------------------------------------------
232 //------------------------------------------------------------------
233 /// Get the RegisterContext for this frame, if possible.
235 /// Returns a shared pointer to the RegisterContext for this stack frame.
236 /// Only a live StackFrame object will be able to return a RegisterContext -
237 /// callers must be prepared for an empty shared pointer being returned.
239 /// Even a live StackFrame RegisterContext may not be able to provide all
240 /// registers. Only the currently executing frame (frame 0) can reliably
241 /// provide every register in the register context.
244 /// The RegisterContext shared point for this frame.
245 //------------------------------------------------------------------
246 lldb::RegisterContextSP
247 GetRegisterContext ();
249 const lldb::RegisterContextSP &
250 GetRegisterContextSP () const
252 return m_reg_context_sp;
255 //------------------------------------------------------------------
256 /// Retrieve the list of variables that are in scope at this StackFrame's pc.
258 /// A frame that is not live may return an empty VariableList for a given
259 /// pc value even though variables would be available at this point if
260 /// it were a live stack frame.
262 /// @param[in] get_file_globals
263 /// Whether to also retrieve compilation-unit scoped variables
264 /// that are visisble to the entire compilation unit (e.g. file
265 /// static in C, globals that are homed in this CU).
268 /// A pointer to a list of variables.
269 //------------------------------------------------------------------
271 GetVariableList (bool get_file_globals);
273 //------------------------------------------------------------------
274 /// Retrieve the list of variables that are in scope at this StackFrame's pc.
276 /// A frame that is not live may return an empty VariableListSP for a
277 /// given pc value even though variables would be available at this point
278 /// if it were a live stack frame.
280 /// @param[in] get_file_globals
281 /// Whether to also retrieve compilation-unit scoped variables
282 /// that are visisble to the entire compilation unit (e.g. file
283 /// static in C, globals that are homed in this CU).
286 /// A pointer to a list of variables.
287 //------------------------------------------------------------------
289 GetInScopeVariableList (bool get_file_globals);
291 //------------------------------------------------------------------
292 /// Create a ValueObject for a variable name / pathname, possibly
293 /// including simple dereference/child selection syntax.
295 /// @param[in] var_expr
296 /// The string specifying a variable to base the VariableObject off
299 /// @param[in] use_dynamic
300 /// Whether the correct dynamic type of an object pointer should be
301 /// determined before creating the object, or if the static type is
302 /// sufficient. One of the DynamicValueType enumerated values.
304 /// @param[in] options
305 /// An unsigned integer of flags, values from StackFrame::ExpressionPathOption
307 /// @param[in] var_sp
308 /// A VariableSP that will be set to the variable described in the
312 /// Record any errors encountered while evaluating var_expr.
315 /// A shared pointer to the ValueObject described by var_expr.
316 //------------------------------------------------------------------
318 GetValueForVariableExpressionPath (const char *var_expr,
319 lldb::DynamicValueType use_dynamic,
321 lldb::VariableSP &var_sp,
324 //------------------------------------------------------------------
325 /// Determine whether this StackFrame has debug information available or not
328 // true if debug information is available for this frame (function,
329 // compilation unit, block, etc.)
330 //------------------------------------------------------------------
332 HasDebugInformation ();
334 //------------------------------------------------------------------
335 /// Return the disassembly for the instructions of this StackFrame's function
336 /// as a single C string.
339 // C string with the assembly instructions for this function.
340 //------------------------------------------------------------------
344 //------------------------------------------------------------------
345 /// Print a description for this frame using the frame-format formatter settings.
348 /// The Stream to print the description to.
350 /// @param [in] frame_marker
351 /// Optional string that will be prepended to the frame output description.
352 //------------------------------------------------------------------
354 DumpUsingSettingsFormat (Stream *strm, const char *frame_marker = NULL);
356 //------------------------------------------------------------------
357 /// Print a description for this frame using a default format.
360 /// The Stream to print the description to.
362 /// @param [in] show_frame_index
363 /// Whether to print the frame number or not.
365 /// @param [in] show_fullpaths
366 /// Whether to print the full source paths or just the file base name.
367 //------------------------------------------------------------------
369 Dump (Stream *strm, bool show_frame_index, bool show_fullpaths);
371 //------------------------------------------------------------------
372 /// Print a description of this stack frame and/or the source context/assembly
373 /// for this stack frame.
376 /// The Stream to send the output to.
378 /// @param[in] show_frame_info
379 /// If true, print the frame info by calling DumpUsingSettingsFormat().
381 /// @param[in] show_source
382 /// If true, print source or disassembly as per the user's settings.
384 /// @param[in] frame_marker
385 /// Passed to DumpUsingSettingsFormat() for the frame info printing.
388 /// Returns true if successful.
389 //------------------------------------------------------------------
391 GetStatus (Stream &strm,
392 bool show_frame_info,
394 const char *frame_marker = NULL);
396 //------------------------------------------------------------------
397 /// Query whether this frame is a concrete frame on the call stack,
398 /// or if it is an inlined frame derived from the debug information
399 /// and presented by the debugger.
402 /// true if this is an inlined frame.
403 //------------------------------------------------------------------
407 //------------------------------------------------------------------
408 /// Query this frame to find what frame it is in this Thread's StackFrameList.
411 /// StackFrame index 0 indicates the currently-executing function. Inline
412 /// frames are included in this frame index count.
413 //------------------------------------------------------------------
415 GetFrameIndex () const;
417 //------------------------------------------------------------------
418 /// Query this frame to find what frame it is in this Thread's StackFrameList,
419 /// not counting inlined frames.
422 /// StackFrame index 0 indicates the currently-executing function. Inline
423 /// frames are not included in this frame index count; their concrete
424 /// frame index will be the same as the concrete frame that they are
426 //------------------------------------------------------------------
428 GetConcreteFrameIndex () const
430 return m_concrete_frame_index;
433 //------------------------------------------------------------------
434 /// Create a ValueObject for a given Variable in this StackFrame.
436 /// @params [in] variable_sp
437 /// The Variable to base this ValueObject on
439 /// @params [in] use_dynamic
440 /// Whether the correct dynamic type of the variable should be
441 /// determined before creating the ValueObject, or if the static type
442 /// is sufficient. One of the DynamicValueType enumerated values.
445 // A ValueObject for this variable.
446 //------------------------------------------------------------------
448 GetValueObjectForFrameVariable (const lldb::VariableSP &variable_sp, lldb::DynamicValueType use_dynamic);
450 //------------------------------------------------------------------
451 /// Add an arbitrary Variable object (e.g. one that specifics a global or static)
452 /// to a StackFrame's list of ValueObjects.
454 /// @params [in] variable_sp
455 /// The Variable to base this ValueObject on
457 /// @params [in] use_dynamic
458 /// Whether the correct dynamic type of the variable should be
459 /// determined before creating the ValueObject, or if the static type
460 /// is sufficient. One of the DynamicValueType enumerated values.
463 // A ValueObject for this variable.
464 //------------------------------------------------------------------
466 TrackGlobalVariable (const lldb::VariableSP &variable_sp, lldb::DynamicValueType use_dynamic);
468 //------------------------------------------------------------------
469 // lldb::ExecutionContextScope pure virtual functions
470 //------------------------------------------------------------------
471 virtual lldb::TargetSP
474 virtual lldb::ProcessSP
477 virtual lldb::ThreadSP
480 virtual lldb::StackFrameSP
481 CalculateStackFrame ();
484 CalculateExecutionContext (ExecutionContext &exe_ctx);
487 friend class StackFrameList;
490 SetSymbolContextScope (SymbolContextScope *symbol_scope);
493 UpdateCurrentFrameFromPreviousFrame (StackFrame &prev_frame);
496 UpdatePreviousFrameFromCurrentFrame (StackFrame &curr_frame);
499 HasCachedData () const;
502 //------------------------------------------------------------------
503 // For StackFrame only
504 //------------------------------------------------------------------
505 lldb::ThreadWP m_thread_wp;
506 uint32_t m_frame_index;
507 uint32_t m_concrete_frame_index;
508 lldb::RegisterContextSP m_reg_context_sp;
510 Address m_frame_code_addr; // The frame code address (might not be the same as the actual PC for inlined frames) as a section/offset address
514 Error m_frame_base_error;
515 bool m_cfa_is_valid; // Does this frame have a CFA? Different from CFA == LLDB_INVALID_ADDRESS
517 bool m_stop_id_is_valid; // Does this frame have a stop_id? Use it when referring to the m_frame_code_addr.
518 bool m_is_history_frame;
519 lldb::VariableListSP m_variable_list_sp;
520 ValueObjectList m_variable_list_value_objects; // Value objects for each variable in m_variable_list_sp
521 StreamString m_disassembly;
522 DISALLOW_COPY_AND_ASSIGN (StackFrame);
525 } // namespace lldb_private
527 #endif // liblldb_StackFrame_h_