1 //===-- SBFrame.h -----------------------------------------------*- C++ -*-===// 2 // 3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions. 4 // See https://llvm.org/LICENSE.txt for license information. 5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception 6 // 7 //===----------------------------------------------------------------------===// 8 9 #ifndef LLDB_API_SBFRAME_H 10 #define LLDB_API_SBFRAME_H 11 12 #include "lldb/API/SBDefines.h" 13 #include "lldb/API/SBValueList.h" 14 15 namespace lldb_private { 16 namespace python { 17 class SWIGBridge; 18 } 19 namespace lua { 20 class SWIGBridge; 21 } 22 } // namespace lldb_private 23 24 namespace lldb { 25 26 class LLDB_API SBFrame { 27 public: 28 SBFrame(); 29 30 SBFrame(const lldb::SBFrame &rhs); 31 32 const lldb::SBFrame &operator=(const lldb::SBFrame &rhs); 33 34 ~SBFrame(); 35 36 bool IsEqual(const lldb::SBFrame &that) const; 37 38 explicit operator bool() const; 39 40 bool IsValid() const; 41 42 uint32_t GetFrameID() const; 43 44 lldb::addr_t GetCFA() const; 45 46 lldb::addr_t GetPC() const; 47 48 bool SetPC(lldb::addr_t new_pc); 49 50 lldb::addr_t GetSP() const; 51 52 lldb::addr_t GetFP() const; 53 54 lldb::SBAddress GetPCAddress() const; 55 56 lldb::SBSymbolContext GetSymbolContext(uint32_t resolve_scope) const; 57 58 lldb::SBModule GetModule() const; 59 60 lldb::SBCompileUnit GetCompileUnit() const; 61 62 lldb::SBFunction GetFunction() const; 63 64 lldb::SBSymbol GetSymbol() const; 65 66 /// Gets the deepest block that contains the frame PC. 67 /// 68 /// See also GetFrameBlock(). 69 lldb::SBBlock GetBlock() const; 70 71 /// Get the appropriate function name for this frame. Inlined functions in 72 /// LLDB are represented by Blocks that have inlined function information, so 73 /// just looking at the SBFunction or SBSymbol for a frame isn't enough. 74 /// This function will return the appropriate function, symbol or inlined 75 /// function name for the frame. 76 /// 77 /// This function returns: 78 /// - the name of the inlined function (if there is one) 79 /// - the name of the concrete function (if there is one) 80 /// - the name of the symbol (if there is one) 81 /// - NULL 82 /// 83 /// See also IsInlined(). 84 const char *GetFunctionName(); 85 86 // Get an appropriate function name for this frame that is suitable for 87 // display to a user 88 const char *GetDisplayFunctionName(); 89 90 const char *GetFunctionName() const; 91 92 // Return the frame function's language. If there isn't a function, then 93 // guess the language type from the mangled name. 94 lldb::LanguageType GuessLanguage() const; 95 96 /// Return true if this frame represents an inlined function. 97 /// 98 /// See also GetFunctionName(). 99 bool IsInlined(); 100 101 bool IsInlined() const; 102 103 bool IsArtificial(); 104 105 bool IsArtificial() const; 106 107 /// Return whether a frame recognizer decided this frame should not 108 /// be displayes in backtraces etc. 109 bool IsHidden() const; 110 111 /// The version that doesn't supply a 'use_dynamic' value will use the 112 /// target's default. 113 lldb::SBValue EvaluateExpression(const char *expr); 114 115 lldb::SBValue EvaluateExpression(const char *expr, 116 lldb::DynamicValueType use_dynamic); 117 118 lldb::SBValue EvaluateExpression(const char *expr, 119 lldb::DynamicValueType use_dynamic, 120 bool unwind_on_error); 121 122 lldb::SBValue EvaluateExpression(const char *expr, 123 const SBExpressionOptions &options); 124 125 /// Language plugins can use this API to report language-specific 126 /// runtime information about this compile unit, such as additional 127 /// language version details or feature flags. 128 SBStructuredData GetLanguageSpecificData() const; 129 130 /// Gets the lexical block that defines the stack frame. Another way to think 131 /// of this is it will return the block that contains all of the variables 132 /// for a stack frame. Inlined functions are represented as SBBlock objects 133 /// that have inlined function information: the name of the inlined function, 134 /// where it was called from. The block that is returned will be the first 135 /// block at or above the block for the PC (SBFrame::GetBlock()) that defines 136 /// the scope of the frame. When a function contains no inlined functions, 137 /// this will be the top most lexical block that defines the function. 138 /// When a function has inlined functions and the PC is currently 139 /// in one of those inlined functions, this method will return the inlined 140 /// block that defines this frame. If the PC isn't currently in an inlined 141 /// function, the lexical block that defines the function is returned. 142 lldb::SBBlock GetFrameBlock() const; 143 144 lldb::SBLineEntry GetLineEntry() const; 145 146 lldb::SBThread GetThread() const; 147 148 const char *Disassemble() const; 149 150 void Clear(); 151 152 bool operator==(const lldb::SBFrame &rhs) const; 153 154 bool operator!=(const lldb::SBFrame &rhs) const; 155 156 /// The version that doesn't supply a 'use_dynamic' value will use the 157 /// target's default. 158 lldb::SBValueList GetVariables(bool arguments, bool locals, bool statics, 159 bool in_scope_only); 160 161 lldb::SBValueList GetVariables(bool arguments, bool locals, bool statics, 162 bool in_scope_only, 163 lldb::DynamicValueType use_dynamic); 164 165 lldb::SBValueList GetVariables(const lldb::SBVariablesOptions &options); 166 167 lldb::SBValueList GetRegisters(); 168 169 lldb::SBValue FindRegister(const char *name); 170 171 /// The version that doesn't supply a 'use_dynamic' value will use the 172 /// target's default. 173 lldb::SBValue FindVariable(const char *var_name); 174 175 lldb::SBValue FindVariable(const char *var_name, 176 lldb::DynamicValueType use_dynamic); 177 178 // Find a value for a variable expression path like "rect.origin.x" or 179 // "pt_ptr->x", "*self", "*this->obj_ptr". The returned value is _not_ and 180 // expression result and is not a constant object like 181 // SBFrame::EvaluateExpression(...) returns, but a child object of the 182 // variable value. 183 lldb::SBValue GetValueForVariablePath(const char *var_expr_cstr, 184 DynamicValueType use_dynamic); 185 186 /// The version that doesn't supply a 'use_dynamic' value will use the 187 /// target's default. 188 lldb::SBValue GetValueForVariablePath(const char *var_path); 189 190 /// Find variables, register sets, registers, or persistent variables using 191 /// the frame as the scope. 192 /// 193 /// NB. This function does not look up ivars in the function object pointer. 194 /// To do that use GetValueForVariablePath. 195 /// 196 /// The version that doesn't supply a 'use_dynamic' value will use the 197 /// target's default. 198 lldb::SBValue FindValue(const char *name, ValueType value_type); 199 200 lldb::SBValue FindValue(const char *name, ValueType value_type, 201 lldb::DynamicValueType use_dynamic); 202 203 bool GetDescription(lldb::SBStream &description); 204 205 /// Similar to \a GetDescription() but the format of the description can be 206 /// configured via the \p format parameter. See 207 /// https://lldb.llvm.org/use/formatting.html for more information on format 208 /// strings. 209 /// 210 /// \param[in] format 211 /// The format to use for generating the description. 212 /// 213 /// \param[out] output 214 /// The stream where the description will be written to. 215 /// 216 /// \return 217 /// An error object with an error message in case of failures. 218 SBError GetDescriptionWithFormat(const SBFormat &format, SBStream &output); 219 220 protected: 221 friend class SBBlock; 222 friend class SBExecutionContext; 223 friend class SBInstruction; 224 friend class SBThread; 225 friend class SBValue; 226 227 friend class lldb_private::python::SWIGBridge; 228 friend class lldb_private::lua::SWIGBridge; 229 230 SBFrame(const lldb::StackFrameSP &lldb_object_sp); 231 232 lldb::StackFrameSP GetFrameSP() const; 233 234 void SetFrameSP(const lldb::StackFrameSP &lldb_object_sp); 235 236 lldb::ExecutionContextRefSP m_opaque_sp; 237 }; 238 239 } // namespace lldb 240 241 #endif // LLDB_API_SBFRAME_H 242