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