From 13b1213de3bd977f65bcdf47ab0f6e4fb14ba056 Mon Sep 17 00:00:00 2001 From: Greg Clayton Date: Fri, 26 Oct 2012 17:53:21 +0000 Subject: [PATCH] Updated the "breakpoint command add" documentation and fixed the web site docs for the signature of the python breakpoint callback functions. llvm-svn: 166789 --- .../Commands/CommandObjectBreakpointCommand.cpp | 233 +++++++++++---------- lldb/www/python-reference.html | 15 +- 2 files changed, 137 insertions(+), 111 deletions(-) diff --git a/lldb/source/Commands/CommandObjectBreakpointCommand.cpp b/lldb/source/Commands/CommandObjectBreakpointCommand.cpp index 8f19dde..f308ae3 100644 --- a/lldb/source/Commands/CommandObjectBreakpointCommand.cpp +++ b/lldb/source/Commands/CommandObjectBreakpointCommand.cpp @@ -44,71 +44,86 @@ public: m_options (interpreter) { SetHelpLong ( -"\nGeneral information about entering breakpoint commands \n\ ------------------------------------------------------- \n\ - \n\ -This command will cause you to be prompted to enter the command or set \n\ -of commands you wish to be executed when the specified breakpoint is \n\ -hit. You will be told to enter your command(s), and will see a '> ' \n\ -prompt. Because you can enter one or many commands to be executed when \n\ -a breakpoint is hit, you will continue to be prompted after each \n\ -new-line that you enter, until you enter the word 'DONE', which will \n\ -cause the commands you have entered to be stored with the breakpoint \n\ -and executed when the breakpoint is hit. \n\ - \n\ -Syntax checking is not necessarily done when breakpoint commands are \n\ -entered. An improperly written breakpoint command will attempt to get \n\ -executed when the breakpoint gets hit, and usually silently fail. If \n\ -your breakpoint command does not appear to be getting executed, go \n\ -back and check your syntax. \n\ - \n\ - \n\ -Special information about PYTHON breakpoint commands \n\ ----------------------------------------------------- \n\ - \n\ -You may enter either one line of Python or multiple lines of Python \n\ -(including defining whole functions, if desired). If you enter a \n\ -single line of Python, that will be passed to the Python interpreter \n\ -'as is' when the breakpoint gets hit. If you enter function \n\ -definitions, they will be passed to the Python interpreter as soon as \n\ -you finish entering the breakpoint command, and they can be called \n\ -later (don't forget to add calls to them, if you want them called when \n\ -the breakpoint is hit). If you enter multiple lines of Python that \n\ -are not function definitions, they will be collected into a new, \n\ -automatically generated Python function, and a call to the newly \n\ -generated function will be attached to the breakpoint. \n\ - \n\ -This auto-generated function is passed in two arguments: \n\ - \n\ - frame: an SBFrame object representing the frame which hit the breakpoint. \n\ - From the frame you can get back to the thread and process. \n\ - bp_loc: the number of the breakpoint location that was hit. \n\ - This is useful since one breakpoint can have many locations. \n\ - \n\ -Important Note: Because loose Python code gets collected into functions, \n\ -if you want to access global variables in the 'loose' code, you need to \n\ -specify that they are global, using the 'global' keyword. Be sure to \n\ -use correct Python syntax, including indentation, when entering Python \n\ -breakpoint commands. \n\ - \n\ -As a third option, you can pass the name of an already existing Python function \n\ -and that function will be attached to the breakpoint. It will get passed the \n\ -frame and bp_loc arguments mentioned above. \n\ - \n\ -Example Python one-line breakpoint command: \n\ - \n\ -(lldb) breakpoint command add -s python 1 \n\ -Enter your Python command(s). Type 'DONE' to end. \n\ -> print \"Hit this breakpoint!\" \n\ -> DONE \n\ - \n\ -As a convenience, this also works for a short Python one-liner: \n\ -(lldb) breakpoint command add -s python 1 -o \"import time; print time.asctime()\" \n\ -(lldb) run \n\ -Launching '.../a.out' (x86_64) \n\ -(lldb) Fri Sep 10 12:17:45 2010 \n\ -Process 21778 Stopped \n\ -* thread #1: tid = 0x2e03, 0x0000000100000de8 a.out`c + 7 at main.c:39, stop reason = breakpoint 1.1, queue = com.apple.main-thread \n\ +"\nGeneral information about entering breakpoint commands\n\ +------------------------------------------------------\n\ +\n\ +This command will cause you to be prompted to enter the command or set of\n\ +commands you wish to be executed when the specified breakpoint is hit. You\n\ +will be told to enter your command(s), and will see a '> 'prompt. Because\n\ +you can enter one or many commands to be executed when a breakpoint is hit,\n\ +you will continue to be prompted after each new-line that you enter, until you\n\ +enter the word 'DONE', which will cause the commands you have entered to be\n\ +stored with the breakpoint and executed when the breakpoint is hit.\n\ +\n\ +Syntax checking is not necessarily done when breakpoint commands are entered.\n\ +An improperly written breakpoint command will attempt to get executed when the\n\ +breakpoint gets hit, and usually silently fail. If your breakpoint command does\n\ +not appear to be getting executed, go back and check your syntax.\n\ +\n\ +Special information about PYTHON breakpoint commands\n\ +----------------------------------------------------\n\ +\n\ +You may enter either one line of Python, multiple lines of Python (including\n\ +function definitions), or specify a Python function in a module that has already,\n\ +or will be imported. If you enter a single line of Python, that will be passed\n\ +to the Python interpreter 'as is' when the breakpoint gets hit. If you enter\n\ +function definitions, they will be passed to the Python interpreter as soon as\n\ +you finish entering the breakpoint command, and they can be called later (don't\n\ +forget to add calls to them, if you want them called when the breakpoint is\n\ +hit). If you enter multiple lines of Python that are not function definitions,\n\ +they will be collected into a new, automatically generated Python function, and\n\ +a call to the newly generated function will be attached to the breakpoint.\n\ +\n\ +\n\ +This auto-generated function is passed in three arguments:\n\ +\n\ + frame: a lldb.SBFrame object for the frame which hit breakpoint.\n\ + bp_loc: a lldb.SBBreakpointLocation object that represents the breakpoint\n\ + location that was hit.\n\ + dict: the python session dictionary hit.\n\ +\n\ +When specifying a python function with the --python-function option, you need\n\ +to supply the function name prepended by the module name. So if you import a\n\ +module named 'myutils' that contains a 'breakpoint_callback' function, you would\n\ +specify the option as:\n\ +\n\ + --python-function myutils.breakpoint_callback\n\ +\n\ +The function itself must have the following prototype:\n\ +\n\ +def breakpoint_callback(frame, bp_loc, dict):\n\ + # Your code goes here\n\ +\n\ +The arguments are the same as the 3 auto generation function arguments listed\n\ +above. Note that the global variable 'lldb.frame' will NOT be setup when this\n\ +function is called, so be sure to use the 'frame' argument. The 'frame' argument\n\ +can get you to the thread (frame.GetThread()), the thread can get you to the\n\ +process (thread.GetProcess()), and the process can get you back to the target\n\ +(process.GetTarget()).\n\ +\n\ +Important Note: Because loose Python code gets collected into functions, if you\n\ +want to access global variables in the 'loose' code, you need to specify that\n\ +they are global, using the 'global' keyword. Be sure to use correct Python\n\ +syntax, including indentation, when entering Python breakpoint commands.\n\ +\n\ +As a third option, you can pass the name of an already existing Python function\n\ +and that function will be attached to the breakpoint. It will get passed the\n\ +frame and bp_loc arguments mentioned above.\n\ +\n\ +Example Python one-line breakpoint command:\n\ +\n\ +(lldb) breakpoint command add -s python 1\n\ +Enter your Python command(s). Type 'DONE' to end.\n\ +> print \"Hit this breakpoint!\"\n\ +> DONE\n\ +\n\ +As a convenience, this also works for a short Python one-liner:\n\ +(lldb) breakpoint command add -s python 1 -o \"import time; print time.asctime()\"\n\ +(lldb) run\n\ +Launching '.../a.out' (x86_64)\n\ +(lldb) Fri Sep 10 12:17:45 2010\n\ +Process 21778 Stopped\n\ +* thread #1: tid = 0x2e03, 0x0000000100000de8 a.out`c + 7 at main.c:39, stop reason = breakpoint 1.1, queue = com.apple.main-thread\n\ 36 \n\ 37 int c(int val)\n\ 38 {\n\ @@ -116,50 +131,50 @@ Process 21778 Stopped \n\ 40 }\n\ 41 \n\ 42 int main (int argc, char const *argv[])\n\ -(lldb) \n\ - \n\ -Example multiple line Python breakpoint command, using function definition: \n\ - \n\ -(lldb) breakpoint command add -s python 1 \n\ -Enter your Python command(s). Type 'DONE' to end. \n\ -> def breakpoint_output (bp_no): \n\ -> out_string = \"Hit breakpoint number \" + repr (bp_no) \n\ -> print out_string \n\ -> return True \n\ -> breakpoint_output (1) \n\ -> DONE \n\ - \n\ - \n\ -Example multiple line Python breakpoint command, using 'loose' Python: \n\ - \n\ -(lldb) breakpoint command add -s p 1 \n\ -Enter your Python command(s). Type 'DONE' to end. \n\ -> global bp_count \n\ -> bp_count = bp_count + 1 \n\ -> print \"Hit this breakpoint \" + repr(bp_count) + \" times!\" \n\ -> DONE \n\ - \n\ -In this case, since there is a reference to a global variable, \n\ -'bp_count', you will also need to make sure 'bp_count' exists and is \n\ -initialized: \n\ - \n\ -(lldb) script \n\ ->>> bp_count = 0 \n\ ->>> quit() \n\ - \n\ -(lldb) \n\ - \n\ - \n\ -Final Note: If you get a warning that no breakpoint command was generated, \n\ -but you did not get any syntax errors, you probably forgot to add a call \n\ -to your functions. \n\ - \n\ -Special information about debugger command breakpoint commands \n\ --------------------------------------------------------------- \n\ - \n\ -You may enter any debugger command, exactly as you would at the \n\ -debugger prompt. You may enter as many debugger commands as you like, \n\ -but do NOT enter more than one command per line. \n" ); +(lldb)\n\ +\n\ +Example multiple line Python breakpoint command, using function definition:\n\ +\n\ +(lldb) breakpoint command add -s python 1\n\ +Enter your Python command(s). Type 'DONE' to end.\n\ +> def breakpoint_output (bp_no):\n\ +> out_string = \"Hit breakpoint number \" + repr (bp_no)\n\ +> print out_string\n\ +> return True\n\ +> breakpoint_output (1)\n\ +> DONE\n\ +\n\ +\n\ +Example multiple line Python breakpoint command, using 'loose' Python:\n\ +\n\ +(lldb) breakpoint command add -s p 1\n\ +Enter your Python command(s). Type 'DONE' to end.\n\ +> global bp_count\n\ +> bp_count = bp_count + 1\n\ +> print \"Hit this breakpoint \" + repr(bp_count) + \" times!\"\n\ +> DONE\n\ +\n\ +In this case, since there is a reference to a global variable,\n\ +'bp_count', you will also need to make sure 'bp_count' exists and is\n\ +initialized:\n\ +\n\ +(lldb) script\n\ +>>> bp_count = 0\n\ +>>> quit()\n\ +\n\ +(lldb)\n\ +\n\ +\n\ +Final Note: If you get a warning that no breakpoint command was generated, but\n\ +you did not get any syntax errors, you probably forgot to add a call to your\n\ +functions.\n\ +\n\ +Special information about debugger command breakpoint commands\n\ +--------------------------------------------------------------\n\ +\n\ +You may enter any debugger command, exactly as you would at the debugger prompt.\n\ +You may enter as many debugger commands as you like, but do NOT enter more than\n\ +one command per line.\n" ); CommandArgumentEntry arg; CommandArgumentData bp_id_arg; diff --git a/lldb/www/python-reference.html b/lldb/www/python-reference.html index e1d7f9d..007ac7e 100755 --- a/lldb/www/python-reference.html +++ b/lldb/www/python-reference.html @@ -213,9 +213,9 @@ frame #0: 0x0000000100000bb6 a.out main + 54 at main.c:16 scripts to breakpoints provides a way to create complex breakpoint conditions and also allows for smart logging and data gathering.

When your process hits a breakpoint to which you have attached some python code, the code is executed as the - body of a function which takes two arguments:

+ body of a function which takes three arguments:

-

def breakpoint_function_wrapper(frame, bp_loc):
+
def breakpoint_function_wrapper(frame, bp_loc, dict):
   # Your code goes here
 

                     

@@ -251,6 +251,17 @@ frame #0: 0x0000000100000bb6 a.out main + 54 at main.c:16
                             are represented by lldb.SBBreakpointLocation objects.
                         
+                    
+                        
+                        
+                        
+                    

                     

+                            dict
+                        
+                            dict
+                        
+                            The python session dictionary as a standard python dictionary object.
+                        

                     

              
An example will show how simple it is to write some python code and attach it to a breakpoint. 
                 The following example will allow you to track the order in which the functions in a given shared library 
-- 
2.7.4