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 /// 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 some
63 /// point in the past. We may only have pc values. We may have pc values
64 /// and the stop_id when the stack trace was recorded. We may have a CFA,
65 /// 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
168 /// information to it on an as-needed basis. This helps to avoid different
169 /// functions looking up symbolic information for a given pc value multiple
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 the
186 /// call invocation is made. It will not change during the lifetime of a
187 /// 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 pointer
224 /// to the innermost lexical Block that the frame is currently executing.
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
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 it
258 /// 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
274 /// A frame that is not live may return an empty VariableListSP for a
275 /// given pc value even though variables would be available at this point if
276 /// it were a live stack frame.
278 /// @param[in] get_file_globals
279 /// Whether to also retrieve compilation-unit scoped variables
280 /// that are visible to the entire compilation unit (e.g. file
281 /// static in C, globals that are homed in this CU).
284 /// A pointer to a list of variables.
285 //------------------------------------------------------------------
287 GetInScopeVariableList(bool get_file_globals,
288 bool must_have_valid_location = false);
290 //------------------------------------------------------------------
291 /// Create a ValueObject for a variable name / pathname, possibly including
292 /// simple dereference/child selection syntax.
294 /// @param[in] var_expr
295 /// The string specifying a variable to base the VariableObject off
298 /// @param[in] use_dynamic
299 /// Whether the correct dynamic type of an object pointer should be
300 /// determined before creating the object, or if the static type is
301 /// sufficient. One of the DynamicValueType enumerated values.
303 /// @param[in] options
304 /// An unsigned integer of flags, values from
305 /// 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 //------------------------------------------------------------------
317 lldb::ValueObjectSP GetValueForVariableExpressionPath(
318 llvm::StringRef var_expr, lldb::DynamicValueType use_dynamic,
319 uint32_t options, lldb::VariableSP &var_sp, Status &error);
321 //------------------------------------------------------------------
322 /// Determine whether this StackFrame has debug information available or not
325 // true if debug information is available for this frame (function,
326 // compilation unit, block, etc.)
327 //------------------------------------------------------------------
328 bool HasDebugInformation();
330 //------------------------------------------------------------------
331 /// Return the disassembly for the instructions of this StackFrame's
332 /// function as a single C string.
335 // C string with the assembly instructions for this function.
336 //------------------------------------------------------------------
337 const char *Disassemble();
339 //------------------------------------------------------------------
340 /// Print a description for this frame using the frame-format formatter
344 /// The Stream to print the description to.
346 /// @param [in] show_unique
347 /// Whether to print the function arguments or not for backtrace unique.
349 /// @param [in] frame_marker
350 /// Optional string that will be prepended to the frame output description.
351 //------------------------------------------------------------------
352 void DumpUsingSettingsFormat(Stream *strm, bool show_unique = false,
353 const char *frame_marker = nullptr);
355 //------------------------------------------------------------------
356 /// Print a description for this frame using a default format.
359 /// The Stream to print the description to.
361 /// @param [in] show_frame_index
362 /// Whether to print the frame number or not.
364 /// @param [in] show_fullpaths
365 /// Whether to print the full source paths or just the file base name.
366 //------------------------------------------------------------------
367 void Dump(Stream *strm, bool show_frame_index, bool show_fullpaths);
369 //------------------------------------------------------------------
370 /// Print a description of this stack frame and/or the source
371 /// context/assembly for this stack frame.
374 /// The Stream to send the output to.
376 /// @param[in] show_frame_info
377 /// If true, print the frame info by calling DumpUsingSettingsFormat().
379 /// @param[in] show_source
380 /// If true, print source or disassembly as per the user's settings.
382 /// @param[in] show_unique
383 /// If true, print using backtrace unique style, without function
384 /// arguments as per the user's settings.
386 /// @param[in] frame_marker
387 /// Passed to DumpUsingSettingsFormat() for the frame info printing.
390 /// Returns true if successful.
391 //------------------------------------------------------------------
392 bool GetStatus(Stream &strm, bool show_frame_info, bool show_source,
393 bool show_unique = false, const char *frame_marker = nullptr);
395 //------------------------------------------------------------------
396 /// Query whether this frame is a concrete frame on the call stack, or if it
397 /// is an inlined frame derived from the debug information and presented by
401 /// true if this is an inlined frame.
402 //------------------------------------------------------------------
405 //------------------------------------------------------------------
406 /// Query this frame to find what frame it is in this Thread's
410 /// StackFrame index 0 indicates the currently-executing function. Inline
411 /// frames are included in this frame index count.
412 //------------------------------------------------------------------
413 uint32_t GetFrameIndex() const;
415 //------------------------------------------------------------------
416 /// Query this frame to find what frame it is in this Thread's
417 /// StackFrameList, not counting inlined frames.
420 /// StackFrame index 0 indicates the currently-executing function. Inline
421 /// frames are not included in this frame index count; their concrete
422 /// frame index will be the same as the concrete frame that they are
424 //------------------------------------------------------------------
425 uint32_t GetConcreteFrameIndex() const { return m_concrete_frame_index; }
427 //------------------------------------------------------------------
428 /// Create a ValueObject for a given Variable in this StackFrame.
430 /// @params [in] variable_sp
431 /// The Variable to base this ValueObject on
433 /// @params [in] use_dynamic
434 /// Whether the correct dynamic type of the variable should be
435 /// determined before creating the ValueObject, or if the static type
436 /// is sufficient. One of the DynamicValueType enumerated values.
439 // A ValueObject for this variable.
440 //------------------------------------------------------------------
442 GetValueObjectForFrameVariable(const lldb::VariableSP &variable_sp,
443 lldb::DynamicValueType use_dynamic);
445 //------------------------------------------------------------------
446 /// Add an arbitrary Variable object (e.g. one that specifics a global or
447 /// static) to a StackFrame's list of ValueObjects.
449 /// @params [in] variable_sp
450 /// The Variable to base this ValueObject on
452 /// @params [in] use_dynamic
453 /// Whether the correct dynamic type of the variable should be
454 /// determined before creating the ValueObject, or if the static type
455 /// is sufficient. One of the DynamicValueType enumerated values.
458 // A ValueObject for this variable.
459 //------------------------------------------------------------------
460 lldb::ValueObjectSP TrackGlobalVariable(const lldb::VariableSP &variable_sp,
461 lldb::DynamicValueType use_dynamic);
463 //------------------------------------------------------------------
464 /// Query this frame to determine what the default language should be when
465 /// parsing expressions given the execution context.
468 /// The language of the frame if known, else lldb::eLanguageTypeUnknown.
469 //------------------------------------------------------------------
470 lldb::LanguageType GetLanguage();
472 // similar to GetLanguage(), but is allowed to take a potentially incorrect
473 // guess 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
492 /// to 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_