Page MenuHomePhabricator
Differential D104281 Diff 353434 lldb/docs/use/scripting-reference.rst

Changeset View

Standalone View

View Options

lldb/docs/use/scripting-reference.rst

  • This file was moved from lldb/docs/use/python-reference.rst.
Python Reference Scripting Reference
================ ===================
tammelaUnsubmitted
Not Done
ReplyInline Actions

I'm seeing some references to a "python script" when it should be really just "the following script" or something more neutral.

A quick way to solve this is to search for [Pp]ython and try to rewrite the phrase into something generic

tammela: I'm seeing some references to a "python script" when it should be really just "the following…
The entire LLDB API is available as Python functions through a script bridging Python can be used as a programmatic interface within the LLDB command
interface. This means the LLDB API's can be used directly from python either interpreter (we refer to this for brevity as the embedded interpreter).
interactively or to build python apps that provide debugger features.
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 Of course, in this context it has full access to the LLDB API - with some
additional conveniences we will call out in the FAQ. additional conveniences we will call out in the FAQ.
Additionally, 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.
At present, Lua is experimentally available as an embedded interpreter in LLDB.
Since some scripting features are still unavailable in Lua, there is no language
switch tab on code blocks of unsupported features. If you want to use Lua
interpreter, you should ensure that your LLDB is compiled with Lua support.
See :doc:`Building </resources/build>` for instructions.
.. contents:: .. contents::
:local: :local:
Documentation Built-in Documentation
-------------- ----------------------
The LLDB API is contained in a python module named lldb. A useful resource when The LLDB API is contained in a Python module named ``lldb``. A useful resource
writing Python extensions is the lldb Python classes reference guide. when writing Python extensions is the `lldb` Python classes reference guide.
The documentation is also accessible in an interactive debugger session with The documentation is also accessible in an interactive debugger session with
the following command: the following command:
:: ::
(lldb) script help(lldb) (lldb) script help(lldb)
Help on package lldb: Help on package lldb:
Show All 20 Lines (lldb) script help(lldb.SBFrame)
| Represents one of the stack frames associated with a thread. | Represents one of the stack frames associated with a thread.
| SBThread contains SBFrame(s). For example (from test/lldbutil.py), | SBThread contains SBFrame(s). For example (from test/lldbutil.py),
| |
| def print_stacktrace(thread, string_buffer = False): | def print_stacktrace(thread, string_buffer = False):
| '''Prints a simple stack trace of this thread.''' | '''Prints a simple stack trace of this thread.'''
| |
... ...
Or you can get help using any python object, here we use the lldb.process
Or you can get help using any Python object, here we use the lldb.process
object which is a global variable in the lldb module which represents the object which is a global variable in the lldb module which represents the
currently selected process: currently selected process:
:: ::
(lldb) script help(lldb.process) (lldb) script help(lldb.process)
Help on SBProcess in module lldb object: Help on SBProcess in module lldb object:
class SBProcess(__builtin__.object) class SBProcess(__builtin__.object)
| Represents the process associated with the target program. | Represents the process associated with the target program.
| |
| SBProcess supports thread iteration. For example (from test/lldbutil.py), | SBProcess supports thread iteration. For example (from test/lldbutil.py),
| |
| # ================================================== | # ==================================================
| # Utility functions related to Threads and Processes | # Utility functions related to Threads and Processes
| # ================================================== | # ==================================================
| |
... ...
Embedded Python Interpreter Embedded Script Interpreter
--------------------------- ---------------------------
The embedded python interpreter can be accessed in a variety of ways from The embedded script interpreter can be accessed in a variety of ways from
within LLDB. The easiest way is to use the lldb command script with no within LLDB. The easiest way is to use the LLDB command ``script`` with no
arguments at the lldb command prompt: arguments at the LLDB command prompt.
By default, the embedded script interpreter is Python. To choose the language
you prefer, you can specify default language via ``--script-language`` options
when launching LLDB:
::
$ lldb --script-language lua
or pass a parameter to LLDB command ``script``.
:: ::
(lldb) script -l lua --
Language features are all available in the embedded script interpreter:
.. tabs::
.. code-tab:: python
(lldb) script (lldb) script
Python Interactive Interpreter. To exit, type 'quit()', 'exit()' or Ctrl-D. Python Interactive Interpreter. To exit, type 'quit()', 'exit()' or Ctrl-D.
>>> 2+3 >>> 2+3
5 5
>>> hex(12345) >>> hex(12345)
'0x3039' '0x3039'
>>> >>>
This drops you into the embedded python interpreter. When running under the .. code-tab:: lua
script command, lldb sets some convenience variables that give you quick access :emphasize-lines: 1
(lldb) script -l lua --
>>> t = { 1, 2, 3 }
>>> print(t[1])
1
>>> print(t[1] + t[2])
3
>>>
This drops you into the embedded script interpreter. When running under the
script command, LLDB sets some convenience variables that give you quick access
to the currently selected entities that characterize the program and debugger to the currently selected entities that characterize the program and debugger
state. In each case, if there is no currently selected entity of the state. In each case, if there is no currently selected entity of the
appropriate type, the variable's IsValid method will return false. These appropriate type, the variable's IsValid method will return false. These
variables are: variables are:
+-------------------+---------------------+-------------------------------------+-------------------------------------------------------------------------------------+ +-------------------+---------------------+-------------------------------------+-------------------------------------------------------------------------------------+
| Variable | Type | Equivalent | Description | | Variable | Type | Equivalent | Description |
+-------------------+---------------------+-------------------------------------+-------------------------------------------------------------------------------------+ +-------------------+---------------------+-------------------------------------+-------------------------------------------------------------------------------------+
Show All 29 Lines
While extremely convenient, these variables have a couple caveats that you 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 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 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. API's to change, for example, the currently selected stack frame or thread.
Moreover, they are only defined and meaningful while in the interactive Python 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 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 you should not use them when defining custom formatters, breakpoint scripts and
commands (or any other Python extension point that LLDB provides). For the commands (or any other script extension point that LLDB provides). For the
latter you'll be passed an `SBDebugger`, `SBTarget`, `SBProcess`, `SBThread` or latter you'll be passed an `SBDebugger`, `SBTarget`, `SBProcess`, `SBThread` or
`SBframe` instance and you can use the functions from the "Equivalent" column `SBframe` instance and you can use the functions from the "Equivalent" column
to navigate between them. to navigate between them.
As a rationale for such behavior, consider that lldb can run in a multithreaded 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 environment, and another thread might call the "script" command, changing the
value out from under you. value out from under you.
To get started with these objects and LLDB scripting, please note that almost To get started with these objects and LLDB scripting, please note that almost
all of the lldb Python objects are able to briefly describe themselves when you all of the lldb objects are able to briefly describe themselves when you pass
pass them to the Python print function: them to ``print`` function:
:: .. tabs::
.. code-tab:: python
(lldb) script (lldb) script
Python Interactive Interpreter. To exit, type 'quit()', 'exit()' or Ctrl-D. Python Interactive Interpreter. To exit, type 'quit()', 'exit()' or Ctrl-D.
>>> print lldb.debugger >>> print lldb.debugger
Debugger (instance: "debugger_1", id: 1) Debugger (instance: "debugger_1", id: 1)
>>> print lldb.target >>> print lldb.target
a.out a.out
>>> print lldb.process >>> print lldb.process
SBProcess: pid = 59289, state = stopped, threads = 1, executable = a.out SBProcess: pid = 59289, state = stopped, threads = 1, executable = a.out
>>> print lldb.thread >>> print lldb.thread
SBThread: tid = 0x1f03 SBThread: tid = 0x1f03
>>> print lldb.frame >>> print lldb.frame
frame #0: 0x0000000100000bb6 a.out main + 54 at main.c:16 frame #0: 0x0000000100000bb6 a.out main + 54 at main.c:16
.. code-tab:: lua
Running a python script when a breakpoint gets hit (lldb) script -l lua --
-------------------------------------------------- >>> print(lldb.debugger)
Debugger (instance: "debugger_1", id: 1)
One very powerful use of the lldb Python API is to have a python script run >>> print(lldb.target)
when a breakpoint gets hit. Adding python scripts to breakpoints provides a way a.out
to create complex breakpoint conditions and also allows for smart logging and >>> print(lldb.process)
data gathering. SBProcess: pid = 3385871, state = stopped, threads = 1, executable = a.out
>>> print(lldb.thread)
thread #1: tid = 3385871, name = 'a.out', stop reason = breakpoint 1.1
>>> print(lldb.frame)
frame #0: 0x000055555555514f a.out main at test.c:5:3
Running a script when a breakpoint gets hit
-------------------------------------------
One very powerful use of the LLDB API is to have a 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.
When your process hits a breakpoint to which you have attached some python 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 code, the code is executed as the body of a function which takes three
arguments: arguments:
:: .. tabs::
.. code-tab:: python
def breakpoint_function_wrapper(frame, bp_loc, internal_dict): def breakpoint_function_wrapper(frame, bp_loc, internal_dict):
# Your code goes here # Your code goes here
.. code-tab:: lua
function breakpoint_function_wrapper(frame, bp_loc)
-- Your code goes here
or: or:
:: .. tabs::
.. code-tab:: python
def breakpoint_function_wrapper(frame, bp_loc, extra_args, internal_dict): def breakpoint_function_wrapper(frame, bp_loc, extra_args, internal_dict):
# Your code goes here # Your code goes here
.. code-tab:: lua
function breakpoint_function_wrapper(frame, bp_loc, ...)
-- Your code goes here
+-------------------+-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+ +-------------------+-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
| Argument | Type | Description | | Argument | Type | Description |
+-------------------+-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+ +-------------------+-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
| `frame` | `lldb.SBFrame` | The current stack frame where the breakpoint got hit. | | `frame` | `lldb.SBFrame` | The current stack frame where the breakpoint got hit. |
| | | The object will always be valid. | | | | 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`. | | | | 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` | | `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 | | | | objects. These breakpoint objects can have one or more locations. These locations |
| | | are represented by `lldb.SBBreakpointLocation` objects. | | | | 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 | | `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", | | | | 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 | | | | 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. | | | | 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. |
+-------------------+-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+ +-------------------+-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
| `internal_dict` | `dict` | The python session dictionary as a standard python dictionary object. | | `internal_dict` | `dict` | The Python session dictionary as a standard python dictionary object. |
+-------------------+-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+ +-------------------+-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
Optionally, a Python breakpoint command can return a value. Returning False 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 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 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 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 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 conditions are met, and you do not want to inspect the program state manually
Show All 16 Lines
location so we won't count this function again; then log some info and continue location so we won't count this function again; then log some info and continue
the process. the process.
Note we also have to initialize our counter, which we do with the simple Note we also have to initialize our counter, which we do with the simple
one-line version of the script command. one-line version of the script command.
Here is the code: Here is the code:
:: .. tabs::
.. code-tab:: python
(lldb) breakpoint set --func-regex=. --shlib=libfoo.dylib (lldb) breakpoint set --func-regex=. --shlib=libfoo.dylib
Breakpoint created: 1: regex = '.', module = libfoo.dylib, locations = 223 Breakpoint created: 1: regex = '.', module = libfoo.dylib, locations = 223
(lldb) script counter = 0 (lldb) script counter = 0
(lldb) breakpoint command add --script-type python 1 (lldb) breakpoint command add --script-type python 1
Enter your Python command(s). Type 'DONE' to end. Enter your Python command(s). Type 'DONE' to end.
> # Increment our counter. Since we are in a function, this must be a global python variable > # Increment our counter. Since we are in a function, this must be a global python variable
> global counter > global counter
> counter += 1 > counter += 1
> # Get the name of the function > # Get the name of the function
> name = frame.GetFunctionName() > name = frame.GetFunctionName()
> # Print the order and the function name > # Print the order and the function name
> print '[%i] %s' % (counter, name) > print '[%i] %s' % (counter, name)
> # Disable the current breakpoint location so it doesn't get hit again > # Disable the current breakpoint location so it doesn't get hit again
> bp_loc.SetEnabled(False) > bp_loc.SetEnabled(False)
> # No need to stop here > # No need to stop here
> return False > return False
> DONE > DONE
The breakpoint command add command above attaches a python script to breakpoint 1. To remove the breakpoint command: .. code-tab:: lua
(lldb) breakpoint set --func-regex=. --shlib=libfoo.dylib
Breakpoint created: 1: regex = '.', module = libfoo.dylib, locations = 223
(lldb) script -l lua -- counter = 0
(lldb) breakpoint command add -s lua 1
Enter your Lua command(s). Type 'quit' to end.
The commands are compiled as the body of the following Lua function
function (frame, bp_loc, ...) end
..> -- Increment our counter
..> counter = counter + 1
..> -- Get the name of the function
..> name = frame:GetFunctionName()
..> -- Print the order and the function name
..> print(string.format('[%i] %s', counter, name))
..> -- Disable the current breakpoint location so it doesn't get hit again
..> bp_loc:SetEnabled(false)
..> -- No need to stop here
..> return false
..> quit
The breakpoint command add command above attaches a python script to
breakpoint 1. To remove the breakpoint command:
:: ::
(lldb) breakpoint command delete 1 (lldb) breakpoint command delete 1
Using the python api's to create custom breakpoints Create custom breakpoints
--------------------------------------------------- -------------------------
Another use of the Python API's in lldb is to create a custom breakpoint Another use of the scripting API's in lldb is to create a custom breakpoint
resolver. This facility was added in r342259. resolver. This facility was added in r342259.
It allows you to provide the algorithm which will be used in the breakpoint's 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 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 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 understand how this works you need to know a little about how lldb handles
breakpoints. breakpoints.
▲ Show 20 Lines • Show All 133 Lines • ▼ Show 20 Lines
can pass in an arbitrary SBStructuredData object, so you can create more can pass in an arbitrary SBStructuredData object, so you can create more
complex parametrizations. SBStructuredData has a handy SetFromJSON method which complex parametrizations. SBStructuredData has a handy SetFromJSON method which
you can use for this purpose. Your __init__ function gets passed this you can use for this purpose. Your __init__ function gets passed this
SBStructuredData object. This API also allows you to directly provide the list 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 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 you pass in empty lists, the breakpoint will use the default "search
everywhere,accept everything" filter. everywhere,accept everything" filter.
Using the python API' to create custom stepping logic Create custom stepping logic
----------------------------------------------------- ----------------------------
A slightly esoteric use of the Python API's is to construct custom stepping 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 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 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 works as a thread plan, and responds to the requests the state machine makes to
run its operations. run its operations.
There is a longer discussion of scripted thread plans and the state machine, There is a longer discussion of scripted thread plans and the state machine,
▲ Show 20 Lines • Show All 45 Lines • ▼ Show 20 Lines
in/out/over and run-to-address) in front of itself on the stack, which can be 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 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 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 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 doesn't explain. For instance, step over plans don't explain a breakpoint hit
while performing the step-over. while performing the step-over.
Create a new lldb command using a Python function Create a new lldb command
------------------------------------------------- -------------------------
tammelaUnsubmitted
Not Done
ReplyInline Actions

So I'm guessing some sections are still missing some updates because the Lua functionality is not there yet right?

If so, I would add some note that this is not currently supported in Lua.

tammela: So I'm guessing some sections are still missing some updates because the Lua functionality is…
Python functions can be used to create new LLDB command interpreter commands, 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 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. very flexible and easy way to extend LLDB to meet your debugging requirements.
To write a python function that implements a new LLDB command define the To write a python function that implements a new LLDB command define the
function to take four arguments as follows: function to take four arguments as follows:
Show All 23 Lines::
def command_function(debugger, command, exe_ctx, result, internal_dict): def command_function(debugger, command, exe_ctx, result, internal_dict):
# Your code goes here # Your code goes here
+-------------------+--------------------------------+----------------------------------------------------------------------------------------------------------------------------------+ +-------------------+--------------------------------+----------------------------------------------------------------------------------------------------------------------------------+
| Argument | Type | Description | | Argument | Type | Description |
+-------------------+--------------------------------+----------------------------------------------------------------------------------------------------------------------------------+ +-------------------+--------------------------------+----------------------------------------------------------------------------------------------------------------------------------+
| `debugger` | `lldb.SBDebugger` | The current debugger object. | | `debugger` | `lldb.SBDebugger` | The current debugger object. |
+-------------------+--------------------------------+----------------------------------------------------------------------------------------------------------------------------------+ +-------------------+--------------------------------+----------------------------------------------------------------------------------------------------------------------------------+
| `command` | `python string` | A python string containing all arguments for your command. If you need to chop up the arguments | | `command` | `string` | A python string containing all arguments for your command. If you need to chop up the arguments |
| | | try using the `shlex` module's shlex.split(command) to properly extract the | | | | try using the `shlex` module's shlex.split(command) to properly extract the |
| | | arguments. | | | | arguments. |
+-------------------+--------------------------------+----------------------------------------------------------------------------------------------------------------------------------+ +-------------------+--------------------------------+----------------------------------------------------------------------------------------------------------------------------------+
| `exe_ctx` | `lldb.SBExecutionContext` | An execution context object carrying around information on the inferior process' context in which the command is expected to act | | `exe_ctx` | `lldb.SBExecutionContext` | An execution context object carrying around information on the inferior process' context in which the command is expected to act |
| | | | | | | |
| | | *Optional since lldb 3.5.2, unavailable before* | | | | *Optional since lldb 3.5.2, unavailable before* |
+-------------------+--------------------------------+----------------------------------------------------------------------------------------------------------------------------------+ +-------------------+--------------------------------+----------------------------------------------------------------------------------------------------------------------------------+
| `result` | `lldb.SBCommandReturnObject` | A return object which encapsulates success/failure information for the command and output text | | `result` | `lldb.SBCommandReturnObject` | A return object which encapsulates success/failure information for the command and output text |
▲ Show 20 Lines • Show All 344 Lines • Show Last 20 Lines