contrib/llvm/tools/lldb/include/lldb/Target/StackFrame.h

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