1 //===-- SWIG Interface for SBFrame ------------------------------*- 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 namespace lldb {
10 
11 %feature("docstring",
12 "Represents one of the stack frames associated with a thread.
13 SBThread contains SBFrame(s). For example (from test/lldbutil.py),
14 
15 def print_stacktrace(thread, string_buffer = False):
16     '''Prints a simple stack trace of this thread.'''
17 
18     ...
19 
20     for i in range(depth):
21         frame = thread.GetFrameAtIndex(i)
22         function = frame.GetFunction()
23 
24         load_addr = addrs[i].GetLoadAddress(target)
25         if not function:
26             file_addr = addrs[i].GetFileAddress()
27             start_addr = frame.GetSymbol().GetStartAddress().GetFileAddress()
28             symbol_offset = file_addr - start_addr
29             print >> output, '  frame #{num}: {addr:#016x} {mod}`{symbol} + {offset}'.format(
30                 num=i, addr=load_addr, mod=mods[i], symbol=symbols[i], offset=symbol_offset)
31         else:
32             print >> output, '  frame #{num}: {addr:#016x} {mod}`{func} at {file}:{line} {args}'.format(
33                 num=i, addr=load_addr, mod=mods[i],
34                 func='%s [inlined]' % funcs[i] if frame.IsInlined() else funcs[i],
35                 file=files[i], line=lines[i],
36                 args=get_args_as_string(frame, showFuncName=False) if not frame.IsInlined() else '()')
37 
38     ...
39 
40 And,
41 
42     for frame in thread:
43         print frame
44 
45 See also SBThread."
46 ) SBFrame;
47 class SBFrame
48 {
49 public:
50     SBFrame ();
51 
52     SBFrame (const lldb::SBFrame &rhs);
53 
54    ~SBFrame();
55 
56     bool
57     IsEqual (const lldb::SBFrame &rhs) const;
58 
59     bool
60     IsValid() const;
61 
62     explicit operator bool() const;
63 
64     uint32_t
65     GetFrameID () const;
66 
67     %feature("docstring", "
68     Get the Canonical Frame Address for this stack frame.
69     This is the DWARF standard's definition of a CFA, a stack address
70     that remains constant throughout the lifetime of the function.
71     Returns an lldb::addr_t stack address, or LLDB_INVALID_ADDRESS if
72     the CFA cannot be determined.") GetCFA;
73     lldb::addr_t
74     GetCFA () const;
75 
76     lldb::addr_t
77     GetPC () const;
78 
79     bool
80     SetPC (lldb::addr_t new_pc);
81 
82     lldb::addr_t
83     GetSP () const;
84 
85     lldb::addr_t
86     GetFP () const;
87 
88     lldb::SBAddress
89     GetPCAddress () const;
90 
91     lldb::SBSymbolContext
92     GetSymbolContext (uint32_t resolve_scope) const;
93 
94     lldb::SBModule
95     GetModule () const;
96 
97     lldb::SBCompileUnit
98     GetCompileUnit () const;
99 
100     lldb::SBFunction
101     GetFunction () const;
102 
103     lldb::SBSymbol
104     GetSymbol () const;
105 
106     %feature("docstring", "
107     Gets the deepest block that contains the frame PC.
108 
109     See also GetFrameBlock().") GetBlock;
110     lldb::SBBlock
111     GetBlock () const;
112 
113     %feature("docstring", "
114     Get the appropriate function name for this frame. Inlined functions in
115     LLDB are represented by Blocks that have inlined function information, so
116     just looking at the SBFunction or SBSymbol for a frame isn't enough.
117     This function will return the appropriate function, symbol or inlined
118     function name for the frame.
119 
120     This function returns:
121     - the name of the inlined function (if there is one)
122     - the name of the concrete function (if there is one)
123     - the name of the symbol (if there is one)
124     - NULL
125 
126     See also IsInlined().") GetFunctionName;
127     const char *
128     GetFunctionName();
129 
130      const char *
131      GetDisplayFunctionName ();
132 
133     const char *
134     GetFunctionName() const;
135 
136     %feature("docstring", "
137     Returns the language of the frame's SBFunction, or if there.
138     is no SBFunction, guess the language from the mangled name.
139     .") GuessLanguage;
140     lldb::LanguageType
141     GuessLanguage() const;
142 
143     %feature("docstring", "
144     Return true if this frame represents an inlined function.
145 
146     See also GetFunctionName().") IsInlined;
147     bool
148     IsInlined();
149 
150     bool
151     IsInlined() const;
152 
153     %feature("docstring", "
154     Return true if this frame is artificial (e.g a frame synthesized to
155     capture a tail call). Local variables may not be available in an artificial
156     frame.") IsArtificial;
157     bool
158     IsArtificial();
159 
160     bool
161     IsArtificial() const;
162 
163     %feature("docstring", "
164     The version that doesn't supply a 'use_dynamic' value will use the
165     target's default.") EvaluateExpression;
166     lldb::SBValue
167     EvaluateExpression (const char *expr);
168 
169     lldb::SBValue
170     EvaluateExpression (const char *expr, lldb::DynamicValueType use_dynamic);
171 
172     lldb::SBValue
173     EvaluateExpression (const char *expr, lldb::DynamicValueType use_dynamic, bool unwind_on_error);
174 
175     lldb::SBValue
176     EvaluateExpression (const char *expr, SBExpressionOptions &options);
177 
178     %feature("docstring", "
179     Gets the lexical block that defines the stack frame. Another way to think
180     of this is it will return the block that contains all of the variables
181     for a stack frame. Inlined functions are represented as SBBlock objects
182     that have inlined function information: the name of the inlined function,
183     where it was called from. The block that is returned will be the first
184     block at or above the block for the PC (SBFrame::GetBlock()) that defines
185     the scope of the frame. When a function contains no inlined functions,
186     this will be the top most lexical block that defines the function.
187     When a function has inlined functions and the PC is currently
188     in one of those inlined functions, this method will return the inlined
189     block that defines this frame. If the PC isn't currently in an inlined
190     function, the lexical block that defines the function is returned.") GetFrameBlock;
191     lldb::SBBlock
192     GetFrameBlock () const;
193 
194     lldb::SBLineEntry
195     GetLineEntry () const;
196 
197     lldb::SBThread
198     GetThread () const;
199 
200     const char *
201     Disassemble () const;
202 
203     void
204     Clear();
205 
206     bool
207     operator == (const lldb::SBFrame &rhs) const;
208 
209     bool
210     operator != (const lldb::SBFrame &rhs) const;
211 
212     %feature("docstring", "
213     The version that doesn't supply a 'use_dynamic' value will use the
214     target's default.") GetVariables;
215     lldb::SBValueList
216     GetVariables (bool arguments,
217                   bool locals,
218                   bool statics,
219                   bool in_scope_only);
220 
221     lldb::SBValueList
222     GetVariables (bool arguments,
223                   bool locals,
224                   bool statics,
225                   bool in_scope_only,
226                   lldb::DynamicValueType  use_dynamic);
227 
228     lldb::SBValueList
229     GetVariables (const lldb::SBVariablesOptions& options);
230 
231     lldb::SBValueList
232     GetRegisters ();
233 
234     %feature("docstring", "
235     The version that doesn't supply a 'use_dynamic' value will use the
236     target's default.") FindVariable;
237     lldb::SBValue
238     FindVariable (const char *var_name);
239 
240     lldb::SBValue
241     FindVariable (const char *var_name, lldb::DynamicValueType use_dynamic);
242 
243     lldb::SBValue
244     FindRegister (const char *name);
245 
246     %feature("docstring", "
247     Get a lldb.SBValue for a variable path.
248 
249     Variable paths can include access to pointer or instance members:
250         rect_ptr->origin.y
251         pt.x
252     Pointer dereferences:
253         *this->foo_ptr
254         **argv
255     Address of:
256         &pt
257         &my_array[3].x
258     Array accesses and treating pointers as arrays:
259         int_array[1]
260         pt_ptr[22].x
261 
262     Unlike EvaluateExpression() which returns lldb.SBValue objects
263     with constant copies of the values at the time of evaluation,
264     the result of this function is a value that will continue to
265     track the current value of the value as execution progresses
266     in the current frame.") GetValueForVariablePath;
267     lldb::SBValue
268     GetValueForVariablePath (const char *var_path);
269 
270     lldb::SBValue
271     GetValueForVariablePath (const char *var_path, lldb::DynamicValueType use_dynamic);
272 
273     %feature("docstring", "
274     Find variables, register sets, registers, or persistent variables using
275     the frame as the scope.
276 
277     The version that doesn't supply a 'use_dynamic' value will use the
278     target's default.") FindValue;
279     lldb::SBValue
280     FindValue (const char *name, ValueType value_type);
281 
282     lldb::SBValue
283     FindValue (const char *name, ValueType value_type, lldb::DynamicValueType use_dynamic);
284 
285     bool
286     GetDescription (lldb::SBStream &description);
287 
288     STRING_EXTENSION(SBFrame)
289 
290 #ifdef SWIGPYTHON
291     %pythoncode %{
292         def get_all_variables(self):
293             return self.GetVariables(True,True,True,True)
294 
295         def get_parent_frame(self):
296             parent_idx = self.idx + 1
297             if parent_idx >= 0 and parent_idx < len(self.thread.frame):
298                 return self.thread.frame[parent_idx]
299             else:
300                 return SBFrame()
301 
302         def get_arguments(self):
303             return self.GetVariables(True,False,False,False)
304 
305         def get_locals(self):
306             return self.GetVariables(False,True,False,False)
307 
308         def get_statics(self):
309             return self.GetVariables(False,False,True,False)
310 
311         def var(self, var_expr_path):
312             '''Calls through to lldb.SBFrame.GetValueForVariablePath() and returns
313             a value that represents the variable expression path'''
314             return self.GetValueForVariablePath(var_expr_path)
315 
316         def get_registers_access(self):
317             class registers_access(object):
318                 '''A helper object that exposes a flattened view of registers, masking away the notion of register sets for easy scripting.'''
319                 def __init__(self, regs):
320                     self.regs = regs
321 
322                 def __getitem__(self, key):
323                     if type(key) is str:
324                         for i in range(0,len(self.regs)):
325                             rs = self.regs[i]
326                             for j in range (0,rs.num_children):
327                                 reg = rs.GetChildAtIndex(j)
328                                 if reg.name == key: return reg
329                     else:
330                         return lldb.SBValue()
331 
332             return registers_access(self.registers)
333 
334         pc = property(GetPC, SetPC)
335         addr = property(GetPCAddress, None, doc='''A read only property that returns the program counter (PC) as a section offset address (lldb.SBAddress).''')
336         fp = property(GetFP, None, doc='''A read only property that returns the frame pointer (FP) as an unsigned integer.''')
337         sp = property(GetSP, None, doc='''A read only property that returns the stack pointer (SP) as an unsigned integer.''')
338         module = property(GetModule, None, doc='''A read only property that returns an lldb object that represents the module (lldb.SBModule) for this stack frame.''')
339         compile_unit = property(GetCompileUnit, None, doc='''A read only property that returns an lldb object that represents the compile unit (lldb.SBCompileUnit) for this stack frame.''')
340         function = property(GetFunction, None, doc='''A read only property that returns an lldb object that represents the function (lldb.SBFunction) for this stack frame.''')
341         symbol = property(GetSymbol, None, doc='''A read only property that returns an lldb object that represents the symbol (lldb.SBSymbol) for this stack frame.''')
342         block = property(GetBlock, None, doc='''A read only property that returns an lldb object that represents the block (lldb.SBBlock) for this stack frame.''')
343         is_inlined = property(IsInlined, None, doc='''A read only property that returns an boolean that indicates if the block frame is an inlined function.''')
344         name = property(GetFunctionName, None, doc='''A read only property that retuns the name for the function that this frame represents. Inlined stack frame might have a concrete function that differs from the name of the inlined function (a named lldb.SBBlock).''')
345         line_entry = property(GetLineEntry, None, doc='''A read only property that returns an lldb object that represents the line table entry (lldb.SBLineEntry) for this stack frame.''')
346         thread = property(GetThread, None, doc='''A read only property that returns an lldb object that represents the thread (lldb.SBThread) for this stack frame.''')
347         disassembly = property(Disassemble, None, doc='''A read only property that returns the disassembly for this stack frame as a python string.''')
348         idx = property(GetFrameID, None, doc='''A read only property that returns the zero based stack frame index.''')
349         variables = property(get_all_variables, None, doc='''A read only property that returns a list() that contains a collection of lldb.SBValue objects that represent the variables in this stack frame.''')
350         vars = property(get_all_variables, None, doc='''A read only property that returns a list() that contains a collection of lldb.SBValue objects that represent the variables in this stack frame.''')
351         locals = property(get_locals, None, doc='''A read only property that returns a list() that contains a collection of lldb.SBValue objects that represent the local variables in this stack frame.''')
352         args = property(get_arguments, None, doc='''A read only property that returns a list() that contains a collection of lldb.SBValue objects that represent the argument variables in this stack frame.''')
353         arguments = property(get_arguments, None, doc='''A read only property that returns a list() that contains a collection of lldb.SBValue objects that represent the argument variables in this stack frame.''')
354         statics = property(get_statics, None, doc='''A read only property that returns a list() that contains a collection of lldb.SBValue objects that represent the static variables in this stack frame.''')
355         registers = property(GetRegisters, None, doc='''A read only property that returns a list() that contains a collection of lldb.SBValue objects that represent the CPU registers for this stack frame.''')
356         regs = property(GetRegisters, None, doc='''A read only property that returns a list() that contains a collection of lldb.SBValue objects that represent the CPU registers for this stack frame.''')
357         register = property(get_registers_access, None, doc='''A read only property that returns an helper object providing a flattened indexable view of the CPU registers for this stack frame.''')
358         reg = property(get_registers_access, None, doc='''A read only property that returns an helper object providing a flattened indexable view of the CPU registers for this stack frame''')
359         parent = property(get_parent_frame, None, doc='''A read only property that returns the parent (caller) frame of the current frame.''')
360     %}
361 #endif
362 };
363 
364 } // namespace lldb
365