This is an archive of the discontinued LLVM Phabricator instance.

Differential D97778

[lldb] Extend Python convenience variable table with equivalent APIs
ClosedPublic

Authored by JDevlieghere on Mar 2 2021, 9:32 AM.

Details

Reviewers
mib
teemperor
Group Reviewers
Restricted Project
Commits
rGf46a441b1c5d: [lldb] Extend Python convenience variable table with equivalent APIs
Summary

Add a column to the table of convenience variables with the equivalent API to get to the current debugger, target, process, etc. We often get asked to make convenience variables available outside of the interactive interpreter. After explaining why that's not possible, a common complaint is that it's hard to find out how to get to these variables in a non-interactive context, for example how to get to the current frame when given a thread.. This patch aims to alleviate that by including the APIs to navigate between these instances in the table.

Diff Detail

Event Timeline

JDevlieghere requested review of this revision.Mar 2 2021, 9:32 AM
JDevlieghere created this revision.
mib accepted this revision.Mar 2 2021, 9:37 AM
mib added a subscriber: mib.

Cool! LGTM!

This revision is now accepted and ready to land.Mar 2 2021, 9:37 AM
JDevlieghere updated this revision to Diff 327489.Mar 2 2021, 9:42 AM

Use backticks (everywhere)

JDevlieghere updated this revision to Diff 327501.Mar 2 2021, 9:58 AM

Use single backtick so Sphinx automatically links the API docs.

Harbormaster completed remote builds in B91597: Diff 327487.Mar 2 2021, 11:15 AM
Harbormaster completed remote builds in B91599: Diff 327489.Mar 2 2021, 11:20 AM
Harbormaster completed remote builds in B91607: Diff 327501.Mar 2 2021, 11:49 AM
teemperor accepted this revision.Mar 2 2021, 1:42 PM
This revision was landed with ongoing or failed builds.Mar 2 2021, 4:14 PM
Closed by commit rGf46a441b1c5d: [lldb] Extend Python convenience variable table with equivalent APIs (authored by JDevlieghere). · Explain Why
This revision was automatically updated to reflect the committed changes.
JDevlieghere added a commit: rGf46a441b1c5d: [lldb] Extend Python convenience variable table with equivalent APIs.
Herald added a project: Restricted Project. · View Herald TranscriptMar 2 2021, 4:14 PM

Revision Contents

PathSize
lldb/
docs/
use/
151 lines

Diff 327616

lldb/docs/use/python-reference.rst

Show First 20 Lines • Show All 92 Lines • ▼ Show 20 Lines
This drops you into the embedded python interpreter. When running under the This drops you into the embedded python interpreter. When running under the
script command, lldb sets some convenience variables that give you quick access script command, lldb sets some convenience variables that give you quick access
to the currently selected entities that characterize the program and debugger to the currently selected entities that characterize the program and debugger
state. In each case, if there is no currently selected entity of the state. In each case, if there is no currently selected entity of the
appropriate type, the variable's IsValid method will return false. These appropriate type, the variable's IsValid method will return false. These
variables are: variables are:
+-------------------+---------------------+-------------------------------------------------------------------------------------+ +-------------------+---------------------+-------------------------------------+-------------------------------------------------------------------------------------+
| Variable | Type | Description | | Variable | Type | Equivalent | Description |
+-------------------+---------------------+-------------------------------------------------------------------------------------+ +-------------------+---------------------+-------------------------------------+-------------------------------------------------------------------------------------+
| **lldb.debugger** | **lldb.SBDebugger** | Contains the debugger object whose **script** command was invoked. | | `lldb.debugger` | `lldb.SBDebugger` | `SBTarget.GetDebugger` | Contains the debugger object whose `script` command was invoked. |
| | | The **lldb.SBDebugger** object owns the command interpreter | | | | | The `lldb.SBDebugger` object owns the command interpreter |
| | | and all the targets in your debug session. There will always be a | | | | | and all the targets in your debug session. There will always be a |
| | | Debugger in the embedded interpreter. | | | | | Debugger in the embedded interpreter. |
+-------------------+---------------------+-------------------------------------------------------------------------------------+ +-------------------+---------------------+-------------------------------------+-------------------------------------------------------------------------------------+
| **lldb.target** | **lldb.SBTarget** | Contains the currently selected target - for instance the one made with the | | `lldb.target` | `lldb.SBTarget` | `SBDebugger.GetSelectedTarget` | Contains the currently selected target - for instance the one made with the |
| | | **file** or selected by the **target select <target-index>** command. | | | | | `file` or selected by the `target select <target-index>` command. |
| | | The **lldb.SBTarget** manages one running process, and all the executable | | | | `SBProcess.GetTarget` | The `lldb.SBTarget` manages one running process, and all the executable |
| | | and debug files for the process. | | | | | and debug files for the process. |
+-------------------+---------------------+-------------------------------------------------------------------------------------+ +-------------------+---------------------+-------------------------------------+-------------------------------------------------------------------------------------+
| **lldb.process** | **lldb.SBProcess** | Contains the process of the currently selected target. | | `lldb.process` | `lldb.SBProcess` | `SBTarget.GetProcess` | Contains the process of the currently selected target. |
| | | The **lldb.SBProcess** object manages the threads and allows access to | | | | | The `lldb.SBProcess` object manages the threads and allows access to |
| | | memory for the process. | | | | `SBThread.GetProcess` | memory for the process. |
+-------------------+---------------------+-------------------------------------------------------------------------------------+ +-------------------+---------------------+-------------------------------------+-------------------------------------------------------------------------------------+
| **lldb.thread** | **lldb.SBThread** | Contains the currently selected thread. | | `lldb.thread` | `lldb.SBThread` | `SBProcess.GetSelectedThread` | Contains the currently selected thread. |
| | | The **lldb.SBThread** object manages the stack frames in that thread. | | | | | The `lldb.SBThread` object manages the stack frames in that thread. |
| | | A thread is always selected in the command interpreter when a target stops. | | | | `SBFrame.GetThread` | A thread is always selected in the command interpreter when a target stops. |
| | | The **thread select <thread-index>** command can be used to change the | | | | | The `thread select <thread-index>` command can be used to change the |
| | | currently selected thread. So as long as you have a stopped process, there will be | | | | | currently selected thread. So as long as you have a stopped process, there will be |
| | | some selected thread. | | | | | some selected thread. |
+-------------------+---------------------+-------------------------------------------------------------------------------------+ +-------------------+---------------------+-------------------------------------+-------------------------------------------------------------------------------------+
| **lldb.frame** | **lldb.SBFrame** | Contains the currently selected stack frame. | | `lldb.frame` | `lldb.SBFrame` | `SBThread.GetSelectedFrame` | Contains the currently selected stack frame. |
| | | The **lldb.SBFrame** object manage the stack locals and the register set for | | | | | The `lldb.SBFrame` object manage the stack locals and the register set for |
| | | that stack. | | | | | that stack. |
| | | A stack frame is always selected in the command interpreter when a target stops. | | | | | A stack frame is always selected in the command interpreter when a target stops. |
| | | The **frame select <frame-index>** command can be used to change the | | | | | The `frame select <frame-index>` command can be used to change the |
| | | currently selected frame. So as long as you have a stopped process, there will | | | | | currently selected frame. So as long as you have a stopped process, there will |
| | | be some selected frame. | | | | | be some selected frame. |
+-------------------+---------------------+-------------------------------------------------------------------------------------+ +-------------------+---------------------+-------------------------------------+-------------------------------------------------------------------------------------+
While extremely convenient, these variables have a couple caveats that you While extremely convenient, these variables have a couple caveats that you
should be aware of. First of all, they hold the values of the selected objects should be aware of. First of all, they hold the values of the selected objects
on entry to the embedded interpreter. They do not update as you use the LLDB on entry to the embedded interpreter. They do not update as you use the LLDB
API's to change, for example, the currently selected stack frame or thread. API's to change, for example, the currently selected stack frame or thread.
Moreover, they are only defined and meaningful while in the interactive Python Moreover, they are only defined and meaningful while in the interactive Python
interpreter. There is no guarantee on their value in any other situation, hence interpreter. There is no guarantee on their value in any other situation, hence
you should not use them when defining Python formatters, breakpoint scripts and you should not use them when defining Python formatters, breakpoint scripts and
commands (or any other Python extension point that LLDB provides). As a commands (or any other Python extension point that LLDB provides). For the
rationale for such behavior, consider that lldb can run in a multithreaded latter you'll be passed an `SBDebugger`, `SBTarget`, `SBProcess`, `SBThread` or
`SBframe` instance and you can use the functions from the "Equivalent" column
to navigate between them.
As a rationale for such behavior, consider that lldb can run in a multithreaded
environment, and another thread might call the "script" command, changing the environment, and another thread might call the "script" command, changing the
value out from under you. value out from under you.
To get started with these objects and LLDB scripting, please note that almost To get started with these objects and LLDB scripting, please note that almost
all of the lldb Python objects are able to briefly describe themselves when you all of the lldb Python objects are able to briefly describe themselves when you
pass them to the Python print function: pass them to the Python print function:
:: ::
Show All 35 Lines::
def breakpoint_function_wrapper(frame, bp_loc, extra_args, internal_dict): def breakpoint_function_wrapper(frame, bp_loc, extra_args, internal_dict):
# Your code goes here # Your code goes here
+-------------------+-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+ +-------------------+-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
| Argument | Type | Description | | Argument | Type | Description |
+-------------------+-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+ +-------------------+-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
| **frame** | **lldb.SBFrame** | The current stack frame where the breakpoint got hit. | | `frame` | `lldb.SBFrame` | The current stack frame where the breakpoint got hit. |
| | | The object will always be valid. | | | | The object will always be valid. |
| | | This **frame** argument might *not* match the currently selected stack frame found in the **lldb** module global variable **lldb.frame**. | | | | This `frame` argument might *not* match the currently selected stack frame found in the `lldb` module global variable `lldb.frame`. |
+-------------------+-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+ +-------------------+-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
| **bp_loc** | **lldb.SBBreakpointLocation** | The breakpoint location that just got hit. Breakpoints are represented by **lldb.SBBreakpoint** | | `bp_loc` | `lldb.SBBreakpointLocation` | The breakpoint location that just got hit. Breakpoints are represented by `lldb.SBBreakpoint` |
| | | objects. These breakpoint objects can have one or more locations. These locations | | | | objects. These breakpoint objects can have one or more locations. These locations |
| | | are represented by **lldb.SBBreakpointLocation** objects. | | | | are represented by `lldb.SBBreakpointLocation` objects. |
+-------------------+-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+ +-------------------+-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
| **extra_args** | **lldb.SBStructuredData** | **Optional** If your breakpoint callback function takes this extra parameter, then when the callback gets added to a breakpoint, its | | `extra_args` | `lldb.SBStructuredData` | `Optional` If your breakpoint callback function takes this extra parameter, then when the callback gets added to a breakpoint, its |
| | | contents can parametrize this use of the callback. For instance, instead of writing a callback that stops when the caller is "Foo", | | | | contents can parametrize this use of the callback. For instance, instead of writing a callback that stops when the caller is "Foo", |
| | | you could take the function name from a field in the **extra_args**, making the callback more general. The **-k** and **-v** options | | | | you could take the function name from a field in the `extra_args`, making the callback more general. The `-k` and `-v` options |
| | | to **breakpoint command add** will be passed as a Dictionary in the **extra_args** parameter, or you can provide it with the SB API's. | | | | to `breakpoint command add` will be passed as a Dictionary in the `extra_args` parameter, or you can provide it with the SB API's. |
+-------------------+-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+ +-------------------+-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
| **internal_dict** | **dict** | The python session dictionary as a standard python dictionary object. | | `internal_dict` | `dict` | The python session dictionary as a standard python dictionary object. |
+-------------------+-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+ +-------------------+-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
Optionally, a Python breakpoint command can return a value. Returning False Optionally, a Python breakpoint command can return a value. Returning False
tells LLDB that you do not want to stop at the breakpoint. Any other return tells LLDB that you do not want to stop at the breakpoint. Any other return
value (including None or leaving out the return statement altogether) is akin value (including None or leaving out the return statement altogether) is akin
to telling LLDB to actually stop at the breakpoint. This can be useful in to telling LLDB to actually stop at the breakpoint. This can be useful in
situations where a breakpoint only needs to stop the process when certain situations where a breakpoint only needs to stop the process when certain
conditions are met, and you do not want to inspect the program state manually conditions are met, and you do not want to inspect the program state manually
▲ Show 20 Lines • Show All 119 Lines • ▼ Show 20 Lines
At present, when adding a scripted Breakpoint type, you can only provide a At present, when adding a scripted Breakpoint type, you can only provide a
custom Resolver, not a custom SearchFilter. custom Resolver, not a custom SearchFilter.
The custom Resolver is provided as a Python class with the following methods: The custom Resolver is provided as a Python class with the following methods:
+--------------------+---------------------------------------+------------------------------------------------------------------------------------------------------------------+ +--------------------+---------------------------------------+------------------------------------------------------------------------------------------------------------------+
| Name | Arguments | Description | | Name | Arguments | Description |
+--------------------+---------------------------------------+------------------------------------------------------------------------------------------------------------------+ +--------------------+---------------------------------------+------------------------------------------------------------------------------------------------------------------+
| **__init__** | **bkpt: lldb.SBBreakpoint** | This is the constructor for the new Resolver. | | `__init__` | `bkpt: lldb.SBBreakpoint` | This is the constructor for the new Resolver. |
| | **extra_args: lldb.SBStructuredData** | | | | `extra_args: lldb.SBStructuredData` | |
| | | | | | | |
| | | **bkpt** is the breakpoint owning this Resolver. | | | | `bkpt` is the breakpoint owning this Resolver. |
| | | | | | | |
| | | | | | | |
| | | **extra_args** is an SBStructuredData object that the user can pass in when creating instances of this | | | | `extra_args` is an SBStructuredData object that the user can pass in when creating instances of this |
| | | breakpoint. It is not required, but is quite handy. For instance if you were implementing a breakpoint on some | | | | breakpoint. It is not required, but is quite handy. For instance if you were implementing a breakpoint on some |
| | | symbol name, you could write a generic symbol name based Resolver, and then allow the user to pass | | | | symbol name, you could write a generic symbol name based Resolver, and then allow the user to pass |
| | | in the particular symbol in the extra_args | | | | in the particular symbol in the extra_args |
+--------------------+---------------------------------------+------------------------------------------------------------------------------------------------------------------+ +--------------------+---------------------------------------+------------------------------------------------------------------------------------------------------------------+
| **__callback__** | **sym_ctx: lldb.SBSymbolContext** | This is the Resolver callback. | | `__callback__` | `sym_ctx: lldb.SBSymbolContext` | This is the Resolver callback. |
| | | The **sym_ctx** argument will be filled with the current stage | | | | The `sym_ctx` argument will be filled with the current stage |
| | | of the search. | | | | of the search. |
| | | | | | | |
| | | | | | | |
| | | For instance, if you asked for a search depth of lldb.eSearchDepthCompUnit, then the | | | | For instance, if you asked for a search depth of lldb.eSearchDepthCompUnit, then the |
| | | target, module and compile_unit fields of the sym_ctx will be filled. The callback should look just in the | | | | target, module and compile_unit fields of the sym_ctx will be filled. The callback should look just in the |
| | | context passed in **sym_ctx** for new locations. If the callback finds an address of interest, it | | | | context passed in `sym_ctx` for new locations. If the callback finds an address of interest, it |
| | | can add it to the breakpoint with the **SBBreakpoint::AddLocation** method, using the breakpoint passed | | | | can add it to the breakpoint with the `SBBreakpoint::AddLocation` method, using the breakpoint passed |
| | | in to the **__init__** method. | | | | in to the `__init__` method. |
+--------------------+---------------------------------------+------------------------------------------------------------------------------------------------------------------+ +--------------------+---------------------------------------+------------------------------------------------------------------------------------------------------------------+
| **__get_depth__** | **None** | Specify the depth at which you wish your callback to get called. The currently supported options are: | | `__get_depth__` | `None` | Specify the depth at which you wish your callback to get called. The currently supported options are: |
| | | | | | | |
| | | lldb.eSearchDepthModule | | | | lldb.eSearchDepthModule |
| | | lldb.eSearchDepthCompUnit | | | | lldb.eSearchDepthCompUnit |
| | | lldb.eSearchDepthFunction | | | | lldb.eSearchDepthFunction |
| | | | | | | |
| | | For instance, if you are looking | | | | For instance, if you are looking |
| | | up symbols, which are stored at the Module level, you will want to get called back module by module. | | | | up symbols, which are stored at the Module level, you will want to get called back module by module. |
| | | So you would want to return **lldb.eSearchDepthModule**. This method is optional. If not provided the search | | | | So you would want to return `lldb.eSearchDepthModule`. This method is optional. If not provided the search |
| | | will be done at Module depth. | | | | will be done at Module depth. |
+--------------------+---------------------------------------+------------------------------------------------------------------------------------------------------------------+ +--------------------+---------------------------------------+------------------------------------------------------------------------------------------------------------------+
| **get_short_help** | **None** | This is an optional method. If provided, the returned string will be printed at the beginning of | | `get_short_help` | `None` | This is an optional method. If provided, the returned string will be printed at the beginning of |
| | | the description for this breakpoint. | | | | the description for this breakpoint. |
+--------------------+---------------------------------------+------------------------------------------------------------------------------------------------------------------+ +--------------------+---------------------------------------+------------------------------------------------------------------------------------------------------------------+
To define a new breakpoint command defined by this class from the lldb command To define a new breakpoint command defined by this class from the lldb command
line, use the command: line, use the command:
:: ::
▲ Show 20 Lines • Show All 55 Lines • ▼ Show 20 Lines
plans are set to be "MasterPlans", and not "OkayToDiscard". plans are set to be "MasterPlans", and not "OkayToDiscard".
To implement a scripted step, you define a python class that has the following To implement a scripted step, you define a python class that has the following
methods: methods:
+-------------------+------------------------------------+---------------------------------------------------------------------------------------+ +-------------------+------------------------------------+---------------------------------------------------------------------------------------+
| Name | Arguments | Description | | Name | Arguments | Description |
+-------------------+------------------------------------+---------------------------------------------------------------------------------------+ +-------------------+------------------------------------+---------------------------------------------------------------------------------------+
| **__init__** | **thread_plan: lldb.SBThreadPlan** | This is the underlying SBThreadPlan that is pushed onto the plan stack. | | `__init__` | `thread_plan: lldb.SBThreadPlan` | This is the underlying SBThreadPlan that is pushed onto the plan stack. |
| | | You will want to store this away in an ivar. Also, if you are going to | | | | You will want to store this away in an ivar. Also, if you are going to |
| | | use one of the canned thread plans, you can queue it at this point. | | | | use one of the canned thread plans, you can queue it at this point. |
+-------------------+------------------------------------+---------------------------------------------------------------------------------------+ +-------------------+------------------------------------+---------------------------------------------------------------------------------------+
| **explains_stop** | **event: lldb.SBEvent** | Return True if this stop is part of your thread plans logic, false otherwise. | | `explains_stop` | `event: lldb.SBEvent` | Return True if this stop is part of your thread plans logic, false otherwise. |
+-------------------+------------------------------------+---------------------------------------------------------------------------------------+ +-------------------+------------------------------------+---------------------------------------------------------------------------------------+
| **is_stale** | **None** | If your plan is no longer relevant (for instance, you were | | `is_stale` | `None` | If your plan is no longer relevant (for instance, you were |
| | | stepping in a particular stack frame, but some other operation | | | | stepping in a particular stack frame, but some other operation |
| | | pushed that frame off the stack) return True and your plan will | | | | pushed that frame off the stack) return True and your plan will |
| | | get popped. | | | | get popped. |
+-------------------+------------------------------------+---------------------------------------------------------------------------------------+ +-------------------+------------------------------------+---------------------------------------------------------------------------------------+
| **should_step** | **None** | Return True if you want lldb to instruction step one instruction, | | `should_step` | `None` | Return True if you want lldb to instruction step one instruction, |
| | | or False to continue till the next breakpoint is hit. | | | | or False to continue till the next breakpoint is hit. |
+-------------------+------------------------------------+---------------------------------------------------------------------------------------+ +-------------------+------------------------------------+---------------------------------------------------------------------------------------+
| **should_stop** | **event: lldb.SBEvent** | If your plan wants to stop and return control to the user at this point, return True. | | `should_stop` | `event: lldb.SBEvent` | If your plan wants to stop and return control to the user at this point, return True. |
| | | If your plan is done at this point, call SetPlanComplete on your | | | | If your plan is done at this point, call SetPlanComplete on your |
| | | thread plan instance. | | | | thread plan instance. |
| | | Also, do any work you need here to set up the next stage of stepping. | | | | Also, do any work you need here to set up the next stage of stepping. |
+-------------------+------------------------------------+---------------------------------------------------------------------------------------+ +-------------------+------------------------------------+---------------------------------------------------------------------------------------+
To use this class to implement a step, use the command: To use this class to implement a step, use the command:
:: ::
▲ Show 20 Lines • Show All 44 Lines • ▼ Show 20 Lines
:: ::
def command_function(debugger, command, exe_ctx, result, internal_dict): def command_function(debugger, command, exe_ctx, result, internal_dict):
# Your code goes here # Your code goes here
+-------------------+--------------------------------+----------------------------------------------------------------------------------------------------------------------------------+ +-------------------+--------------------------------+----------------------------------------------------------------------------------------------------------------------------------+
| Argument | Type | Description | | Argument | Type | Description |
+-------------------+--------------------------------+----------------------------------------------------------------------------------------------------------------------------------+ +-------------------+--------------------------------+----------------------------------------------------------------------------------------------------------------------------------+
| **debugger** | **lldb.SBDebugger** | The current debugger object. | | `debugger` | `lldb.SBDebugger` | The current debugger object. |
+-------------------+--------------------------------+----------------------------------------------------------------------------------------------------------------------------------+ +-------------------+--------------------------------+----------------------------------------------------------------------------------------------------------------------------------+
| **command** | **python string** | A python string containing all arguments for your command. If you need to chop up the arguments | | `command` | `python string` | A python string containing all arguments for your command. If you need to chop up the arguments |
| | | try using the **shlex** module's shlex.split(command) to properly extract the | | | | try using the `shlex` module's shlex.split(command) to properly extract the |
| | | arguments. | | | | arguments. |
+-------------------+--------------------------------+----------------------------------------------------------------------------------------------------------------------------------+ +-------------------+--------------------------------+----------------------------------------------------------------------------------------------------------------------------------+
| **exe_ctx** | **lldb.SBExecutionContext** | An execution context object carrying around information on the inferior process' context in which the command is expected to act | | `exe_ctx` | `lldb.SBExecutionContext` | An execution context object carrying around information on the inferior process' context in which the command is expected to act |
| | | | | | | |
| | | *Optional since lldb 3.5.2, unavailable before* | | | | *Optional since lldb 3.5.2, unavailable before* |
+-------------------+--------------------------------+----------------------------------------------------------------------------------------------------------------------------------+ +-------------------+--------------------------------+----------------------------------------------------------------------------------------------------------------------------------+
| **result** | **lldb.SBCommandReturnObject** | A return object which encapsulates success/failure information for the command and output text | | `result` | `lldb.SBCommandReturnObject` | A return object which encapsulates success/failure information for the command and output text |
| | | that needs to be printed as a result of the command. The plain Python "print" command also works but | | | | that needs to be printed as a result of the command. The plain Python "print" command also works but |
| | | text won't go in the result by default (it is useful as a temporary logging facility). | | | | text won't go in the result by default (it is useful as a temporary logging facility). |
+-------------------+--------------------------------+----------------------------------------------------------------------------------------------------------------------------------+ +-------------------+--------------------------------+----------------------------------------------------------------------------------------------------------------------------------+
| **internal_dict** | **python dict object** | The dictionary for the current embedded script session which contains all variables | | `internal_dict` | `python dict object` | The dictionary for the current embedded script session which contains all variables |
| | | and functions. | | | | and functions. |
+-------------------+--------------------------------+----------------------------------------------------------------------------------------------------------------------------------+ +-------------------+--------------------------------+----------------------------------------------------------------------------------------------------------------------------------+
Since lldb 3.7, Python commands can also be implemented by means of a class Since lldb 3.7, Python commands can also be implemented by means of a class
which should implement the following interface: which should implement the following interface:
:: ::
▲ Show 20 Lines • Show All 295 Lines • ▼ Show 20 Lines
constructor of the Python object managing the stop hook. This allows for constructor of the Python object managing the stop hook. This allows for
parametrization of the stop hooks. parametrization of the stop hooks.
To add a Python-based stop hook, first define a class with the following methods: To add a Python-based stop hook, first define a class with the following methods:
+--------------------+---------------------------------------+------------------------------------------------------------------------------------------------------------------+ +--------------------+---------------------------------------+------------------------------------------------------------------------------------------------------------------+
| Name | Arguments | Description | | Name | Arguments | Description |
+--------------------+---------------------------------------+------------------------------------------------------------------------------------------------------------------+ +--------------------+---------------------------------------+------------------------------------------------------------------------------------------------------------------+
| **__init__** | **target: lldb.SBTarget** | This is the constructor for the new stop-hook. | | `__init__` | `target: lldb.SBTarget` | This is the constructor for the new stop-hook. |
| | **extra_args: lldb.SBStructuredData** | | | | `extra_args: lldb.SBStructuredData` | |
| | | | | | | |
| | | **target** is the SBTarget to which the stop hook is added. | | | | `target` is the SBTarget to which the stop hook is added. |
| | | | | | | |
| | | **extra_args** is an SBStructuredData object that the user can pass in when creating instances of this | | | | `extra_args` is an SBStructuredData object that the user can pass in when creating instances of this |
| | | breakpoint. It is not required, but allows for reuse of stop-hook classes. | | | | breakpoint. It is not required, but allows for reuse of stop-hook classes. |
+--------------------+---------------------------------------+------------------------------------------------------------------------------------------------------------------+ +--------------------+---------------------------------------+------------------------------------------------------------------------------------------------------------------+
| **handle_stop** | **exe_ctx: lldb.SBExecutionContext** | This is the called when the target stops. | | `handle_stop` | `exe_ctx: lldb.SBExecutionContext` | This is the called when the target stops. |
| | **stream: lldb.SBStream** | | | | `stream: lldb.SBStream` | |
| | | **exe_ctx** argument will be filled with the current stop point for which the stop hook is | | | | `exe_ctx` argument will be filled with the current stop point for which the stop hook is |
| | | being evaluated. | | | | being evaluated. |
| | | | | | | |
| | | **stream** an lldb.SBStream, anything written to this stream will be written to the debugger console. | | | | `stream` an lldb.SBStream, anything written to this stream will be written to the debugger console. |
| | | | | | | |
| | | The return value is a "Should Stop" vote from this thread. If the method returns either True or no return | | | | The return value is a "Should Stop" vote from this thread. If the method returns either True or no return |
| | | this thread votes to stop. If it returns False, then the thread votes to continue after all the stop-hooks | | | | this thread votes to stop. If it returns False, then the thread votes to continue after all the stop-hooks |
| | | are evaluated. | | | | are evaluated. |
| | | Note, the --auto-continue flag to 'target stop-hook add' overrides a True return value from the method. | | | | Note, the --auto-continue flag to 'target stop-hook add' overrides a True return value from the method. |
+--------------------+---------------------------------------+------------------------------------------------------------------------------------------------------------------+ +--------------------+---------------------------------------+------------------------------------------------------------------------------------------------------------------+
To use this class in lldb, run the command: To use this class in lldb, run the command:
:: ::
(lldb) command script import MyModule.py (lldb) command script import MyModule.py
(lldb) target stop-hook add -P MyModule.MyStopHook -k first -v 1 -k second -v 2 (lldb) target stop-hook add -P MyModule.MyStopHook -k first -v 1 -k second -v 2
where MyModule.py is the file containing the class definition MyStopHook. where MyModule.py is the file containing the class definition MyStopHook.