Coverage Report

Created: 2022-01-18 06:27

/Users/buildslave/jenkins/workspace/coverage/llvm-project/lldb/include/lldb/Target/StackFrame.h
Line
Count
Source
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
26
namespace 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
40
class StackFrame : public ExecutionContextScope,
41
                   public std::enable_shared_from_this<StackFrame> {
42
public:
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
500k
  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
4.55k
  const lldb::RegisterContextSP &GetRegisterContextSP() const {
242
4.55k
    return m_reg_context_sp;
243
4.55k
  }
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
82
  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
19.7k
  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
488
protected:
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
499
private:
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