Author: Jim Ingham Date: 2021-02-09T15:33:36-08:00 New Revision: 365b186c242b0c3516d7dbb174f3a258c1c8361c
URL: https://github.com/llvm/llvm-project/commit/365b186c242b0c3516d7dbb174f3a258c1c8361c DIFF: https://github.com/llvm/llvm-project/commit/365b186c242b0c3516d7dbb174f3a258c1c8361c.diff LOG: Add documentation for the extra_args parameter to breakpoint commands. Differential Revision: https://reviews.llvm.org/D96368 Added: Modified: lldb/docs/use/python-reference.rst lldb/source/Commands/CommandObjectBreakpointCommand.cpp Removed: ################################################################################ diff --git a/lldb/docs/use/python-reference.rst b/lldb/docs/use/python-reference.rst index e5542bb5b0ae..f3ce744128c9 100644 --- a/lldb/docs/use/python-reference.rst +++ b/lldb/docs/use/python-reference.rst @@ -182,20 +182,32 @@ arguments: def breakpoint_function_wrapper(frame, bp_loc, dict): # Your code goes here +or: -+------------+-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+ -| Argument | Type | Description | -+------------+-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+ -| **frame** | **lldb.SBFrame** | The current stack frame where the breakpoint got hit. | -| | | 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**. | -+------------+-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+ -| **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 | -| | | are represented by **lldb.SBBreakpointLocation** objects. | -+------------+-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+ -| **dict** | **dict** | The python session dictionary as a standard python dictionary object. | -+------------+-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+ +:: + + def breakpoint_function_wrapper(frame, bp_loc, extra_args, dict): + # Your code goes here + + ++----------------+-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+ +| Argument | Type | Description | ++----------------+-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+ +| **frame** | **lldb.SBFrame** | The current stack frame where the breakpoint got hit. | +| | | 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**. | ++----------------+-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+ +| **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 | +| | | 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 | +| | | 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 | +| | | 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. | ++----------------+-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+ +| **dict** | **dict** | The python session dictionary as a standard python dictionary object. | ++----------------+-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+ 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 diff --git a/lldb/source/Commands/CommandObjectBreakpointCommand.cpp b/lldb/source/Commands/CommandObjectBreakpointCommand.cpp index caaf3bfb482f..241a75e7fbb2 100644 --- a/lldb/source/Commands/CommandObjectBreakpointCommand.cpp +++ b/lldb/source/Commands/CommandObjectBreakpointCommand.cpp @@ -117,14 +117,22 @@ to supply the function name prepended by the module name:" --python-function myutils.breakpoint_callback -The function itself must have the following prototype: +The function itself must have either of the following prototypes: def breakpoint_callback(frame, bp_loc, dict): # Your code goes here +or: + +def breakpoint_callback(frame, bp_loc, extra_args, dict): + # Your code goes here + )" "The arguments are the same as the arguments passed to generated functions as \ -described above. Note that the global variable 'lldb.frame' will NOT be updated when \ +described above. In the second form, any -k and -v pairs provided to the command will \ +be packaged into a SBDictionary in an SBStructuredData and passed as the extra_args parameter. \ +\n\n\ +Note that the global variable 'lldb.frame' will NOT be updated when \ this function is called, so be sure to use the 'frame' argument. The 'frame' argument \ can get you to the thread via frame.GetThread(), the thread can get you to the \ process via thread.GetProcess(), and the process can get you back to the target \ _______________________________________________ lldb-commits mailing list lldb-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/lldb-commits
