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_
18 // Other libraries and framework includes
20 #include "lldb/Core/Error.h"
21 #include "lldb/Core/Flags.h"
22 #include "lldb/Core/Scalar.h"
23 #include "lldb/Core/StreamString.h"
24 #include "lldb/Core/UserID.h"
25 #include "lldb/Core/ValueObjectList.h"
26 #include "lldb/Symbol/SymbolContext.h"
27 #include "lldb/Target/ExecutionContextScope.h"
28 #include "lldb/Target/StackID.h"
30 namespace lldb_private {
32 /// @class StackFrame StackFrame.h "lldb/Target/StackFrame.h"
34 /// @brief This base class provides an interface to stack frames.
36 /// StackFrames may have a Canonical Frame Address (CFA) or not.
37 /// A frame may have a plain pc value or it may have a pc value + stop_id
38 /// to indicate a specific point in the debug session so the correct section
39 /// load list is used for symbolication.
41 /// Local variables may be available, or not. A register context may be
42 /// available, or not.
44 class StackFrame : public ExecutionContextScope,
45 public std::enable_shared_from_this<StackFrame> {
47 enum ExpressionPathOption {
48 eExpressionPathOptionCheckPtrVsMember = (1u << 0),
49 eExpressionPathOptionsNoFragileObjcIvar = (1u << 1),
50 eExpressionPathOptionsNoSyntheticChildren = (1u << 2),
51 eExpressionPathOptionsNoSyntheticArrayRange = (1u << 3),
52 eExpressionPathOptionsAllowDirectIVarAccess = (1u << 4),
53 eExpressionPathOptionsInspectAnonymousUnions = (1u << 5)
56 //------------------------------------------------------------------
57 /// Construct a StackFrame object without supplying a RegisterContextSP.
59 /// This is the one constructor that doesn't take a RegisterContext
60 /// parameter. This ctor may be called when creating a history StackFrame;
61 /// these are used if we've collected a stack trace of pc addresses at
62 /// some point in the past. We may only have pc values. We may have pc
63 /// values and the stop_id when the stack trace was recorded. We may have a
64 /// CFA, or more likely, we won't.
66 /// @param [in] thread_sp
67 /// The Thread that this frame belongs to.
69 /// @param [in] frame_idx
70 /// This StackFrame's frame index number in the Thread. If inlined stack
71 /// frames are being created, this may differ from the concrete_frame_idx
72 /// which is the frame index without any inlined stack frames.
74 /// @param [in] concrete_frame_idx
75 /// The StackFrame's frame index number in the Thread without any inlined
76 /// stack frames being included in the index.
79 /// The Canonical Frame Address (this terminology from DWARF) for this
80 /// stack frame. The CFA for a stack frame does not change over the
81 /// span of the stack frame's existence. It is often the value of the
82 /// caller's stack pointer before the call instruction into this frame's
83 /// function. It is usually not the same as the frame pointer register's
86 /// @param [in] cfa_is_valid
87 /// A history stack frame may not have a CFA value collected. We want to
88 /// distinguish between "no CFA available" and a CFA of
89 /// LLDB_INVALID_ADDRESS.
92 /// The current pc value of this stack frame.
94 /// @param [in] stop_id
95 /// The stop_id which should be used when looking up symbols for the pc
97 /// if appropriate. This argument is ignored if stop_id_is_valid is false.
99 /// @param [in] stop_id_is_valid
100 /// If the stop_id argument provided is not needed for this StackFrame, this
101 /// should be false. If this is a history stack frame and we know the
103 /// when the pc value was collected, that stop_id should be provided and
107 /// @param [in] is_history_frame
108 /// If this is a historical stack frame -- possibly without CFA or registers
110 /// local variables -- then this should be set to true.
112 /// @param [in] sc_ptr
113 /// Optionally seed the StackFrame with the SymbolContext information that
115 /// already been discovered.
116 //------------------------------------------------------------------
117 StackFrame(const lldb::ThreadSP &thread_sp, lldb::user_id_t frame_idx,
118 lldb::user_id_t concrete_frame_idx, lldb::addr_t cfa,
119 bool cfa_is_valid, lldb::addr_t pc, uint32_t stop_id,
120 bool stop_id_is_valid, bool is_history_frame,
121 const SymbolContext *sc_ptr);
123 StackFrame(const lldb::ThreadSP &thread_sp, lldb::user_id_t frame_idx,
124 lldb::user_id_t concrete_frame_idx,
125 const lldb::RegisterContextSP ®_context_sp, lldb::addr_t cfa,
126 lldb::addr_t pc, const SymbolContext *sc_ptr);
128 StackFrame(const lldb::ThreadSP &thread_sp, lldb::user_id_t frame_idx,
129 lldb::user_id_t concrete_frame_idx,
130 const lldb::RegisterContextSP ®_context_sp, lldb::addr_t cfa,
131 const Address &pc, const SymbolContext *sc_ptr);
133 ~StackFrame() override;
135 lldb::ThreadSP GetThread() const { return m_thread_wp.lock(); }
137 StackID &GetStackID();
139 //------------------------------------------------------------------
140 /// Get an Address for the current pc value in this StackFrame.
142 /// May not be the same as the actual PC value for inlined stack frames.
145 /// The Address object set to the current PC value.
146 //------------------------------------------------------------------
147 const Address &GetFrameCodeAddress();
149 //------------------------------------------------------------------
150 /// Change the pc value for a given thread.
152 /// Change the current pc value for the frame on this thread.
155 /// The load address that the pc will be set to.
158 /// true if the pc was changed. false if this failed -- possibly
159 /// because this frame is not a live StackFrame.
160 //------------------------------------------------------------------
161 bool ChangePC(lldb::addr_t pc);
163 //------------------------------------------------------------------
164 /// Provide a SymbolContext for this StackFrame's current pc value.
166 /// The StackFrame maintains this SymbolContext and adds additional
168 /// to it on an as-needed basis. This helps to avoid different functions
169 /// looking up symbolic information for a given pc value multiple times.
171 /// @params [in] resolve_scope
172 /// Flags from the SymbolContextItem enumerated type which specify what
173 /// type of symbol context is needed by this caller.
176 /// A SymbolContext reference which includes the types of information
177 /// requested by resolve_scope, if they are available.
178 //------------------------------------------------------------------
179 const SymbolContext &GetSymbolContext(uint32_t resolve_scope);
181 //------------------------------------------------------------------
182 /// Return the Canonical Frame Address (DWARF term) for this frame.
184 /// The CFA is typically the value of the stack pointer register before
185 /// the call invocation is made. It will not change during the lifetime
186 /// of a stack frame. It is often not the same thing as the frame pointer
189 /// Live StackFrames will always have a CFA but other types of frames may
190 /// not be able to supply one.
192 /// @param [out] value
193 /// The address of the CFA for this frame, if available.
195 /// @param [out] error_ptr
196 /// If there is an error determining the CFA address, this may contain a
197 /// string explaining the failure.
200 /// Returns true if the CFA value was successfully set in value. Some
201 /// frames may be unable to provide this value; they will return false.
202 //------------------------------------------------------------------
203 bool GetFrameBaseValue(Scalar &value, Error *error_ptr);
205 //------------------------------------------------------------------
206 /// Get the DWARFExpression corresponding to the Canonical Frame Address.
208 /// Often a register (bp), but sometimes a register + offset.
210 /// @param [out] error_ptr
211 /// If there is an error determining the CFA address, this may contain a
212 /// string explaining the failure.
215 /// Returns the corresponding DWARF expression, or NULL.
216 //------------------------------------------------------------------
217 DWARFExpression *GetFrameBaseExpression(Error *error_ptr);
219 //------------------------------------------------------------------
220 /// Get the current lexical scope block for this StackFrame, if possible.
222 /// If debug information is available for this stack frame, return a
223 /// pointer to the innermost lexical Block that the frame is currently
227 /// A pointer to the current Block. nullptr is returned if this can
229 //------------------------------------------------------------------
230 Block *GetFrameBlock();
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 GetRegisterContext();
248 const lldb::RegisterContextSP &GetRegisterContextSP() const {
249 return m_reg_context_sp;
252 //------------------------------------------------------------------
253 /// Retrieve the list of variables that are in scope at this StackFrame's pc.
255 /// A frame that is not live may return an empty VariableList for a given
256 /// pc value even though variables would be available at this point if
257 /// it were a live stack frame.
259 /// @param[in] get_file_globals
260 /// Whether to also retrieve compilation-unit scoped variables
261 /// that are visible to the entire compilation unit (e.g. file
262 /// static in C, globals that are homed in this CU).
265 /// A pointer to a list of variables.
266 //------------------------------------------------------------------
267 VariableList *GetVariableList(bool get_file_globals);
269 //------------------------------------------------------------------
270 /// Retrieve the list of variables that are in scope at this StackFrame's pc.
272 /// A frame that is not live may return an empty VariableListSP for a
273 /// given pc value even though variables would be available at this point
274 /// if it were a live stack frame.
276 /// @param[in] get_file_globals
277 /// Whether to also retrieve compilation-unit scoped variables
278 /// that are visible to the entire compilation unit (e.g. file
279 /// static in C, globals that are homed in this CU).
282 /// A pointer to a list of variables.
283 //------------------------------------------------------------------
285 GetInScopeVariableList(bool get_file_globals,
286 bool must_have_valid_location = false);
288 //------------------------------------------------------------------
289 /// Create a ValueObject for a variable name / pathname, possibly
290 /// including simple dereference/child selection syntax.
292 /// @param[in] var_expr
293 /// The string specifying a variable to base the VariableObject off
296 /// @param[in] use_dynamic
297 /// Whether the correct dynamic type of an object pointer should be
298 /// determined before creating the object, or if the static type is
299 /// sufficient. One of the DynamicValueType enumerated values.
301 /// @param[in] options
302 /// An unsigned integer of flags, values from
303 /// StackFrame::ExpressionPathOption
305 /// @param[in] var_sp
306 /// A VariableSP that will be set to the variable described in the
310 /// Record any errors encountered while evaluating var_expr.
313 /// A shared pointer to the ValueObject described by var_expr.
314 //------------------------------------------------------------------
315 lldb::ValueObjectSP GetValueForVariableExpressionPath(
316 llvm::StringRef var_expr, lldb::DynamicValueType use_dynamic,
317 uint32_t options, lldb::VariableSP &var_sp, Error &error);
319 //------------------------------------------------------------------
320 /// Determine whether this StackFrame has debug information available or not
323 // true if debug information is available for this frame (function,
324 // compilation unit, block, etc.)
325 //------------------------------------------------------------------
326 bool HasDebugInformation();
328 //------------------------------------------------------------------
329 /// Return the disassembly for the instructions of this StackFrame's function
330 /// as a single C string.
333 // C string with the assembly instructions for this function.
334 //------------------------------------------------------------------
335 const char *Disassemble();
337 //------------------------------------------------------------------
338 /// Print a description for this frame using the frame-format formatter
342 /// The Stream to print the description to.
344 /// @param [in] frame_marker
345 /// Optional string that will be prepended to the frame output description.
346 //------------------------------------------------------------------
347 void DumpUsingSettingsFormat(Stream *strm,
348 const char *frame_marker = nullptr);
350 //------------------------------------------------------------------
351 /// Print a description for this frame using a default format.
354 /// The Stream to print the description to.
356 /// @param [in] show_frame_index
357 /// Whether to print the frame number or not.
359 /// @param [in] show_fullpaths
360 /// Whether to print the full source paths or just the file base name.
361 //------------------------------------------------------------------
362 void Dump(Stream *strm, bool show_frame_index, bool show_fullpaths);
364 //------------------------------------------------------------------
365 /// Print a description of this stack frame and/or the source context/assembly
366 /// for this stack frame.
369 /// The Stream to send the output to.
371 /// @param[in] show_frame_info
372 /// If true, print the frame info by calling DumpUsingSettingsFormat().
374 /// @param[in] show_source
375 /// If true, print source or disassembly as per the user's settings.
377 /// @param[in] frame_marker
378 /// Passed to DumpUsingSettingsFormat() for the frame info printing.
381 /// Returns true if successful.
382 //------------------------------------------------------------------
383 bool GetStatus(Stream &strm, bool show_frame_info, bool show_source,
384 const char *frame_marker = nullptr);
386 //------------------------------------------------------------------
387 /// Query whether this frame is a concrete frame on the call stack,
388 /// or if it is an inlined frame derived from the debug information
389 /// and presented by the debugger.
392 /// true if this is an inlined frame.
393 //------------------------------------------------------------------
396 //------------------------------------------------------------------
397 /// Query this frame to find what frame it is in this Thread's StackFrameList.
400 /// StackFrame index 0 indicates the currently-executing function. Inline
401 /// frames are included in this frame index count.
402 //------------------------------------------------------------------
403 uint32_t GetFrameIndex() const;
405 //------------------------------------------------------------------
406 /// Query this frame to find what frame it is in this Thread's StackFrameList,
407 /// not counting inlined frames.
410 /// StackFrame index 0 indicates the currently-executing function. Inline
411 /// frames are not included in this frame index count; their concrete
412 /// frame index will be the same as the concrete frame that they are
414 //------------------------------------------------------------------
415 uint32_t GetConcreteFrameIndex() const { return m_concrete_frame_index; }
417 //------------------------------------------------------------------
418 /// Create a ValueObject for a given Variable in this StackFrame.
420 /// @params [in] variable_sp
421 /// The Variable to base this ValueObject on
423 /// @params [in] use_dynamic
424 /// Whether the correct dynamic type of the variable should be
425 /// determined before creating the ValueObject, or if the static type
426 /// is sufficient. One of the DynamicValueType enumerated values.
429 // A ValueObject for this variable.
430 //------------------------------------------------------------------
432 GetValueObjectForFrameVariable(const lldb::VariableSP &variable_sp,
433 lldb::DynamicValueType use_dynamic);
435 //------------------------------------------------------------------
436 /// Add an arbitrary Variable object (e.g. one that specifics a global or
438 /// to a StackFrame's list of ValueObjects.
440 /// @params [in] variable_sp
441 /// The Variable to base this ValueObject on
443 /// @params [in] use_dynamic
444 /// Whether the correct dynamic type of the variable should be
445 /// determined before creating the ValueObject, or if the static type
446 /// is sufficient. One of the DynamicValueType enumerated values.
449 // A ValueObject for this variable.
450 //------------------------------------------------------------------
451 lldb::ValueObjectSP TrackGlobalVariable(const lldb::VariableSP &variable_sp,
452 lldb::DynamicValueType use_dynamic);
454 //------------------------------------------------------------------
455 /// Query this frame to determine what the default language should be
456 /// when parsing expressions given the execution context.
459 /// The language of the frame if known, else lldb::eLanguageTypeUnknown.
460 //------------------------------------------------------------------
461 lldb::LanguageType GetLanguage();
463 // similar to GetLanguage(), but is allowed to take a potentially incorrect
465 // if exact information is not available
466 lldb::LanguageType GuessLanguage();
468 //------------------------------------------------------------------
469 /// Attempt to econstruct the ValueObject for a given raw address touched by
470 /// the current instruction. The ExpressionPath should indicate how to get
471 /// to this value using "frame variable."
473 /// @params [in] addr
477 /// The ValueObject if found. If valid, it has a valid ExpressionPath.
478 //------------------------------------------------------------------
479 lldb::ValueObjectSP GuessValueForAddress(lldb::addr_t addr);
481 //------------------------------------------------------------------
482 /// Attempt to reconstruct the ValueObject for the address contained in a
483 /// given register plus an offset. The ExpressionPath should indicate how to
484 /// get to this value using "frame variable."
487 /// The name of the register.
489 /// @params [in] offset
490 /// The offset from the register. Particularly important for sp...
493 /// The ValueObject if found. If valid, it has a valid ExpressionPath.
494 //------------------------------------------------------------------
495 lldb::ValueObjectSP GuessValueForRegisterAndOffset(ConstString reg,
498 //------------------------------------------------------------------
499 // lldb::ExecutionContextScope pure virtual functions
500 //------------------------------------------------------------------
501 lldb::TargetSP CalculateTarget() override;
503 lldb::ProcessSP CalculateProcess() override;
505 lldb::ThreadSP CalculateThread() override;
507 lldb::StackFrameSP CalculateStackFrame() override;
509 void CalculateExecutionContext(ExecutionContext &exe_ctx) override;
512 friend class StackFrameList;
514 void SetSymbolContextScope(SymbolContextScope *symbol_scope);
516 void UpdateCurrentFrameFromPreviousFrame(StackFrame &prev_frame);
518 void UpdatePreviousFrameFromCurrentFrame(StackFrame &curr_frame);
520 bool HasCachedData() const;
523 //------------------------------------------------------------------
524 // For StackFrame only
525 //------------------------------------------------------------------
526 lldb::ThreadWP m_thread_wp;
527 uint32_t m_frame_index;
528 uint32_t m_concrete_frame_index;
529 lldb::RegisterContextSP m_reg_context_sp;
531 Address m_frame_code_addr; // The frame code address (might not be the same as
532 // the actual PC for inlined frames) as a
533 // section/offset address
537 Error m_frame_base_error;
538 bool m_cfa_is_valid; // Does this frame have a CFA? Different from CFA ==
539 // LLDB_INVALID_ADDRESS
541 bool m_stop_id_is_valid; // Does this frame have a stop_id? Use it when
542 // referring to the m_frame_code_addr.
543 bool m_is_history_frame;
544 lldb::VariableListSP m_variable_list_sp;
545 ValueObjectList m_variable_list_value_objects; // Value objects for each
547 // m_variable_list_sp
548 StreamString m_disassembly;
549 std::recursive_mutex m_mutex;
551 DISALLOW_COPY_AND_ASSIGN(StackFrame);
554 } // namespace lldb_private
556 #endif // liblldb_StackFrame_h_