StackFrame.h revision 263363
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 27namespace 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 41class StackFrame : 42 public ExecutionContextScope, 43 public std::enable_shared_from_this<StackFrame> 44{ 45public: 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 ®_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 ®_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 486protected: 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 501private: 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_ 528