diff options
Diffstat (limited to 'www/python-reference.html')
| -rwxr-xr-x | www/python-reference.html | 991 |
1 files changed, 0 insertions, 991 deletions
diff --git a/www/python-reference.html b/www/python-reference.html deleted file mode 100755 index bde728f9a4c9f..0000000000000 --- a/www/python-reference.html +++ /dev/null @@ -1,991 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> -<html xmlns="http://www.w3.org/1999/xhtml"> -<head> -<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" /> -<link href="style.css" rel="stylesheet" type="text/css" /> -<title>LLDB Python Reference</title> -</head> - -<body> - <div class="www_title"> - LLDB Python Reference - </div> - -<div id="container"> - <div id="content"> - <!--#include virtual="sidebar.incl"--> - <div id="middle"> - <div class="post"> - <h1 class ="postheader">Introduction</h1> - <div class="postcontent"> - - <p>The entire LLDB API is available as Python functions through a script bridging interface. - This means the LLDB API's can be used directly from python either interactively or to build python apps that - provide debugger features. </p> - <p>Additionally, Python can be used as a programmatic interface within the - lldb command interpreter (we refer to this for brevity as the embedded interpreter). Of course, - in this context it has full access to the LLDB API - with some additional conveniences we will - call out in the FAQ.</p> - - </div> - <div class="postfooter"></div> - <div class="post"> - <h1 class ="postheader">Documentation</h1> - <div class="postcontent"> - - <p>The LLDB API is contained in a python module named <b>lldb</b>. A useful resource when writing Python extensions is the <a href="python_reference/index.html">lldb Python classes reference guide</a>.</p> - <p>The documentation is also accessible in an interactive debugger session with the following command:</p> -<code><pre><tt>(lldb) <b>script help(lldb)</b> - Help on package lldb: - - NAME - lldb - The lldb module contains the public APIs for Python binding. - - FILE - /System/Library/PrivateFrameworks/LLDB.framework/Versions/A/Resources/Python/lldb/__init__.py - - DESCRIPTION -... -</tt></pre></code> - <p>You can also get help using a module class name. The full API that is exposed for that class will be displayed in a man page style window. Below we want to get help on the lldb.SBFrame class:</p> -<code><pre><tt>(lldb) <b>script help(lldb.SBFrame)</b> - Help on class SBFrame in module lldb: - - class SBFrame(__builtin__.object) - | Represents one of the stack frames associated with a thread. - | SBThread contains SBFrame(s). For example (from test/lldbutil.py), - | - | def print_stacktrace(thread, string_buffer = False): - | '''Prints a simple stack trace of this thread.''' - | -... -</tt></pre></code> - <p>Or you can get help using any python object, here we use the <b>lldb.process</b> object which is a global variable in the <b>lldb</b> module which represents the currently selected process:</p> -<code><pre><tt>(lldb) <b>script help(lldb.process)</b> - Help on SBProcess in module lldb object: - - class SBProcess(__builtin__.object) - | Represents the process associated with the target program. - | - | SBProcess supports thread iteration. For example (from test/lldbutil.py), - | - | # ================================================== - | # Utility functions related to Threads and Processes - | # ================================================== - | -... -</tt></pre></code> - - </div> - <div class="postfooter"></div> - - <div class="post"> - <h1 class ="postheader">Embedded Python Interpreter</h1> - <div class="postcontent"> - - <p>The embedded python interpreter can be accessed in a variety of ways from within LLDB. The - easiest way is to use the lldb command <b>script</b> with no arguments at the lldb command prompt:</p> -<code><pre><tt>(lldb) <strong>script</strong> -Python Interactive Interpreter. To exit, type 'quit()', 'exit()' or Ctrl-D. ->>> 2+3 -5 ->>> hex(12345) -'0x3039' ->>> -</tt></pre></code> - - <p>This drops you into the embedded python interpreter. When running under the <b>script</b> command, - lldb sets some convenience variables that give you quick access to the currently selected entities that characterize - the program and debugger state. In each case, if there is no currently selected entity of the appropriate - type, the variable's <b>IsValid</b> method will return false. These variables are:</p> - - <table class="stats" width="620" cellspacing="0"> - <tr> - <td class="hed" width="20%">Variable</td> - <td class="hed" width="10%">Type</td> - <td class="hed" width="70%">Description</td> - </tr> - - <tr> - <td class="content"> - <b>lldb.debugger</b> - </td> - <td class="content"> - <b>lldb.SBDebugger</b> - </td> - <td class="content"> - Contains the debugger object whose <b>script</b> command was invoked. - The <b>lldb.SBDebugger</b> object owns the command interpreter - and all the targets in your debug session. There will always be a - Debugger in the embedded interpreter. - </td> - </tr> - <tr> - <td class="content"> - <b>lldb.target</b> - </td> - <td class="content"> - <b>lldb.SBTarget</b> - </td> - <td class="content"> - Contains the currently selected target - for instance the one made with the - <b>file</b> or selected by the <b>target select <target-index></b> command. - The <b>lldb.SBTarget</b> manages one running process, and all the executable - and debug files for the process. - </td> - </tr> - <tr> - <td class="content"> - <b>lldb.process</b> - </td> - <td class="content"> - <b>lldb.SBProcess</b> - </td> - <td class="content"> - Contains the process of the currently selected target. - The <b>lldb.SBProcess</b> object manages the threads and allows access to - memory for the process. - </td> - </tr> - <tr> - <td class="content"> - <b>lldb.thread</b> - </td> - <td class="content"> - <b>lldb.SBThread</b> - </td> - <td class="content"> - Contains the currently selected thread. - The <b>lldb.SBThread</b> object manages the stack frames in that thread. - A thread is always selected in the command interpreter when a target stops. - The <b>thread select <thread-index></b> command can be used to change the - currently selected thread. So as long as you have a stopped process, there will be - some selected thread. - </td> - </tr> - <tr> - <td class="content"> - <b>lldb.frame</b> - </td> - <td class="content"> - <b>lldb.SBFrame</b> - </td> - <td class="content"> - Contains the currently selected stack frame. - The <b>lldb.SBFrame</b> object manage the stack locals and the register set for - that stack. - A stack frame is always selected in the command interpreter when a target stops. - The <b>frame select <frame-index></b> command can be used to change the - currently selected frame. So as long as you have a stopped process, there will - be some selected frame. - </td> - </tr> - </table> - - <p>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 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. - <p>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 you should not use them when defining - Python formatters, breakpoint scripts and commands (or any other Python extension point that LLDB provides). - 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 value out - from under you.</p> - - <p>To get started with these objects and LLDB scripting, please note that almost - all of the <b>lldb</b> Python objects are able to briefly describe themselves when you pass them - to the Python <b>print</b> function: -<code><pre><tt>(lldb) <b>script</b> -Python Interactive Interpreter. To exit, type 'quit()', 'exit()' or Ctrl-D. ->>> <strong>print lldb.debugger</strong> -Debugger (instance: "debugger_1", id: 1) ->>> <strong>print lldb.target</strong> -a.out ->>> <strong>print lldb.process</strong> -SBProcess: pid = 59289, state = stopped, threads = 1, executable = a.out ->>> <strong>print lldb.thread</strong> -SBThread: tid = 0x1f03 ->>> <strong>print lldb.frame</strong> -frame #0: 0x0000000100000bb6 a.out main + 54 at main.c:16 -</tt></pre></code> - - </div> - <div class="postfooter"></div> - - </div> - <div class="post"> - <h1 class ="postheader">Running a Python script when a breakpoint gets hit</h1> - <div class="postcontent"> - - <p>One very powerful use of the lldb Python API is to have a python script run when a breakpoint gets hit. Adding python - scripts to breakpoints provides a way to create complex breakpoint - conditions and also allows for smart logging and data gathering.</p> - <p>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 three arguments:</p> - <p> -<code><pre><tt>def breakpoint_function_wrapper(<b>frame</b>, <b>bp_loc</b>, <b>dict</b>): - <font color=green># Your code goes here</font> -</tt></pre></code> - <p><table class="stats" width="620" cellspacing="0"> - <tr> - <td class="hed" width="10%">Argument</td> - <td class="hed" width="10%">Type</td> - <td class="hed" width="80%">Description</td> - </tr> - - <tr> - <td class="content"> - <b>frame</b> - </td> - <td class="content"> - <b>lldb.SBFrame</b> - </td> - <td class="content"> - The current stack frame where the breakpoint got hit. - The object will always be valid. - This <b>frame</b> argument might <i>not</i> match the currently selected stack frame found in the <b>lldb</b> module global variable <b>lldb.frame</b>. - </td> - </tr> - <tr> - <td class="content"> - <b>bp_loc</b> - </td> - <td class="content"> - <b>lldb.SBBreakpointLocation</b> - </td> - <td class="content"> - The breakpoint location that just got hit. Breakpoints are represented by <b>lldb.SBBreakpoint</b> - objects. These breakpoint objects can have one or more locations. These locations - are represented by <b>lldb.SBBreakpointLocation</b> objects. - </td> - </tr> - <tr> - <td class="content"> - <b>dict</b> - </td> - <td class="content"> - <b>dict</b> - </td> - <td class="content"> - The python session dictionary as a standard python dictionary object. - </td> - </tr> - </table> - <p>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 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 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 at every stop and then continue. - <p>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 - are first executed during one run of your program. This is a simple method to gather an order file which - can be used to optimize function placement within a binary for execution locality.</p> - <p>We do this by setting a regular expression breakpoint - that will match every function in the shared library. The regular expression '.' will match - any string that has at least one character in it, so we will use that. - This will result in one <b>lldb.SBBreakpoint</b> object - that contains an <b>lldb.SBBreakpointLocation</b> object for each function. As the breakpoint gets - hit, we use a counter to track the order in which the function at this particular breakpoint location got hit. - Since our code is passed the location that was hit, we can get the name of the function from the location, - disable the location so we won't count this function again; then log some info and continue the process.</p> - <p>Note we also have to initialize our counter, which we do with the simple one-line version of the <b>script</b> - command. - <p>Here is the code: - -<code><pre><tt>(lldb) <strong>breakpoint set --func-regex=. --shlib=libfoo.dylib</strong> -Breakpoint created: 1: regex = '.', module = libfoo.dylib, locations = 223 -(lldb) <strong>script counter = 0</strong> -(lldb) <strong>breakpoint command add --script-type python 1</strong> -Enter your Python command(s). Type 'DONE' to end. -> <font color=green># Increment our counter. Since we are in a function, this must be a global python variable</font> -> <strong>global counter</strong> -> <strong>counter += 1</strong> -> <font color=green># Get the name of the function</font> -> <strong>name = frame.GetFunctionName()</strong> -> <font color=green># Print the order and the function name</font> -> <strong>print '[%i] %s' % (counter, name)</strong> -> <font color=green># Disable the current breakpoint location so it doesn't get hit again</font> -> <strong>bp_loc.SetEnabled(False)</strong> -> <font color=green># No need to stop here</font> -> <strong>return False</strong> -> <strong>DONE</strong> -</tt></pre></code> - <p>The <b>breakpoint command add</b> command above attaches a python script to breakpoint 1. - To remove the breakpoint command: - <p><code>(lldb) <strong>breakpoint command delete 1</strong></code> - </div> - - </div> - </div> - <div class="post"> - <h1 class ="postheader">Using the Python API's to create custom breakpoints</h1> - <div class="postcontent"> - - <p>Another use of the Python API's in lldb is to create a custom breakpoint resolver. This facility - was added in r342259. - </p> - <p> - It allows you to provide the algorithm which will be used in the breakpoint's - search of the space of the code in a given Target - to determine where to set the breakpoint locations - the actual places where the breakpoint will trigger. - To understand how this works you need to know a little about how lldb handles breakpoints. - </p> - <p> - In lldb, a breakpoint is composed of three parts: the Searcher, the Resolver, and the Stop Options. The Searcher and - Resolver cooperate to determine how breakpoint locations are set and differ between each breakpoint type. - Stop options determine what happens when a location triggers and includes the commands, conditions, ignore counts, etc. - Stop options are common between all breakpoint types, so for our purposes only the Searcher and Resolver are relevant. - </p> - <p> - The Searcher's job is to traverse in a structured way the code in the current target. It - proceeds from the Target, to search all the Modules in the Target, in each Module it can recurse - into the Compile Units in that module, and within each Compile Unit it can recurse over the Functions - it contains. - </p> - <p> - The Searcher can be provided with a SearchFilter that it will use to restrict this search. For instance, if the - SearchFilter specifies a list of Modules, the Searcher will not recurse into Modules that aren't on the list. - When you pass the <b>-s modulename</b> flag to <b>break set</b> you are creating a Module-based search filter. - When you pass <b>-f filename.c</b> to <b>break set -n</b> you are creating a file based search filter. If neither - of these is specified, the breakpoint will have a no-op search filter, so all parts of the program are searched - and all locations accepted. - </p> - <p> - The Resolver has two functions. The most important one is the callback it provides. This will get called at the appropriate time - in the course of the search. The callback is where the job of adding locations to the breakpoint gets done. - </p> - <p> - The other function is specifying to the Searcher at what depth in the above described recursion it wants to be - called. Setting a search depth also provides a stop for the recursion. For instance, if you request a Module depth - search, then the callback will be called for each Module as it gets added to the Target, but the searcher will not recurse into the - Compile Units in the module. - </p> - <p> - One other slight sublety is that the depth at which you get called back is not necessarily the depth at which the - the SearchFilter is specified. For instance, if you are doing symbol searches, it is convenient to use the Module - depth for the search, since symbols are stored in the module. - But the SearchFilter might specify some subset of CompileUnits, so not all the symbols you might find in each module - will pass the search. You don't need to - handle this situation yourself, since <b>SBBreakpoint::AddLocation</b> will only add locations that pass the Search Filter. - This API returns an SBError to inform you whether your location was added. - </p> - <p> - When the breakpoint is originally created, its Searcher will process all the currently loaded modules. - The Searcher will also visit any new modules as they are added to the target. This happens, for instance, when - a new shared library gets added to the target in the course of running, or on rerunning if any of the currently - loaded modules have been changed. Note, in the latter case, all the locations set in the old module will get - deleted and you will be asked to recreate them in the new version of the module when your callback gets called - with that module. For this reason, you shouldn't - try to manage the locations you add to the breakpoint yourself. Note that the Breakpoint takes care of - deduplicating equal addresses in AddLocation, so you shouldn't need to worry about that anyway. - </p> - <p> - At present, when adding a scripted Breakpoint type, you can only provide a custom Resolver, not a custom SearchFilter. - </p> - <p> - The custom Resolver is provided as a Python class with the following methods: - </p> -</tt></pre></code> - <p><table class="stats" width="620" cellspacing="0"> - <tr> - <td class="hed" width="10%">Name</td> - <td class="hed" width="10%">Arguments</td> - <td class="hed" width="80%">Description</td> - </tr> - - - <tr> - <td class="content"> - <b>__init__</b> - </td> - <td class="content"> - <b>bkpt: lldb.SBBreakpoint</b> - <b>extra_args: lldb.SBStructuredData</b> - </td> - <td class="content"> - <p> - This is the constructor for the new Resolver. - </p> - <p> - <b>bkpt</b> is the breakpoint owning this Resolver. - </p> - <p> - <b>extra_args</b> 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 - 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 - </td> - </tr> - - <tr> - <td class="content"> - <b>__callback__</b> - </td> - <td class="content"> - <b>sym_ctx: lldb.SBSymbolContext</b> - </td> - <td class="content"> - This is the Resolver callback. - The <b>sym_ctx</b> argument will be filled with the current stage - of the search. - </p> - <p> - 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 - context passed in <b>sym_ctx</b> for new locations. If the callback finds an address of interest, it - can add it to the breakpoint with the <b>SBBreakpoint::AddLocation</b> method, using the breakpoint passed - in to the <b>__init__</b> method. - </td> - </tr> - <tr> - <td class="content"> - <b>__get_depth__</b> - </td> - <td class="content"> - <b>None</b> - </td> - <td class="content"> - Specify the depth at which you wish your callback to get called. The currently supported options are: - <dl> - <dt>lldb.eSearchDepthModule</dt> - <dt>lldb.eSearchDepthCompUnit</dt> - <dt>lldb.eSearchDepthFunction</dt> - </dl> - 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. - So you would want to return <b>lldb.eSearchDepthModule</b>. This method is optional. If not provided the search - will be done at Module depth. - </td> - </tr> - <tr> - <td class="content"> - <b>get_short_help</b> - </td> - <td class="content"> - <b>None</b> - </td> - <td class="content"> - This is an optional method. If provided, the returned string will be printed at the beginning of - the description for this breakpoint. - </td> - </tr> - </table> - - <p>To define a new breakpoint command defined by this class from the lldb command line, use the command:</p> - -<code><pre><tt>(lldb) <strong>breakpoint set -P MyModule.MyResolverClass</strong> -</tt></pre></code> - <p>You can also populate the extra_args SBStructuredData with a dictionary of key/value pairs with:</p> - -<code><pre><tt>(lldb) <strong>breakpoint set -P MyModule.MyResolverClass -k key_1 -v value_1 -k key_2 -v value_2</strong> -</tt></pre></code> - <p>Although you can't write a scripted SearchFilter, both the command line and the SB API's for adding a - scripted resolver allow you to specify a SearchFilter restricted to certain modules or certain compile - units. When using the command line to create the resolver, you can specify a Module specific SearchFilter - by passing the <b>-s ModuleName</b> option - which can be specified multiple times. - You can also specify a SearchFilter restricted to certain - compile units by passing in the <b>-f CompUnitName</b> option. This can also be specified more than - once. And you can mix the two to specify "this comp unit in this module". So, for instance, - </p> - -<code><pre><tt>(lldb) <strong>breakpoint set -P MyModule.MyResolverClass -s a.out</strong> -</tt></pre></code> - <p> - will use your resolver, but will only recurse into or accept new locations in the module a.out. - </p> - - <p>Another option for creating scripted breakpoints is to use the <b>SBTarget.CreateBreakpointFromScript</b> API. - This one has the advantage that you can pass in an arbitrary SBStructuredData object, so you can - create more complex parametrizations. - SBStructuredData has a handy SetFromJSON method which you can use for this purpose. - Your __init__ function gets passed this SBStructuredData object. - This API also allows you to directly provide the list of Modules and the list of CompileUnits that will - make up the SearchFilter. If you pass in empty lists, the breakpoint will use the default "search everywhere,accept - everything" filter. - </p> - - </div> - <div class="post"> - <h1 class ="postheader">Using the Python API's to create custom stepping logic</h1> - <div class="postcontent"> - - <p>A slightly esoteric use of the Python API's is to construct custom stepping types. LLDB's stepping is - driven by a stack of "thread plans" and a fairly simple state machine that runs the plans. You can create - a Python class that works as a thread plan, and responds to the requests the state machine makes to run - its operations. </p> - <p>There is a longer discussion of scripted thread plans and the state machine, and several interesting examples - of their use in:</p> - <a href="http://llvm.org/svn/llvm-project/lldb/trunk/examples/python/scripted_step.py">scripted_step.py</a> - - <p> And for a MUCH fuller discussion of the whole state machine, see:</p> - - <a href="http://llvm.org/svn/llvm-project/lldb/trunk/include/lldb/Target/ThreadPlan.h">ThreadPlan.h</a> - - <p>If you are reading those comments it is useful to know that scripted thread plans are set to be - "MasterPlans", and not "OkayToDiscard". - - <p>To implement a scripted step, you define a python class that has the following methods:</p> -</tt></pre></code> - <p><table class="stats" width="620" cellspacing="0"> - <tr> - <td class="hed" width="10%">Name</td> - <td class="hed" width="10%">Arguments</td> - <td class="hed" width="80%">Description</td> - </tr> - - - <tr> - <td class="content"> - <b>__init__</b> - </td> - <td class="content"> - <b>thread_plan: lldb.SBThreadPlan</b> - </td> - <td class="content"> - 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 - use one of the canned thread plans, you can queue it at this point. - </td> - </tr> - - <tr> - <td class="content"> - <b>explains_stop</b> - </td> - <td class="content"> - <b>event: lldb.SBEvent</b> - </td> - <td class="content"> - Return True if this stop is part of your thread plans logic, false otherwise. - </td> - </tr> - <tr> - <td class="content"> - <b>is_stale</b> - </td> - <td class="content"> - <b>None</b> - </td> - <td class="content"> - If your plan is no longer relevant (for instance, you were - stepping in a particular stack frame, but some other operation - pushed that frame off the stack) return True and your plan will - get popped. - </td> - </tr> - <tr> - <td class="content"> - <b>should_step</b> - </td> - <td class="content"> - <b>None</b> - </td> - <td class="content"> - Return True if you want lldb to instruction step one instruction, - or False to continue till the next breakpoint is hit. - </td> - </tr> - <tr> - <td class="content"> - <b>should_stop</b> - </td> - <td class="content"> - <b>event: lldb.SBEvent</b> - </td> - <td class="content"> - 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 - thread plan instance. - Also, do any work you need here to set up the next stage of stepping. - </td> - </tr> - </table> - - <p>To use this class to implement a step, use the command:</p> - -<code><pre><tt>(lldb) <strong>thread step-scripted -C MyModule.MyStepPlanClass</strong> -</tt></pre></code> - <p>Or use the SBThread.StepUsingScriptedThreadPlan API. The SBThreadPlan passed into - your __init__ function can also push several common plans (step in/out/over and run-to-address) - in front of itself on the stack, which can be used to compose more complex stepping operations. - When you use subsidiary plans your explains_stop and should_stop methods won't get called until - the subsidiary plan is done, or the process stops for an event the subsidiary plan doesn't - explain. For instance, step over plans don't explain a breakpoint hit while performing the - step-over.</p> - - </div> - - </div> - <div class="post"> - <h1 class ="postheader">Create a new LLDB command using a python function</h1> - <div class="postcontent"> - - <p>Python functions can be used to create new LLDB command interpreter commands, which will work - like all the natively defined lldb commands. This provides a very flexible and easy way to extend LLDB to meet your - debugging requirements. </p> - <p>To write a python function that implements a new LLDB command define the function to take four arguments as follows:</p> - - <code><pre><tt>def command_function(<b>debugger</b>, <b>command</b>, <b>result</b>, <b>internal_dict</b>): - <font color=green># Your code goes here</font> - </tt></pre></code> - - Optionally, you can also provide a Python docstring, and LLDB will use it when providing help for your command, as in: - <code><pre><tt>def command_function(<b>debugger</b>, <b>command</b>, <b>result</b>, <b>internal_dict</b>): - <font color=green>"""This command takes a lot of options and does many fancy things"""</font> - <font color=green># Your code goes here</font> - </tt></pre></code> - - Starting with SVN revision 218834, LLDB Python commands can also take an SBExecutionContext as an argument. - This is useful in cases where the command's notion of <i>where to act</i> is independent of the currently-selected entities in the debugger.<br/> - This feature is enabled if the command-implementing function can be recognized as taking 5 arguments, or a variable number of arguments, and it alters the signature as such: - <code><pre><tt>def command_function(<b>debugger</b>, <b>command</b>, <b>exe_ctx</b>, <b>result</b>, <b>internal_dict</b>): - <font color=green># Your code goes here</font> - </tt></pre></code> - - - <p><table class="stats" width="620" cellspacing="0"> - <tr> - <td class="hed" width="10%">Argument</td> - <td class="hed" width="10%">Type</td> - <td class="hed" width="80%">Description</td> - </tr> - - <tr> - <td class="content"> - <b>debugger</b> - </td> - <td class="content"> - <b>lldb.SBDebugger</b> - </td> - <td class="content"> - The current debugger object. - </td> - </tr> - <tr> - <td class="content"> - <b>command</b> - </td> - <td class="content"> - <b>python string</b> - </td> - <td class="content"> - A python string containing all arguments for your command. If you need to chop up the arguments - try using the <b>shlex</b> module's <code>shlex.split(command)</code> to properly extract the - arguments. - </td> - </tr> - <tr> - <td class="content"> - <b>exe_ctx</b> - </td> - <td class="content"> - <b>lldb.SBExecutionContext</b> - </td> - <td class="content"> - An execution context object carrying around information on the inferior process' context in which the command is expected to act - <br/><i>Optional since SVN r218834, unavailable before</i> - </td> - </tr> - <tr> - <td class="content"> - <b>result</b> - </td> - <td class="content"> - <b>lldb.SBCommandReturnObject</b> - </td> - <td class="content"> - 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 - text won't go in the result by default (it is useful as a temporary logging facility). - </td> - </tr> - <tr> - <td class="content"> - <b>internal_dict</b> - </td> - <td class="content"> - <b>python dict object</b> - </td> - <td class="content"> - The dictionary for the current embedded script session which contains all variables - and functions. - </td> - </tr> - </table> - - <p>Starting with SVN revision 232224, Python commands can also be implemented by means of a class - which should implement the following interface:</p> - - <code> - <font color=blue>class</font> CommandObjectType:<br/> - <font color=blue>def</font> __init__(self, debugger, session_dict):<br/> - <i>this call should initialize the command with respect to the command interpreter for the passed-in debugger</i> <br/> - <font color=blue>def</font> __call__(self, debugger, command, exe_ctx, result): <br/> - <i>this is the actual bulk of the command, akin to Python command functions</i> <br/> - <font color=blue>def</font> get_short_help(self): <br/> - <i>this call should return the short help text for this command</i><sup>[1]</sup><br/> - <font color=blue>def</font> get_long_help(self): <br/> - <i>this call should return the long help text for this command</i><sup>[1]</sup><br/> - </code> - -<sup>[1]</sup> This method is optional. - - <p>As a convenience, you can treat the result object as a Python file object, and say - <code><pre><tt>print >>result, "my command does lots of cool stuff"</tt></pre></code> - SBCommandReturnObject and SBStream - both support this file-like behavior by providing write() and flush() calls at the Python layer.</p> - <p>One other handy convenience when defining lldb command-line commands is the command - <b>command script import</b> which will import a module specified by file path - so you - don't have to change your PYTHONPATH for temporary scripts. It also has another convenience - that if your new script module has a function of the form:</p> - -<code><pre><tt>def __lldb_init_module(<b>debugger</b>, <b>internal_dict</b>): - <font color=green># Command Initialization code goes here</font> -</tt></pre></code> - - <p>where <b>debugger</b> and <b>internal_dict</b> are as above, that function will get run when the module is loaded - allowing you to add whatever commands you want into the current debugger. Note that - this function will only be run when using the LLDB command <b>command script import</b>, - it will not get run if anyone imports your module from another module. - If you want to always run code when your module is loaded from LLDB - <u>or</u> when loaded via an <b>import</b> statement in python code - you can test the <b>lldb.debugger</b> object, since you imported the - <lldb> module at the top of the python <b>ls.py</b> module. This test - must be in code that isn't contained inside of any function or class, - just like the standard test for <b>__main__</b> like all python modules - usually do. Sample code would look like: - -<code><pre><tt>if __name__ == '__main__': - <font color=green># Create a new debugger instance in your module if your module - # can be run from the command line. When we run a script from - # the command line, we won't have any debugger object in - # lldb.debugger, so we can just create it if it will be needed</font> - lldb.debugger = lldb.SBDebugger.Create() -elif lldb.debugger: - <font color=green># Module is being run inside the LLDB interpreter</font> - lldb.debugger.HandleCommand('command script add -f ls.ls ls') - print 'The "ls" python command has been installed and is ready for use.' -</tt></pre></code> - <p>Now we can create a module called <b>ls.py</b> in the file <b>~/ls.py</b> that will implement a function that - can be used by LLDB's python command code:</p> - -<code><pre><tt><font color=green>#!/usr/bin/python</font> - -import lldb -import commands -import optparse -import shlex - -def ls(debugger, command, result, internal_dict): - print >>result, (commands.getoutput('/bin/ls %s' % command)) - -<font color=green># And the initialization code to add your commands </font> -def __lldb_init_module(debugger, internal_dict): - debugger.HandleCommand('command script add -f ls.ls ls') - print 'The "ls" python command has been installed and is ready for use.' -</tt></pre></code> - <p>Now we can load the module into LLDB and use it</p> -<code><pre><tt>% lldb -(lldb) <strong>command script import ~/ls.py</strong> -The "ls" python command has been installed and is ready for use. -(lldb) <strong>ls -l /tmp/</strong> -total 365848 --rw-r--r--@ 1 someuser wheel 6148 Jan 19 17:27 .DS_Store --rw------- 1 someuser wheel 7331 Jan 19 15:37 crash.log -</tt></pre></code> - <p>A more interesting template has been created in the source repository that can help you to create - lldb command quickly:</p> - <a href="http://llvm.org/svn/llvm-project/lldb/trunk/examples/python/cmdtemplate.py">cmdtemplate.py</a> - <p> - A commonly required facility is being able to create a command that does some token substitution, and then runs a different debugger command - (usually, it po'es the result of an expression evaluated on its argument). For instance, given the following program: - <code><pre><tt> -#import <Foundation/Foundation.h> -NSString* -ModifyString(NSString* src) -{ - return [src stringByAppendingString:@"foobar"]; -} - -int main() -{ - NSString* aString = @"Hello world"; - NSString* anotherString = @"Let's be friends"; - return 1; -} - </tt></pre></code> - you may want a pofoo X command, that equates po [ModifyString(X) capitalizedString]. - The following debugger interaction shows how to achieve that goal: - <code><pre><tt> -(lldb) <b>script</b> -Python Interactive Interpreter. To exit, type 'quit()', 'exit()' or Ctrl-D. ->>> <b>def pofoo_funct(debugger, command, result, internal_dict):</b> -... <b>cmd = "po [ModifyString(" + command + ") capitalizedString]"</b> -... <b>lldb.debugger.HandleCommand(cmd)</b> -... ->>> ^D -(lldb) <b>command script add pofoo -f pofoo_funct</b> -(lldb) <b>pofoo aString</b> -$1 = 0x000000010010aa00 Hello Worldfoobar -(lldb) <b>pofoo anotherString</b> -$2 = 0x000000010010aba0 Let's Be Friendsfoobar</tt></pre></code> - </div> - <div class="post"> - <h1 class ="postheader">Using the lldb.py module in python</h1> - <div class="postcontent"> - - <p>LLDB has all of its core code build into a shared library which gets - used by the <b>lldb</b> command line application. On Mac OS X this - shared library is a framework: <b>LLDB.framework</b> and on other - unix variants the program is a shared library: <b>lldb.so</b>. LLDB also - provides an lldb.py module that contains the bindings from LLDB into Python. - To use the - <b>LLDB.framework</b> to create your own stand-alone python programs, you will - need to tell python where to look in order to find this module. This - is done by setting the <b>PYTHONPATH</b> environment variable, adding - a path to the directory that contains the <b>lldb.py</b> python module. The - lldb driver program has an option to report the path to the lldb module. - You can use that to point to correct lldb.py: - - <p>For csh and tcsh:</p> - <p><code>% <b>setenv PYTHONPATH `lldb -P`</b></p> - <p>For sh and bash: - <p><code>% <b>export PYTHONPATH=`lldb -P`</b></p> - - <p> Alternately, you can append the LLDB Python directory to the <b>sys.path</b> list directly in - your Python code before importing the lldb module.</p> - - <p> - Now your python scripts are ready to import the lldb module. Below is a - python script that will launch a program from the current working directory - called "a.out", set a breakpoint at "main", and then run and hit the breakpoint, - and print the process, thread and frame objects if the process stopped: - - </p> -<code><pre><tt><font color=green>#!/usr/bin/python</font> - -import lldb -import os - -def disassemble_instructions(insts): - for i in insts: - print i - -<font color=green># Set the path to the executable to debug</font> -exe = "./a.out" - -<font color=green># Create a new debugger instance</font> -debugger = lldb.SBDebugger.Create() - -<font color=green># When we step or continue, don't return from the function until the process -# stops. Otherwise we would have to handle the process events ourselves which, while doable is -#a little tricky. We do this by setting the async mode to false.</font> -debugger.SetAsync (False) - -<font color=green># Create a target from a file and arch</font> -print "Creating a target for '%s'" % exe - -target = debugger.CreateTargetWithFileAndArch (exe, lldb.LLDB_ARCH_DEFAULT) - -if target: - <font color=green># If the target is valid set a breakpoint at main</font> - main_bp = target.BreakpointCreateByName ("main", target.GetExecutable().GetFilename()); - - print main_bp - - <font color=green># Launch the process. Since we specified synchronous mode, we won't return - # from this function until we hit the breakpoint at main</font> - process = target.LaunchSimple (None, None, os.getcwd()) - - <font color=green># Make sure the launch went ok</font> - if process: - <font color=green># Print some simple process info</font> - state = process.GetState () - print process - if state == lldb.eStateStopped: - <font color=green># Get the first thread</font> - thread = process.GetThreadAtIndex (0) - if thread: - <font color=green># Print some simple thread info</font> - print thread - <font color=green># Get the first frame</font> - frame = thread.GetFrameAtIndex (0) - if frame: - <font color=green># Print some simple frame info</font> - print frame - function = frame.GetFunction() - <font color=green># See if we have debug info (a function)</font> - if function: - <font color=green># We do have a function, print some info for the function</font> - print function - <font color=green># Now get all instructions for this function and print them</font> - insts = function.GetInstructions(target) - disassemble_instructions (insts) - else: - <font color=green># See if we have a symbol in the symbol table for where we stopped</font> - symbol = frame.GetSymbol(); - if symbol: - <font color=green># We do have a symbol, print some info for the symbol</font> - print symbol -</tt></pre></code> - </div> - <div class="postfooter"></div> - </div> - - <div class="post"> - <h1 class ="postheader">Writing LLDB frame recognizers in Python</h1> - <div class="postcontent"> - - <p>Frame recognizers allow for retrieving information about special frames based on - ABI, arguments or other special properties of that frame, even without source - code or debug info. Currently, one use case is to extract function arguments - that would otherwise be unaccesible, or augment existing arguments.</p> - - <p>Adding a custom frame recognizer is done by implementing a Python class - and using the '<b>frame recognizer add</b>' command. The Python class should have a - '<b>get_recognized_arguments</b>' method and it will receive an argument of type - <b>lldb.SBFrame</b> representing the current frame that we are trying to recognize. - The method should return a (possibly empty) list of <b>lldb.SBValue</b> objects that - represent the recognized arguments.</p> - - <p>An example of a recognizer that retrieves the file descriptor values from libc - functions '<b>read</b>', '<b>write</b>' and '<b>close</b>' follows:</p> - -<code><pre><tt> class LibcFdRecognizer(object): - def get_recognized_arguments(self, frame): - if frame.name in ["read", "write", "close"]: - fd = frame.EvaluateExpression("$arg1").unsigned - value = lldb.target.CreateValueFromExpression("fd", "(int)%d" % fd) - return [value] - return [] -</tt></pre></code> - - <p>The file containing this implementation can be imported via '<b>command script - import</b>' and then we can register this recognizer with '<b>frame recognizer add</b>'. - It's important to restrict the recognizer to the libc library (which is - libsystem_kernel.dylib on macOS) to avoid matching functions with the same name in other modules:</p> - -<code><pre><tt>(lldb) <b>command script import .../fd_recognizer.py</b> -(lldb) <b>frame recognizer add -l fd_recognizer.LibcFdRecognizer -n read -s libsystem_kernel.dylib</b> -</tt></pre></code> - - <p>When the program is stopped at the beginning of the '<b>read</b>' function in libc, we - can view the recognizer arguments in '<b>frame variable</b>':</p> - -<code><pre><tt>(lldb) <b>b read</b> -(lldb) <b>r</b> -Process 1234 stopped -* thread #1, queue = 'com.apple.main-thread', stop reason = breakpoint 1.3 - frame #0: 0x00007fff06013ca0 libsystem_kernel.dylib`read -(lldb) <b>frame variable</b> -(int) fd = 3 -</tt></pre></code> - - </div> - <div class="postfooter"></div> - </div> - - </div> -</div> -</body> -</html> |