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
9namespace lldb {
10
11%feature("docstring",
12"Represents one of the stack frames associated with a thread.
13SBThread contains SBFrame(s). For example (from test/lldbutil.py),
14
15def 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
40And,
41
42    for frame in thread:
43        print frame
44
45See also SBThread."
46) SBFrame;
47class SBFrame
48{
49public:
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