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