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