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_
16 #include "lldb/Utility/Flags.h"
18 #include "lldb/Core/ValueObjectList.h"
19 #include "lldb/Symbol/SymbolContext.h"
20 #include "lldb/Target/ExecutionContextScope.h"
21 #include "lldb/Target/StackID.h"
22 #include "lldb/Utility/Scalar.h"
23 #include "lldb/Utility/Status.h"
24 #include "lldb/Utility/StreamString.h"
25 #include "lldb/Utility/UserID.h"
27 namespace lldb_private {
29 /// @class StackFrame StackFrame.h "lldb/Target/StackFrame.h"
31 /// 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 indicate a specific point in
35 /// the debug session so the correct section load list is used for
38 /// Local variables may be available, or not. A register context may be
39 /// available, or not.
41 class StackFrame : public ExecutionContextScope,
42 public std::enable_shared_from_this<StackFrame> {
44 enum ExpressionPathOption {
45 eExpressionPathOptionCheckPtrVsMember = (1u << 0),
46 eExpressionPathOptionsNoFragileObjcIvar = (1u << 1),
47 eExpressionPathOptionsNoSyntheticChildren = (1u << 2),
48 eExpressionPathOptionsNoSyntheticArrayRange = (1u << 3),
49 eExpressionPathOptionsAllowDirectIVarAccess = (1u << 4),
50 eExpressionPathOptionsInspectAnonymousUnions = (1u << 5)
54 /// A regular stack frame with access to registers and local variables.
57 /// A historical stack frame -- possibly without CFA or registers or
61 /// An artificial stack frame (e.g. a synthesized result of inferring
62 /// missing tail call frames from a backtrace) with limited support for
67 //------------------------------------------------------------------
68 /// Construct a StackFrame object without supplying a RegisterContextSP.
70 /// This is the one constructor that doesn't take a RegisterContext
71 /// parameter. This ctor may be called when creating a history StackFrame;
72 /// these are used if we've collected a stack trace of pc addresses at some
73 /// point in the past. We may only have pc values. We may have a CFA,
74 /// or more likely, we won't.
76 /// @param [in] thread_sp
77 /// The Thread that this frame belongs to.
79 /// @param [in] frame_idx
80 /// This StackFrame's frame index number in the Thread. If inlined stack
81 /// frames are being created, this may differ from the concrete_frame_idx
82 /// which is the frame index without any inlined stack frames.
84 /// @param [in] concrete_frame_idx
85 /// The StackFrame's frame index number in the Thread without any inlined
86 /// stack frames being included in the index.
89 /// The Canonical Frame Address (this terminology from DWARF) for this
90 /// stack frame. The CFA for a stack frame does not change over the
91 /// span of the stack frame's existence. It is often the value of the
92 /// caller's stack pointer before the call instruction into this frame's
93 /// function. It is usually not the same as the frame pointer register's
96 /// @param [in] cfa_is_valid
97 /// A history stack frame may not have a CFA value collected. We want to
98 /// distinguish between "no CFA available" and a CFA of
99 /// LLDB_INVALID_ADDRESS.
102 /// The current pc value of this stack frame.
104 /// @param [in] frame_kind
106 /// @param [in] sc_ptr
107 /// Optionally seed the StackFrame with the SymbolContext information that
109 /// already been discovered.
110 //------------------------------------------------------------------
111 StackFrame(const lldb::ThreadSP &thread_sp, lldb::user_id_t frame_idx,
112 lldb::user_id_t concrete_frame_idx, lldb::addr_t cfa,
113 bool cfa_is_valid, lldb::addr_t pc, Kind frame_kind,
114 const SymbolContext *sc_ptr);
116 StackFrame(const lldb::ThreadSP &thread_sp, lldb::user_id_t frame_idx,
117 lldb::user_id_t concrete_frame_idx,
118 const lldb::RegisterContextSP ®_context_sp, lldb::addr_t cfa,
119 lldb::addr_t pc, const SymbolContext *sc_ptr);
121 StackFrame(const lldb::ThreadSP &thread_sp, lldb::user_id_t frame_idx,
122 lldb::user_id_t concrete_frame_idx,
123 const lldb::RegisterContextSP ®_context_sp, lldb::addr_t cfa,
124 const Address &pc, const SymbolContext *sc_ptr);
126 ~StackFrame() override;
128 lldb::ThreadSP GetThread() const { return m_thread_wp.lock(); }
130 StackID &GetStackID();
132 //------------------------------------------------------------------
133 /// Get an Address for the current pc value in this StackFrame.
135 /// May not be the same as the actual PC value for inlined stack frames.
138 /// The Address object set to the current PC value.
139 //------------------------------------------------------------------
140 const Address &GetFrameCodeAddress();
142 //------------------------------------------------------------------
143 /// Change the pc value for a given thread.
145 /// Change the current pc value for the frame on this thread.
148 /// The load address that the pc will be set to.
151 /// true if the pc was changed. false if this failed -- possibly
152 /// because this frame is not a live StackFrame.
153 //------------------------------------------------------------------
154 bool ChangePC(lldb::addr_t pc);
156 //------------------------------------------------------------------
157 /// Provide a SymbolContext for this StackFrame's current pc value.
159 /// The StackFrame maintains this SymbolContext and adds additional
160 /// information to it on an as-needed basis. This helps to avoid different
161 /// functions looking up symbolic information for a given pc value multiple
164 /// @params [in] resolve_scope
165 /// Flags from the SymbolContextItem enumerated type which specify what
166 /// type of symbol context is needed by this caller.
169 /// A SymbolContext reference which includes the types of information
170 /// requested by resolve_scope, if they are available.
171 //------------------------------------------------------------------
172 const SymbolContext &GetSymbolContext(lldb::SymbolContextItem resolve_scope);
174 //------------------------------------------------------------------
175 /// Return the Canonical Frame Address (DWARF term) for this frame.
177 /// The CFA is typically the value of the stack pointer register before the
178 /// call invocation is made. It will not change during the lifetime of a
179 /// stack frame. It is often not the same thing as the frame pointer
182 /// Live StackFrames will always have a CFA but other types of frames may
183 /// not be able to supply one.
185 /// @param [out] value
186 /// The address of the CFA for this frame, if available.
188 /// @param [out] error_ptr
189 /// If there is an error determining the CFA address, this may contain a
190 /// string explaining the failure.
193 /// Returns true if the CFA value was successfully set in value. Some
194 /// frames may be unable to provide this value; they will return false.
195 //------------------------------------------------------------------
196 bool GetFrameBaseValue(Scalar &value, Status *error_ptr);
198 //------------------------------------------------------------------
199 /// Get the DWARFExpression corresponding to the Canonical Frame Address.
201 /// Often a register (bp), but sometimes a register + offset.
203 /// @param [out] error_ptr
204 /// If there is an error determining the CFA address, this may contain a
205 /// string explaining the failure.
208 /// Returns the corresponding DWARF expression, or NULL.
209 //------------------------------------------------------------------
210 DWARFExpression *GetFrameBaseExpression(Status *error_ptr);
212 //------------------------------------------------------------------
213 /// Get the current lexical scope block for this StackFrame, if possible.
215 /// If debug information is available for this stack frame, return a pointer
216 /// to the innermost lexical Block that the frame is currently executing.
219 /// A pointer to the current Block. nullptr is returned if this can
221 //------------------------------------------------------------------
222 Block *GetFrameBlock();
224 //------------------------------------------------------------------
225 /// Get the RegisterContext for this frame, if possible.
227 /// Returns a shared pointer to the RegisterContext for this stack frame.
228 /// Only a live StackFrame object will be able to return a RegisterContext -
229 /// callers must be prepared for an empty shared pointer being returned.
231 /// Even a live StackFrame RegisterContext may not be able to provide all
232 /// registers. Only the currently executing frame (frame 0) can reliably
233 /// provide every register in the register context.
236 /// The RegisterContext shared point for this frame.
237 //------------------------------------------------------------------
238 lldb::RegisterContextSP GetRegisterContext();
240 const lldb::RegisterContextSP &GetRegisterContextSP() const {
241 return m_reg_context_sp;
244 //------------------------------------------------------------------
245 /// Retrieve the list of variables that are in scope at this StackFrame's
248 /// A frame that is not live may return an empty VariableList for a given
249 /// pc value even though variables would be available at this point if it
250 /// were a live stack frame.
252 /// @param[in] get_file_globals
253 /// Whether to also retrieve compilation-unit scoped variables
254 /// that are visible to the entire compilation unit (e.g. file
255 /// static in C, globals that are homed in this CU).
258 /// A pointer to a list of variables.
259 //------------------------------------------------------------------
260 VariableList *GetVariableList(bool get_file_globals);
262 //------------------------------------------------------------------
263 /// Retrieve the list of variables that are in scope at this StackFrame's
266 /// A frame that is not live may return an empty VariableListSP for a
267 /// given pc value even though variables would be available at this point if
268 /// it were a live stack frame.
270 /// @param[in] get_file_globals
271 /// Whether to also retrieve compilation-unit scoped variables
272 /// that are visible to the entire compilation unit (e.g. file
273 /// static in C, globals that are homed in this CU).
276 /// A pointer to a list of variables.
277 //------------------------------------------------------------------
279 GetInScopeVariableList(bool get_file_globals,
280 bool must_have_valid_location = false);
282 //------------------------------------------------------------------
283 /// Create a ValueObject for a variable name / pathname, possibly including
284 /// simple dereference/child selection syntax.
286 /// @param[in] var_expr
287 /// The string specifying a variable to base the VariableObject off
290 /// @param[in] use_dynamic
291 /// Whether the correct dynamic type of an object pointer should be
292 /// determined before creating the object, or if the static type is
293 /// sufficient. One of the DynamicValueType enumerated values.
295 /// @param[in] options
296 /// An unsigned integer of flags, values from
297 /// StackFrame::ExpressionPathOption
299 /// @param[in] var_sp
300 /// A VariableSP that will be set to the variable described in the
304 /// Record any errors encountered while evaluating var_expr.
307 /// A shared pointer to the ValueObject described by var_expr.
308 //------------------------------------------------------------------
309 lldb::ValueObjectSP GetValueForVariableExpressionPath(
310 llvm::StringRef var_expr, lldb::DynamicValueType use_dynamic,
311 uint32_t options, lldb::VariableSP &var_sp, Status &error);
313 //------------------------------------------------------------------
314 /// Determine whether this StackFrame has debug information available or not
317 // true if debug information is available for this frame (function,
318 // compilation unit, block, etc.)
319 //------------------------------------------------------------------
320 bool HasDebugInformation();
322 //------------------------------------------------------------------
323 /// Return the disassembly for the instructions of this StackFrame's
324 /// function as a single C string.
327 // C string with the assembly instructions for this function.
328 //------------------------------------------------------------------
329 const char *Disassemble();
331 //------------------------------------------------------------------
332 /// Print a description for this frame using the frame-format formatter
336 /// The Stream to print the description to.
338 /// @param [in] show_unique
339 /// Whether to print the function arguments or not for backtrace unique.
341 /// @param [in] frame_marker
342 /// Optional string that will be prepended to the frame output description.
343 //------------------------------------------------------------------
344 void DumpUsingSettingsFormat(Stream *strm, bool show_unique = false,
345 const char *frame_marker = nullptr);
347 //------------------------------------------------------------------
348 /// Print a description for this frame using a default format.
351 /// The Stream to print the description to.
353 /// @param [in] show_frame_index
354 /// Whether to print the frame number or not.
356 /// @param [in] show_fullpaths
357 /// Whether to print the full source paths or just the file base name.
358 //------------------------------------------------------------------
359 void Dump(Stream *strm, bool show_frame_index, bool show_fullpaths);
361 //------------------------------------------------------------------
362 /// Print a description of this stack frame and/or the source
363 /// context/assembly for this stack frame.
366 /// The Stream to send the output to.
368 /// @param[in] show_frame_info
369 /// If true, print the frame info by calling DumpUsingSettingsFormat().
371 /// @param[in] show_source
372 /// If true, print source or disassembly as per the user's settings.
374 /// @param[in] show_unique
375 /// If true, print using backtrace unique style, without function
376 /// arguments as per the user's settings.
378 /// @param[in] frame_marker
379 /// Passed to DumpUsingSettingsFormat() for the frame info printing.
382 /// Returns true if successful.
383 //------------------------------------------------------------------
384 bool GetStatus(Stream &strm, bool show_frame_info, bool show_source,
385 bool show_unique = false, const char *frame_marker = nullptr);
387 //------------------------------------------------------------------
388 /// Query whether this frame is a concrete frame on the call stack, or if it
389 /// is an inlined frame derived from the debug information and presented by
393 /// true if this is an inlined frame.
394 //------------------------------------------------------------------
397 //------------------------------------------------------------------
398 /// Query whether this frame is part of a historical backtrace.
399 //------------------------------------------------------------------
400 bool IsHistorical() const;
402 //------------------------------------------------------------------
403 /// Query whether this frame is artificial (e.g a synthesized result of
404 /// inferring missing tail call frames from a backtrace). Artificial frames
405 /// may have limited support for inspecting variables.
406 //------------------------------------------------------------------
407 bool IsArtificial() const;
409 //------------------------------------------------------------------
410 /// Query this frame to find what frame it is in this Thread's
414 /// StackFrame index 0 indicates the currently-executing function. Inline
415 /// frames are included in this frame index count.
416 //------------------------------------------------------------------
417 uint32_t GetFrameIndex() const;
419 //------------------------------------------------------------------
420 /// Set this frame's synthetic frame index.
421 //------------------------------------------------------------------
422 void SetFrameIndex(uint32_t index) { m_frame_index = index; }
424 //------------------------------------------------------------------
425 /// Query this frame to find what frame it is in this Thread's
426 /// StackFrameList, not counting inlined frames.
429 /// StackFrame index 0 indicates the currently-executing function. Inline
430 /// frames are not included in this frame index count; their concrete
431 /// frame index will be the same as the concrete frame that they are
433 //------------------------------------------------------------------
434 uint32_t GetConcreteFrameIndex() const { return m_concrete_frame_index; }
436 //------------------------------------------------------------------
437 /// Create a ValueObject for a given Variable in this StackFrame.
439 /// @params [in] variable_sp
440 /// The Variable to base this ValueObject on
442 /// @params [in] use_dynamic
443 /// Whether the correct dynamic type of the variable should be
444 /// determined before creating the ValueObject, or if the static type
445 /// is sufficient. One of the DynamicValueType enumerated values.
448 // A ValueObject for this variable.
449 //------------------------------------------------------------------
451 GetValueObjectForFrameVariable(const lldb::VariableSP &variable_sp,
452 lldb::DynamicValueType use_dynamic);
454 //------------------------------------------------------------------
455 /// Add an arbitrary Variable object (e.g. one that specifics a global or
456 /// static) to a StackFrame's list of ValueObjects.
458 /// @params [in] variable_sp
459 /// The Variable to base this ValueObject on
461 /// @params [in] use_dynamic
462 /// Whether the correct dynamic type of the variable should be
463 /// determined before creating the ValueObject, or if the static type
464 /// is sufficient. One of the DynamicValueType enumerated values.
467 // A ValueObject for this variable.
468 //------------------------------------------------------------------
469 lldb::ValueObjectSP TrackGlobalVariable(const lldb::VariableSP &variable_sp,
470 lldb::DynamicValueType use_dynamic);
472 //------------------------------------------------------------------
473 /// Query this frame to determine what the default language should be when
474 /// parsing expressions given the execution context.
477 /// The language of the frame if known, else lldb::eLanguageTypeUnknown.
478 //------------------------------------------------------------------
479 lldb::LanguageType GetLanguage();
481 // similar to GetLanguage(), but is allowed to take a potentially incorrect
482 // guess if exact information is not available
483 lldb::LanguageType GuessLanguage();
485 //------------------------------------------------------------------
486 /// Attempt to econstruct the ValueObject for a given raw address touched by
487 /// the current instruction. The ExpressionPath should indicate how to get
488 /// to this value using "frame variable."
490 /// @params [in] addr
494 /// The ValueObject if found. If valid, it has a valid ExpressionPath.
495 //------------------------------------------------------------------
496 lldb::ValueObjectSP GuessValueForAddress(lldb::addr_t addr);
498 //------------------------------------------------------------------
499 /// Attempt to reconstruct the ValueObject for the address contained in a
500 /// given register plus an offset. The ExpressionPath should indicate how
501 /// to get to this value using "frame variable."
504 /// The name of the register.
506 /// @params [in] offset
507 /// The offset from the register. Particularly important for sp...
510 /// The ValueObject if found. If valid, it has a valid ExpressionPath.
511 //------------------------------------------------------------------
512 lldb::ValueObjectSP GuessValueForRegisterAndOffset(ConstString reg,
515 //------------------------------------------------------------------
516 /// Attempt to reconstruct the ValueObject for a variable with a given \a name
517 /// from within the current StackFrame, within the current block. The search
518 /// for the variable starts in the deepest block corresponding to the current
519 /// PC in the stack frame and traverse through all parent blocks stopping at
520 /// inlined function boundaries.
522 /// @params [in] name
523 /// The name of the variable.
526 /// The ValueObject if found.
527 //------------------------------------------------------------------
528 lldb::ValueObjectSP FindVariable(ConstString name);
530 //------------------------------------------------------------------
531 // lldb::ExecutionContextScope pure virtual functions
532 //------------------------------------------------------------------
533 lldb::TargetSP CalculateTarget() override;
535 lldb::ProcessSP CalculateProcess() override;
537 lldb::ThreadSP CalculateThread() override;
539 lldb::StackFrameSP CalculateStackFrame() override;
541 void CalculateExecutionContext(ExecutionContext &exe_ctx) override;
543 lldb::RecognizedStackFrameSP GetRecognizedFrame();
546 friend class StackFrameList;
548 void SetSymbolContextScope(SymbolContextScope *symbol_scope);
550 void UpdateCurrentFrameFromPreviousFrame(StackFrame &prev_frame);
552 void UpdatePreviousFrameFromCurrentFrame(StackFrame &curr_frame);
554 bool HasCachedData() const;
557 //------------------------------------------------------------------
558 // For StackFrame only
559 //------------------------------------------------------------------
560 lldb::ThreadWP m_thread_wp;
561 uint32_t m_frame_index;
562 uint32_t m_concrete_frame_index;
563 lldb::RegisterContextSP m_reg_context_sp;
565 Address m_frame_code_addr; // The frame code address (might not be the same as
566 // the actual PC for inlined frames) as a
567 // section/offset address
571 Status m_frame_base_error;
572 bool m_cfa_is_valid; // Does this frame have a CFA? Different from CFA ==
573 // LLDB_INVALID_ADDRESS
574 Kind m_stack_frame_kind;
575 lldb::VariableListSP m_variable_list_sp;
576 ValueObjectList m_variable_list_value_objects; // Value objects for each
578 // m_variable_list_sp
579 lldb::RecognizedStackFrameSP m_recognized_frame_sp;
580 StreamString m_disassembly;
581 std::recursive_mutex m_mutex;
583 DISALLOW_COPY_AND_ASSIGN(StackFrame);
586 } // namespace lldb_private
588 #endif // liblldb_StackFrame_h_