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_SBFrame_h_
10 #define LLDB_SBFrame_h_
11 
12 #include "lldb/API/SBDefines.h"
13 #include "lldb/API/SBValueList.h"
14 
15 namespace lldb {
16 
17 class LLDB_API SBFrame {
18 public:
19   SBFrame();
20 
21   SBFrame(const lldb::SBFrame &rhs);
22 
23   const lldb::SBFrame &operator=(const lldb::SBFrame &rhs);
24 
25   ~SBFrame();
26 
27   bool IsEqual(const lldb::SBFrame &that) const;
28 
29   explicit operator bool() const;
30 
31   bool IsValid() const;
32 
33   uint32_t GetFrameID() const;
34 
35   lldb::addr_t GetCFA() const;
36 
37   lldb::addr_t GetPC() const;
38 
39   bool SetPC(lldb::addr_t new_pc);
40 
41   lldb::addr_t GetSP() const;
42 
43   lldb::addr_t GetFP() const;
44 
45   lldb::SBAddress GetPCAddress() const;
46 
47   lldb::SBSymbolContext GetSymbolContext(uint32_t resolve_scope) const;
48 
49   lldb::SBModule GetModule() const;
50 
51   lldb::SBCompileUnit GetCompileUnit() const;
52 
53   lldb::SBFunction GetFunction() const;
54 
55   lldb::SBSymbol GetSymbol() const;
56 
57   /// Gets the deepest block that contains the frame PC.
58   ///
59   /// See also GetFrameBlock().
60   lldb::SBBlock GetBlock() const;
61 
62   /// Get the appropriate function name for this frame. Inlined functions in
63   /// LLDB are represented by Blocks that have inlined function information, so
64   /// just looking at the SBFunction or SBSymbol for a frame isn't enough.
65   /// This function will return the appropriate function, symbol or inlined
66   /// function name for the frame.
67   ///
68   /// This function returns:
69   /// - the name of the inlined function (if there is one)
70   /// - the name of the concrete function (if there is one)
71   /// - the name of the symbol (if there is one)
72   /// - NULL
73   ///
74   /// See also IsInlined().
75   const char *GetFunctionName();
76 
77   // Get an appropriate function name for this frame that is suitable for
78   // display to a user
79   const char *GetDisplayFunctionName();
80 
81   const char *GetFunctionName() const;
82 
83   // Return the frame function's language.  If there isn't a function, then
84   // guess the language type from the mangled name.
85   lldb::LanguageType GuessLanguage() const;
86 
87   /// Return true if this frame represents an inlined function.
88   ///
89   /// See also GetFunctionName().
90   bool IsInlined();
91 
92   bool IsInlined() const;
93 
94   bool IsArtificial();
95 
96   bool IsArtificial() const;
97 
98   /// The version that doesn't supply a 'use_dynamic' value will use the
99   /// target's default.
100   lldb::SBValue EvaluateExpression(const char *expr);
101 
102   lldb::SBValue EvaluateExpression(const char *expr,
103                                    lldb::DynamicValueType use_dynamic);
104 
105   lldb::SBValue EvaluateExpression(const char *expr,
106                                    lldb::DynamicValueType use_dynamic,
107                                    bool unwind_on_error);
108 
109   lldb::SBValue EvaluateExpression(const char *expr,
110                                    const SBExpressionOptions &options);
111 
112   /// Gets the lexical block that defines the stack frame. Another way to think
113   /// of this is it will return the block that contains all of the variables
114   /// for a stack frame. Inlined functions are represented as SBBlock objects
115   /// that have inlined function information: the name of the inlined function,
116   /// where it was called from. The block that is returned will be the first
117   /// block at or above the block for the PC (SBFrame::GetBlock()) that defines
118   /// the scope of the frame. When a function contains no inlined functions,
119   /// this will be the top most lexical block that defines the function.
120   /// When a function has inlined functions and the PC is currently
121   /// in one of those inlined functions, this method will return the inlined
122   /// block that defines this frame. If the PC isn't currently in an inlined
123   /// function, the lexical block that defines the function is returned.
124   lldb::SBBlock GetFrameBlock() const;
125 
126   lldb::SBLineEntry GetLineEntry() const;
127 
128   lldb::SBThread GetThread() const;
129 
130   const char *Disassemble() const;
131 
132   void Clear();
133 
134   bool operator==(const lldb::SBFrame &rhs) const;
135 
136   bool operator!=(const lldb::SBFrame &rhs) const;
137 
138   /// The version that doesn't supply a 'use_dynamic' value will use the
139   /// target's default.
140   lldb::SBValueList GetVariables(bool arguments, bool locals, bool statics,
141                                  bool in_scope_only);
142 
143   lldb::SBValueList GetVariables(bool arguments, bool locals, bool statics,
144                                  bool in_scope_only,
145                                  lldb::DynamicValueType use_dynamic);
146 
147   lldb::SBValueList GetVariables(const lldb::SBVariablesOptions &options);
148 
149   lldb::SBValueList GetRegisters();
150 
151   lldb::SBValue FindRegister(const char *name);
152 
153   /// The version that doesn't supply a 'use_dynamic' value will use the
154   /// target's default.
155   lldb::SBValue FindVariable(const char *var_name);
156 
157   lldb::SBValue FindVariable(const char *var_name,
158                              lldb::DynamicValueType use_dynamic);
159 
160   // Find a value for a variable expression path like "rect.origin.x" or
161   // "pt_ptr->x", "*self", "*this->obj_ptr". The returned value is _not_ and
162   // expression result and is not a constant object like
163   // SBFrame::EvaluateExpression(...) returns, but a child object of the
164   // variable value.
165   lldb::SBValue GetValueForVariablePath(const char *var_expr_cstr,
166                                         DynamicValueType use_dynamic);
167 
168   /// The version that doesn't supply a 'use_dynamic' value will use the
169   /// target's default.
170   lldb::SBValue GetValueForVariablePath(const char *var_path);
171 
172   /// Find variables, register sets, registers, or persistent variables using
173   /// the frame as the scope.
174   ///
175   /// NB. This function does not look up ivars in the function object pointer.
176   /// To do that use GetValueForVariablePath.
177   ///
178   /// The version that doesn't supply a 'use_dynamic' value will use the
179   /// target's default.
180   lldb::SBValue FindValue(const char *name, ValueType value_type);
181 
182   lldb::SBValue FindValue(const char *name, ValueType value_type,
183                           lldb::DynamicValueType use_dynamic);
184 
185   bool GetDescription(lldb::SBStream &description);
186 
187   SBFrame(const lldb::StackFrameSP &lldb_object_sp);
188 
189 protected:
190   friend class SBBlock;
191   friend class SBExecutionContext;
192   friend class SBInstruction;
193   friend class SBThread;
194   friend class SBValue;
195 
196   lldb::StackFrameSP GetFrameSP() const;
197 
198   void SetFrameSP(const lldb::StackFrameSP &lldb_object_sp);
199 
200   lldb::ExecutionContextRefSP m_opaque_sp;
201 };
202 
203 } // namespace lldb
204 
205 #endif // LLDB_SBFrame_h_
206