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   /// The version that doesn't supply a 'use_dynamic' value will use the
108   /// target's default.
109   lldb::SBValue EvaluateExpression(const char *expr);
110 
111   lldb::SBValue EvaluateExpression(const char *expr,
112                                    lldb::DynamicValueType use_dynamic);
113 
114   lldb::SBValue EvaluateExpression(const char *expr,
115                                    lldb::DynamicValueType use_dynamic,
116                                    bool unwind_on_error);
117 
118   lldb::SBValue EvaluateExpression(const char *expr,
119                                    const SBExpressionOptions &options);
120 
121   /// Gets the lexical block that defines the stack frame. Another way to think
122   /// of this is it will return the block that contains all of the variables
123   /// for a stack frame. Inlined functions are represented as SBBlock objects
124   /// that have inlined function information: the name of the inlined function,
125   /// where it was called from. The block that is returned will be the first
126   /// block at or above the block for the PC (SBFrame::GetBlock()) that defines
127   /// the scope of the frame. When a function contains no inlined functions,
128   /// this will be the top most lexical block that defines the function.
129   /// When a function has inlined functions and the PC is currently
130   /// in one of those inlined functions, this method will return the inlined
131   /// block that defines this frame. If the PC isn't currently in an inlined
132   /// function, the lexical block that defines the function is returned.
133   lldb::SBBlock GetFrameBlock() const;
134 
135   lldb::SBLineEntry GetLineEntry() const;
136 
137   lldb::SBThread GetThread() const;
138 
139   const char *Disassemble() const;
140 
141   void Clear();
142 
143   bool operator==(const lldb::SBFrame &rhs) const;
144 
145   bool operator!=(const lldb::SBFrame &rhs) const;
146 
147   /// The version that doesn't supply a 'use_dynamic' value will use the
148   /// target's default.
149   lldb::SBValueList GetVariables(bool arguments, bool locals, bool statics,
150                                  bool in_scope_only);
151 
152   lldb::SBValueList GetVariables(bool arguments, bool locals, bool statics,
153                                  bool in_scope_only,
154                                  lldb::DynamicValueType use_dynamic);
155 
156   lldb::SBValueList GetVariables(const lldb::SBVariablesOptions &options);
157 
158   lldb::SBValueList GetRegisters();
159 
160   lldb::SBValue FindRegister(const char *name);
161 
162   /// The version that doesn't supply a 'use_dynamic' value will use the
163   /// target's default.
164   lldb::SBValue FindVariable(const char *var_name);
165 
166   lldb::SBValue FindVariable(const char *var_name,
167                              lldb::DynamicValueType use_dynamic);
168 
169   // Find a value for a variable expression path like "rect.origin.x" or
170   // "pt_ptr->x", "*self", "*this->obj_ptr". The returned value is _not_ and
171   // expression result and is not a constant object like
172   // SBFrame::EvaluateExpression(...) returns, but a child object of the
173   // variable value.
174   lldb::SBValue GetValueForVariablePath(const char *var_expr_cstr,
175                                         DynamicValueType use_dynamic);
176 
177   /// The version that doesn't supply a 'use_dynamic' value will use the
178   /// target's default.
179   lldb::SBValue GetValueForVariablePath(const char *var_path);
180 
181   /// Find variables, register sets, registers, or persistent variables using
182   /// the frame as the scope.
183   ///
184   /// NB. This function does not look up ivars in the function object pointer.
185   /// To do that use GetValueForVariablePath.
186   ///
187   /// The version that doesn't supply a 'use_dynamic' value will use the
188   /// target's default.
189   lldb::SBValue FindValue(const char *name, ValueType value_type);
190 
191   lldb::SBValue FindValue(const char *name, ValueType value_type,
192                           lldb::DynamicValueType use_dynamic);
193 
194   bool GetDescription(lldb::SBStream &description);
195 
196 protected:
197   friend class SBBlock;
198   friend class SBExecutionContext;
199   friend class SBInstruction;
200   friend class SBThread;
201   friend class SBValue;
202 
203   friend class lldb_private::python::SWIGBridge;
204   friend class lldb_private::lua::SWIGBridge;
205 
206   SBFrame(const lldb::StackFrameSP &lldb_object_sp);
207 
208   lldb::StackFrameSP GetFrameSP() const;
209 
210   void SetFrameSP(const lldb::StackFrameSP &lldb_object_sp);
211 
212   lldb::ExecutionContextRefSP m_opaque_sp;
213 };
214 
215 } // namespace lldb
216 
217 #endif // LLDB_API_SBFRAME_H
218