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/Utility/Flags.h"
22 #include "lldb/Core/Scalar.h"
23 #include "lldb/Core/ValueObjectList.h"
24 #include "lldb/Symbol/SymbolContext.h"
25 #include "lldb/Target/ExecutionContextScope.h"
26 #include "lldb/Target/StackID.h"
27 #include "lldb/Utility/Status.h"
28 #include "lldb/Utility/StreamString.h"
29 #include "lldb/Utility/UserID.h"
31 namespace lldb_private {
33 /// @class StackFrame StackFrame.h "lldb/Target/StackFrame.h"
35 /// @brief This base class provides an interface to stack frames.
37 /// StackFrames may have a Canonical Frame Address (CFA) or not.
38 /// A frame may have a plain pc value or it may have a pc value + stop_id
39 /// to indicate a specific point in the debug session so the correct section
40 /// load list is used for symbolication.
42 /// Local variables may be available, or not. A register context may be
43 /// available, or not.
45 class StackFrame : public ExecutionContextScope,
46 public std::enable_shared_from_this<StackFrame> {
48 enum ExpressionPathOption {
49 eExpressionPathOptionCheckPtrVsMember = (1u << 0),
50 eExpressionPathOptionsNoFragileObjcIvar = (1u << 1),
51 eExpressionPathOptionsNoSyntheticChildren = (1u << 2),
52 eExpressionPathOptionsNoSyntheticArrayRange = (1u << 3),
53 eExpressionPathOptionsAllowDirectIVarAccess = (1u << 4),
54 eExpressionPathOptionsInspectAnonymousUnions = (1u << 5)
57 //------------------------------------------------------------------
58 /// Construct a StackFrame object without supplying a RegisterContextSP.
60 /// This is the one constructor that doesn't take a RegisterContext
61 /// parameter. This ctor may be called when creating a history StackFrame;
62 /// these are used if we've collected a stack trace of pc addresses at
63 /// some point in the past. We may only have pc values. We may have pc
64 /// values and the stop_id when the stack trace was recorded. We may have a
65 /// CFA, or more likely, we won't.
67 /// @param [in] thread_sp
68 /// The Thread that this frame belongs to.
70 /// @param [in] frame_idx
71 /// This StackFrame's frame index number in the Thread. If inlined stack
72 /// frames are being created, this may differ from the concrete_frame_idx
73 /// which is the frame index without any inlined stack frames.
75 /// @param [in] concrete_frame_idx
76 /// The StackFrame's frame index number in the Thread without any inlined
77 /// stack frames being included in the index.
80 /// The Canonical Frame Address (this terminology from DWARF) for this
81 /// stack frame. The CFA for a stack frame does not change over the
82 /// span of the stack frame's existence. It is often the value of the
83 /// caller's stack pointer before the call instruction into this frame's
84 /// function. It is usually not the same as the frame pointer register's
87 /// @param [in] cfa_is_valid
88 /// A history stack frame may not have a CFA value collected. We want to
89 /// distinguish between "no CFA available" and a CFA of
90 /// LLDB_INVALID_ADDRESS.
93 /// The current pc value of this stack frame.
95 /// @param [in] stop_id
96 /// The stop_id which should be used when looking up symbols for the pc
98 /// if appropriate. This argument is ignored if stop_id_is_valid is false.
100 /// @param [in] stop_id_is_valid
101 /// If the stop_id argument provided is not needed for this StackFrame, this
102 /// should be false. If this is a history stack frame and we know the
104 /// when the pc value was collected, that stop_id should be provided and
108 /// @param [in] is_history_frame
109 /// If this is a historical stack frame -- possibly without CFA or registers
111 /// local variables -- then this should be set to true.
113 /// @param [in] sc_ptr
114 /// Optionally seed the StackFrame with the SymbolContext information that
116 /// already been discovered.
117 //------------------------------------------------------------------
118 StackFrame(const lldb::ThreadSP &thread_sp, lldb::user_id_t frame_idx,
119 lldb::user_id_t concrete_frame_idx, lldb::addr_t cfa,
120 bool cfa_is_valid, lldb::addr_t pc, uint32_t stop_id,
121 bool stop_id_is_valid, bool is_history_frame,
122 const SymbolContext *sc_ptr);
124 StackFrame(const lldb::ThreadSP &thread_sp, lldb::user_id_t frame_idx,
125 lldb::user_id_t concrete_frame_idx,
126 const lldb::RegisterContextSP ®_context_sp, lldb::addr_t cfa,
127 lldb::addr_t pc, const SymbolContext *sc_ptr);
129 StackFrame(const lldb::ThreadSP &thread_sp, lldb::user_id_t frame_idx,
130 lldb::user_id_t concrete_frame_idx,
131 const lldb::RegisterContextSP ®_context_sp, lldb::addr_t cfa,
132 const Address &pc, const SymbolContext *sc_ptr);
134 ~StackFrame() override;
136 lldb::ThreadSP GetThread() const { return m_thread_wp.lock(); }
138 StackID &GetStackID();
140 //------------------------------------------------------------------
141 /// Get an Address for the current pc value in this StackFrame.
143 /// May not be the same as the actual PC value for inlined stack frames.
146 /// The Address object set to the current PC value.
147 //------------------------------------------------------------------
148 const Address &GetFrameCodeAddress();
150 //------------------------------------------------------------------
151 /// Change the pc value for a given thread.
153 /// Change the current pc value for the frame on this thread.
156 /// The load address that the pc will be set to.
159 /// true if the pc was changed. false if this failed -- possibly
160 /// because this frame is not a live StackFrame.
161 //------------------------------------------------------------------
162 bool ChangePC(lldb::addr_t pc);
164 //------------------------------------------------------------------
165 /// Provide a SymbolContext for this StackFrame's current pc value.
167 /// The StackFrame maintains this SymbolContext and adds additional
169 /// to it on an as-needed basis. This helps to avoid different functions
170 /// looking up symbolic information for a given pc value multiple times.
172 /// @params [in] resolve_scope
173 /// Flags from the SymbolContextItem enumerated type which specify what
174 /// type of symbol context is needed by this caller.
177 /// A SymbolContext reference which includes the types of information
178 /// requested by resolve_scope, if they are available.
179 //------------------------------------------------------------------
180 const SymbolContext &GetSymbolContext(uint32_t resolve_scope);
182 //------------------------------------------------------------------
183 /// Return the Canonical Frame Address (DWARF term) for this frame.
185 /// The CFA is typically the value of the stack pointer register before
186 /// the call invocation is made. It will not change during the lifetime
187 /// of a stack frame. It is often not the same thing as the frame pointer
190 /// Live StackFrames will always have a CFA but other types of frames may
191 /// not be able to supply one.
193 /// @param [out] value
194 /// The address of the CFA for this frame, if available.
196 /// @param [out] error_ptr
197 /// If there is an error determining the CFA address, this may contain a
198 /// string explaining the failure.
201 /// Returns true if the CFA value was successfully set in value. Some
202 /// frames may be unable to provide this value; they will return false.
203 //------------------------------------------------------------------
204 bool GetFrameBaseValue(Scalar &value, Status *error_ptr);
206 //------------------------------------------------------------------
207 /// Get the DWARFExpression corresponding to the Canonical Frame Address.
209 /// Often a register (bp), but sometimes a register + offset.
211 /// @param [out] error_ptr
212 /// If there is an error determining the CFA address, this may contain a
213 /// string explaining the failure.
216 /// Returns the corresponding DWARF expression, or NULL.
217 //------------------------------------------------------------------
218 DWARFExpression *GetFrameBaseExpression(Status *error_ptr);
220 //------------------------------------------------------------------
221 /// Get the current lexical scope block for this StackFrame, if possible.
223 /// If debug information is available for this stack frame, return a
224 /// pointer to the innermost lexical Block that the frame is currently
228 /// A pointer to the current Block. nullptr is returned if this can
230 //------------------------------------------------------------------
231 Block *GetFrameBlock();
233 //------------------------------------------------------------------
234 /// Get the RegisterContext for this frame, if possible.
236 /// Returns a shared pointer to the RegisterContext for this stack frame.
237 /// Only a live StackFrame object will be able to return a RegisterContext -
238 /// callers must be prepared for an empty shared pointer being returned.
240 /// Even a live StackFrame RegisterContext may not be able to provide all
241 /// registers. Only the currently executing frame (frame 0) can reliably
242 /// provide every register in the register context.
245 /// The RegisterContext shared point for this frame.
246 //------------------------------------------------------------------
247 lldb::RegisterContextSP GetRegisterContext();
249 const lldb::RegisterContextSP &GetRegisterContextSP() const {
250 return m_reg_context_sp;
253 //------------------------------------------------------------------
254 /// Retrieve the list of variables that are in scope at this StackFrame's pc.
256 /// A frame that is not live may return an empty VariableList for a given
257 /// pc value even though variables would be available at this point if
258 /// it were a live stack frame.
260 /// @param[in] get_file_globals
261 /// Whether to also retrieve compilation-unit scoped variables
262 /// that are visible to the entire compilation unit (e.g. file
263 /// static in C, globals that are homed in this CU).
266 /// A pointer to a list of variables.
267 //------------------------------------------------------------------
268 VariableList *GetVariableList(bool get_file_globals);
270 //------------------------------------------------------------------
271 /// Retrieve the list of variables that are in scope at this StackFrame's pc.
273 /// A frame that is not live may return an empty VariableListSP for a
274 /// given pc value even though variables would be available at this point
275 /// if it were a live stack frame.
277 /// @param[in] get_file_globals
278 /// Whether to also retrieve compilation-unit scoped variables
279 /// that are visible to the entire compilation unit (e.g. file
280 /// static in C, globals that are homed in this CU).
283 /// A pointer to a list of variables.
284 //------------------------------------------------------------------
286 GetInScopeVariableList(bool get_file_globals,
287 bool must_have_valid_location = false);
289 //------------------------------------------------------------------
290 /// Create a ValueObject for a variable name / pathname, possibly
291 /// including simple dereference/child selection syntax.
293 /// @param[in] var_expr
294 /// The string specifying a variable to base the VariableObject off
297 /// @param[in] use_dynamic
298 /// Whether the correct dynamic type of an object pointer should be
299 /// determined before creating the object, or if the static type is
300 /// sufficient. One of the DynamicValueType enumerated values.
302 /// @param[in] options
303 /// An unsigned integer of flags, values from
304 /// StackFrame::ExpressionPathOption
306 /// @param[in] var_sp
307 /// A VariableSP that will be set to the variable described in the
311 /// Record any errors encountered while evaluating var_expr.
314 /// A shared pointer to the ValueObject described by var_expr.
315 //------------------------------------------------------------------
316 lldb::ValueObjectSP GetValueForVariableExpressionPath(
317 llvm::StringRef var_expr, lldb::DynamicValueType use_dynamic,
318 uint32_t options, lldb::VariableSP &var_sp, Status &error);
320 //------------------------------------------------------------------
321 /// Determine whether this StackFrame has debug information available or not
324 // true if debug information is available for this frame (function,
325 // compilation unit, block, etc.)
326 //------------------------------------------------------------------
327 bool HasDebugInformation();
329 //------------------------------------------------------------------
330 /// Return the disassembly for the instructions of this StackFrame's function
331 /// as a single C string.
334 // C string with the assembly instructions for this function.
335 //------------------------------------------------------------------
336 const char *Disassemble();
338 //------------------------------------------------------------------
339 /// Print a description for this frame using the frame-format formatter
343 /// The Stream to print the description to.
345 /// @param [in] show_unique
346 /// Whether to print the function arguments or not for backtrace unique.
348 /// @param [in] frame_marker
349 /// Optional string that will be prepended to the frame output description.
350 //------------------------------------------------------------------
351 void DumpUsingSettingsFormat(Stream *strm, bool show_unique = false,
352 const char *frame_marker = nullptr);
354 //------------------------------------------------------------------
355 /// Print a description for this frame using a default format.
358 /// The Stream to print the description to.
360 /// @param [in] show_frame_index
361 /// Whether to print the frame number or not.
363 /// @param [in] show_fullpaths
364 /// Whether to print the full source paths or just the file base name.
365 //------------------------------------------------------------------
366 void Dump(Stream *strm, bool show_frame_index, bool show_fullpaths);
368 //------------------------------------------------------------------
369 /// Print a description of this stack frame and/or the source context/assembly
370 /// for this stack frame.
373 /// The Stream to send the output to.
375 /// @param[in] show_frame_info
376 /// If true, print the frame info by calling DumpUsingSettingsFormat().
378 /// @param[in] show_source
379 /// If true, print source or disassembly as per the user's settings.
381 /// @param[in] show_unique
382 /// If true, print using backtrace unique style, without function
383 /// arguments as per the user's settings.
385 /// @param[in] frame_marker
386 /// Passed to DumpUsingSettingsFormat() for the frame info printing.
389 /// Returns true if successful.
390 //------------------------------------------------------------------
391 bool GetStatus(Stream &strm, bool show_frame_info, bool show_source,
392 bool show_unique = false, const char *frame_marker = nullptr);
394 //------------------------------------------------------------------
395 /// Query whether this frame is a concrete frame on the call stack,
396 /// or if it is an inlined frame derived from the debug information
397 /// and presented by the debugger.
400 /// true if this is an inlined frame.
401 //------------------------------------------------------------------
404 //------------------------------------------------------------------
405 /// Query this frame to find what frame it is in this Thread's StackFrameList.
408 /// StackFrame index 0 indicates the currently-executing function. Inline
409 /// frames are included in this frame index count.
410 //------------------------------------------------------------------
411 uint32_t GetFrameIndex() const;
413 //------------------------------------------------------------------
414 /// Query this frame to find what frame it is in this Thread's StackFrameList,
415 /// not counting inlined frames.
418 /// StackFrame index 0 indicates the currently-executing function. Inline
419 /// frames are not included in this frame index count; their concrete
420 /// frame index will be the same as the concrete frame that they are
422 //------------------------------------------------------------------
423 uint32_t GetConcreteFrameIndex() const { return m_concrete_frame_index; }
425 //------------------------------------------------------------------
426 /// Create a ValueObject for a given Variable in this StackFrame.
428 /// @params [in] variable_sp
429 /// The Variable to base this ValueObject on
431 /// @params [in] use_dynamic
432 /// Whether the correct dynamic type of the variable should be
433 /// determined before creating the ValueObject, or if the static type
434 /// is sufficient. One of the DynamicValueType enumerated values.
437 // A ValueObject for this variable.
438 //------------------------------------------------------------------
440 GetValueObjectForFrameVariable(const lldb::VariableSP &variable_sp,
441 lldb::DynamicValueType use_dynamic);
443 //------------------------------------------------------------------
444 /// Add an arbitrary Variable object (e.g. one that specifics a global or
446 /// to a StackFrame's list of ValueObjects.
448 /// @params [in] variable_sp
449 /// The Variable to base this ValueObject on
451 /// @params [in] use_dynamic
452 /// Whether the correct dynamic type of the variable should be
453 /// determined before creating the ValueObject, or if the static type
454 /// is sufficient. One of the DynamicValueType enumerated values.
457 // A ValueObject for this variable.
458 //------------------------------------------------------------------
459 lldb::ValueObjectSP TrackGlobalVariable(const lldb::VariableSP &variable_sp,
460 lldb::DynamicValueType use_dynamic);
462 //------------------------------------------------------------------
463 /// Query this frame to determine what the default language should be
464 /// when parsing expressions given the execution context.
467 /// The language of the frame if known, else lldb::eLanguageTypeUnknown.
468 //------------------------------------------------------------------
469 lldb::LanguageType GetLanguage();
471 // similar to GetLanguage(), but is allowed to take a potentially incorrect
473 // if exact information is not available
474 lldb::LanguageType GuessLanguage();
476 //------------------------------------------------------------------
477 /// Attempt to econstruct the ValueObject for a given raw address touched by
478 /// the current instruction. The ExpressionPath should indicate how to get
479 /// to this value using "frame variable."
481 /// @params [in] addr
485 /// The ValueObject if found. If valid, it has a valid ExpressionPath.
486 //------------------------------------------------------------------
487 lldb::ValueObjectSP GuessValueForAddress(lldb::addr_t addr);
489 //------------------------------------------------------------------
490 /// Attempt to reconstruct the ValueObject for the address contained in a
491 /// given register plus an offset. The ExpressionPath should indicate how to
492 /// get to this value using "frame variable."
495 /// The name of the register.
497 /// @params [in] offset
498 /// The offset from the register. Particularly important for sp...
501 /// The ValueObject if found. If valid, it has a valid ExpressionPath.
502 //------------------------------------------------------------------
503 lldb::ValueObjectSP GuessValueForRegisterAndOffset(ConstString reg,
506 //------------------------------------------------------------------
507 // lldb::ExecutionContextScope pure virtual functions
508 //------------------------------------------------------------------
509 lldb::TargetSP CalculateTarget() override;
511 lldb::ProcessSP CalculateProcess() override;
513 lldb::ThreadSP CalculateThread() override;
515 lldb::StackFrameSP CalculateStackFrame() override;
517 void CalculateExecutionContext(ExecutionContext &exe_ctx) override;
520 friend class StackFrameList;
522 void SetSymbolContextScope(SymbolContextScope *symbol_scope);
524 void UpdateCurrentFrameFromPreviousFrame(StackFrame &prev_frame);
526 void UpdatePreviousFrameFromCurrentFrame(StackFrame &curr_frame);
528 bool HasCachedData() const;
531 //------------------------------------------------------------------
532 // For StackFrame only
533 //------------------------------------------------------------------
534 lldb::ThreadWP m_thread_wp;
535 uint32_t m_frame_index;
536 uint32_t m_concrete_frame_index;
537 lldb::RegisterContextSP m_reg_context_sp;
539 Address m_frame_code_addr; // The frame code address (might not be the same as
540 // the actual PC for inlined frames) as a
541 // section/offset address
545 Status m_frame_base_error;
546 bool m_cfa_is_valid; // Does this frame have a CFA? Different from CFA ==
547 // LLDB_INVALID_ADDRESS
549 bool m_stop_id_is_valid; // Does this frame have a stop_id? Use it when
550 // referring to the m_frame_code_addr.
551 bool m_is_history_frame;
552 lldb::VariableListSP m_variable_list_sp;
553 ValueObjectList m_variable_list_value_objects; // Value objects for each
555 // m_variable_list_sp
556 StreamString m_disassembly;
557 std::recursive_mutex m_mutex;
559 DISALLOW_COPY_AND_ASSIGN(StackFrame);
562 } // namespace lldb_private
564 #endif // liblldb_StackFrame_h_