1061da546Spatrick //===-- SWIG Interface for SBFrame ------------------------------*- C++ -*-===// 2061da546Spatrick // 3061da546Spatrick // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions. 4061da546Spatrick // See https://llvm.org/LICENSE.txt for license information. 5061da546Spatrick // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception 6061da546Spatrick // 7061da546Spatrick //===----------------------------------------------------------------------===// 8061da546Spatrick 9061da546Spatrick namespace lldb { 10061da546Spatrick 11061da546Spatrick %feature("docstring", 12061da546Spatrick "Represents one of the stack frames associated with a thread. 13*be691f3bSpatrick 14*be691f3bSpatrick SBThread contains SBFrame(s). For example (from test/lldbutil.py), :: 15061da546Spatrick 16061da546Spatrick def print_stacktrace(thread, string_buffer = False): 17061da546Spatrick '''Prints a simple stack trace of this thread.''' 18061da546Spatrick 19061da546Spatrick ... 20061da546Spatrick 21061da546Spatrick for i in range(depth): 22061da546Spatrick frame = thread.GetFrameAtIndex(i) 23061da546Spatrick function = frame.GetFunction() 24061da546Spatrick 25061da546Spatrick load_addr = addrs[i].GetLoadAddress(target) 26061da546Spatrick if not function: 27061da546Spatrick file_addr = addrs[i].GetFileAddress() 28061da546Spatrick start_addr = frame.GetSymbol().GetStartAddress().GetFileAddress() 29061da546Spatrick symbol_offset = file_addr - start_addr 30061da546Spatrick print >> output, ' frame #{num}: {addr:#016x} {mod}`{symbol} + {offset}'.format( 31061da546Spatrick num=i, addr=load_addr, mod=mods[i], symbol=symbols[i], offset=symbol_offset) 32061da546Spatrick else: 33061da546Spatrick print >> output, ' frame #{num}: {addr:#016x} {mod}`{func} at {file}:{line} {args}'.format( 34061da546Spatrick num=i, addr=load_addr, mod=mods[i], 35061da546Spatrick func='%s [inlined]' % funcs[i] if frame.IsInlined() else funcs[i], 36061da546Spatrick file=files[i], line=lines[i], 37061da546Spatrick args=get_args_as_string(frame, showFuncName=False) if not frame.IsInlined() else '()') 38061da546Spatrick 39061da546Spatrick ... 40061da546Spatrick 41*be691f3bSpatrick And, :: 42061da546Spatrick 43061da546Spatrick for frame in thread: 44061da546Spatrick print frame 45061da546Spatrick 46061da546Spatrick See also SBThread." 47061da546Spatrick ) SBFrame; 48061da546Spatrick class SBFrame 49061da546Spatrick { 50061da546Spatrick public: 51061da546Spatrick SBFrame (); 52061da546Spatrick 53061da546Spatrick SBFrame (const lldb::SBFrame &rhs); 54061da546Spatrick 55061da546Spatrick ~SBFrame(); 56061da546Spatrick 57061da546Spatrick bool 58061da546Spatrick IsEqual (const lldb::SBFrame &rhs) const; 59061da546Spatrick 60061da546Spatrick bool 61061da546Spatrick IsValid() const; 62061da546Spatrick 63061da546Spatrick explicit operator bool() const; 64061da546Spatrick 65061da546Spatrick uint32_t 66061da546Spatrick GetFrameID () const; 67061da546Spatrick 68061da546Spatrick %feature("docstring", " 69061da546Spatrick Get the Canonical Frame Address for this stack frame. 70061da546Spatrick This is the DWARF standard's definition of a CFA, a stack address 71061da546Spatrick that remains constant throughout the lifetime of the function. 72061da546Spatrick Returns an lldb::addr_t stack address, or LLDB_INVALID_ADDRESS if 73061da546Spatrick the CFA cannot be determined.") GetCFA; 74061da546Spatrick lldb::addr_t 75061da546Spatrick GetCFA () const; 76061da546Spatrick 77061da546Spatrick lldb::addr_t 78061da546Spatrick GetPC () const; 79061da546Spatrick 80061da546Spatrick bool 81061da546Spatrick SetPC (lldb::addr_t new_pc); 82061da546Spatrick 83061da546Spatrick lldb::addr_t 84061da546Spatrick GetSP () const; 85061da546Spatrick 86061da546Spatrick lldb::addr_t 87061da546Spatrick GetFP () const; 88061da546Spatrick 89061da546Spatrick lldb::SBAddress 90061da546Spatrick GetPCAddress () const; 91061da546Spatrick 92061da546Spatrick lldb::SBSymbolContext 93061da546Spatrick GetSymbolContext (uint32_t resolve_scope) const; 94061da546Spatrick 95061da546Spatrick lldb::SBModule 96061da546Spatrick GetModule () const; 97061da546Spatrick 98061da546Spatrick lldb::SBCompileUnit 99061da546Spatrick GetCompileUnit () const; 100061da546Spatrick 101061da546Spatrick lldb::SBFunction 102061da546Spatrick GetFunction () const; 103061da546Spatrick 104061da546Spatrick lldb::SBSymbol 105061da546Spatrick GetSymbol () const; 106061da546Spatrick 107061da546Spatrick %feature("docstring", " 108061da546Spatrick Gets the deepest block that contains the frame PC. 109061da546Spatrick 110061da546Spatrick See also GetFrameBlock().") GetBlock; 111061da546Spatrick lldb::SBBlock 112061da546Spatrick GetBlock () const; 113061da546Spatrick 114061da546Spatrick %feature("docstring", " 115061da546Spatrick Get the appropriate function name for this frame. Inlined functions in 116061da546Spatrick LLDB are represented by Blocks that have inlined function information, so 117061da546Spatrick just looking at the SBFunction or SBSymbol for a frame isn't enough. 118061da546Spatrick This function will return the appropriate function, symbol or inlined 119061da546Spatrick function name for the frame. 120061da546Spatrick 121061da546Spatrick This function returns: 122061da546Spatrick - the name of the inlined function (if there is one) 123061da546Spatrick - the name of the concrete function (if there is one) 124061da546Spatrick - the name of the symbol (if there is one) 125061da546Spatrick - NULL 126061da546Spatrick 127061da546Spatrick See also IsInlined().") GetFunctionName; 128061da546Spatrick const char * 129061da546Spatrick GetFunctionName(); 130061da546Spatrick 131061da546Spatrick const char * 132061da546Spatrick GetDisplayFunctionName (); 133061da546Spatrick 134061da546Spatrick const char * 135061da546Spatrick GetFunctionName() const; 136061da546Spatrick 137061da546Spatrick %feature("docstring", " 138061da546Spatrick Returns the language of the frame's SBFunction, or if there. 139061da546Spatrick is no SBFunction, guess the language from the mangled name. 140061da546Spatrick .") GuessLanguage; 141061da546Spatrick lldb::LanguageType 142061da546Spatrick GuessLanguage() const; 143061da546Spatrick 144061da546Spatrick %feature("docstring", " 145061da546Spatrick Return true if this frame represents an inlined function. 146061da546Spatrick 147061da546Spatrick See also GetFunctionName().") IsInlined; 148061da546Spatrick bool 149061da546Spatrick IsInlined(); 150061da546Spatrick 151061da546Spatrick bool 152061da546Spatrick IsInlined() const; 153061da546Spatrick 154061da546Spatrick %feature("docstring", " 155061da546Spatrick Return true if this frame is artificial (e.g a frame synthesized to 156061da546Spatrick capture a tail call). Local variables may not be available in an artificial 157061da546Spatrick frame.") IsArtificial; 158061da546Spatrick bool 159061da546Spatrick IsArtificial(); 160061da546Spatrick 161061da546Spatrick bool 162061da546Spatrick IsArtificial() const; 163061da546Spatrick 164061da546Spatrick %feature("docstring", " 165061da546Spatrick The version that doesn't supply a 'use_dynamic' value will use the 166061da546Spatrick target's default.") EvaluateExpression; 167061da546Spatrick lldb::SBValue 168061da546Spatrick EvaluateExpression (const char *expr); 169061da546Spatrick 170061da546Spatrick lldb::SBValue 171061da546Spatrick EvaluateExpression (const char *expr, lldb::DynamicValueType use_dynamic); 172061da546Spatrick 173061da546Spatrick lldb::SBValue 174061da546Spatrick EvaluateExpression (const char *expr, lldb::DynamicValueType use_dynamic, bool unwind_on_error); 175061da546Spatrick 176061da546Spatrick lldb::SBValue 177061da546Spatrick EvaluateExpression (const char *expr, SBExpressionOptions &options); 178061da546Spatrick 179061da546Spatrick %feature("docstring", " 180061da546Spatrick Gets the lexical block that defines the stack frame. Another way to think 181061da546Spatrick of this is it will return the block that contains all of the variables 182061da546Spatrick for a stack frame. Inlined functions are represented as SBBlock objects 183061da546Spatrick that have inlined function information: the name of the inlined function, 184061da546Spatrick where it was called from. The block that is returned will be the first 185061da546Spatrick block at or above the block for the PC (SBFrame::GetBlock()) that defines 186061da546Spatrick the scope of the frame. When a function contains no inlined functions, 187061da546Spatrick this will be the top most lexical block that defines the function. 188061da546Spatrick When a function has inlined functions and the PC is currently 189061da546Spatrick in one of those inlined functions, this method will return the inlined 190061da546Spatrick block that defines this frame. If the PC isn't currently in an inlined 191061da546Spatrick function, the lexical block that defines the function is returned.") GetFrameBlock; 192061da546Spatrick lldb::SBBlock 193061da546Spatrick GetFrameBlock () const; 194061da546Spatrick 195061da546Spatrick lldb::SBLineEntry 196061da546Spatrick GetLineEntry () const; 197061da546Spatrick 198061da546Spatrick lldb::SBThread 199061da546Spatrick GetThread () const; 200061da546Spatrick 201061da546Spatrick const char * 202061da546Spatrick Disassemble () const; 203061da546Spatrick 204061da546Spatrick void 205061da546Spatrick Clear(); 206061da546Spatrick 207061da546Spatrick bool 208061da546Spatrick operator == (const lldb::SBFrame &rhs) const; 209061da546Spatrick 210061da546Spatrick bool 211061da546Spatrick operator != (const lldb::SBFrame &rhs) const; 212061da546Spatrick 213061da546Spatrick %feature("docstring", " 214061da546Spatrick The version that doesn't supply a 'use_dynamic' value will use the 215061da546Spatrick target's default.") GetVariables; 216061da546Spatrick lldb::SBValueList 217061da546Spatrick GetVariables (bool arguments, 218061da546Spatrick bool locals, 219061da546Spatrick bool statics, 220061da546Spatrick bool in_scope_only); 221061da546Spatrick 222061da546Spatrick lldb::SBValueList 223061da546Spatrick GetVariables (bool arguments, 224061da546Spatrick bool locals, 225061da546Spatrick bool statics, 226061da546Spatrick bool in_scope_only, 227061da546Spatrick lldb::DynamicValueType use_dynamic); 228061da546Spatrick 229061da546Spatrick lldb::SBValueList 230061da546Spatrick GetVariables (const lldb::SBVariablesOptions& options); 231061da546Spatrick 232061da546Spatrick lldb::SBValueList 233061da546Spatrick GetRegisters (); 234061da546Spatrick 235061da546Spatrick %feature("docstring", " 236061da546Spatrick The version that doesn't supply a 'use_dynamic' value will use the 237061da546Spatrick target's default.") FindVariable; 238061da546Spatrick lldb::SBValue 239061da546Spatrick FindVariable (const char *var_name); 240061da546Spatrick 241061da546Spatrick lldb::SBValue 242061da546Spatrick FindVariable (const char *var_name, lldb::DynamicValueType use_dynamic); 243061da546Spatrick 244061da546Spatrick lldb::SBValue 245061da546Spatrick FindRegister (const char *name); 246061da546Spatrick 247061da546Spatrick %feature("docstring", " 248061da546Spatrick Get a lldb.SBValue for a variable path. 249061da546Spatrick 250*be691f3bSpatrick Variable paths can include access to pointer or instance members: :: 251*be691f3bSpatrick 252061da546Spatrick rect_ptr->origin.y 253061da546Spatrick pt.x 254*be691f3bSpatrick 255*be691f3bSpatrick Pointer dereferences: :: 256*be691f3bSpatrick 257061da546Spatrick *this->foo_ptr 258061da546Spatrick **argv 259*be691f3bSpatrick 260*be691f3bSpatrick Address of: :: 261*be691f3bSpatrick 262061da546Spatrick &pt 263061da546Spatrick &my_array[3].x 264*be691f3bSpatrick 265*be691f3bSpatrick Array accesses and treating pointers as arrays: :: 266*be691f3bSpatrick 267061da546Spatrick int_array[1] 268061da546Spatrick pt_ptr[22].x 269061da546Spatrick 270*be691f3bSpatrick Unlike `EvaluateExpression()` which returns :py:class:`SBValue` objects 271061da546Spatrick with constant copies of the values at the time of evaluation, 272061da546Spatrick the result of this function is a value that will continue to 273061da546Spatrick track the current value of the value as execution progresses 274061da546Spatrick in the current frame.") GetValueForVariablePath; 275061da546Spatrick lldb::SBValue 276061da546Spatrick GetValueForVariablePath (const char *var_path); 277061da546Spatrick 278061da546Spatrick lldb::SBValue 279061da546Spatrick GetValueForVariablePath (const char *var_path, lldb::DynamicValueType use_dynamic); 280061da546Spatrick 281061da546Spatrick %feature("docstring", " 282061da546Spatrick Find variables, register sets, registers, or persistent variables using 283061da546Spatrick the frame as the scope. 284061da546Spatrick 285*be691f3bSpatrick The version that doesn't supply a ``use_dynamic`` value will use the 286061da546Spatrick target's default.") FindValue; 287061da546Spatrick lldb::SBValue 288061da546Spatrick FindValue (const char *name, ValueType value_type); 289061da546Spatrick 290061da546Spatrick lldb::SBValue 291061da546Spatrick FindValue (const char *name, ValueType value_type, lldb::DynamicValueType use_dynamic); 292061da546Spatrick 293061da546Spatrick bool 294061da546Spatrick GetDescription (lldb::SBStream &description); 295061da546Spatrick 296061da546Spatrick STRING_EXTENSION(SBFrame) 297061da546Spatrick 298061da546Spatrick #ifdef SWIGPYTHON 299061da546Spatrick %pythoncode %{ 300061da546Spatrick def get_all_variables(self): 301061da546Spatrick return self.GetVariables(True,True,True,True) 302061da546Spatrick 303061da546Spatrick def get_parent_frame(self): 304061da546Spatrick parent_idx = self.idx + 1 305061da546Spatrick if parent_idx >= 0 and parent_idx < len(self.thread.frame): 306061da546Spatrick return self.thread.frame[parent_idx] 307061da546Spatrick else: 308061da546Spatrick return SBFrame() 309061da546Spatrick 310061da546Spatrick def get_arguments(self): 311061da546Spatrick return self.GetVariables(True,False,False,False) 312061da546Spatrick 313061da546Spatrick def get_locals(self): 314061da546Spatrick return self.GetVariables(False,True,False,False) 315061da546Spatrick 316061da546Spatrick def get_statics(self): 317061da546Spatrick return self.GetVariables(False,False,True,False) 318061da546Spatrick 319061da546Spatrick def var(self, var_expr_path): 320061da546Spatrick '''Calls through to lldb.SBFrame.GetValueForVariablePath() and returns 321061da546Spatrick a value that represents the variable expression path''' 322061da546Spatrick return self.GetValueForVariablePath(var_expr_path) 323061da546Spatrick 324061da546Spatrick def get_registers_access(self): 325061da546Spatrick class registers_access(object): 326061da546Spatrick '''A helper object that exposes a flattened view of registers, masking away the notion of register sets for easy scripting.''' 327061da546Spatrick def __init__(self, regs): 328061da546Spatrick self.regs = regs 329061da546Spatrick 330061da546Spatrick def __getitem__(self, key): 331061da546Spatrick if type(key) is str: 332061da546Spatrick for i in range(0,len(self.regs)): 333061da546Spatrick rs = self.regs[i] 334061da546Spatrick for j in range (0,rs.num_children): 335061da546Spatrick reg = rs.GetChildAtIndex(j) 336061da546Spatrick if reg.name == key: return reg 337061da546Spatrick else: 338061da546Spatrick return lldb.SBValue() 339061da546Spatrick 340061da546Spatrick return registers_access(self.registers) 341061da546Spatrick 342061da546Spatrick pc = property(GetPC, SetPC) 343061da546Spatrick addr = property(GetPCAddress, None, doc='''A read only property that returns the program counter (PC) as a section offset address (lldb.SBAddress).''') 344061da546Spatrick fp = property(GetFP, None, doc='''A read only property that returns the frame pointer (FP) as an unsigned integer.''') 345061da546Spatrick sp = property(GetSP, None, doc='''A read only property that returns the stack pointer (SP) as an unsigned integer.''') 346061da546Spatrick module = property(GetModule, None, doc='''A read only property that returns an lldb object that represents the module (lldb.SBModule) for this stack frame.''') 347061da546Spatrick 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.''') 348061da546Spatrick function = property(GetFunction, None, doc='''A read only property that returns an lldb object that represents the function (lldb.SBFunction) for this stack frame.''') 349061da546Spatrick symbol = property(GetSymbol, None, doc='''A read only property that returns an lldb object that represents the symbol (lldb.SBSymbol) for this stack frame.''') 350061da546Spatrick block = property(GetBlock, None, doc='''A read only property that returns an lldb object that represents the block (lldb.SBBlock) for this stack frame.''') 351061da546Spatrick is_inlined = property(IsInlined, None, doc='''A read only property that returns an boolean that indicates if the block frame is an inlined function.''') 352061da546Spatrick 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).''') 353061da546Spatrick 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.''') 354061da546Spatrick thread = property(GetThread, None, doc='''A read only property that returns an lldb object that represents the thread (lldb.SBThread) for this stack frame.''') 355061da546Spatrick disassembly = property(Disassemble, None, doc='''A read only property that returns the disassembly for this stack frame as a python string.''') 356061da546Spatrick idx = property(GetFrameID, None, doc='''A read only property that returns the zero based stack frame index.''') 357061da546Spatrick 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.''') 358061da546Spatrick 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.''') 359061da546Spatrick 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.''') 360061da546Spatrick 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.''') 361061da546Spatrick 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.''') 362061da546Spatrick 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.''') 363061da546Spatrick 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.''') 364061da546Spatrick 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.''') 365061da546Spatrick 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.''') 366061da546Spatrick 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''') 367061da546Spatrick parent = property(get_parent_frame, None, doc='''A read only property that returns the parent (caller) frame of the current frame.''') 368061da546Spatrick %} 369061da546Spatrick #endif 370061da546Spatrick }; 371061da546Spatrick 372061da546Spatrick } // namespace lldb 373