jingham created this revision.
jingham added a reviewer: JDevlieghere.
jingham requested review of this revision.
Herald added a project: LLDB.
Herald added a subscriber: lldb-commits.
I forgot to document this when adding the feature. Added docs here in both the
python-reference.rst and in the command help.
Repository:
rG LLVM Github Monorepo
https://reviews.llvm.org/D96368
Files:
lldb/docs/use/python-reference.rst
lldb/source/Commands/CommandObjectBreakpointCommand.cpp
Index: lldb/source/Commands/CommandObjectBreakpointCommand.cpp
===================================================================
--- lldb/source/Commands/CommandObjectBreakpointCommand.cpp
+++ lldb/source/Commands/CommandObjectBreakpointCommand.cpp
@@ -117,14 +117,22 @@
--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 \
Index: lldb/docs/use/python-reference.rst
===================================================================
--- lldb/docs/use/python-reference.rst
+++ lldb/docs/use/python-reference.rst
@@ -182,20 +182,32 @@
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
Index: lldb/source/Commands/CommandObjectBreakpointCommand.cpp
===================================================================
--- lldb/source/Commands/CommandObjectBreakpointCommand.cpp
+++ lldb/source/Commands/CommandObjectBreakpointCommand.cpp
@@ -117,14 +117,22 @@
--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 \
Index: lldb/docs/use/python-reference.rst
===================================================================
--- lldb/docs/use/python-reference.rst
+++ lldb/docs/use/python-reference.rst
@@ -182,20 +182,32 @@
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
_______________________________________________
lldb-commits mailing list
[email protected]
https://lists.llvm.org/cgi-bin/mailman/listinfo/lldb-commits
