diff options
Diffstat (limited to 'contrib/llvm-project/lldb/bindings')
68 files changed, 1138 insertions, 670 deletions
diff --git a/contrib/llvm-project/lldb/bindings/interface/SBAddress.i b/contrib/llvm-project/lldb/bindings/interface/SBAddress.i index 6fd06c83d293..8e95d36e580d 100644 --- a/contrib/llvm-project/lldb/bindings/interface/SBAddress.i +++ b/contrib/llvm-project/lldb/bindings/interface/SBAddress.i @@ -17,8 +17,9 @@ libraries, bundles, frameworks) being loaded at different addresses than the addresses found in the object file that represents them on disk. There are currently two types of addresses for a section: - o file addresses - o load addresses + +* file addresses +* load addresses File addresses represents the virtual addresses that are in the 'on disk' object files. These virtual addresses are converted to be @@ -108,18 +109,17 @@ public: An address might refer to code or data from an existing module, or it might refer to something on the stack or heap. The following functions will only return valid values if the address has been resolved to a code - or data address using 'void SBAddress::SetLoadAddress(...)' or - 'lldb::SBAddress SBTarget::ResolveLoadAddress (...)'.") GetSymbolContext; + or data address using :py:class:`SBAddress.SetLoadAddress' or + :py:class:`SBTarget.ResolveLoadAddress`.") GetSymbolContext; lldb::SBSymbolContext GetSymbolContext (uint32_t resolve_scope); %feature("docstring", " GetModule() and the following grab individual objects for a given address and are less efficient if you want more than one symbol related objects. - Use one of the following when you want multiple debug symbol related - objects for an address: - lldb::SBSymbolContext SBAddress::GetSymbolContext (uint32_t resolve_scope); - lldb::SBSymbolContext SBTarget::ResolveSymbolContextForAddress (const SBAddress &addr, uint32_t resolve_scope); + Use :py:class:`SBAddress.GetSymbolContext` or + :py:class:`SBTarget.ResolveSymbolContextForAddress` when you want multiple + debug symbol related objects for an address. One or more bits from the SymbolContextItem enumerations can be logically OR'ed together to more efficiently retrieve multiple symbol objects.") GetModule; lldb::SBModule diff --git a/contrib/llvm-project/lldb/bindings/interface/SBAttachInfo.i b/contrib/llvm-project/lldb/bindings/interface/SBAttachInfo.i index 3f4634e14619..9ac96e6dd7be 100644 --- a/contrib/llvm-project/lldb/bindings/interface/SBAttachInfo.i +++ b/contrib/llvm-project/lldb/bindings/interface/SBAttachInfo.i @@ -7,7 +7,9 @@ //===----------------------------------------------------------------------===// namespace lldb { - +%feature("docstring", +"Describes how to attach when calling :py:class:`SBTarget.Attach`." +) SBAttachInfo; class SBAttachInfo { public: diff --git a/contrib/llvm-project/lldb/bindings/interface/SBBlock.i b/contrib/llvm-project/lldb/bindings/interface/SBBlock.i index 812b41fe5c3e..3972b939b18b 100644 --- a/contrib/llvm-project/lldb/bindings/interface/SBBlock.i +++ b/contrib/llvm-project/lldb/bindings/interface/SBBlock.i @@ -22,7 +22,7 @@ public: ~SBBlock (); %feature("docstring", - "Does this block represent an inlined function?" + "Is this block contained within an inlined function?" ) IsInlined; bool IsInlined () const; diff --git a/contrib/llvm-project/lldb/bindings/interface/SBBreakpoint.i b/contrib/llvm-project/lldb/bindings/interface/SBBreakpoint.i index a2d747db0bf6..37fcc7fbab48 100644 --- a/contrib/llvm-project/lldb/bindings/interface/SBBreakpoint.i +++ b/contrib/llvm-project/lldb/bindings/interface/SBBreakpoint.i @@ -11,7 +11,7 @@ namespace lldb { "Represents a logical breakpoint and its associated settings. For example (from test/functionalities/breakpoint/breakpoint_ignore_count/ -TestBreakpointIgnoreCount.py), +TestBreakpointIgnoreCount.py),:: def breakpoint_ignore_count_python(self): '''Use Python APIs to set breakpoint ignore count.''' @@ -62,13 +62,13 @@ TestBreakpointIgnoreCount.py), process.Continue() -SBBreakpoint supports breakpoint location iteration, for example, +SBBreakpoint supports breakpoint location iteration, for example,:: for bl in breakpoint: print('breakpoint location load addr: %s' % hex(bl.GetLoadAddress())) print('breakpoint location condition: %s' % hex(bl.GetCondition())) -and rich comparison methods which allow the API program to use, +and rich comparison methods which allow the API program to use,:: if aBreakpoint == bBreakpoint: ... @@ -100,6 +100,9 @@ public: void ClearAllBreakpointSites (); + lldb::SBTarget + GetTarget() const; + lldb::SBBreakpointLocation FindLocationByAddress (lldb::addr_t vm_addr); @@ -234,6 +237,8 @@ public: SBError AddLocation(SBAddress &address); + SBStructuredData SBBreakpoint::SerializeToStructuredData(); + static bool EventIsBreakpointEvent (const lldb::SBEvent &event); @@ -308,6 +313,10 @@ public: class SBBreakpointListImpl; + +%feature("docstring", +"Represents a list of :py:class:`SBBreakpoint`." +) SBBreakpointList; class LLDB_API SBBreakpointList { public: diff --git a/contrib/llvm-project/lldb/bindings/interface/SBBreakpointLocation.i b/contrib/llvm-project/lldb/bindings/interface/SBBreakpointLocation.i index dc39c83c2d67..fc37475ba745 100644 --- a/contrib/llvm-project/lldb/bindings/interface/SBBreakpointLocation.i +++ b/contrib/llvm-project/lldb/bindings/interface/SBBreakpointLocation.i @@ -15,7 +15,7 @@ A breakpoint location is defined by the breakpoint that produces it, and the address that resulted in this particular instantiation. Each breakpoint location has its settable options. -SBBreakpoint contains SBBreakpointLocation(s). See docstring of SBBreakpoint +:py:class:`SBBreakpoint` contains SBBreakpointLocation(s). See docstring of SBBreakpoint for retrieval of an SBBreakpointLocation from an SBBreakpoint." ) SBBreakpointLocation; class SBBreakpointLocation diff --git a/contrib/llvm-project/lldb/bindings/interface/SBBreakpointName.i b/contrib/llvm-project/lldb/bindings/interface/SBBreakpointName.i index e280d4224591..c0fdcc748988 100644 --- a/contrib/llvm-project/lldb/bindings/interface/SBBreakpointName.i +++ b/contrib/llvm-project/lldb/bindings/interface/SBBreakpointName.i @@ -8,12 +8,12 @@ namespace lldb { %feature("docstring", -"Represents a breakpoint name registered in a given SBTarget. +"Represents a breakpoint name registered in a given :py:class:`SBTarget`. Breakpoint names provide a way to act on groups of breakpoints. When you add a name to a group of breakpoints, you can then use the name in all the command line lldb commands for that name. You can also configure the SBBreakpointName -options and those options will be propagated to any SBBreakpoints currently +options and those options will be propagated to any :py:class:`SBBreakpoint` s currently using that name. Adding a name to a breakpoint will also apply any of the set options to that breakpoint. diff --git a/contrib/llvm-project/lldb/bindings/interface/SBBroadcaster.i b/contrib/llvm-project/lldb/bindings/interface/SBBroadcaster.i index 79100e171b49..e97d8f964bde 100644 --- a/contrib/llvm-project/lldb/bindings/interface/SBBroadcaster.i +++ b/contrib/llvm-project/lldb/bindings/interface/SBBroadcaster.i @@ -9,9 +9,11 @@ namespace lldb { %feature("docstring", -"Represents an entity which can broadcast events. A default broadcaster is +"Represents an entity which can broadcast events. + +A default broadcaster is associated with an SBCommandInterpreter, SBProcess, and SBTarget. For -example, use +example, use :: broadcaster = process.GetBroadcaster() diff --git a/contrib/llvm-project/lldb/bindings/interface/SBCommandInterpreter.i b/contrib/llvm-project/lldb/bindings/interface/SBCommandInterpreter.i index 498084ae3ab1..b9a32716cfd6 100644 --- a/contrib/llvm-project/lldb/bindings/interface/SBCommandInterpreter.i +++ b/contrib/llvm-project/lldb/bindings/interface/SBCommandInterpreter.i @@ -9,9 +9,11 @@ namespace lldb { %feature("docstring", -"SBCommandInterpreter handles/interprets commands for lldb. You get the -command interpreter from the SBDebugger instance. For example (from test/ -python_api/interpreter/TestCommandInterpreterAPI.py), +"SBCommandInterpreter handles/interprets commands for lldb. + +You get the command interpreter from the :py:class:`SBDebugger` instance. + +For example (from test/ python_api/interpreter/TestCommandInterpreterAPI.py),:: def command_interpreter_api(self): '''Test the SBCommandInterpreter APIs.''' diff --git a/contrib/llvm-project/lldb/bindings/interface/SBCommandInterpreterRunOptions.i b/contrib/llvm-project/lldb/bindings/interface/SBCommandInterpreterRunOptions.i index f9ccbbd24dbe..1a618a228bbe 100644 --- a/contrib/llvm-project/lldb/bindings/interface/SBCommandInterpreterRunOptions.i +++ b/contrib/llvm-project/lldb/bindings/interface/SBCommandInterpreterRunOptions.i @@ -10,13 +10,15 @@ namespace lldb { %feature("docstring", "SBCommandInterpreterRunOptions controls how the RunCommandInterpreter runs the code it is fed. + A default SBCommandInterpreterRunOptions object has: - StopOnContinue: false - StopOnError: false - StopOnCrash: false - EchoCommands: true - PrintResults: true - AddToHistory: true + +* StopOnContinue: false +* StopOnError: false +* StopOnCrash: false +* EchoCommands: true +* PrintResults: true +* AddToHistory: true ") SBCommandInterpreterRunOptions; class SBCommandInterpreterRunOptions diff --git a/contrib/llvm-project/lldb/bindings/interface/SBCommandReturnObject.i b/contrib/llvm-project/lldb/bindings/interface/SBCommandReturnObject.i index affa16520f28..b07ef1c5eb1c 100644 --- a/contrib/llvm-project/lldb/bindings/interface/SBCommandReturnObject.i +++ b/contrib/llvm-project/lldb/bindings/interface/SBCommandReturnObject.i @@ -10,10 +10,10 @@ namespace lldb { %feature("docstring", "Represents a container which holds the result from command execution. -It works with SBCommandInterpreter.HandleCommand() to encapsulate the result +It works with :py:class:`SBCommandInterpreter.HandleCommand()` to encapsulate the result of command execution. -See SBCommandInterpreter for example usage of SBCommandReturnObject." +See :py:class:`SBCommandInterpreter` for example usage of SBCommandReturnObject." ) SBCommandReturnObject; class SBCommandReturnObject { diff --git a/contrib/llvm-project/lldb/bindings/interface/SBCommunication.i b/contrib/llvm-project/lldb/bindings/interface/SBCommunication.i index 87d3d0c9c5e4..8611e83e92ad 100644 --- a/contrib/llvm-project/lldb/bindings/interface/SBCommunication.i +++ b/contrib/llvm-project/lldb/bindings/interface/SBCommunication.i @@ -8,6 +8,9 @@ namespace lldb { +%feature("docstring", +"Allows sending/receiving data." +) SBCommunication; class SBCommunication { public: diff --git a/contrib/llvm-project/lldb/bindings/interface/SBCompileUnit.i b/contrib/llvm-project/lldb/bindings/interface/SBCompileUnit.i index d6a4c07038c6..4c8efaedb7dc 100644 --- a/contrib/llvm-project/lldb/bindings/interface/SBCompileUnit.i +++ b/contrib/llvm-project/lldb/bindings/interface/SBCompileUnit.i @@ -11,7 +11,7 @@ namespace lldb { %feature("docstring", "Represents a compilation unit, or compiled source file. -SBCompileUnit supports line entry iteration. For example, +SBCompileUnit supports line entry iteration. For example,:: # Now get the SBSymbolContext from this frame. We want everything. :-) context = frame0.GetSymbolContext(lldb.eSymbolContextEverything) @@ -25,23 +25,23 @@ SBCompileUnit supports line entry iteration. For example, print('start addr: %s' % str(lineEntry.GetStartAddress())) print('end addr: %s' % str(lineEntry.GetEndAddress())) -produces: - -line entry: /Volumes/data/lldb/svn/trunk/test/python_api/symbol-context/main.c:20 -start addr: a.out[0x100000d98] -end addr: a.out[0x100000da3] -line entry: /Volumes/data/lldb/svn/trunk/test/python_api/symbol-context/main.c:21 -start addr: a.out[0x100000da3] -end addr: a.out[0x100000da9] -line entry: /Volumes/data/lldb/svn/trunk/test/python_api/symbol-context/main.c:22 -start addr: a.out[0x100000da9] -end addr: a.out[0x100000db6] -line entry: /Volumes/data/lldb/svn/trunk/test/python_api/symbol-context/main.c:23 -start addr: a.out[0x100000db6] -end addr: a.out[0x100000dbc] -... - -See also SBSymbolContext and SBLineEntry" +produces: :: + + line entry: /Volumes/data/lldb/svn/trunk/test/python_api/symbol-context/main.c:20 + start addr: a.out[0x100000d98] + end addr: a.out[0x100000da3] + line entry: /Volumes/data/lldb/svn/trunk/test/python_api/symbol-context/main.c:21 + start addr: a.out[0x100000da3] + end addr: a.out[0x100000da9] + line entry: /Volumes/data/lldb/svn/trunk/test/python_api/symbol-context/main.c:22 + start addr: a.out[0x100000da9] + end addr: a.out[0x100000db6] + line entry: /Volumes/data/lldb/svn/trunk/test/python_api/symbol-context/main.c:23 + start addr: a.out[0x100000db6] + end addr: a.out[0x100000dbc] + ... + +See also :py:class:`SBSymbolContext` and :py:class:`SBLineEntry`" ) SBCompileUnit; class SBCompileUnit { diff --git a/contrib/llvm-project/lldb/bindings/interface/SBData.i b/contrib/llvm-project/lldb/bindings/interface/SBData.i index 3e74240329e0..a1fb4472cd23 100644 --- a/contrib/llvm-project/lldb/bindings/interface/SBData.i +++ b/contrib/llvm-project/lldb/bindings/interface/SBData.i @@ -9,6 +9,9 @@ namespace lldb { +%feature("docstring", +"Represents a data buffer." +) SBData; class SBData { public: diff --git a/contrib/llvm-project/lldb/bindings/interface/SBDebugger.i b/contrib/llvm-project/lldb/bindings/interface/SBDebugger.i index f2e23a7ed780..cf4411980cc3 100644 --- a/contrib/llvm-project/lldb/bindings/interface/SBDebugger.i +++ b/contrib/llvm-project/lldb/bindings/interface/SBDebugger.i @@ -12,108 +12,108 @@ namespace lldb { "SBDebugger is the primordial object that creates SBTargets and provides access to them. It also manages the overall debugging experiences. -For example (from example/disasm.py), - -import lldb -import os -import sys - -def disassemble_instructions (insts): - for i in insts: - print i - -... - -# Create a new debugger instance -debugger = lldb.SBDebugger.Create() - -# When we step or continue, don't return from the function until the process -# stops. We do this by setting the async mode to false. -debugger.SetAsync (False) - -# Create a target from a file and arch -print('Creating a target for \'%s\'' % exe) - -target = debugger.CreateTargetWithFileAndArch (exe, lldb.LLDB_ARCH_DEFAULT) - -if target: - # If the target is valid set a breakpoint at main - main_bp = target.BreakpointCreateByName (fname, target.GetExecutable().GetFilename()); - - print main_bp - - # Launch the process. Since we specified synchronous mode, we won't return - # from this function until we hit the breakpoint at main - process = target.LaunchSimple (None, None, os.getcwd()) - - # Make sure the launch went ok - if process: - # Print some simple process info - state = process.GetState () - print process - if state == lldb.eStateStopped: - # Get the first thread - thread = process.GetThreadAtIndex (0) - if thread: - # Print some simple thread info - print thread - # Get the first frame - frame = thread.GetFrameAtIndex (0) - if frame: - # Print some simple frame info - print frame - function = frame.GetFunction() - # See if we have debug info (a function) - if function: - # We do have a function, print some info for the function - print function - # Now get all instructions for this function and print them - insts = function.GetInstructions(target) - disassemble_instructions (insts) - else: - # See if we have a symbol in the symbol table for where we stopped - symbol = frame.GetSymbol(); - if symbol: - # We do have a symbol, print some info for the symbol - print symbol - # Now get all instructions for this symbol and print them - insts = symbol.GetInstructions(target) +For example (from example/disasm.py),:: + + import lldb + import os + import sys + + def disassemble_instructions (insts): + for i in insts: + print i + + ... + + # Create a new debugger instance + debugger = lldb.SBDebugger.Create() + + # When we step or continue, don't return from the function until the process + # stops. We do this by setting the async mode to false. + debugger.SetAsync (False) + + # Create a target from a file and arch + print('Creating a target for \'%s\'' % exe) + + target = debugger.CreateTargetWithFileAndArch (exe, lldb.LLDB_ARCH_DEFAULT) + + if target: + # If the target is valid set a breakpoint at main + main_bp = target.BreakpointCreateByName (fname, target.GetExecutable().GetFilename()); + + print main_bp + + # Launch the process. Since we specified synchronous mode, we won't return + # from this function until we hit the breakpoint at main + process = target.LaunchSimple (None, None, os.getcwd()) + + # Make sure the launch went ok + if process: + # Print some simple process info + state = process.GetState () + print process + if state == lldb.eStateStopped: + # Get the first thread + thread = process.GetThreadAtIndex (0) + if thread: + # Print some simple thread info + print thread + # Get the first frame + frame = thread.GetFrameAtIndex (0) + if frame: + # Print some simple frame info + print frame + function = frame.GetFunction() + # See if we have debug info (a function) + if function: + # We do have a function, print some info for the function + print function + # Now get all instructions for this function and print them + insts = function.GetInstructions(target) disassemble_instructions (insts) - - registerList = frame.GetRegisters() - print('Frame registers (size of register set = %d):' % registerList.GetSize()) - for value in registerList: - #print value - print('%s (number of children = %d):' % (value.GetName(), value.GetNumChildren())) - for child in value: - print('Name: ', child.GetName(), ' Value: ', child.GetValue()) - - print('Hit the breakpoint at main, enter to continue and wait for program to exit or \'Ctrl-D\'/\'quit\' to terminate the program') - next = sys.stdin.readline() - if not next or next.rstrip('\n') == 'quit': - print('Terminating the inferior process...') - process.Kill() + else: + # See if we have a symbol in the symbol table for where we stopped + symbol = frame.GetSymbol(); + if symbol: + # We do have a symbol, print some info for the symbol + print symbol + # Now get all instructions for this symbol and print them + insts = symbol.GetInstructions(target) + disassemble_instructions (insts) + + registerList = frame.GetRegisters() + print('Frame registers (size of register set = %d):' % registerList.GetSize()) + for value in registerList: + #print value + print('%s (number of children = %d):' % (value.GetName(), value.GetNumChildren())) + for child in value: + print('Name: ', child.GetName(), ' Value: ', child.GetValue()) + + print('Hit the breakpoint at main, enter to continue and wait for program to exit or \'Ctrl-D\'/\'quit\' to terminate the program') + next = sys.stdin.readline() + if not next or next.rstrip('\\n') == 'quit': + print('Terminating the inferior process...') + process.Kill() + else: + # Now continue to the program exit + process.Continue() + # When we return from the above function we will hopefully be at the + # program exit. Print out some process info + print process + elif state == lldb.eStateExited: + print('Didn\'t hit the breakpoint at main, program has exited...') else: - # Now continue to the program exit - process.Continue() - # When we return from the above function we will hopefully be at the - # program exit. Print out some process info - print process - elif state == lldb.eStateExited: - print('Didn\'t hit the breakpoint at main, program has exited...') - else: - print('Unexpected process state: %s, killing process...' % debugger.StateAsCString (state)) - process.Kill() + print('Unexpected process state: %s, killing process...' % debugger.StateAsCString (state)) + process.Kill() Sometimes you need to create an empty target that will get filled in later. The most common use for this is to attach to a process by name or pid where you don't know the executable up front. The most convenient way -to do this is: +to do this is: :: -target = debugger.CreateTarget('') -error = lldb.SBError() -process = target.AttachToProcessWithName(debugger.GetListener(), 'PROCESS_NAME', False, error) + target = debugger.CreateTarget('') + error = lldb.SBError() + process = target.AttachToProcessWithName(debugger.GetListener(), 'PROCESS_NAME', False, error) -or the equivalent arguments for AttachToProcessWithID.") SBDebugger; +or the equivalent arguments for :py:class:`SBTarget.AttachToProcessWithID` .") SBDebugger; class SBDebugger { public: @@ -498,12 +498,12 @@ A tuple with the number of errors encountered by the interpreter, a boolean indicating whether quitting the interpreter was requested and another boolean set to True in case of a crash. -Example: +Example: :: -# Start an interactive lldb session from a script (with a valid debugger object -# created beforehand): -n_errors, quit_requested, has_crashed = debugger.RunCommandInterpreter(True, - False, lldb.SBCommandInterpreterRunOptions(), 0, False, False)") RunCommandInterpreter; + # Start an interactive lldb session from a script (with a valid debugger object + # created beforehand): + n_errors, quit_requested, has_crashed = debugger.RunCommandInterpreter(True, + False, lldb.SBCommandInterpreterRunOptions(), 0, False, False)") RunCommandInterpreter; %apply int& INOUT { int& num_errors }; %apply bool& INOUT { bool& quit_requested }; %apply bool& INOUT { bool& stopped_for_crash }; diff --git a/contrib/llvm-project/lldb/bindings/interface/SBEnvironment.i b/contrib/llvm-project/lldb/bindings/interface/SBEnvironment.i index 4ca22fc314d2..daf25bc26d9c 100644 --- a/contrib/llvm-project/lldb/bindings/interface/SBEnvironment.i +++ b/contrib/llvm-project/lldb/bindings/interface/SBEnvironment.i @@ -11,7 +11,8 @@ namespace lldb { %feature("docstring", "Represents the environment of a certain process. -Example: +Example: :: + for entry in lldb.debugger.GetSelectedTarget().GetEnvironment().GetEntries(): print(entry) diff --git a/contrib/llvm-project/lldb/bindings/interface/SBError.i b/contrib/llvm-project/lldb/bindings/interface/SBError.i index ea48e2263a77..5af6b4856bd8 100644 --- a/contrib/llvm-project/lldb/bindings/interface/SBError.i +++ b/contrib/llvm-project/lldb/bindings/interface/SBError.i @@ -11,7 +11,7 @@ namespace lldb { %feature("docstring", "Represents a container for holding any error code. -For example (from test/python_api/hello_world/TestHelloWorld.py), +For example (from test/python_api/hello_world/TestHelloWorld.py), :: def hello_world_attach_with_id_api(self): '''Create target, spawn a process, and attach to it by id.''' @@ -45,7 +45,7 @@ For example (from test/python_api/hello_world/TestHelloWorld.py), checks that after the attach, there is no error condition by asserting that error.Success() is True and we get back a valid process object. -And (from test/python_api/event/TestEvent.py), +And (from test/python_api/event/TestEvent.py), :: # Now launch the process, and do not stop at entry point. error = lldb.SBError() diff --git a/contrib/llvm-project/lldb/bindings/interface/SBEvent.i b/contrib/llvm-project/lldb/bindings/interface/SBEvent.i index 99aa5319e371..2ebf599eb893 100644 --- a/contrib/llvm-project/lldb/bindings/interface/SBEvent.i +++ b/contrib/llvm-project/lldb/bindings/interface/SBEvent.i @@ -13,27 +13,27 @@ class SBBroadcaster; %feature("docstring", "API clients can register to receive events. -For example, check out the following output: +For example, check out the following output: :: -Try wait for event... -Event description: 0x103d0bb70 Event: broadcaster = 0x1009c8410, type = 0x00000001, data = { process = 0x1009c8400 (pid = 21528), state = running} -Event data flavor: Process::ProcessEventData -Process state: running + Try wait for event... + Event description: 0x103d0bb70 Event: broadcaster = 0x1009c8410, type = 0x00000001, data = { process = 0x1009c8400 (pid = 21528), state = running} + Event data flavor: Process::ProcessEventData + Process state: running -Try wait for event... -Event description: 0x103a700a0 Event: broadcaster = 0x1009c8410, type = 0x00000001, data = { process = 0x1009c8400 (pid = 21528), state = stopped} -Event data flavor: Process::ProcessEventData -Process state: stopped + Try wait for event... + Event description: 0x103a700a0 Event: broadcaster = 0x1009c8410, type = 0x00000001, data = { process = 0x1009c8400 (pid = 21528), state = stopped} + Event data flavor: Process::ProcessEventData + Process state: stopped -Try wait for event... -Event description: 0x103d0d4a0 Event: broadcaster = 0x1009c8410, type = 0x00000001, data = { process = 0x1009c8400 (pid = 21528), state = exited} -Event data flavor: Process::ProcessEventData -Process state: exited + Try wait for event... + Event description: 0x103d0d4a0 Event: broadcaster = 0x1009c8410, type = 0x00000001, data = { process = 0x1009c8400 (pid = 21528), state = exited} + Event data flavor: Process::ProcessEventData + Process state: exited -Try wait for event... -timeout occurred waiting for event... + Try wait for event... + timeout occurred waiting for event... -from test/python_api/event/TestEventspy: +from test/python_api/event/TestEventspy: :: def do_listen_for_and_print_event(self): '''Create a listener and use SBEvent API to print the events received.''' diff --git a/contrib/llvm-project/lldb/bindings/interface/SBExecutionContext.i b/contrib/llvm-project/lldb/bindings/interface/SBExecutionContext.i index 46968d04ae32..5fc5c0571182 100644 --- a/contrib/llvm-project/lldb/bindings/interface/SBExecutionContext.i +++ b/contrib/llvm-project/lldb/bindings/interface/SBExecutionContext.i @@ -8,6 +8,9 @@ namespace lldb { +%feature("docstring", +"Describes the program context in which a command should be executed." +) SBExecutionContext; class SBExecutionContext { public: diff --git a/contrib/llvm-project/lldb/bindings/interface/SBFile.i b/contrib/llvm-project/lldb/bindings/interface/SBFile.i index c86c5f26f147..4a2f58e0e78f 100644 --- a/contrib/llvm-project/lldb/bindings/interface/SBFile.i +++ b/contrib/llvm-project/lldb/bindings/interface/SBFile.i @@ -93,7 +93,7 @@ public: If there is no underlying python file to unwrap, GetFile will use the file descriptor, if available to create a new python - file object using `open(fd, mode=..., closefd=False)` + file object using ``open(fd, mode=..., closefd=False)`` "); FileSP GetFile(); }; diff --git a/contrib/llvm-project/lldb/bindings/interface/SBFileSpec.i b/contrib/llvm-project/lldb/bindings/interface/SBFileSpec.i index d287a940c051..b549321487ec 100644 --- a/contrib/llvm-project/lldb/bindings/interface/SBFileSpec.i +++ b/contrib/llvm-project/lldb/bindings/interface/SBFileSpec.i @@ -13,7 +13,7 @@ namespace lldb { basename. The string values of the paths are put into uniqued string pools for fast comparisons and efficient memory usage. -For example, the following code +For example, the following code :: lineEntry = context.GetLineEntry() self.expect(lineEntry.GetFileSpec().GetDirectory(), 'The line entry should have the correct directory', diff --git a/contrib/llvm-project/lldb/bindings/interface/SBFileSpecList.i b/contrib/llvm-project/lldb/bindings/interface/SBFileSpecList.i index 96641613f459..384dd4c4ae08 100644 --- a/contrib/llvm-project/lldb/bindings/interface/SBFileSpecList.i +++ b/contrib/llvm-project/lldb/bindings/interface/SBFileSpecList.i @@ -8,6 +8,9 @@ namespace lldb { +%feature("docstring", +"Represents a list of :py:class:`SBFileSpec`." +) SBFileSpecList; class SBFileSpecList { public: diff --git a/contrib/llvm-project/lldb/bindings/interface/SBFrame.i b/contrib/llvm-project/lldb/bindings/interface/SBFrame.i index c65b88f863e7..7bbf63c713f3 100644 --- a/contrib/llvm-project/lldb/bindings/interface/SBFrame.i +++ b/contrib/llvm-project/lldb/bindings/interface/SBFrame.i @@ -10,34 +10,35 @@ namespace lldb { %feature("docstring", "Represents one of the stack frames associated with a thread. -SBThread contains SBFrame(s). For example (from test/lldbutil.py), -def print_stacktrace(thread, string_buffer = False): - '''Prints a simple stack trace of this thread.''' +SBThread contains SBFrame(s). For example (from test/lldbutil.py), :: - ... + def print_stacktrace(thread, string_buffer = False): + '''Prints a simple stack trace of this thread.''' - for i in range(depth): - frame = thread.GetFrameAtIndex(i) - function = frame.GetFunction() + ... - load_addr = addrs[i].GetLoadAddress(target) - if not function: - file_addr = addrs[i].GetFileAddress() - start_addr = frame.GetSymbol().GetStartAddress().GetFileAddress() - symbol_offset = file_addr - start_addr - print >> output, ' frame #{num}: {addr:#016x} {mod}`{symbol} + {offset}'.format( - num=i, addr=load_addr, mod=mods[i], symbol=symbols[i], offset=symbol_offset) - else: - print >> output, ' frame #{num}: {addr:#016x} {mod}`{func} at {file}:{line} {args}'.format( - num=i, addr=load_addr, mod=mods[i], - func='%s [inlined]' % funcs[i] if frame.IsInlined() else funcs[i], - file=files[i], line=lines[i], - args=get_args_as_string(frame, showFuncName=False) if not frame.IsInlined() else '()') + for i in range(depth): + frame = thread.GetFrameAtIndex(i) + function = frame.GetFunction() - ... + load_addr = addrs[i].GetLoadAddress(target) + if not function: + file_addr = addrs[i].GetFileAddress() + start_addr = frame.GetSymbol().GetStartAddress().GetFileAddress() + symbol_offset = file_addr - start_addr + print >> output, ' frame #{num}: {addr:#016x} {mod}`{symbol} + {offset}'.format( + num=i, addr=load_addr, mod=mods[i], symbol=symbols[i], offset=symbol_offset) + else: + print >> output, ' frame #{num}: {addr:#016x} {mod}`{func} at {file}:{line} {args}'.format( + num=i, addr=load_addr, mod=mods[i], + func='%s [inlined]' % funcs[i] if frame.IsInlined() else funcs[i], + file=files[i], line=lines[i], + args=get_args_as_string(frame, showFuncName=False) if not frame.IsInlined() else '()') + + ... -And, +And, :: for frame in thread: print frame @@ -246,20 +247,27 @@ public: %feature("docstring", " Get a lldb.SBValue for a variable path. - Variable paths can include access to pointer or instance members: + Variable paths can include access to pointer or instance members: :: + rect_ptr->origin.y pt.x - Pointer dereferences: + + Pointer dereferences: :: + *this->foo_ptr **argv - Address of: + + Address of: :: + &pt &my_array[3].x - Array accesses and treating pointers as arrays: + + Array accesses and treating pointers as arrays: :: + int_array[1] pt_ptr[22].x - Unlike EvaluateExpression() which returns lldb.SBValue objects + Unlike `EvaluateExpression()` which returns :py:class:`SBValue` objects with constant copies of the values at the time of evaluation, the result of this function is a value that will continue to track the current value of the value as execution progresses @@ -274,7 +282,7 @@ public: Find variables, register sets, registers, or persistent variables using the frame as the scope. - The version that doesn't supply a 'use_dynamic' value will use the + The version that doesn't supply a ``use_dynamic`` value will use the target's default.") FindValue; lldb::SBValue FindValue (const char *name, ValueType value_type); diff --git a/contrib/llvm-project/lldb/bindings/interface/SBFunction.i b/contrib/llvm-project/lldb/bindings/interface/SBFunction.i index 630c4db22c55..dec073e9e12f 100644 --- a/contrib/llvm-project/lldb/bindings/interface/SBFunction.i +++ b/contrib/llvm-project/lldb/bindings/interface/SBFunction.i @@ -11,7 +11,7 @@ namespace lldb { %feature("docstring", "Represents a generic function, which can be inlined or not. -For example (from test/lldbutil.py, but slightly modified for doc purpose), +For example (from test/lldbutil.py, but slightly modified for doc purpose),:: ... diff --git a/contrib/llvm-project/lldb/bindings/interface/SBHostOS.i b/contrib/llvm-project/lldb/bindings/interface/SBHostOS.i index 14f4186cb9f3..791fa5a2085e 100644 --- a/contrib/llvm-project/lldb/bindings/interface/SBHostOS.i +++ b/contrib/llvm-project/lldb/bindings/interface/SBHostOS.i @@ -8,6 +8,9 @@ namespace lldb { +%feature("docstring", +"Provides information about the host system." +) SBHostOS; class SBHostOS { public: diff --git a/contrib/llvm-project/lldb/bindings/interface/SBInstruction.i b/contrib/llvm-project/lldb/bindings/interface/SBInstruction.i index d50a080fd045..e9e018b7deed 100644 --- a/contrib/llvm-project/lldb/bindings/interface/SBInstruction.i +++ b/contrib/llvm-project/lldb/bindings/interface/SBInstruction.i @@ -13,6 +13,9 @@ namespace lldb { +%feature("docstring", +"Represents a (machine language) instruction." +) SBInstruction; class SBInstruction { public: diff --git a/contrib/llvm-project/lldb/bindings/interface/SBInstructionList.i b/contrib/llvm-project/lldb/bindings/interface/SBInstructionList.i index 135732302757..b51c0374c3ad 100644 --- a/contrib/llvm-project/lldb/bindings/interface/SBInstructionList.i +++ b/contrib/llvm-project/lldb/bindings/interface/SBInstructionList.i @@ -14,12 +14,12 @@ namespace lldb { "Represents a list of machine instructions. SBFunction and SBSymbol have GetInstructions() methods which return SBInstructionList instances. -SBInstructionList supports instruction (SBInstruction instance) iteration. -For example (see also SBDebugger for a more complete example), +SBInstructionList supports instruction (:py:class:`SBInstruction` instance) iteration. +For example (see also :py:class:`SBDebugger` for a more complete example), :: -def disassemble_instructions (insts): - for i in insts: - print i + def disassemble_instructions (insts): + for i in insts: + print i defines a function which takes an SBInstructionList instance and prints out the machine instructions in assembly format." diff --git a/contrib/llvm-project/lldb/bindings/interface/SBLanguageRuntime.i b/contrib/llvm-project/lldb/bindings/interface/SBLanguageRuntime.i index f28170b9ce77..d8698ee36c0d 100644 --- a/contrib/llvm-project/lldb/bindings/interface/SBLanguageRuntime.i +++ b/contrib/llvm-project/lldb/bindings/interface/SBLanguageRuntime.i @@ -8,6 +8,9 @@ namespace lldb { +%feature("docstring", +"Utility functions for :ref:`LanguageType`" +) SBLanguageRuntime; class SBLanguageRuntime { public: diff --git a/contrib/llvm-project/lldb/bindings/interface/SBLaunchInfo.i b/contrib/llvm-project/lldb/bindings/interface/SBLaunchInfo.i index 1de89b58b272..d76656ddd493 100644 --- a/contrib/llvm-project/lldb/bindings/interface/SBLaunchInfo.i +++ b/contrib/llvm-project/lldb/bindings/interface/SBLaunchInfo.i @@ -8,6 +8,9 @@ namespace lldb { +%feature("docstring", +"Describes how a target or program should be launched." +) SBLaunchInfo; class SBLaunchInfo { public: diff --git a/contrib/llvm-project/lldb/bindings/interface/SBLineEntry.i b/contrib/llvm-project/lldb/bindings/interface/SBLineEntry.i index be365377ba8b..24f25ed1b4e5 100644 --- a/contrib/llvm-project/lldb/bindings/interface/SBLineEntry.i +++ b/contrib/llvm-project/lldb/bindings/interface/SBLineEntry.i @@ -10,7 +10,9 @@ namespace lldb { %feature("docstring", "Specifies an association with a contiguous range of instructions and -a source file location. SBCompileUnit contains SBLineEntry(s). For example, +a source file location. + +:py:class:`SBCompileUnit` contains SBLineEntry(s). For example, :: for lineEntry in compileUnit: print('line entry: %s:%d' % (str(lineEntry.GetFileSpec()), @@ -18,23 +20,23 @@ a source file location. SBCompileUnit contains SBLineEntry(s). For example, print('start addr: %s' % str(lineEntry.GetStartAddress())) print('end addr: %s' % str(lineEntry.GetEndAddress())) -produces: - -line entry: /Volumes/data/lldb/svn/trunk/test/python_api/symbol-context/main.c:20 -start addr: a.out[0x100000d98] -end addr: a.out[0x100000da3] -line entry: /Volumes/data/lldb/svn/trunk/test/python_api/symbol-context/main.c:21 -start addr: a.out[0x100000da3] -end addr: a.out[0x100000da9] -line entry: /Volumes/data/lldb/svn/trunk/test/python_api/symbol-context/main.c:22 -start addr: a.out[0x100000da9] -end addr: a.out[0x100000db6] -line entry: /Volumes/data/lldb/svn/trunk/test/python_api/symbol-context/main.c:23 -start addr: a.out[0x100000db6] -end addr: a.out[0x100000dbc] -... - -See also SBCompileUnit." +produces: :: + + line entry: /Volumes/data/lldb/svn/trunk/test/python_api/symbol-context/main.c:20 + start addr: a.out[0x100000d98] + end addr: a.out[0x100000da3] + line entry: /Volumes/data/lldb/svn/trunk/test/python_api/symbol-context/main.c:21 + start addr: a.out[0x100000da3] + end addr: a.out[0x100000da9] + line entry: /Volumes/data/lldb/svn/trunk/test/python_api/symbol-context/main.c:22 + start addr: a.out[0x100000da9] + end addr: a.out[0x100000db6] + line entry: /Volumes/data/lldb/svn/trunk/test/python_api/symbol-context/main.c:23 + start addr: a.out[0x100000db6] + end addr: a.out[0x100000dbc] + ... + +See also :py:class:`SBCompileUnit` ." ) SBLineEntry; class SBLineEntry { diff --git a/contrib/llvm-project/lldb/bindings/interface/SBListener.i b/contrib/llvm-project/lldb/bindings/interface/SBListener.i index 535aef9f0ae7..9062e7534423 100644 --- a/contrib/llvm-project/lldb/bindings/interface/SBListener.i +++ b/contrib/llvm-project/lldb/bindings/interface/SBListener.i @@ -11,7 +11,7 @@ namespace lldb { %feature("docstring", "API clients can register its own listener to debugger events. -See aslo SBEvent for example usage of creating and adding a listener." +See also :py:class:`SBEvent` for example usage of creating and adding a listener." ) SBListener; class SBListener { diff --git a/contrib/llvm-project/lldb/bindings/interface/SBMemoryRegionInfoList.i b/contrib/llvm-project/lldb/bindings/interface/SBMemoryRegionInfoList.i index e408fc0f88b8..c2e74f1cd0dc 100644 --- a/contrib/llvm-project/lldb/bindings/interface/SBMemoryRegionInfoList.i +++ b/contrib/llvm-project/lldb/bindings/interface/SBMemoryRegionInfoList.i @@ -8,6 +8,9 @@ namespace lldb { +%feature("docstring", +"Represents a list of :py:class:`SBMemoryRegionInfo`." +) SBMemoryRegionInfoList; class SBMemoryRegionInfoList { public: diff --git a/contrib/llvm-project/lldb/bindings/interface/SBModule.i b/contrib/llvm-project/lldb/bindings/interface/SBModule.i index e902af0c49ce..606c9a5bbd0c 100644 --- a/contrib/llvm-project/lldb/bindings/interface/SBModule.i +++ b/contrib/llvm-project/lldb/bindings/interface/SBModule.i @@ -40,30 +40,30 @@ The module is designed to be able to select a single slice of an executable image as it would appear on disk and during program execution. -You can retrieve SBModule from SBSymbolContext, which in turn is available +You can retrieve SBModule from :py:class:`SBSymbolContext` , which in turn is available from SBFrame. -SBModule supports symbol iteration, for example, +SBModule supports symbol iteration, for example, :: for symbol in module: name = symbol.GetName() saddr = symbol.GetStartAddress() eaddr = symbol.GetEndAddress() -and rich comparison methods which allow the API program to use, +and rich comparison methods which allow the API program to use, :: if thisModule == thatModule: print('This module is the same as that module') to test module equality. A module also contains object file sections, namely -SBSection. SBModule supports section iteration through section_iter(), for -example, +:py:class:`SBSection` . SBModule supports section iteration through section_iter(), for +example, :: print('Number of sections: %d' % module.GetNumSections()) for sec in module.section_iter(): print(sec) -And to iterate the symbols within a SBSection, use symbol_in_section_iter(), +And to iterate the symbols within a SBSection, use symbol_in_section_iter(), :: # Iterates the text section and prints each symbols within each sub-section. for subsec in text_sec: @@ -72,7 +72,7 @@ And to iterate the symbols within a SBSection, use symbol_in_section_iter(), print(INDENT2 + repr(sym)) print(INDENT2 + 'symbol type: %s' % symbol_type_to_str(sym.GetType())) -produces this following output: +produces this following output: :: [0x0000000100001780-0x0000000100001d5c) a.out.__TEXT.__text id = {0x00000004}, name = 'mask_access(MaskAction, unsigned int)', range = [0x00000001000017c0-0x0000000100001870) @@ -204,15 +204,15 @@ public: GetCompileUnitAtIndex (uint32_t); %feature("docstring", " - Find compile units related to *this module and passed source + Find compile units related to this module and passed source file. @param[in] sb_file_spec - A lldb::SBFileSpec object that contains source file + A :py:class:`SBFileSpec` object that contains source file specification. @return - A lldb::SBSymbolContextList that gets filled in with all of + A :py:class:`SBSymbolContextList` that gets filled in with all of the symbol contexts for all the matches.") FindCompileUnits; lldb::SBSymbolContextList FindCompileUnits (const lldb::SBFileSpec &sb_file_spec); @@ -353,6 +353,17 @@ public: static uint32_t GetNumberAllocatedModules(); + %feature("docstring", " + Removes all modules which are no longer needed by any part of LLDB from + the module cache. + + This is an implementation detail exposed for testing and should not be + relied upon. Use SBDebugger::MemoryPressureDetected instead to reduce + LLDB's memory consumption during execution. + ") GarbageCollectAllocatedModules; + static void + GarbageCollectAllocatedModules(); + STRING_EXTENSION(SBModule) #ifdef SWIGPYTHON diff --git a/contrib/llvm-project/lldb/bindings/interface/SBModuleSpec.i b/contrib/llvm-project/lldb/bindings/interface/SBModuleSpec.i index 64d0aa641a77..8b4c6a92160a 100644 --- a/contrib/llvm-project/lldb/bindings/interface/SBModuleSpec.i +++ b/contrib/llvm-project/lldb/bindings/interface/SBModuleSpec.i @@ -95,6 +95,9 @@ public: }; +%feature("docstring", +"Represents a list of :py:class:`SBModuleSpec`." +) SBModuleSpecList; class SBModuleSpecList { public: diff --git a/contrib/llvm-project/lldb/bindings/interface/SBPlatform.i b/contrib/llvm-project/lldb/bindings/interface/SBPlatform.i index 81945222c059..65615be7a361 100644 --- a/contrib/llvm-project/lldb/bindings/interface/SBPlatform.i +++ b/contrib/llvm-project/lldb/bindings/interface/SBPlatform.i @@ -9,6 +9,9 @@ namespace lldb { +%feature("docstring", +"Describes how :py:class:`SBPlatform.ConnectRemote` connects to a remote platform." +) SBPlatformConnectOptions; class SBPlatformConnectOptions { public: @@ -42,9 +45,13 @@ public: SetLocalCacheDirectory(const char *path); }; +%feature("docstring", +"Represents a shell command that can be run by :py:class:`SBPlatform.Run`." +) SBPlatformShellCommand; class SBPlatformShellCommand { public: + SBPlatformShellCommand (const char *shell, const char *shell_command); SBPlatformShellCommand (const char *shell_command); SBPlatformShellCommand (const SBPlatformShellCommand &rhs); @@ -55,6 +62,12 @@ public: Clear(); const char * + GetShell(); + + void + SetShell(const char *shell_interpreter); + + const char * GetCommand(); void @@ -97,7 +110,7 @@ current processes on the remote host, attach to one of those processes, install programs on the remote system, attach and launch processes, and much more. -Every SBTarget has a corresponding SBPlatform. The platform can be +Every :py:class:`SBTarget` has a corresponding SBPlatform. The platform can be specified upon target creation, or the currently selected platform will attempt to be used when creating the target automatically as long as the currently selected platform matches the target architecture diff --git a/contrib/llvm-project/lldb/bindings/interface/SBProcess.i b/contrib/llvm-project/lldb/bindings/interface/SBProcess.i index b54c4629f9df..e30b89d1ed39 100644 --- a/contrib/llvm-project/lldb/bindings/interface/SBProcess.i +++ b/contrib/llvm-project/lldb/bindings/interface/SBProcess.i @@ -11,24 +11,22 @@ namespace lldb { %feature("docstring", "Represents the process associated with the target program. -SBProcess supports thread iteration. For example (from test/lldbutil.py), - -# ================================================== -# Utility functions related to Threads and Processes -# ================================================== - -def get_stopped_threads(process, reason): - '''Returns the thread(s) with the specified stop reason in a list. - - The list can be empty if no such thread exists. - ''' - threads = [] - for t in process: - if t.GetStopReason() == reason: - threads.append(t) - return threads - -... +SBProcess supports thread iteration. For example (from test/lldbutil.py), :: + + # ================================================== + # Utility functions related to Threads and Processes + # ================================================== + + def get_stopped_threads(process, reason): + '''Returns the thread(s) with the specified stop reason in a list. + + The list can be empty if no such thread exists. + ''' + threads = [] + for t in process: + if t.GetStopReason() == reason: + threads.append(t) + return threads " ) SBProcess; class SBProcess @@ -246,67 +244,67 @@ public: %feature("autodoc", " Reads memory from the current process's address space and removes any traps that may have been inserted into the memory. It returns the byte - buffer in a Python string. Example: + buffer in a Python string. Example: :: - # Read 4 bytes from address 'addr' and assume error.Success() is True. - content = process.ReadMemory(addr, 4, error) - new_bytes = bytearray(content)") ReadMemory; + # Read 4 bytes from address 'addr' and assume error.Success() is True. + content = process.ReadMemory(addr, 4, error) + new_bytes = bytearray(content)") ReadMemory; size_t ReadMemory (addr_t addr, void *buf, size_t size, lldb::SBError &error); %feature("autodoc", " Writes memory to the current process's address space and maintains any - traps that might be present due to software breakpoints. Example: + traps that might be present due to software breakpoints. Example: :: - # Create a Python string from the byte array. - new_value = str(bytes) - result = process.WriteMemory(addr, new_value, error) - if not error.Success() or result != len(bytes): - print('SBProcess.WriteMemory() failed!')") WriteMemory; + # Create a Python string from the byte array. + new_value = str(bytes) + result = process.WriteMemory(addr, new_value, error) + if not error.Success() or result != len(bytes): + print('SBProcess.WriteMemory() failed!')") WriteMemory; size_t WriteMemory (addr_t addr, const void *buf, size_t size, lldb::SBError &error); %feature("autodoc", " Reads a NULL terminated C string from the current process's address space. It returns a python string of the exact length, or truncates the string if - the maximum character limit is reached. Example: + the maximum character limit is reached. Example: :: - # Read a C string of at most 256 bytes from address '0x1000' - error = lldb.SBError() - cstring = process.ReadCStringFromMemory(0x1000, 256, error) - if error.Success(): - print('cstring: ', cstring) - else - print('error: ', error)") ReadCStringFromMemory; + # Read a C string of at most 256 bytes from address '0x1000' + error = lldb.SBError() + cstring = process.ReadCStringFromMemory(0x1000, 256, error) + if error.Success(): + print('cstring: ', cstring) + else + print('error: ', error)") ReadCStringFromMemory; size_t ReadCStringFromMemory (addr_t addr, void *char_buf, size_t size, lldb::SBError &error); %feature("autodoc", " Reads an unsigned integer from memory given a byte size and an address. - Returns the unsigned integer that was read. Example: + Returns the unsigned integer that was read. Example: :: - # Read a 4 byte unsigned integer from address 0x1000 - error = lldb.SBError() - uint = ReadUnsignedFromMemory(0x1000, 4, error) - if error.Success(): - print('integer: %u' % uint) - else - print('error: ', error)") ReadUnsignedFromMemory; + # Read a 4 byte unsigned integer from address 0x1000 + error = lldb.SBError() + uint = ReadUnsignedFromMemory(0x1000, 4, error) + if error.Success(): + print('integer: %u' % uint) + else + print('error: ', error)") ReadUnsignedFromMemory; uint64_t ReadUnsignedFromMemory (addr_t addr, uint32_t byte_size, lldb::SBError &error); %feature("autodoc", " - Reads a pointer from memory from an address and returns the value. Example: + Reads a pointer from memory from an address and returns the value. Example: :: - # Read a pointer from address 0x1000 - error = lldb.SBError() - ptr = ReadPointerFromMemory(0x1000, error) - if error.Success(): - print('pointer: 0x%x' % ptr) - else - print('error: ', error)") ReadPointerFromMemory; + # Read a pointer from address 0x1000 + error = lldb.SBError() + ptr = ReadPointerFromMemory(0x1000, error) + if error.Success(): + print('pointer: 0x%x' % ptr) + else + print('error: ', error)") ReadPointerFromMemory; lldb::addr_t ReadPointerFromMemory (addr_t addr, lldb::SBError &error); @@ -414,11 +412,11 @@ public: %feature("autodoc", " Get information about the process. Valid process info will only be returned when the process is alive, - use IsValid() to check if the info returned is valid. + use IsValid() to check if the info returned is valid. :: - process_info = process.GetProcessInfo() - if process_info.IsValid(): - process_info.GetProcessID()") GetProcessInfo; + process_info = process.GetProcessInfo() + if process_info.IsValid(): + process_info.GetProcessID()") GetProcessInfo; lldb::SBProcessInfo GetProcessInfo(); diff --git a/contrib/llvm-project/lldb/bindings/interface/SBQueue.i b/contrib/llvm-project/lldb/bindings/interface/SBQueue.i index f209d59f1bf9..9f2ec56b241c 100644 --- a/contrib/llvm-project/lldb/bindings/interface/SBQueue.i +++ b/contrib/llvm-project/lldb/bindings/interface/SBQueue.i @@ -8,6 +8,9 @@ namespace lldb { +%feature("docstring", +"Represents a libdispatch queue in the process." +) SBQueue; class SBQueue { public: diff --git a/contrib/llvm-project/lldb/bindings/interface/SBQueueItem.i b/contrib/llvm-project/lldb/bindings/interface/SBQueueItem.i index 089771e80378..2270d958e17d 100644 --- a/contrib/llvm-project/lldb/bindings/interface/SBQueueItem.i +++ b/contrib/llvm-project/lldb/bindings/interface/SBQueueItem.i @@ -8,6 +8,9 @@ namespace lldb { +%feature("docstring", +"This class represents an item in an :py:class:`SBQueue`." +) SBQueueItem; class SBQueueItem { public: diff --git a/contrib/llvm-project/lldb/bindings/interface/SBReproducer.i b/contrib/llvm-project/lldb/bindings/interface/SBReproducer.i index 7c9b007db3c0..bc9a5bab3cfa 100644 --- a/contrib/llvm-project/lldb/bindings/interface/SBReproducer.i +++ b/contrib/llvm-project/lldb/bindings/interface/SBReproducer.i @@ -7,6 +7,10 @@ //===----------------------------------------------------------------------===// namespace lldb { + +%feature("docstring", +"Controls LLDB's reproducer functionality." +) SBReproducer; class SBReproducer { public: diff --git a/contrib/llvm-project/lldb/bindings/interface/SBSection.i b/contrib/llvm-project/lldb/bindings/interface/SBSection.i index 3d1c900917fd..b86d4e99c5ea 100644 --- a/contrib/llvm-project/lldb/bindings/interface/SBSection.i +++ b/contrib/llvm-project/lldb/bindings/interface/SBSection.i @@ -12,7 +12,7 @@ namespace lldb { "Represents an executable image section. SBSection supports iteration through its subsection, represented as SBSection -as well. For example, +as well. For example, :: for sec in exe_module: if sec.GetName() == '__TEXT': @@ -22,18 +22,18 @@ as well. For example, for subsec in sec: print INDENT + repr(subsec) -produces: +produces: :: -[0x0000000100000000-0x0000000100002000) a.out.__TEXT - Number of subsections: 6 - [0x0000000100001780-0x0000000100001d5c) a.out.__TEXT.__text - [0x0000000100001d5c-0x0000000100001da4) a.out.__TEXT.__stubs - [0x0000000100001da4-0x0000000100001e2c) a.out.__TEXT.__stub_helper - [0x0000000100001e2c-0x0000000100001f10) a.out.__TEXT.__cstring - [0x0000000100001f10-0x0000000100001f68) a.out.__TEXT.__unwind_info - [0x0000000100001f68-0x0000000100001ff8) a.out.__TEXT.__eh_frame + [0x0000000100000000-0x0000000100002000) a.out.__TEXT + Number of subsections: 6 + [0x0000000100001780-0x0000000100001d5c) a.out.__TEXT.__text + [0x0000000100001d5c-0x0000000100001da4) a.out.__TEXT.__stubs + [0x0000000100001da4-0x0000000100001e2c) a.out.__TEXT.__stub_helper + [0x0000000100001e2c-0x0000000100001f10) a.out.__TEXT.__cstring + [0x0000000100001f10-0x0000000100001f68) a.out.__TEXT.__unwind_info + [0x0000000100001f68-0x0000000100001ff8) a.out.__TEXT.__eh_frame -See also SBModule." +See also :py:class:`SBModule` ." ) SBSection; class SBSection diff --git a/contrib/llvm-project/lldb/bindings/interface/SBSourceManager.i b/contrib/llvm-project/lldb/bindings/interface/SBSourceManager.i index dfbdc612a06e..12dd1bdb0d18 100644 --- a/contrib/llvm-project/lldb/bindings/interface/SBSourceManager.i +++ b/contrib/llvm-project/lldb/bindings/interface/SBSourceManager.i @@ -11,7 +11,7 @@ namespace lldb { %feature("docstring", "Represents a central authority for displaying source code. -For example (from test/source-manager/TestSourceManager.py), +For example (from test/source-manager/TestSourceManager.py), :: # Create the filespec for 'main.c'. filespec = lldb.SBFileSpec('main.c', False) diff --git a/contrib/llvm-project/lldb/bindings/interface/SBStream.i b/contrib/llvm-project/lldb/bindings/interface/SBStream.i index edd67f87c3fb..acf44e351d5f 100644 --- a/contrib/llvm-project/lldb/bindings/interface/SBStream.i +++ b/contrib/llvm-project/lldb/bindings/interface/SBStream.i @@ -14,7 +14,7 @@ namespace lldb { "Represents a destination for streaming data output to. By default, a string stream is created. -For example (from test/source-manager/TestSourceManager.py), +For example (from test/source-manager/TestSourceManager.py), :: # Create the filespec for 'main.c'. filespec = lldb.SBFileSpec('main.c', False) diff --git a/contrib/llvm-project/lldb/bindings/interface/SBStringList.i b/contrib/llvm-project/lldb/bindings/interface/SBStringList.i index c8e1e357ed2b..d80ae9f9c5b9 100644 --- a/contrib/llvm-project/lldb/bindings/interface/SBStringList.i +++ b/contrib/llvm-project/lldb/bindings/interface/SBStringList.i @@ -8,6 +8,9 @@ namespace lldb { +%feature("docstring", +"Represents a list of strings." +) SBStringList; class SBStringList { public: diff --git a/contrib/llvm-project/lldb/bindings/interface/SBStructuredData.i b/contrib/llvm-project/lldb/bindings/interface/SBStructuredData.i index c7601bf6cf95..5aba35229855 100644 --- a/contrib/llvm-project/lldb/bindings/interface/SBStructuredData.i +++ b/contrib/llvm-project/lldb/bindings/interface/SBStructuredData.i @@ -8,12 +8,11 @@ namespace lldb { - %feature("docstring", - "A class representing a StructuredData event. +%feature("docstring", + "A class representing a StructuredData event. - This class wraps the event type generated by StructuredData - features." - ) SBStructuredData; +This class wraps the event type generated by StructuredData features." +) SBStructuredData; class SBStructuredData { public: diff --git a/contrib/llvm-project/lldb/bindings/interface/SBSymbol.i b/contrib/llvm-project/lldb/bindings/interface/SBSymbol.i index 4e17ab5af0fd..fa0b3e4e1378 100644 --- a/contrib/llvm-project/lldb/bindings/interface/SBSymbol.i +++ b/contrib/llvm-project/lldb/bindings/interface/SBSymbol.i @@ -10,9 +10,7 @@ namespace lldb { %feature("docstring", "Represents the symbol possibly associated with a stack frame. -SBModule contains SBSymbol(s). SBSymbol can also be retrieved from SBFrame. - -See also SBModule and SBFrame." +:py:class:`SBModule` contains SBSymbol(s). SBSymbol can also be retrieved from :py:class:`SBFrame` ." ) SBSymbol; class SBSymbol { diff --git a/contrib/llvm-project/lldb/bindings/interface/SBSymbolContext.i b/contrib/llvm-project/lldb/bindings/interface/SBSymbolContext.i index b6b336516c94..9818fdb09498 100644 --- a/contrib/llvm-project/lldb/bindings/interface/SBSymbolContext.i +++ b/contrib/llvm-project/lldb/bindings/interface/SBSymbolContext.i @@ -15,7 +15,7 @@ Many debugger functions require a context when doing lookups. This class provides a common structure that can be used as the result of a query that can contain a single result. -For example, +For example, :: exe = os.path.join(os.getcwd(), 'a.out') diff --git a/contrib/llvm-project/lldb/bindings/interface/SBSymbolContextList.i b/contrib/llvm-project/lldb/bindings/interface/SBSymbolContextList.i index f5adcfcebfb5..e9d4aa8d62db 100644 --- a/contrib/llvm-project/lldb/bindings/interface/SBSymbolContextList.i +++ b/contrib/llvm-project/lldb/bindings/interface/SBSymbolContextList.i @@ -11,7 +11,7 @@ namespace lldb { %feature("docstring", "Represents a list of symbol context object. See also SBSymbolContext. -For example (from test/python_api/target/TestTargetAPI.py), +For example (from test/python_api/target/TestTargetAPI.py), :: def find_functions(self, exe_name): '''Exercise SBTaget.FindFunctions() API.''' diff --git a/contrib/llvm-project/lldb/bindings/interface/SBTarget.i b/contrib/llvm-project/lldb/bindings/interface/SBTarget.i index 57b5ccea6399..f874726b42d8 100644 --- a/contrib/llvm-project/lldb/bindings/interface/SBTarget.i +++ b/contrib/llvm-project/lldb/bindings/interface/SBTarget.i @@ -11,40 +11,40 @@ namespace lldb { %feature("docstring", "Represents the target program running under the debugger. -SBTarget supports module, breakpoint, and watchpoint iterations. For example, +SBTarget supports module, breakpoint, and watchpoint iterations. For example, :: for m in target.module_iter(): print m -produces: +produces: :: -(x86_64) /Volumes/data/lldb/svn/trunk/test/python_api/lldbutil/iter/a.out -(x86_64) /usr/lib/dyld -(x86_64) /usr/lib/libstdc++.6.dylib -(x86_64) /usr/lib/libSystem.B.dylib -(x86_64) /usr/lib/system/libmathCommon.A.dylib -(x86_64) /usr/lib/libSystem.B.dylib(__commpage) + (x86_64) /Volumes/data/lldb/svn/trunk/test/python_api/lldbutil/iter/a.out + (x86_64) /usr/lib/dyld + (x86_64) /usr/lib/libstdc++.6.dylib + (x86_64) /usr/lib/libSystem.B.dylib + (x86_64) /usr/lib/system/libmathCommon.A.dylib + (x86_64) /usr/lib/libSystem.B.dylib(__commpage) -and, +and, :: for b in target.breakpoint_iter(): print b -produces: +produces: :: -SBBreakpoint: id = 1, file ='main.cpp', line = 66, locations = 1 -SBBreakpoint: id = 2, file ='main.cpp', line = 85, locations = 1 + SBBreakpoint: id = 1, file ='main.cpp', line = 66, locations = 1 + SBBreakpoint: id = 2, file ='main.cpp', line = 85, locations = 1 -and, +and, :: for wp_loc in target.watchpoint_iter(): print wp_loc -produces: +produces: :: -Watchpoint 1: addr = 0x1034ca048 size = 4 state = enabled type = rw - declare @ '/Volumes/data/lldb/svn/trunk/test/python_api/watchpoint/main.c:12' - hw_index = 0 hit_count = 2 ignore_count = 0" + Watchpoint 1: addr = 0x1034ca048 size = 4 state = enabled type = rw + declare @ '/Volumes/data/lldb/svn/trunk/test/python_api/watchpoint/main.c:12' + hw_index = 0 hit_count = 2 ignore_count = 0" ) SBTarget; class SBTarget { @@ -208,30 +208,16 @@ public: %feature("docstring", " Launch a new process with sensible defaults. - @param[in] argv - The argument array. - - @param[in] envp - The environment array. - - @param[in] working_directory - The working directory to have the child process run in + :param argv: The argument array. + :param envp: The environment array. + :param working_directory: The working directory to have the child process run in + :return: The newly created process. + :rtype: SBProcess - Default: listener - Set to the target's debugger (SBTarget::GetDebugger()) + A pseudo terminal will be used as stdin/stdout/stderr. + No launch flags are passed and the target's debuger is used as a listener. - Default: launch_flags - Empty launch flags - - Default: stdin_path - Default: stdout_path - Default: stderr_path - A pseudo terminal will be used. - - @return - A process object for the newly created process. - - For example, + For example, :: process = target.LaunchSimple(['X', 'Y', 'Z'], None, os.getcwd()) @@ -389,16 +375,13 @@ public: FindModule (const lldb::SBFileSpec &file_spec); %feature("docstring", " - Find compile units related to *this target and passed source + Find compile units related to this target and passed source file. - @param[in] sb_file_spec - A lldb::SBFileSpec object that contains source file + :param sb_file_spec: A :py:class:`lldb::SBFileSpec` object that contains source file specification. - - @return - A lldb::SBSymbolContextList that gets filled in with all of - the symbol contexts for all the matches.") FindCompileUnits; + :return: The symbol contexts for all the matches. + :rtype: SBSymbolContextList") FindCompileUnits; lldb::SBSymbolContextList FindCompileUnits (const lldb::SBFileSpec &sb_file_spec); @@ -414,18 +397,18 @@ public: %feature("docstring", " Architecture data byte width accessor - @return - The size in 8-bit (host) bytes of a minimum addressable - unit from the Architecture's data bus") GetDataByteSize; + :return: The size in 8-bit (host) bytes of a minimum addressable unit from the Architecture's data bus. + + ") GetDataByteSize; uint32_t GetDataByteSize (); %feature("docstring", " - Architecture code byte width accessor + Architecture code byte width accessor. - @return - The size in 8-bit (host) bytes of a minimum addressable - unit from the Architecture's code bus") GetCodeByteSize; + :return: The size in 8-bit (host) bytes of a minimum addressable unit from the Architecture's code bus. + + ") GetCodeByteSize; uint32_t GetCodeByteSize (); @@ -446,17 +429,16 @@ public: %feature("docstring", " Find functions by name. - @param[in] name - The name of the function we are looking for. + :param name: The name of the function we are looking for. - @param[in] name_type_mask + :param name_type_mask: A logical OR of one or more FunctionNameType enum bits that indicate what kind of names should be used when doing the lookup. Bits include fully qualified names, base names, C++ methods, or ObjC selectors. See FunctionNameType for more details. - @return + :return: A lldb::SBSymbolContextList that gets filled in with all of the symbol contexts for all the matches.") FindFunctions; lldb::SBSymbolContextList @@ -580,6 +562,12 @@ public: SBFileSpecList &module_list); lldb::SBBreakpoint + BreakpointCreateByLocation (const lldb::SBFileSpec &file_spec, uint32_t line, + uint32_t column, lldb::addr_t offset, + SBFileSpecList &module_list, + bool move_to_nearest_code); + + lldb::SBBreakpoint BreakpointCreateByName (const char *symbol_name, const char *module_name = NULL); lldb::SBBreakpoint @@ -688,41 +676,42 @@ public: @param[in] class_name This is the name of the class that implements a scripted resolver. - The class should have the following signature: - class Resolver: - def __init__(self, bkpt, extra_args): - # bkpt - the breakpoint for which this is the resolver. When - # the resolver finds an interesting address, call AddLocation - # on this breakpoint to add it. - # - # extra_args - an SBStructuredData that can be used to - # parametrize this instance. Same as the extra_args passed - # to BreakpointCreateFromScript. - - def __get_depth__ (self): - # This is optional, but if defined, you should return the - # depth at which you want the callback to be called. The - # available options are: - # lldb.eSearchDepthModule - # lldb.eSearchDepthCompUnit - # The default if you don't implement this method is - # eSearchDepthModule. - - def __callback__(self, sym_ctx): - # sym_ctx - an SBSymbolContext that is the cursor in the - # search through the program to resolve breakpoints. - # The sym_ctx will be filled out to the depth requested in - # __get_depth__. - # Look in this sym_ctx for new breakpoint locations, - # and if found use bkpt.AddLocation to add them. - # Note, you will only get called for modules/compile_units that - # pass the SearchFilter provided by the module_list & file_list - # passed into BreakpointCreateFromScript. - - def get_short_help(self): - # Optional, but if implemented return a short string that will - # be printed at the beginning of the break list output for the - # breakpoint. + The class should have the following signature: :: + + class Resolver: + def __init__(self, bkpt, extra_args): + # bkpt - the breakpoint for which this is the resolver. When + # the resolver finds an interesting address, call AddLocation + # on this breakpoint to add it. + # + # extra_args - an SBStructuredData that can be used to + # parametrize this instance. Same as the extra_args passed + # to BreakpointCreateFromScript. + + def __get_depth__ (self): + # This is optional, but if defined, you should return the + # depth at which you want the callback to be called. The + # available options are: + # lldb.eSearchDepthModule + # lldb.eSearchDepthCompUnit + # The default if you don't implement this method is + # eSearchDepthModule. + + def __callback__(self, sym_ctx): + # sym_ctx - an SBSymbolContext that is the cursor in the + # search through the program to resolve breakpoints. + # The sym_ctx will be filled out to the depth requested in + # __get_depth__. + # Look in this sym_ctx for new breakpoint locations, + # and if found use bkpt.AddLocation to add them. + # Note, you will only get called for modules/compile_units that + # pass the SearchFilter provided by the module_list & file_list + # passed into BreakpointCreateFromScript. + + def get_short_help(self): + # Optional, but if implemented return a short string that will + # be printed at the beginning of the break list output for the + # breakpoint. @param[in] extra_args This is an SBStructuredData object that will get passed to the @@ -902,11 +891,12 @@ public: %feature("docstring", " Disassemble a specified number of instructions starting at an address. - Parameters: - base_addr -- the address to start disassembly from - count -- the number of instructions to disassemble - flavor_string -- may be 'intel' or 'att' on x86 targets to specify that style of disassembly - Returns an SBInstructionList.") + + :param base_addr: the address to start disassembly from. + :param count: the number of instructions to disassemble. + :param flavor_string: may be 'intel' or 'att' on x86 targets to specify that style of disassembly. + :rtype: SBInstructionList + ") ReadInstructions; lldb::SBInstructionList ReadInstructions (lldb::SBAddress base_addr, uint32_t count); @@ -916,23 +906,25 @@ public: %feature("docstring", " Disassemble the bytes in a buffer and return them in an SBInstructionList. - Parameters: - base_addr -- used for symbolicating the offsets in the byte stream when disassembling - buf -- bytes to be disassembled - size -- (C++) size of the buffer - Returns an SBInstructionList.") + + :param base_addr: used for symbolicating the offsets in the byte stream when disassembling. + :param buf: bytes to be disassembled. + :param size: (C++) size of the buffer. + :rtype: SBInstructionList + ") GetInstructions; lldb::SBInstructionList GetInstructions (lldb::SBAddress base_addr, const void *buf, size_t size); %feature("docstring", " Disassemble the bytes in a buffer and return them in an SBInstructionList, with a supplied flavor. - Parameters: - base_addr -- used for symbolicating the offsets in the byte stream when disassembling - flavor -- may be 'intel' or 'att' on x86 targets to specify that style of disassembly - buf -- bytes to be disassembled - size -- (C++) size of the buffer - Returns an SBInstructionList.") + + :param base_addr: used for symbolicating the offsets in the byte stream when disassembling. + :param flavor: may be 'intel' or 'att' on x86 targets to specify that style of disassembly. + :param buf: bytes to be disassembled. + :param size: (C++) size of the buffer. + :rtype: SBInstructionList + ") GetInstructionsWithFlavor; lldb::SBInstructionList GetInstructionsWithFlavor (lldb::SBAddress base_addr, const char *flavor_string, const void *buf, size_t size); diff --git a/contrib/llvm-project/lldb/bindings/interface/SBThread.i b/contrib/llvm-project/lldb/bindings/interface/SBThread.i index 66466b7947fd..463584d2cab1 100644 --- a/contrib/llvm-project/lldb/bindings/interface/SBThread.i +++ b/contrib/llvm-project/lldb/bindings/interface/SBThread.i @@ -9,7 +9,7 @@ namespace lldb { %feature("docstring", -"Represents a thread of execution. SBProcess contains SBThread(s). +"Represents a thread of execution. :py:class:`SBProcess` contains SBThread(s). SBThreads can be referred to by their ID, which maps to the system specific thread identifier, or by IndexID. The ID may or may not be unique depending on whether the @@ -18,7 +18,7 @@ that will always uniquely reference a particular thread, and when that thread go away it will not be reused. SBThread supports frame iteration. For example (from test/python_api/ -lldbutil/iter/TestLLDBIterator.py), +lldbutil/iter/TestLLDBIterator.py), :: from lldbutil import print_stacktrace stopped_due_to_breakpoint = False @@ -35,7 +35,7 @@ lldbutil/iter/TestLLDBIterator.py), self.assertTrue(stopped_due_to_breakpoint) -See also SBProcess and SBFrame." +See also :py:class:`SBFrame` ." ) SBThread; class SBThread { diff --git a/contrib/llvm-project/lldb/bindings/interface/SBThreadPlan.i b/contrib/llvm-project/lldb/bindings/interface/SBThreadPlan.i index 36131d529b7b..94ae1a42dd3b 100644 --- a/contrib/llvm-project/lldb/bindings/interface/SBThreadPlan.i +++ b/contrib/llvm-project/lldb/bindings/interface/SBThreadPlan.i @@ -18,8 +18,8 @@ namespace lldb { %feature("docstring", "Represents a plan for the execution control of a given thread. -See also SBThread and SBFrame." -) SBThread; +See also :py:class:`SBThread` and :py:class:`SBFrame`." +) SBThreadPlan; class SBThreadPlan { @@ -92,6 +92,14 @@ public: bool IsPlanStale(); + %feature("docstring", "Return whether this plan will ask to stop other threads when it runs.") GetStopOthers; + bool + GetStopOthers(); + + %feature("docstring", "Set whether this plan will ask to stop other threads when it runs.") GetStopOthers; + void + SetStopOthers(bool stop_others); + SBThreadPlan QueueThreadPlanForStepOverRange (SBAddress &start_address, lldb::addr_t range_size); diff --git a/contrib/llvm-project/lldb/bindings/interface/SBTrace.i b/contrib/llvm-project/lldb/bindings/interface/SBTrace.i index a4cb2667ec10..6d4b7e6be27d 100644 --- a/contrib/llvm-project/lldb/bindings/interface/SBTrace.i +++ b/contrib/llvm-project/lldb/bindings/interface/SBTrace.i @@ -8,6 +8,9 @@ namespace lldb { +%feature("docstring", +"Represents a processor trace." +) SBTrace; class LLDB_API SBTrace { public: SBTrace(); diff --git a/contrib/llvm-project/lldb/bindings/interface/SBTraceOptions.i b/contrib/llvm-project/lldb/bindings/interface/SBTraceOptions.i index ce17af5376ca..4a1878b5b76f 100644 --- a/contrib/llvm-project/lldb/bindings/interface/SBTraceOptions.i +++ b/contrib/llvm-project/lldb/bindings/interface/SBTraceOptions.i @@ -8,6 +8,11 @@ namespace lldb { +%feature("docstring", +"Represents the possible options when doing processor tracing. + +See :py:class:`SBProcess.StartTrace`." +) SBTraceOptions; class LLDB_API SBTraceOptions { public: SBTraceOptions(); diff --git a/contrib/llvm-project/lldb/bindings/interface/SBType.i b/contrib/llvm-project/lldb/bindings/interface/SBType.i index 3cd82452084b..e7b3fd11e338 100644 --- a/contrib/llvm-project/lldb/bindings/interface/SBType.i +++ b/contrib/llvm-project/lldb/bindings/interface/SBType.i @@ -9,7 +9,7 @@ namespace lldb { %feature("docstring", -"Represents a member of a type in lldb.") SBTypeMember; +"Represents a member of a type.") SBTypeMember; class SBTypeMember { @@ -60,6 +60,9 @@ protected: std::unique_ptr<lldb_private::TypeMemberImpl> m_opaque_ap; }; +%feature("docstring", +"Represents a member function of a type." +) SBTypeMemberFunction; class SBTypeMemberFunction { public: @@ -111,72 +114,72 @@ protected: "Represents a data type in lldb. The FindFirstType() method of SBTarget/SBModule returns a SBType. -SBType supports the eq/ne operator. For example, - -main.cpp: - -class Task { -public: - int id; - Task *next; - Task(int i, Task *n): - id(i), - next(n) - {} -}; - -int main (int argc, char const *argv[]) -{ - Task *task_head = new Task(-1, NULL); - Task *task1 = new Task(1, NULL); - Task *task2 = new Task(2, NULL); - Task *task3 = new Task(3, NULL); // Orphaned. - Task *task4 = new Task(4, NULL); - Task *task5 = new Task(5, NULL); - - task_head->next = task1; - task1->next = task2; - task2->next = task4; - task4->next = task5; - - int total = 0; - Task *t = task_head; - while (t != NULL) { - if (t->id >= 0) - ++total; - t = t->next; +SBType supports the eq/ne operator. For example,:: + + //main.cpp: + + class Task { + public: + int id; + Task *next; + Task(int i, Task *n): + id(i), + next(n) + {} + }; + + int main (int argc, char const *argv[]) + { + Task *task_head = new Task(-1, NULL); + Task *task1 = new Task(1, NULL); + Task *task2 = new Task(2, NULL); + Task *task3 = new Task(3, NULL); // Orphaned. + Task *task4 = new Task(4, NULL); + Task *task5 = new Task(5, NULL); + + task_head->next = task1; + task1->next = task2; + task2->next = task4; + task4->next = task5; + + int total = 0; + Task *t = task_head; + while (t != NULL) { + if (t->id >= 0) + ++total; + t = t->next; + } + printf('We have a total number of %d tasks\\n', total); + + // This corresponds to an empty task list. + Task *empty_task_head = new Task(-1, NULL); + + return 0; // Break at this line } - printf('We have a total number of %d tasks\\n', total); - - // This corresponds to an empty task list. - Task *empty_task_head = new Task(-1, NULL); - - return 0; // Break at this line -} -find_type.py: + # find_type.py: - # Get the type 'Task'. - task_type = target.FindFirstType('Task') - self.assertTrue(task_type) + # Get the type 'Task'. + task_type = target.FindFirstType('Task') + self.assertTrue(task_type) - # Get the variable 'task_head'. - frame0.FindVariable('task_head') - task_head_type = task_head.GetType() - self.assertTrue(task_head_type.IsPointerType()) + # Get the variable 'task_head'. + frame0.FindVariable('task_head') + task_head_type = task_head.GetType() + self.assertTrue(task_head_type.IsPointerType()) - # task_head_type is 'Task *'. - task_pointer_type = task_type.GetPointerType() - self.assertTrue(task_head_type == task_pointer_type) + # task_head_type is 'Task *'. + task_pointer_type = task_type.GetPointerType() + self.assertTrue(task_head_type == task_pointer_type) - # Get the child mmember 'id' from 'task_head'. - id = task_head.GetChildMemberWithName('id') - id_type = id.GetType() + # Get the child mmember 'id' from 'task_head'. + id = task_head.GetChildMemberWithName('id') + id_type = id.GetType() - # SBType.GetBasicType() takes an enum 'BasicType' (lldb-enumerations.h). - int_type = id_type.GetBasicType(lldb.eBasicTypeInt) - # id_type and int_type should be the same type! - self.assertTrue(id_type == int_type) + # SBType.GetBasicType() takes an enum 'BasicType' (lldb-enumerations.h). + int_type = id_type.GetBasicType(lldb.eBasicTypeInt) + # id_type and int_type should be the same type! + self.assertTrue(id_type == int_type) ...") SBType; class SBType @@ -220,6 +223,9 @@ public: bool IsAnonymousType (); + bool + IsScopedEnumerationType (); + lldb::SBType GetPointerType(); @@ -242,6 +248,9 @@ public: GetCanonicalType(); lldb::SBType + GetEnumerationIntegerType(); + + lldb::SBType GetArrayElementType (); lldb::SBType @@ -277,6 +286,9 @@ public: lldb::SBTypeEnumMemberList GetEnumMembers(); + lldb::SBModule + GetModule(); + const char* GetName(); @@ -330,6 +342,7 @@ public: return template_args return None + module = property(GetModule, None, doc='''A read only property that returns the module in which type is defined.''') name = property(GetName, None, doc='''A read only property that returns the name for this type as a string.''') size = property(GetByteSize, None, doc='''A read only property that returns size in bytes for this type as an integer.''') is_pointer = property(IsPointerType, None, doc='''A read only property that returns a boolean value that indicates if this type is a pointer type.''') @@ -421,35 +434,38 @@ public: }; %feature("docstring", -"Represents a list of SBTypes. The FindTypes() method of SBTarget/SBModule -returns a SBTypeList. +"Represents a list of :py:class:`SBType` s. -SBTypeList supports SBType iteration. For example, +The FindTypes() method of :py:class:`SBTarget`/:py:class:`SBModule` returns a SBTypeList. -main.cpp: +SBTypeList supports :py:class:`SBType` iteration. For example, -class Task { -public: - int id; - Task *next; - Task(int i, Task *n): - id(i), - next(n) - {} -}; +.. code-block:: cpp + + // main.cpp: + + class Task { + public: + int id; + Task *next; + Task(int i, Task *n): + id(i), + next(n) + {} + }; -... +.. code-block:: python -find_type.py: + # find_type.py: - # Get the type 'Task'. - type_list = target.FindTypes('Task') - self.assertTrue(len(type_list) == 1) - # To illustrate the SBType iteration. - for type in type_list: - # do something with type + # Get the type 'Task'. + type_list = target.FindTypes('Task') + self.assertTrue(len(type_list) == 1) + # To illustrate the SBType iteration. + for type in type_list: + # do something with type -...") SBTypeList; +") SBTypeList; class SBTypeList { public: diff --git a/contrib/llvm-project/lldb/bindings/interface/SBTypeEnumMember.i b/contrib/llvm-project/lldb/bindings/interface/SBTypeEnumMember.i index 006bdeaa8cee..b41901027245 100644 --- a/contrib/llvm-project/lldb/bindings/interface/SBTypeEnumMember.i +++ b/contrib/llvm-project/lldb/bindings/interface/SBTypeEnumMember.i @@ -71,10 +71,19 @@ protected: SBTypeEnumMember (const lldb::TypeEnumMemberImplSP &); }; -%feature( - "docstring", - "Represents a list of SBTypeEnumMembers." -) SBTypeEnumMemberList; +%feature("docstring", +"Represents a list of SBTypeEnumMembers. + +SBTypeEnumMemberList supports SBTypeEnumMember iteration. +It also supports [] access either by index, or by enum +element name by doing: :: + + myType = target.FindFirstType('MyEnumWithElementA') + members = myType.GetEnumMembers() + first_elem = members[0] + elem_A = members['A'] + +") SBTypeEnumMemberList; class SBTypeEnumMemberList { @@ -99,6 +108,29 @@ public: uint32_t GetSize(); +#ifdef SWIGPYTHON + %pythoncode %{ + def __iter__(self): + '''Iterate over all members in a lldb.SBTypeEnumMemberList object.''' + return lldb_iter(self, 'GetSize', 'GetTypeEnumMemberAtIndex') + + def __len__(self): + '''Return the number of members in a lldb.SBTypeEnumMemberList object.''' + return self.GetSize() + + def __getitem__(self, key): + num_elements = self.GetSize() + if type(key) is int: + if key < num_elements: + return self.GetTypeEnumMemberAtIndex(key) + elif type(key) is str: + for idx in range(num_elements): + item = self.GetTypeEnumMemberAtIndex(idx) + if item.name == key: + return item + return None + %} +#endif private: std::unique_ptr<lldb_private::TypeEnumMemberListImpl> m_opaque_ap; diff --git a/contrib/llvm-project/lldb/bindings/interface/SBValue.i b/contrib/llvm-project/lldb/bindings/interface/SBValue.i index fb899805c395..dd012e667a20 100644 --- a/contrib/llvm-project/lldb/bindings/interface/SBValue.i +++ b/contrib/llvm-project/lldb/bindings/interface/SBValue.i @@ -13,7 +13,7 @@ namespace lldb { SBValue supports iteration through its child, which in turn is represented as an SBValue. For example, we can get the general purpose registers of a -frame as an SBValue, and iterate through all the registers, +frame as an SBValue, and iterate through all the registers,:: registerSet = frame.registers # Returns an SBValueList. for regs in registerSet: @@ -25,30 +25,30 @@ frame as an SBValue, and iterate through all the registers, for reg in GPRs: print('Name: ', reg.name, ' Value: ', reg.value) -produces the output: - -General Purpose Registers (number of children = 21): -Name: rax Value: 0x0000000100000c5c -Name: rbx Value: 0x0000000000000000 -Name: rcx Value: 0x00007fff5fbffec0 -Name: rdx Value: 0x00007fff5fbffeb8 -Name: rdi Value: 0x0000000000000001 -Name: rsi Value: 0x00007fff5fbffea8 -Name: rbp Value: 0x00007fff5fbffe80 -Name: rsp Value: 0x00007fff5fbffe60 -Name: r8 Value: 0x0000000008668682 -Name: r9 Value: 0x0000000000000000 -Name: r10 Value: 0x0000000000001200 -Name: r11 Value: 0x0000000000000206 -Name: r12 Value: 0x0000000000000000 -Name: r13 Value: 0x0000000000000000 -Name: r14 Value: 0x0000000000000000 -Name: r15 Value: 0x0000000000000000 -Name: rip Value: 0x0000000100000dae -Name: rflags Value: 0x0000000000000206 -Name: cs Value: 0x0000000000000027 -Name: fs Value: 0x0000000000000010 -Name: gs Value: 0x0000000000000048 +produces the output: :: + + General Purpose Registers (number of children = 21): + Name: rax Value: 0x0000000100000c5c + Name: rbx Value: 0x0000000000000000 + Name: rcx Value: 0x00007fff5fbffec0 + Name: rdx Value: 0x00007fff5fbffeb8 + Name: rdi Value: 0x0000000000000001 + Name: rsi Value: 0x00007fff5fbffea8 + Name: rbp Value: 0x00007fff5fbffe80 + Name: rsp Value: 0x00007fff5fbffe60 + Name: r8 Value: 0x0000000008668682 + Name: r9 Value: 0x0000000000000000 + Name: r10 Value: 0x0000000000001200 + Name: r11 Value: 0x0000000000000206 + Name: r12 Value: 0x0000000000000000 + Name: r13 Value: 0x0000000000000000 + Name: r14 Value: 0x0000000000000000 + Name: r15 Value: 0x0000000000000000 + Name: rip Value: 0x0000000100000dae + Name: rflags Value: 0x0000000000000206 + Name: cs Value: 0x0000000000000027 + Name: fs Value: 0x0000000000000010 + Name: gs Value: 0x0000000000000048 See also linked_list_iter() for another perspective on how to iterate through an SBValue instance which interprets the value object as representing the head of a @@ -379,22 +379,18 @@ public: Get an SBData wrapping what this SBValue points to. This method will dereference the current SBValue, if its - data type is a T* or T[], and extract item_count elements - of type T from it, copying their contents in an SBData. + data type is a ``T\*`` or ``T[]``, and extract ``item_count`` elements + of type ``T`` from it, copying their contents in an :py:class:`SBData`. - @param[in] item_idx - The index of the first item to retrieve. For an array + :param item_idx: The index of the first item to retrieve. For an array this is equivalent to array[item_idx], for a pointer - to *(pointer + item_idx). In either case, the measurement - unit for item_idx is the sizeof(T) rather than the byte - - @param[in] item_count - How many items should be copied into the output. By default + to ``\*(pointer + item_idx)``. In either case, the measurement + unit for item_idx is the ``sizeof(T)`` rather than the byte + :param item_count: How many items should be copied into the output. By default only one item is copied, but more can be asked for. - - @return - An SBData with the contents of the copied items, on success. - An empty SBData otherwise.") GetPointeeData; + :return: The contents of the copied items on success. An empty :py:class:`SBData` otherwise. + :rtype: SBData + ") GetPointeeData; lldb::SBData GetPointeeData (uint32_t item_idx = 0, uint32_t item_count = 1); diff --git a/contrib/llvm-project/lldb/bindings/interface/SBValueList.i b/contrib/llvm-project/lldb/bindings/interface/SBValueList.i index 17ba2056f0c2..76fa937b9876 100644 --- a/contrib/llvm-project/lldb/bindings/interface/SBValueList.i +++ b/contrib/llvm-project/lldb/bindings/interface/SBValueList.i @@ -9,61 +9,62 @@ namespace lldb { %feature("docstring", -"Represents a collection of SBValues. Both SBFrame's GetVariables() and -GetRegisters() return a SBValueList. - -SBValueList supports SBValue iteration. For example (from test/lldbutil.py), - -def get_registers(frame, kind): - '''Returns the registers given the frame and the kind of registers desired. - - Returns None if there's no such kind. - ''' - registerSet = frame.GetRegisters() # Return type of SBValueList. - for value in registerSet: - if kind.lower() in value.GetName().lower(): - return value - - return None - -def get_GPRs(frame): - '''Returns the general purpose registers of the frame as an SBValue. - - The returned SBValue object is iterable. An example: - ... - from lldbutil import get_GPRs - regs = get_GPRs(frame) - for reg in regs: - print('%s => %s' % (reg.GetName(), reg.GetValue())) - ... - ''' - return get_registers(frame, 'general purpose') - -def get_FPRs(frame): - '''Returns the floating point registers of the frame as an SBValue. - - The returned SBValue object is iterable. An example: - ... - from lldbutil import get_FPRs - regs = get_FPRs(frame) - for reg in regs: - print('%s => %s' % (reg.GetName(), reg.GetValue())) - ... - ''' - return get_registers(frame, 'floating point') - -def get_ESRs(frame): - '''Returns the exception state registers of the frame as an SBValue. - - The returned SBValue object is iterable. An example: - ... - from lldbutil import get_ESRs - regs = get_ESRs(frame) - for reg in regs: - print('%s => %s' % (reg.GetName(), reg.GetValue())) - ... - ''' - return get_registers(frame, 'exception state')" +"Represents a collection of SBValues. Both :py:class:`SBFrame.GetVariables()` and +:py:class:`SBFrame.GetRegisters()` return a SBValueList. + +SBValueList supports :py:class:`SBValue` iteration. For example (from test/lldbutil.py),:: + + def get_registers(frame, kind): + '''Returns the registers given the frame and the kind of registers desired. + + Returns None if there's no such kind. + ''' + registerSet = frame.GetRegisters() # Return type of SBValueList. + for value in registerSet: + if kind.lower() in value.GetName().lower(): + return value + + return None + + def get_GPRs(frame): + '''Returns the general purpose registers of the frame as an SBValue. + + The returned SBValue object is iterable. An example: + ... + from lldbutil import get_GPRs + regs = get_GPRs(frame) + for reg in regs: + print('%s => %s' % (reg.GetName(), reg.GetValue())) + ... + ''' + return get_registers(frame, 'general purpose') + + def get_FPRs(frame): + '''Returns the floating point registers of the frame as an SBValue. + + The returned SBValue object is iterable. An example: + ... + from lldbutil import get_FPRs + regs = get_FPRs(frame) + for reg in regs: + print('%s => %s' % (reg.GetName(), reg.GetValue())) + ... + ''' + return get_registers(frame, 'floating point') + + def get_ESRs(frame): + '''Returns the exception state registers of the frame as an SBValue. + + The returned SBValue object is iterable. An example: + ... + from lldbutil import get_ESRs + regs = get_ESRs(frame) + for reg in regs: + print('%s => %s' % (reg.GetName(), reg.GetValue())) + ... + ''' + return get_registers(frame, 'exception state') +" ) SBValueList; class SBValueList { diff --git a/contrib/llvm-project/lldb/bindings/interface/SBVariablesOptions.i b/contrib/llvm-project/lldb/bindings/interface/SBVariablesOptions.i index 362f7159d7d2..dfdc8cf5df68 100644 --- a/contrib/llvm-project/lldb/bindings/interface/SBVariablesOptions.i +++ b/contrib/llvm-project/lldb/bindings/interface/SBVariablesOptions.i @@ -8,6 +8,9 @@ namespace lldb { +%feature("docstring", +"Describes which variables should be returned from :py:class:`SBFrame.GetVariables`." +) SBVariablesOptions; class SBVariablesOptions { public: diff --git a/contrib/llvm-project/lldb/bindings/interface/SBWatchpoint.i b/contrib/llvm-project/lldb/bindings/interface/SBWatchpoint.i index cb0bc5f9859a..ac31c60a5614 100644 --- a/contrib/llvm-project/lldb/bindings/interface/SBWatchpoint.i +++ b/contrib/llvm-project/lldb/bindings/interface/SBWatchpoint.i @@ -14,7 +14,7 @@ namespace lldb { A watchpoint is determined by the address and the byte size that resulted in this particular instantiation. Each watchpoint has its settable options. -See also SBTarget.watchpoint_iter() for example usage of iterating through the +See also :py:class:`SBTarget.watchpoint_iter()` for example usage of iterating through the watchpoints of the target." ) SBWatchpoint; class SBWatchpoint diff --git a/contrib/llvm-project/lldb/bindings/lua/lua-swigsafecast.swig b/contrib/llvm-project/lldb/bindings/lua/lua-swigsafecast.swig new file mode 100644 index 000000000000..a3ed37279546 --- /dev/null +++ b/contrib/llvm-project/lldb/bindings/lua/lua-swigsafecast.swig @@ -0,0 +1,21 @@ +template <typename SBClass> +void +PushSBClass (lua_State* L, SBClass* obj); + +void +PushSBClass (lua_State* L, lldb::SBFrame* frame_sb) +{ + SWIG_NewPointerObj(L, frame_sb, SWIGTYPE_p_lldb__SBFrame, 0); +} + +void +PushSBClass (lua_State* L, lldb::SBBreakpointLocation* breakpoint_location_sb) +{ + SWIG_NewPointerObj(L, breakpoint_location_sb, SWIGTYPE_p_lldb__SBBreakpointLocation, 0); +} + +void +PushSBClass (lua_State* L, lldb::SBStructuredData* structured_data_sb) +{ + SWIG_NewPointerObj(L, structured_data_sb, SWIGTYPE_p_lldb__SBStructuredData, 0); +} diff --git a/contrib/llvm-project/lldb/bindings/lua/lua-typemaps.swig b/contrib/llvm-project/lldb/bindings/lua/lua-typemaps.swig index 28d63fa2f402..d912137a5674 100644 --- a/contrib/llvm-project/lldb/bindings/lua/lua-typemaps.swig +++ b/contrib/llvm-project/lldb/bindings/lua/lua-typemaps.swig @@ -1 +1,105 @@ %include <typemaps.i> + +// FIXME: We need to port more typemaps from Python + +//===----------------------------------------------------------------------===// + +// In Lua 5.3 and beyond the VM supports integers, so we need to remap +// SWIG's internal handling of integers. + + +%define LLDB_NUMBER_TYPEMAP(TYPE) + +// Primitive integer mapping +%typemap(in,checkfn="lua_isinteger") TYPE +%{ $1 = (TYPE)lua_tointeger(L, $input); %} +%typemap(in,checkfn="lua_isinteger") const TYPE&($basetype temp) +%{ temp=($basetype)lua_tointeger(L,$input); $1=&temp;%} +%typemap(out) TYPE +%{ lua_pushinteger(L, (lua_Integer) $1); SWIG_arg++;%} +%typemap(out) const TYPE& +%{ lua_pushinteger(L, (lua_Integer) $1); SWIG_arg++;%} + +// Pointer and reference mapping +%typemap(in,checkfn="lua_isinteger") TYPE *INPUT($*ltype temp), TYPE &INPUT($*ltype temp) +%{ temp = ($*ltype)lua_tointeger(L,$input); + $1 = &temp; %} +%typemap(in, numinputs=0) TYPE *OUTPUT ($*ltype temp) +%{ $1 = &temp; %} +%typemap(argout) TYPE *OUTPUT +%{ lua_pushinteger(L, (lua_Integer) *$1); SWIG_arg++;%} +%typemap(in) TYPE *INOUT = TYPE *INPUT; +%typemap(argout) TYPE *INOUT = TYPE *OUTPUT; +%typemap(in) TYPE &OUTPUT = TYPE *OUTPUT; +%typemap(argout) TYPE &OUTPUT = TYPE *OUTPUT; +%typemap(in) TYPE &INOUT = TYPE *INPUT; +%typemap(argout) TYPE &INOUT = TYPE *OUTPUT; +%typemap(in,checkfn="lua_isinteger") const TYPE *INPUT($*ltype temp) +%{ temp = ($*ltype)lua_tointeger(L,$input); + $1 = &temp; %} + +%enddef // LLDB_NUMBER_TYPEMAP + +LLDB_NUMBER_TYPEMAP(unsigned char); +LLDB_NUMBER_TYPEMAP(signed char); +LLDB_NUMBER_TYPEMAP(short); +LLDB_NUMBER_TYPEMAP(unsigned short); +LLDB_NUMBER_TYPEMAP(signed short); +LLDB_NUMBER_TYPEMAP(int); +LLDB_NUMBER_TYPEMAP(unsigned int); +LLDB_NUMBER_TYPEMAP(signed int); +LLDB_NUMBER_TYPEMAP(long); +LLDB_NUMBER_TYPEMAP(unsigned long); +LLDB_NUMBER_TYPEMAP(signed long); +LLDB_NUMBER_TYPEMAP(long long); +LLDB_NUMBER_TYPEMAP(unsigned long long); +LLDB_NUMBER_TYPEMAP(signed long long); + +%apply unsigned long { size_t }; +%apply const unsigned long & { const size_t & }; +%apply long { ssize_t }; +%apply const long & { const ssize_t & }; + +//===----------------------------------------------------------------------===// + +// FIXME: +// Ideally all the typemaps should be revisited in a future SB API revision. +// Typemaps, usually, modifies the function signatures and might spawn +// different LLDB APIs across languages (C++, Python, Lua...). +// Historically, typemaps have been used to replace SWIG's deficiencies, +// but SWIG itself evolved and some API design choices are now redundant. + +//===----------------------------------------------------------------------===// + +// Typemap definitions to allow SWIG to properly handle char buffer. + +// typemap for a char buffer +%typemap(in) (char *dst, size_t dst_len) { + $2 = luaL_checkinteger(L, $input); + if ($2 <= 0) { + return luaL_error(L, "Positive integer expected"); + } + $1 = (char *) malloc($2); +} + +// SBProcess::ReadCStringFromMemory() uses a void*, but needs to be treated +// as char data instead of byte data. +%typemap(in) (void *char_buf, size_t size) = (char *dst, size_t dst_len); + +// Return the char buffer. Discarding any previous return result +%typemap(argout) (char *dst, size_t dst_len) { + lua_pop(L, 1); // Blow away the previous result + if ($result == 0) { + lua_pushliteral(L, ""); + } else { + lua_pushlstring(L, (const char *)$1, $result); + } + free($1); + // SWIG_arg was already incremented +} + +// SBProcess::ReadCStringFromMemory() uses a void*, but needs to be treated +// as char data instead of byte data. +%typemap(argout) (void *char_buf, size_t size) = (char *dst, size_t dst_len); + +//===----------------------------------------------------------------------===// diff --git a/contrib/llvm-project/lldb/bindings/lua/lua-wrapper.swig b/contrib/llvm-project/lldb/bindings/lua/lua-wrapper.swig new file mode 100644 index 000000000000..90c22920ddc1 --- /dev/null +++ b/contrib/llvm-project/lldb/bindings/lua/lua-wrapper.swig @@ -0,0 +1,57 @@ +%header %{ + +template <typename T> +void +PushSBClass(lua_State* L, T* obj); + +%} + +%wrapper %{ + +// This function is called from Lua::CallBreakpointCallback +SWIGEXPORT llvm::Expected<bool> +LLDBSwigLuaBreakpointCallbackFunction +( + lua_State *L, + lldb::StackFrameSP stop_frame_sp, + lldb::BreakpointLocationSP bp_loc_sp, + StructuredDataImpl *extra_args_impl +) +{ + lldb::SBFrame sb_frame(stop_frame_sp); + lldb::SBBreakpointLocation sb_bp_loc(bp_loc_sp); + int nargs = 2; + + llvm::Optional<lldb::SBStructuredData> extra_args; + if (extra_args_impl) + extra_args = lldb::SBStructuredData(extra_args_impl); + + // Push the Lua wrappers + PushSBClass(L, &sb_frame); + PushSBClass(L, &sb_bp_loc); + + if (extra_args.hasValue()) { + PushSBClass(L, extra_args.getPointer()); + nargs++; + } + + // Call into the Lua callback passing 'sb_frame' and 'sb_bp_loc'. + // Expects a boolean return. + if (lua_pcall(L, nargs, 1, 0) != LUA_OK) { + llvm::Error E = llvm::make_error<llvm::StringError>( + llvm::formatv("{0}\n", lua_tostring(L, -1)), + llvm::inconvertibleErrorCode()); + // Pop error message from the stack. + lua_pop(L, 1); + return std::move(E); + } + + // Boolean return from the callback + bool stop = lua_toboolean(L, -1); + lua_pop(L, 1); + + return stop; +} + + +%} diff --git a/contrib/llvm-project/lldb/bindings/lua.swig b/contrib/llvm-project/lldb/bindings/lua/lua.swig index 9bfc49b359bc..c702e4964081 100644 --- a/contrib/llvm-project/lldb/bindings/lua.swig +++ b/contrib/llvm-project/lldb/bindings/lua/lua.swig @@ -9,13 +9,17 @@ %module lldb %include <std_string.i> -%include "./lua/lua-typemaps.swig" -%include "./macros.swig" -%include "./headers.swig" +%include "lua-typemaps.swig" +%include "macros.swig" +%include "headers.swig" %{ +#include "llvm/Support/Error.h" +#include "llvm/Support/FormatVariadic.h" +#include "../bindings/lua/lua-swigsafecast.swig" using namespace lldb_private; using namespace lldb; %} -%include "./interfaces.swig" +%include "interfaces.swig" +%include "lua-wrapper.swig" diff --git a/contrib/llvm-project/lldb/bindings/macros.swig b/contrib/llvm-project/lldb/bindings/macros.swig index 0387f27f3cb9..6793a11c5bd9 100644 --- a/contrib/llvm-project/lldb/bindings/macros.swig +++ b/contrib/llvm-project/lldb/bindings/macros.swig @@ -1,6 +1,5 @@ %define STRING_EXTENSION_LEVEL(Class, Level) %extend { - %nothreadallow; std::string lldb:: ## Class ## ::__str__(){ lldb::SBStream stream; $self->GetDescription (stream, Level); @@ -11,13 +10,11 @@ } return std::string(desc, desc_len); } - %clearnothreadallow; } %enddef %define STRING_EXTENSION(Class) %extend { - %nothreadallow; std::string lldb:: ## Class ## ::__str__(){ lldb::SBStream stream; $self->GetDescription (stream); @@ -28,6 +25,5 @@ } return std::string(desc, desc_len); } - %clearnothreadallow; } %enddef diff --git a/contrib/llvm-project/lldb/bindings/python/python-extensions.swig b/contrib/llvm-project/lldb/bindings/python/python-extensions.swig index 0b23fdd40006..b98b0d458f0c 100644 --- a/contrib/llvm-project/lldb/bindings/python/python-extensions.swig +++ b/contrib/llvm-project/lldb/bindings/python/python-extensions.swig @@ -290,6 +290,7 @@ class declaration(object): self.col = col class value_iter(object): + '''Allows iterating over the children of an :py:class:`SBValue`.''' def __iter__(self): return self @@ -311,19 +312,19 @@ class value_iter(object): self.length = self.sbvalue.GetNumChildren() class value(object): - '''A class designed to wrap lldb.SBValue() objects so the resulting object - can be used as a variable would be in code. So if you have a Point structure - variable in your code in the current frame named "pt", you can initialize an instance - of this class with it: - - pt = lldb.value(lldb.frame.FindVariable("pt")) - print pt - print pt.x - print pt.y - - pt = lldb.value(lldb.frame.FindVariable("rectangle_array")) - print rectangle_array[12] - print rectangle_array[5].origin.x''' + '''Wraps :py:class:`SBValue` objects so the resulting object can be used as a variable would be in code. + + So if you have a Point structure variable in your code in the current frame named "pt", + you can initialize an instance of this class with it: :: + + pt = lldb.value(lldb.frame.FindVariable("pt")) + print pt + print pt.x + print pt.y + + pt = lldb.value(lldb.frame.FindVariable("rectangle_array")) + print rectangle_array[12] + print rectangle_array[5].origin.x''' def __init__(self, sbvalue): self.sbvalue = sbvalue diff --git a/contrib/llvm-project/lldb/bindings/python/python-swigsafecast.swig b/contrib/llvm-project/lldb/bindings/python/python-swigsafecast.swig index d5cafbfa67cb..091fc29b1057 100644 --- a/contrib/llvm-project/lldb/bindings/python/python-swigsafecast.swig +++ b/contrib/llvm-project/lldb/bindings/python/python-swigsafecast.swig @@ -152,3 +152,10 @@ SBTypeToSWIGWrapper (lldb::SBSymbolContext* sym_ctx_sb) { return SWIG_NewPointerObj((void *) sym_ctx_sb, SWIGTYPE_p_lldb__SBSymbolContext, 0); } + +template <> +PyObject* +SBTypeToSWIGWrapper (lldb::SBStream* stream_sb) +{ + return SWIG_NewPointerObj((void *) stream_sb, SWIGTYPE_p_lldb__SBStream, 0); +} diff --git a/contrib/llvm-project/lldb/bindings/python/python-typemaps.h b/contrib/llvm-project/lldb/bindings/python/python-typemaps.h new file mode 100644 index 000000000000..b45352ad6295 --- /dev/null +++ b/contrib/llvm-project/lldb/bindings/python/python-typemaps.h @@ -0,0 +1,17 @@ +#ifndef LLDB_BINDINGS_PYTHON_PYTHON_TYPEMAPS_H +#define LLDB_BINDINGS_PYTHON_PYTHON_TYPEMAPS_H + +// Defined here instead of a .swig file because SWIG 2 doesn't support +// explicit deleted functions. +struct Py_buffer_RAII { + Py_buffer buffer = {}; + Py_buffer_RAII(){}; + Py_buffer &operator=(const Py_buffer_RAII &) = delete; + Py_buffer_RAII(const Py_buffer_RAII &) = delete; + ~Py_buffer_RAII() { + if (buffer.obj) + PyBuffer_Release(&buffer); + } +}; + +#endif // LLDB_BINDINGS_PYTHON_PYTHON_TYPEMAPS_H diff --git a/contrib/llvm-project/lldb/bindings/python/python-typemaps.swig b/contrib/llvm-project/lldb/bindings/python/python-typemaps.swig index c08aeab71f78..b1ace4ff3b1e 100644 --- a/contrib/llvm-project/lldb/bindings/python/python-typemaps.swig +++ b/contrib/llvm-project/lldb/bindings/python/python-typemaps.swig @@ -1,5 +1,11 @@ /* Typemap definitions, to allow SWIG to properly handle 'char**' data types. */ +%inline %{ + +#include "../bindings/python/python-typemaps.h" + +%} + %typemap(in) char ** { /* Check if is a list */ if (PythonList::Check($input)) { @@ -61,7 +67,7 @@ %typemap(in) lldb::tid_t { PythonObject obj = Retain<PythonObject>($input); - lldb::tid_t value = unwrapOrSetPythonException(As<unsigned long long>(obj)); + lldb::tid_t value = unwrapOrSetPythonException(As<unsigned long long>(obj)); if (PyErr_Occurred()) return nullptr; $1 = value; @@ -476,21 +482,6 @@ bool SetNumberFromPyObject<double>(double &number, PyObject *obj) { } } -%inline %{ - -struct Py_buffer_RAII { - Py_buffer buffer = {}; - Py_buffer_RAII() {}; - Py_buffer &operator=(const Py_buffer_RAII &) = delete; - Py_buffer_RAII(const Py_buffer_RAII &) = delete; - ~Py_buffer_RAII() { - if (buffer.obj) - PyBuffer_Release(&buffer); - } -}; - -%} - // These two pybuffer macros are copied out of swig/Lib/python/pybuffer.i, // and fixed so they will not crash if PyObject_GetBuffer fails. // https://github.com/swig/swig/issues/1640 diff --git a/contrib/llvm-project/lldb/bindings/python/python-wrapper.swig b/contrib/llvm-project/lldb/bindings/python/python-wrapper.swig index f9e89373fe25..443ddfb8dd20 100644 --- a/contrib/llvm-project/lldb/bindings/python/python-wrapper.swig +++ b/contrib/llvm-project/lldb/bindings/python/python-wrapper.swig @@ -271,9 +271,6 @@ LLDBSwigPythonCreateScriptedThreadPlan if (python_class_name == NULL || python_class_name[0] == '\0' || !session_dictionary_name) Py_RETURN_NONE; - // I do not want the SBThreadPlan to be deallocated when going out of scope because python - // has ownership of it and will manage memory for this object by itself - lldb::SBThreadPlan *tp_value = new lldb::SBThreadPlan(thread_plan_sp); PyErr_Cleaner py_err_cleaner(true); @@ -286,7 +283,10 @@ LLDBSwigPythonCreateScriptedThreadPlan return nullptr; } - PythonObject tp_arg(PyRefType::Owned, SBTypeToSWIGWrapper(tp_value)); + // I do not want the SBThreadPlan to be deallocated when going out of scope + // because python has ownership of it and will manage memory for this + // object by itself + PythonObject tp_arg(PyRefType::Owned, SBTypeToSWIGWrapper(new lldb::SBThreadPlan(thread_plan_sp))); if (!tp_arg.IsAllocated()) Py_RETURN_NONE; @@ -312,8 +312,7 @@ LLDBSwigPythonCreateScriptedThreadPlan } result = pfunc(tp_arg, dict); } else if (arg_info.get().max_positional_args >= 3) { - lldb::SBStructuredData *args_value = new lldb::SBStructuredData(args_impl); - PythonObject args_arg(PyRefType::Owned, SBTypeToSWIGWrapper(args_value)); + PythonObject args_arg(PyRefType::Owned, SBTypeToSWIGWrapper(new lldb::SBStructuredData(args_impl))); result = pfunc(tp_arg, args_arg, dict); } else { error_string.assign("wrong number of arguments in __init__, should be 2 or 3 (not including self)"); @@ -469,6 +468,127 @@ LLDBSwigPythonCallBreakpointResolver return ret_val; } +SWIGEXPORT void * +LLDBSwigPythonCreateScriptedStopHook +( + lldb::TargetSP target_sp, + const char *python_class_name, + const char *session_dictionary_name, + lldb_private::StructuredDataImpl *args_impl, + Status &error +) +{ + if (python_class_name == NULL || python_class_name[0] == '\0') { + error.SetErrorString("Empty class name."); + Py_RETURN_NONE; + } + if (!session_dictionary_name) { + error.SetErrorString("No session dictionary"); + Py_RETURN_NONE; + } + + PyErr_Cleaner py_err_cleaner(true); + + auto dict = + PythonModule::MainModule().ResolveName<PythonDictionary>( + session_dictionary_name); + auto pfunc = + PythonObject::ResolveNameWithDictionary<PythonCallable>( + python_class_name, dict); + + if (!pfunc.IsAllocated()) { + error.SetErrorStringWithFormat("Could not find class: %s.", + python_class_name); + return nullptr; + } + + lldb::SBTarget *target_val + = new lldb::SBTarget(target_sp); + + PythonObject target_arg(PyRefType::Owned, SBTypeToSWIGWrapper(target_val)); + + lldb::SBStructuredData *args_value = new lldb::SBStructuredData(args_impl); + PythonObject args_arg(PyRefType::Owned, SBTypeToSWIGWrapper(args_value)); + + PythonObject result = pfunc(target_arg, args_arg, dict); + + if (result.IsAllocated()) + { + // Check that the handle_stop callback is defined: + auto callback_func = result.ResolveName<PythonCallable>("handle_stop"); + if (callback_func.IsAllocated()) { + if (auto args_info = callback_func.GetArgInfo()) { + size_t num_args = (*args_info).max_positional_args; + if (num_args != 2) { + error.SetErrorStringWithFormat("Wrong number of args for " + "handle_stop callback, should be 2 (excluding self), got: %zu", + num_args); + Py_RETURN_NONE; + } else + return result.release(); + } else { + error.SetErrorString("Couldn't get num arguments for handle_stop " + "callback."); + Py_RETURN_NONE; + } + return result.release(); + } + else { + error.SetErrorStringWithFormat("Class \"%s\" is missing the required " + "handle_stop callback.", + python_class_name); + result.release(); + } + } + Py_RETURN_NONE; +} + +SWIGEXPORT bool +LLDBSwigPythonStopHookCallHandleStop +( + void *implementor, + lldb::ExecutionContextRefSP exc_ctx_sp, + lldb::StreamSP stream +) +{ + // handle_stop will return a bool with the meaning "should_stop"... + // If you return nothing we'll assume we are going to stop. + // Also any errors should return true, since we should stop on error. + + PyErr_Cleaner py_err_cleaner(false); + PythonObject self(PyRefType::Borrowed, static_cast<PyObject*>(implementor)); + auto pfunc = self.ResolveName<PythonCallable>("handle_stop"); + + if (!pfunc.IsAllocated()) + return true; + + PythonObject result; + lldb::SBExecutionContext sb_exc_ctx(exc_ctx_sp); + PythonObject exc_ctx_arg(PyRefType::Owned, SBTypeToSWIGWrapper(sb_exc_ctx)); + lldb::SBStream sb_stream; + PythonObject sb_stream_arg(PyRefType::Owned, + SBTypeToSWIGWrapper(sb_stream)); + result = pfunc(exc_ctx_arg, sb_stream_arg); + + if (PyErr_Occurred()) + { + stream->PutCString("Python error occurred handling stop-hook."); + PyErr_Print(); + PyErr_Clear(); + return true; + } + + // Now add the result to the output stream. SBStream only + // makes an internally help StreamString which I can't interpose, so I + // have to copy it over here. + stream->PutCString(sb_stream.GetData()); + + if (result.get() == Py_False) + return false; + else + return true; +} + // wrapper that calls an optional instance member of an object taking no arguments static PyObject* LLDBSwigPython_CallOptionalMember diff --git a/contrib/llvm-project/lldb/bindings/python.swig b/contrib/llvm-project/lldb/bindings/python/python.swig index 5b1269878dac..9dc4ab87a4bd 100644 --- a/contrib/llvm-project/lldb/bindings/python.swig +++ b/contrib/llvm-project/lldb/bindings/python/python.swig @@ -12,23 +12,27 @@ Some of the important classes are described here: -o SBTarget: Represents the target program running under the debugger. -o SBProcess: Represents the process associated with the target program. -o SBThread: Represents a thread of execution. SBProcess contains SBThread(s). -o SBFrame: Represents one of the stack frames associated with a thread. SBThread - contains SBFrame(s). -o SBSymbolContext: A container that stores various debugger related info. -o SBValue: Represents the value of a variable, a register, or an expression. -o SBModule: Represents an executable image and its associated object and symbol - files. SBTarget contains SBModule(s). -o SBBreakpoint: Represents a logical breakpoint and its associated settings. - SBTarget contains SBBreakpoint(s). -o SBSymbol: Represents the symbol possibly associated with a stack frame. -o SBCompileUnit: Represents a compilation unit, or compiled source file. -o SBFunction: Represents a generic function, which can be inlined or not. -o SBBlock: Represents a lexical block. SBFunction contains SBBlock(s). -o SBLineEntry: Specifies an association with a contiguous range of instructions - and a source file location. SBCompileUnit contains SBLineEntry(s)." +* :py:class:`SBTarget`: Represents the target program running under the debugger. +* :py:class:`SBProcess`: Represents the process associated with the target program. +* :py:class:`SBThread`: Represents a thread of execution. :py:class:`SBProcess` contains SBThreads. +* :py:class:`SBFrame`: Represents one of the stack frames associated with a thread. :py:class:`SBThread` + contains SBFrame(s). +* :py:class:`SBSymbolContext`: A container that stores various debugger related info. +* :py:class:`SBValue`: Represents the value of a variable, a register, or an expression. +* :py:class:`SBModule`: Represents an executable image and its associated object and symbol + files. :py:class:`SBTarget` contains SBModule. +* :py:class:`SBBreakpoint`: Represents a logical breakpoint and its associated settings. + :py:class:`SBTarget` contains SBBreakpoints. +* :py:class:`SBSymbol`: Represents the symbol possibly associated with a stack frame. +* :py:class:`SBCompileUnit`: Represents a compilation unit, or compiled source file. +* :py:class:`SBFunction`: Represents a generic function, which can be inlined or not. +* :py:class:`SBBlock`: Represents a lexical block. :py:class:`SBFunction` contains SBBlocks. +* :py:class:`SBLineEntry`: Specifies an association with a contiguous range of instructions + and a source file location. :py:class:`SBCompileUnit` contains SBLineEntry. + +The different enums in the `lldb` module are described in :doc:`python_api_enums`. + +" %enddef /* @@ -111,9 +115,9 @@ def lldb_iter(obj, getsize, getelem): %} %include <std_string.i> -%include "./python/python-typemaps.swig" -%include "./macros.swig" -%include "./headers.swig" +%include "python-typemaps.swig" +%include "macros.swig" +%include "headers.swig" %{ #include "../source/Plugins/ScriptInterpreter/Python/PythonDataObjects.h" @@ -123,9 +127,9 @@ using namespace lldb_private::python; using namespace lldb; %} -%include "./interfaces.swig" -%include "./python/python-extensions.swig" -%include "./python/python-wrapper.swig" +%include "interfaces.swig" +%include "python-extensions.swig" +%include "python-wrapper.swig" %pythoncode%{ _initialize = True |