[Lldb-commits] [lldb] 365b186 - Add documentation for the extra_args parameter to breakpoint commands.

[Jim Ingham via lldb-commits]

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 \