contrib/llvm-project/lldb/bindings/interface/SBFrame.i

   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