From 7e9e6ac526ebd90fe8ec0b8d2bb6edd3516ab908 Mon Sep 17 00:00:00 2001 From: Raphael Isemann Date: Sun, 17 Jan 2021 17:40:54 +0100 Subject: [PATCH] [lldb][docs] Fix some RST formatting errors related to code examples. Mostly just making sure the indentation is right (SBDebugger had 0 spaces as it was still plain text, the others had too much indentation or other minor issues). --- lldb/bindings/interface/SBBroadcaster.i | 2 +- .../interface/SBCommandInterpreterRunOptions.i | 1 + lldb/bindings/interface/SBDebugger.i | 190 ++++++++++----------- lldb/bindings/interface/SBProcess.i | 2 - lldb/bindings/interface/SBStructuredData.i | 9 +- lldb/bindings/interface/SBType.i | 12 +- 6 files changed, 107 insertions(+), 109 deletions(-) diff --git a/lldb/bindings/interface/SBBroadcaster.i b/lldb/bindings/interface/SBBroadcaster.i index 79100e1..dd6de1f 100644 --- a/lldb/bindings/interface/SBBroadcaster.i +++ b/lldb/bindings/interface/SBBroadcaster.i @@ -11,7 +11,7 @@ namespace lldb { %feature("docstring", "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/lldb/bindings/interface/SBCommandInterpreterRunOptions.i b/lldb/bindings/interface/SBCommandInterpreterRunOptions.i index bad0992..1a618a2 100644 --- a/lldb/bindings/interface/SBCommandInterpreterRunOptions.i +++ b/lldb/bindings/interface/SBCommandInterpreterRunOptions.i @@ -12,6 +12,7 @@ namespace lldb { "SBCommandInterpreterRunOptions controls how the RunCommandInterpreter runs the code it is fed. A default SBCommandInterpreterRunOptions object has: + * StopOnContinue: false * StopOnError: false * StopOnCrash: false diff --git a/lldb/bindings/interface/SBDebugger.i b/lldb/bindings/interface/SBDebugger.i index f2e23a7..78d737b 100644 --- a/lldb/bindings/interface/SBDebugger.i +++ b/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: diff --git a/lldb/bindings/interface/SBProcess.i b/lldb/bindings/interface/SBProcess.i index ef79016..6f4a5db 100644 --- a/lldb/bindings/interface/SBProcess.i +++ b/lldb/bindings/interface/SBProcess.i @@ -27,8 +27,6 @@ SBProcess supports thread iteration. For example (from test/lldbutil.py), :: if t.GetStopReason() == reason: threads.append(t) return threads - -... " ) SBProcess; class SBProcess diff --git a/lldb/bindings/interface/SBStructuredData.i b/lldb/bindings/interface/SBStructuredData.i index c7601bf..5aba352 100644 --- a/lldb/bindings/interface/SBStructuredData.i +++ b/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/lldb/bindings/interface/SBType.i b/lldb/bindings/interface/SBType.i index bcf4397..e7b3fd1 100644 --- a/lldb/bindings/interface/SBType.i +++ b/lldb/bindings/interface/SBType.i @@ -458,12 +458,12 @@ SBTypeList supports :py:class:`SBType` iteration. For example, # 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; class SBTypeList -- 2.7.4