1//===-- StackFrame.h --------------------------------------------*- C++ -*-===//
2//
3// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4// See https://llvm.org/LICENSE.txt for license information.
5// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
6//
7//===----------------------------------------------------------------------===//
8
9#ifndef LLDB_TARGET_STACKFRAME_H
10#define LLDB_TARGET_STACKFRAME_H
11
12#include <memory>
13#include <mutex>
14
15#include "lldb/Utility/Flags.h"
16
17#include "lldb/Core/ValueObjectList.h"
18#include "lldb/Symbol/SymbolContext.h"
19#include "lldb/Target/ExecutionContextScope.h"
20#include "lldb/Target/StackID.h"
21#include "lldb/Utility/Scalar.h"
22#include "lldb/Utility/Status.h"
23#include "lldb/Utility/StreamString.h"
24#include "lldb/Utility/UserID.h"
25
26namespace lldb_private {
27
28/// \class StackFrame StackFrame.h "lldb/Target/StackFrame.h"
29///
30/// This base class provides an interface to stack frames.
31///
32/// StackFrames may have a Canonical Frame Address (CFA) or not.
33/// A frame may have a plain pc value or it may indicate a specific point in
34/// the debug session so the correct section load list is used for
35/// symbolication.
36///
37/// Local variables may be available, or not. A register context may be
38/// available, or not.
39
40class StackFrame : public ExecutionContextScope,
41 public std::enable_shared_from_this<StackFrame> {
42public:
43 enum ExpressionPathOption {
44 eExpressionPathOptionCheckPtrVsMember = (1u << 0),
45 eExpressionPathOptionsNoFragileObjcIvar = (1u << 1),
46 eExpressionPathOptionsNoSyntheticChildren = (1u << 2),
47 eExpressionPathOptionsNoSyntheticArrayRange = (1u << 3),
48 eExpressionPathOptionsAllowDirectIVarAccess = (1u << 4),
49 eExpressionPathOptionsInspectAnonymousUnions = (1u << 5)
50 };
51
52 enum class Kind {
53 /// A regular stack frame with access to registers and local variables.
54 Regular,
55
56 /// A historical stack frame -- possibly without CFA or registers or
57 /// local variables.
58 History,
59
60 /// An artificial stack frame (e.g. a synthesized result of inferring
61 /// missing tail call frames from a backtrace) with limited support for
62 /// local variables.
63 Artificial
64 };
65
66 /// Construct a StackFrame object without supplying a RegisterContextSP.
67 ///
68 /// This is the one constructor that doesn't take a RegisterContext
69 /// parameter. This ctor may be called when creating a history StackFrame;
70 /// these are used if we've collected a stack trace of pc addresses at some
71 /// point in the past. We may only have pc values. We may have a CFA,
72 /// or more likely, we won't.
73 ///
74 /// \param [in] thread_sp
75 /// The Thread that this frame belongs to.
76 ///
77 /// \param [in] frame_idx
78 /// This StackFrame's frame index number in the Thread. If inlined stack
79 /// frames are being created, this may differ from the concrete_frame_idx
80 /// which is the frame index without any inlined stack frames.
81 ///
82 /// \param [in] concrete_frame_idx
83 /// The StackFrame's frame index number in the Thread without any inlined
84 /// stack frames being included in the index.
85 ///
86 /// \param [in] cfa
87 /// The Canonical Frame Address (this terminology from DWARF) for this
88 /// stack frame. The CFA for a stack frame does not change over the
89 /// span of the stack frame's existence. It is often the value of the
90 /// caller's stack pointer before the call instruction into this frame's
91 /// function. It is usually not the same as the frame pointer register's
92 /// value.
93 ///
94 /// \param [in] cfa_is_valid
95 /// A history stack frame may not have a CFA value collected. We want to
96 /// distinguish between "no CFA available" and a CFA of
97 /// LLDB_INVALID_ADDRESS.
98 ///
99 /// \param [in] pc
100 /// The current pc value of this stack frame.
101 ///
102 /// \param [in] sc_ptr
103 /// Optionally seed the StackFrame with the SymbolContext information that
104 /// has
105 /// already been discovered.
106 StackFrame(const lldb::ThreadSP &thread_sp, lldb::user_id_t frame_idx,
107 lldb::user_id_t concrete_frame_idx, lldb::addr_t cfa,
108 bool cfa_is_valid, lldb::addr_t pc, Kind frame_kind,
109 bool behaves_like_zeroth_frame, const SymbolContext *sc_ptr);
110
111 StackFrame(const lldb::ThreadSP &thread_sp, lldb::user_id_t frame_idx,
112 lldb::user_id_t concrete_frame_idx,
113 const lldb::RegisterContextSP &reg_context_sp, lldb::addr_t cfa,
114 lldb::addr_t pc, bool behaves_like_zeroth_frame,
115 const SymbolContext *sc_ptr);
116
117 StackFrame(const lldb::ThreadSP &thread_sp, lldb::user_id_t frame_idx,
118 lldb::user_id_t concrete_frame_idx,
119 const lldb::RegisterContextSP &reg_context_sp, lldb::addr_t cfa,
120 const Address &pc, bool behaves_like_zeroth_frame,
121 const SymbolContext *sc_ptr);
122
123 ~StackFrame() override;
124
125 lldb::ThreadSP GetThread() const { return m_thread_wp.lock(); }
126
127 StackID &GetStackID();
128
129 /// Get an Address for the current pc value in this StackFrame.
130 ///
131 /// May not be the same as the actual PC value for inlined stack frames.
132 ///
133 /// \return
134 /// The Address object set to the current PC value.
135 const Address &GetFrameCodeAddress();
136
137 /// Get the current code Address suitable for symbolication,
138 /// may not be the same as GetFrameCodeAddress().
139 ///
140 /// For a frame in the middle of the stack, the return-pc is the
141 /// current code address, but for symbolication purposes the
142 /// return address after a noreturn call may point to the next
143 /// function, a DWARF location list entry that is a completely
144 /// different code path, or the wrong source line.
145 ///
146 /// The address returned should be used for symbolication (source line,
147 /// block, function, DWARF location entry selection) but should NOT
148 /// be shown to the user. It may not point to an actual instruction
149 /// boundary.
150 ///
151 /// \return
152 /// The Address object set to the current PC value.
153 Address GetFrameCodeAddressForSymbolication();
154
155 /// Change the pc value for a given thread.
156 ///
157 /// Change the current pc value for the frame on this thread.
158 ///
159 /// \param[in] pc
160 /// The load address that the pc will be set to.
161 ///
162 /// \return
163 /// true if the pc was changed. false if this failed -- possibly
164 /// because this frame is not a live StackFrame.
165 bool ChangePC(lldb::addr_t pc);
166
167 /// Provide a SymbolContext for this StackFrame's current pc value.
168 ///
169 /// The StackFrame maintains this SymbolContext and adds additional
170 /// information to it on an as-needed basis. This helps to avoid different
171 /// functions looking up symbolic information for a given pc value multiple
172 /// times.
173 ///
174 /// \params [in] resolve_scope
175 /// Flags from the SymbolContextItem enumerated type which specify what
176 /// type of symbol context is needed by this caller.
177 ///
178 /// \return
179 /// A SymbolContext reference which includes the types of information
180 /// requested by resolve_scope, if they are available.
181 const SymbolContext &GetSymbolContext(lldb::SymbolContextItem resolve_scope);
182
183 /// Return the Canonical Frame Address (DWARF term) for this frame.
184 ///
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
188 /// register value.
189 ///
190 /// Live StackFrames will always have a CFA but other types of frames may
191 /// not be able to supply one.
192 ///
193 /// \param [out] value
194 /// The address of the CFA for this frame, if available.
195 ///
196 /// \param [out] error_ptr
197 /// If there is an error determining the CFA address, this may contain a
198 /// string explaining the failure.
199 ///
200 /// \return
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 bool GetFrameBaseValue(Scalar &value, Status *error_ptr);
204
205 /// Get the DWARFExpression corresponding to the Canonical Frame Address.
206 ///
207 /// Often a register (bp), but sometimes a register + offset.
208 ///
209 /// \param [out] error_ptr
210 /// If there is an error determining the CFA address, this may contain a
211 /// string explaining the failure.
212 ///
213 /// \return
214 /// Returns the corresponding DWARF expression, or NULL.
215 DWARFExpression *GetFrameBaseExpression(Status *error_ptr);
216
217 /// Get the current lexical scope block for this StackFrame, if possible.
218 ///
219 /// If debug information is available for this stack frame, return a pointer
220 /// to the innermost lexical Block that the frame is currently executing.
221 ///
222 /// \return
223 /// A pointer to the current Block. nullptr is returned if this can
224 /// not be provided.
225 Block *GetFrameBlock();
226
227 /// Get the RegisterContext for this frame, if possible.
228 ///
229 /// Returns a shared pointer to the RegisterContext for this stack frame.
230 /// Only a live StackFrame object will be able to return a RegisterContext -
231 /// callers must be prepared for an empty shared pointer being returned.
232 ///
233 /// Even a live StackFrame RegisterContext may not be able to provide all
234 /// registers. Only the currently executing frame (frame 0) can reliably
235 /// provide every register in the register context.
236 ///
237 /// \return
238 /// The RegisterContext shared point for this frame.
239 lldb::RegisterContextSP GetRegisterContext();
240
241 const lldb::RegisterContextSP &GetRegisterContextSP() const {
242 return m_reg_context_sp;
243 }
244
245 /// Retrieve the list of variables that are in scope at this StackFrame's
246 /// pc.
247 ///
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.
251 ///
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).
256 ///
257 /// \return
258 /// A pointer to a list of variables.
259 VariableList *GetVariableList(bool get_file_globals);
260
261 /// Retrieve the list of variables that are in scope at this StackFrame's
262 /// pc.
263 ///
264 /// A frame that is not live may return an empty VariableListSP for a
265 /// given pc value even though variables would be available at this point if
266 /// it were a live stack frame.
267 ///
268 /// \param[in] get_file_globals
269 /// Whether to also retrieve compilation-unit scoped variables
270 /// that are visible to the entire compilation unit (e.g. file
271 /// static in C, globals that are homed in this CU).
272 ///
273 /// \return
274 /// A pointer to a list of variables.
275 lldb::VariableListSP
276 GetInScopeVariableList(bool get_file_globals,
277 bool must_have_valid_location = false);
278
279 /// Create a ValueObject for a variable name / pathname, possibly including
280 /// simple dereference/child selection syntax.
281 ///
282 /// \param[in] var_expr
283 /// The string specifying a variable to base the VariableObject off
284 /// of.
285 ///
286 /// \param[in] use_dynamic
287 /// Whether the correct dynamic type of an object pointer should be
288 /// determined before creating the object, or if the static type is
289 /// sufficient. One of the DynamicValueType enumerated values.
290 ///
291 /// \param[in] options
292 /// An unsigned integer of flags, values from
293 /// StackFrame::ExpressionPathOption
294 /// enum.
295 /// \param[in] var_sp
296 /// A VariableSP that will be set to the variable described in the
297 /// var_expr path.
298 ///
299 /// \param[in] error
300 /// Record any errors encountered while evaluating var_expr.
301 ///
302 /// \return
303 /// A shared pointer to the ValueObject described by var_expr.
304 lldb::ValueObjectSP GetValueForVariableExpressionPath(
305 llvm::StringRef var_expr, lldb::DynamicValueType use_dynamic,
306 uint32_t options, lldb::VariableSP &var_sp, Status &error);
307
308 /// Determine whether this StackFrame has debug information available or not.
309 ///
310 /// \return
311 /// true if debug information is available for this frame (function,
312 /// compilation unit, block, etc.)
313 bool HasDebugInformation();
314
315 /// Return the disassembly for the instructions of this StackFrame's
316 /// function as a single C string.
317 ///
318 /// \return
319 /// C string with the assembly instructions for this function.
320 const char *Disassemble();
321
322 /// Print a description for this frame using the frame-format formatter
323 /// settings.
324 ///
325 /// \param [in] strm
326 /// The Stream to print the description to.
327 ///
328 /// \param [in] show_unique
329 /// Whether to print the function arguments or not for backtrace unique.
330 ///
331 /// \param [in] frame_marker
332 /// Optional string that will be prepended to the frame output description.
333 void DumpUsingSettingsFormat(Stream *strm, bool show_unique = false,
334 const char *frame_marker = nullptr);
335
336 /// Print a description for this frame using a default format.
337 ///
338 /// \param [in] strm
339 /// The Stream to print the description to.
340 ///
341 /// \param [in] show_frame_index
342 /// Whether to print the frame number or not.
343 ///
344 /// \param [in] show_fullpaths
345 /// Whether to print the full source paths or just the file base name.
346 void Dump(Stream *strm, bool show_frame_index, bool show_fullpaths);
347
348 /// Print a description of this stack frame and/or the source
349 /// context/assembly for this stack frame.
350 ///
351 /// \param[in] strm
352 /// The Stream to send the output to.
353 ///
354 /// \param[in] show_frame_info
355 /// If true, print the frame info by calling DumpUsingSettingsFormat().
356 ///
357 /// \param[in] show_source
358 /// If true, print source or disassembly as per the user's settings.
359 ///
360 /// \param[in] show_unique
361 /// If true, print using backtrace unique style, without function
362 /// arguments as per the user's settings.
363 ///
364 /// \param[in] frame_marker
365 /// Passed to DumpUsingSettingsFormat() for the frame info printing.
366 ///
367 /// \return
368 /// Returns true if successful.
369 bool GetStatus(Stream &strm, bool show_frame_info, bool show_source,
370 bool show_unique = false, const char *frame_marker = nullptr);
371
372 /// Query whether this frame is a concrete frame on the call stack, or if it
373 /// is an inlined frame derived from the debug information and presented by
374 /// the debugger.
375 ///
376 /// \return
377 /// true if this is an inlined frame.
378 bool IsInlined();
379
380 /// Query whether this frame is part of a historical backtrace.
381 bool IsHistorical() const;
382
383 /// Query whether this frame is artificial (e.g a synthesized result of
384 /// inferring missing tail call frames from a backtrace). Artificial frames
385 /// may have limited support for inspecting variables.
386 bool IsArtificial() const;
387
388 /// Query this frame to find what frame it is in this Thread's
389 /// StackFrameList.
390 ///
391 /// \return
392 /// StackFrame index 0 indicates the currently-executing function. Inline
393 /// frames are included in this frame index count.
394 uint32_t GetFrameIndex() const;
395
396 /// Set this frame's synthetic frame index.
397 void SetFrameIndex(uint32_t index) { m_frame_index = index; }
398
399 /// Query this frame to find what frame it is in this Thread's
400 /// StackFrameList, not counting inlined frames.
401 ///
402 /// \return
403 /// StackFrame index 0 indicates the currently-executing function. Inline
404 /// frames are not included in this frame index count; their concrete
405 /// frame index will be the same as the concrete frame that they are
406 /// derived from.
407 uint32_t GetConcreteFrameIndex() const { return m_concrete_frame_index; }
408
409 /// Create a ValueObject for a given Variable in this StackFrame.
410 ///
411 /// \params [in] variable_sp
412 /// The Variable to base this ValueObject on
413 ///
414 /// \params [in] use_dynamic
415 /// Whether the correct dynamic type of the variable should be
416 /// determined before creating the ValueObject, or if the static type
417 /// is sufficient. One of the DynamicValueType enumerated values.
418 ///
419 /// \return
420 /// A ValueObject for this variable.
421 lldb::ValueObjectSP
422 GetValueObjectForFrameVariable(const lldb::VariableSP &variable_sp,
423 lldb::DynamicValueType use_dynamic);
424
425 /// Query this frame to determine what the default language should be when
426 /// parsing expressions given the execution context.
427 ///
428 /// \return
429 /// The language of the frame if known, else lldb::eLanguageTypeUnknown.
430 lldb::LanguageType GetLanguage();
431
432 // similar to GetLanguage(), but is allowed to take a potentially incorrect
433 // guess if exact information is not available
434 lldb::LanguageType GuessLanguage();
435
436 /// Attempt to econstruct the ValueObject for a given raw address touched by
437 /// the current instruction. The ExpressionPath should indicate how to get
438 /// to this value using "frame variable."
439 ///
440 /// \params [in] addr
441 /// The raw address.
442 ///
443 /// \return
444 /// The ValueObject if found. If valid, it has a valid ExpressionPath.
445 lldb::ValueObjectSP GuessValueForAddress(lldb::addr_t addr);
446
447 /// Attempt to reconstruct the ValueObject for the address contained in a
448 /// given register plus an offset. The ExpressionPath should indicate how
449 /// to get to this value using "frame variable."
450 ///
451 /// \params [in] reg
452 /// The name of the register.
453 ///
454 /// \params [in] offset
455 /// The offset from the register. Particularly important for sp...
456 ///
457 /// \return
458 /// The ValueObject if found. If valid, it has a valid ExpressionPath.
459 lldb::ValueObjectSP GuessValueForRegisterAndOffset(ConstString reg,
460 int64_t offset);
461
462 /// Attempt to reconstruct the ValueObject for a variable with a given \a name
463 /// from within the current StackFrame, within the current block. The search
464 /// for the variable starts in the deepest block corresponding to the current
465 /// PC in the stack frame and traverse through all parent blocks stopping at
466 /// inlined function boundaries.
467 ///
468 /// \params [in] name
469 /// The name of the variable.
470 ///
471 /// \return
472 /// The ValueObject if found.
473 lldb::ValueObjectSP FindVariable(ConstString name);
474
475 // lldb::ExecutionContextScope pure virtual functions
476 lldb::TargetSP CalculateTarget() override;
477
478 lldb::ProcessSP CalculateProcess() override;
479
480 lldb::ThreadSP CalculateThread() override;
481
482 lldb::StackFrameSP CalculateStackFrame() override;
483
484 void CalculateExecutionContext(ExecutionContext &exe_ctx) override;
485
486 lldb::RecognizedStackFrameSP GetRecognizedFrame();
487
488protected:
489 friend class StackFrameList;
490
491 void SetSymbolContextScope(SymbolContextScope *symbol_scope);
492
493 void UpdateCurrentFrameFromPreviousFrame(StackFrame &prev_frame);
494
495 void UpdatePreviousFrameFromCurrentFrame(StackFrame &curr_frame);
496
497 bool HasCachedData() const;
498
499private:
500 // For StackFrame only
501 lldb::ThreadWP m_thread_wp;
502 uint32_t m_frame_index;
503 uint32_t m_concrete_frame_index;
504 lldb::RegisterContextSP m_reg_context_sp;
505 StackID m_id;
506 Address m_frame_code_addr; // The frame code address (might not be the same as
507 // the actual PC for inlined frames) as a
508 // section/offset address
509 SymbolContext m_sc;
510 Flags m_flags;
511 Scalar m_frame_base;
512 Status m_frame_base_error;
513 bool m_cfa_is_valid; // Does this frame have a CFA? Different from CFA ==
514 // LLDB_INVALID_ADDRESS
515 Kind m_stack_frame_kind;
516
517 // Whether this frame behaves like the zeroth frame, in the sense
518 // that its pc value might not immediately follow a call (and thus might
519 // be the first address of its function). True for actual frame zero as
520 // well as any other frame with the same trait.
521 bool m_behaves_like_zeroth_frame;
522 lldb::VariableListSP m_variable_list_sp;
523 ValueObjectList m_variable_list_value_objects; // Value objects for each
524 // variable in
525 // m_variable_list_sp
526 lldb::RecognizedStackFrameSP m_recognized_frame_sp;
527 StreamString m_disassembly;
528 std::recursive_mutex m_mutex;
529
530 StackFrame(const StackFrame &) = delete;
531 const StackFrame &operator=(const StackFrame &) = delete;
532};
533
534} // namespace lldb_private
535
536#endif // LLDB_TARGET_STACKFRAME_H
537