diff --git a/lldb/docs/.htaccess b/lldb/docs/.htaccess index f094bd6ebc783..34e7fcb8f5516 100644 --- a/lldb/docs/.htaccess +++ b/lldb/docs/.htaccess @@ -19,6 +19,7 @@ Redirect 301 /resources/architecture.html https://lldb.llvm.org/resources/overvi Redirect 301 /design/sbapi.html https://lldb.llvm.org/resources/sbapi.html Redirect 301 /design/overview.html https://lldb.llvm.org/resources/overview.html Redirect 301 /use/extensions.html https://lldb.llvm.org/resources/extensions.html +Redirect 301 /use/python.html https://lldb.llvm.org/use/tutorials/script-driven-debugging.html Redirect 301 /resources/bots.html https://lldb.llvm.org/resources/test.html # Redirect old Python API to new Python API. diff --git a/lldb/docs/use/python-reference.rst b/lldb/docs/use/python-reference.rst index 4292714c9c208..6ac2ec93fbd1f 100644 --- a/lldb/docs/use/python-reference.rst +++ b/lldb/docs/use/python-reference.rst @@ -10,1126 +10,21 @@ 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. -Documentation --------------- - -The LLDB API is contained in a python module named lldb. A useful resource when -writing Python extensions is the lldb Python classes reference guide. - -The documentation is also accessible in an interactive debugger session with -the following command: - -:: - - (lldb) script help(lldb) - 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 - ... - -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: - -:: - - (lldb) script help(lldb.SBFrame) - 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.''' - | - ... - -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 -currently selected process: - -:: - - (lldb) script help(lldb.process) - 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 - | # ================================================== - | - ... - -Embedded Python Interpreter ---------------------------- - -The embedded python interpreter can be accessed in a variety of ways from -within LLDB. The easiest way is to use the lldb command script with no -arguments at the lldb command prompt: - -:: - - (lldb) script - Python Interactive Interpreter. To exit, type 'quit()', 'exit()' or Ctrl-D. - >>> 2+3 - 5 - >>> hex(12345) - '0x3039' - >>> - -This drops you into the embedded python 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 -state. In each case, if there is no currently selected entity of the -appropriate type, the variable's IsValid method will return false. These -variables are: - -+-------------------+---------------------+-------------------------------------+-------------------------------------------------------------------------------------+ -| Variable | Type | Equivalent | Description | -+-------------------+---------------------+-------------------------------------+-------------------------------------------------------------------------------------+ -| ``lldb.debugger`` | `lldb.SBDebugger` | `SBTarget.GetDebugger` | Contains the debugger object whose ``script`` command was invoked. | -| | | | The `lldb.SBDebugger` object owns the command interpreter | -| | | | and all the targets in your debug session. There will always be a | -| | | | Debugger in the embedded interpreter. | -+-------------------+---------------------+-------------------------------------+-------------------------------------------------------------------------------------+ -| ``lldb.target`` | `lldb.SBTarget` | `SBDebugger.GetSelectedTarget` | Contains the currently selected target - for instance the one made with the | -| | | | ``file`` or selected by the ``target select `` command. | -| | | `SBProcess.GetTarget` | The `lldb.SBTarget` manages one running process, and all the executable | -| | | | and debug files for the process. | -+-------------------+---------------------+-------------------------------------+-------------------------------------------------------------------------------------+ -| ``lldb.process`` | `lldb.SBProcess` | `SBTarget.GetProcess` | Contains the process of the currently selected target. | -| | | | The `lldb.SBProcess` object manages the threads and allows access to | -| | | `SBThread.GetProcess` | memory for the process. | -+-------------------+---------------------+-------------------------------------+-------------------------------------------------------------------------------------+ -| ``lldb.thread`` | `lldb.SBThread` | `SBProcess.GetSelectedThread` | Contains the currently selected thread. | -| | | | The `lldb.SBThread` object manages the stack frames in that thread. | -| | | `SBFrame.GetThread` | A thread is always selected in the command interpreter when a target stops. | -| | | | The ``thread select `` 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. | -+-------------------+---------------------+-------------------------------------+-------------------------------------------------------------------------------------+ -| ``lldb.frame`` | `lldb.SBFrame` | `SBThread.GetSelectedFrame` | Contains the currently selected stack frame. | -| | | | The `lldb.SBFrame` 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 ``frame select `` 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. | -+-------------------+---------------------+-------------------------------------+-------------------------------------------------------------------------------------+ - -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. - -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). For the -latter you'll be passed an `SBDebugger`, `SBTarget`, `SBProcess`, `SBThread` or -`SBFrame` instance and you can use the functions from the "Equivalent" column -to navigate between them. - -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. - -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 -pass them to the Python print function: - -:: - - (lldb) script - Python Interactive Interpreter. To exit, type 'quit()', 'exit()' or Ctrl-D. - >>> print(lldb.debugger) - Debugger (instance: "debugger_1", id: 1) - >>> print(lldb.target) - a.out - >>> print(lldb.process) - SBProcess: pid = 58842, state = stopped, threads = 1, executable = a.out - >>> print(lldb.thread) - thread #1: tid = 0x2265ce3, 0x0000000100000334 a.out`main at t.c:2:3, queue = 'com.apple.main-thread', stop reason = breakpoint 1.1 - >>> print(lldb.frame) - frame #0: 0x0000000100000334 a.out`main at t.c:2:3 - - -Running a python script when a breakpoint gets hit --------------------------------------------------- - -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. - -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: - -:: - - def breakpoint_function_wrapper(frame, bp_loc, internal_dict): - # Your code goes here - -or: - -:: - - def breakpoint_function_wrapper(frame, bp_loc, extra_args, internal_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. | -+-------------------+-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+ -| ``internal_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 -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. - -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. - -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 lldb.SBBreakpoint object that contains an -lldb.SBBreakpointLocation 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. - -Note we also have to initialize our counter, which we do with the simple -one-line version of the script command. - -Here is the code: - -:: - - (lldb) breakpoint set --func-regex=. --shlib=libfoo.dylib - Breakpoint created: 1: regex = '.', module = libfoo.dylib, locations = 223 - (lldb) script counter = 0 - (lldb) breakpoint command add --script-type python 1 - 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 - > global counter - > counter += 1 - > # Get the name of the function - > name = frame.GetFunctionName() - > # Print the order and the function name - > print('[%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 - > DONE - -The breakpoint command add command above attaches a python script to breakpoint 1. To remove the breakpoint command: - -:: - - (lldb) breakpoint command delete 1 - - -Using the python api's to create custom breakpoints ---------------------------------------------------- - - -Another use of the Python API's in lldb is to create a custom breakpoint -resolver. This facility was added in r342259. - -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. - -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. - -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. - -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 -s modulename flag to break set you are creating a Module-based search -filter. When you pass -f filename.c to break set -n 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. - -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. - -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. - -One other slight subtlety is that the depth at which you get called back is not -necessarily the depth at which 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 SBBreakpoint::AddLocation will only add locations that pass the -Search Filter. This API returns an SBError to inform you whether your location -was added. - -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. - -At present, when adding a scripted Breakpoint type, you can only provide a -custom Resolver, not a custom SearchFilter. - -The custom Resolver is provided as a Python class with the following methods: - -+--------------------+---------------------------------------+------------------------------------------------------------------------------------------------------------------+ -| Name | Arguments | Description | -+--------------------+---------------------------------------+------------------------------------------------------------------------------------------------------------------+ -| ``__init__`` | ``bkpt``:`lldb.SBBreakpoint` | This is the constructor for the new Resolver. | -| | ``extra_args``:`lldb.SBStructuredData`| | -| | | | -| | | ``bkpt`` is the breakpoint owning this Resolver. | -| | | | -| | | | -| | | ``extra_args`` 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 | -+--------------------+---------------------------------------+------------------------------------------------------------------------------------------------------------------+ -| ``__callback__`` | ``sym_ctx``:`lldb.SBSymbolContext` | This is the Resolver callback. | -| | | The ``sym_ctx`` argument will be filled with the current stage | -| | | of the search. | -| | | | -| | | | -| | | 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 ``sym_ctx`` for new locations. If the callback finds an address of interest, it | -| | | can add it to the breakpoint with the `SBBreakpoint.AddLocation` method, using the breakpoint passed | -| | | in to the ``__init__`` method. | -+--------------------+---------------------------------------+------------------------------------------------------------------------------------------------------------------+ -| ``__get_depth__`` | ``None`` | Specify the depth at which you wish your callback to get called. The currently supported options are: | -| | | | -| | | `lldb.eSearchDepthModule` | -| | | `lldb.eSearchDepthCompUnit` | -| | | `lldb.eSearchDepthFunction` | -| | | | -| | | 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 `lldb.eSearchDepthModule`. This method is optional. If not provided the search | -| | | will be done at Module depth. | -+--------------------+---------------------------------------+------------------------------------------------------------------------------------------------------------------+ -| ``get_short_help`` | ``None`` | This is an optional method. If provided, the returned string will be printed at the beginning of | -| | | the description for this breakpoint. | -+--------------------+---------------------------------------+------------------------------------------------------------------------------------------------------------------+ - -To define a new breakpoint command defined by this class from the lldb command -line, use the command: - -:: - - (lldb) breakpoint set -P MyModule.MyResolverClass - -You can also populate the extra_args SBStructuredData with a dictionary of -key/value pairs with: - -:: - - (lldb) breakpoint set -P MyModule.MyResolverClass -k key_1 -v value_1 -k key_2 -v value_2 - -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 -s ModuleName option - which can be specified multiple times. You -can also specify a SearchFilter restricted to certain compile units by passing -in the -f CompUnitName 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, - -:: - - (lldb) breakpoint set -P MyModule.MyResolverClass -s a.out - -will use your resolver, but will only recurse into or accept new locations in -the module a.out. - -Another option for creating scripted breakpoints is to use the -SBTarget.BreakpointCreateFromScript 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. - -Using the python API' to create custom stepping logic ------------------------------------------------------ - -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. - -There is a longer discussion of scripted thread plans and the state machine, -and several interesting examples of their use in: - -https://github.com/llvm/llvm-project/blob/main/lldb/examples/python/scripted_step.py - -And for a MUCH fuller discussion of the whole state machine, see: - -https://github.com/llvm/llvm-project/blob/main/lldb/include/lldb/Target/ThreadPlan.h - -If you are reading those comments it is useful to know that scripted thread -plans are set to be "ControllingPlans", and not "OkayToDiscard". - -To implement a scripted step, you define a python class that has the following -methods: - -+-------------------+------------------------------------+---------------------------------------------------------------------------------------+ -| Name | Arguments | Description | -+-------------------+------------------------------------+---------------------------------------------------------------------------------------+ -| ``__init__`` | ``thread_plan``:`lldb.SBThreadPlan`| 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. | -+-------------------+------------------------------------+---------------------------------------------------------------------------------------+ -| ``explains_stop`` | ``event``: `lldb.SBEvent` | Return True if this stop is part of your thread plans logic, false otherwise. | -+-------------------+------------------------------------+---------------------------------------------------------------------------------------+ -| ``is_stale`` | ``None`` | 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. | -+-------------------+------------------------------------+---------------------------------------------------------------------------------------+ -| ``should_step`` | ``None`` | Return ``True`` if you want lldb to instruction step one instruction, | -| | | or False to continue till the next breakpoint is hit. | -+-------------------+------------------------------------+---------------------------------------------------------------------------------------+ -| ``should_stop`` | ``event``: `lldb.SBEvent` | 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. | -+-------------------+------------------------------------+---------------------------------------------------------------------------------------+ - -To use this class to implement a step, use the command: - -:: - - (lldb) thread step-scripted -C MyModule.MyStepPlanClass - -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. - - -Create a new lldb command using a Python function -------------------------------------------------- - -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. - -To write a python function that implements a new LLDB command define the -function to take five arguments as follows: - -:: - - def command_function(debugger, command, exe_ctx, result, internal_dict): - # Your code goes here - -The meaning of the arguments is given in the table below. - -If you provide a Python docstring in your command function LLDB will use it -when providing "long help" for your command, as in: - -:: - - def command_function(debugger, command, result, internal_dict): - """This command takes a lot of options and does many fancy things""" - # Your code goes here - -though providing help can also be done programmatically (see below). - -Prior to lldb 3.5.2 (April 2015), LLDB Python command definitions didn't take the SBExecutionContext -argument. So you may still see commands where the command definition is: - -:: - - def command_function(debugger, command, result, internal_dict): - # Your code goes here - -Using this form is strongly discouraged because it can only operate on the "currently selected" -target, process, thread, frame. The command will behave as expected when run -directly on the command line. But if the command is used in a stop-hook, breakpoint -callback, etc. where the response to the callback determines whether we will select -this or that particular process/frame/thread, the global "currently selected" -entity is not necessarily the one the callback is meant to handle. In that case, this -command definition form can't do the right thing. - -+-------------------+--------------------------------+----------------------------------------------------------------------------------------------------------------------------------+ -| Argument | Type | Description | -+-------------------+--------------------------------+----------------------------------------------------------------------------------------------------------------------------------+ -| ``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 | -| | | try using the ``shlex`` module's ``shlex.split(command)`` to properly extract the | -| | | 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 | -| | | | -| | | *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 | -| | | 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). | -+-------------------+--------------------------------+----------------------------------------------------------------------------------------------------------------------------------+ -| ``internal_dict`` | ``python dict object`` | The dictionary for the current embedded script session which contains all variables | -| | | and functions. | -+-------------------+--------------------------------+----------------------------------------------------------------------------------------------------------------------------------+ - -Since lldb 3.7, Python commands can also be implemented by means of a class -which should implement the following interface: - -.. code-block:: python - - class CommandObjectType: - def __init__(self, debugger, internal_dict): - this call should initialize the command with respect to the command interpreter for the passed-in debugger - def __call__(self, debugger, command, exe_ctx, result): - this is the actual bulk of the command, akin to Python command functions - def get_short_help(self): - this call should return the short help text for this command[1] - def get_long_help(self): - this call should return the long help text for this command[1] - def get_flags(self): - this will be called when the command is added to the command interpreter, - and should return a flag field made from or-ing together the appropriate - elements of the lldb.CommandFlags enum to specify the requirements of this command. - The CommandInterpreter will make sure all these requirements are met, and will - return the standard lldb error if they are not.[1] - def get_repeat_command(self, command): - The auto-repeat command is what will get executed when the user types just - a return at the next prompt after this command is run. Even if your command - was run because it was specified as a repeat command, that invocation will still - get asked for IT'S repeat command, so you can chain a series of repeats, for instance - to implement a pager. - - The command argument is the command that is about to be executed. - - If this call returns None, then the ordinary repeat mechanism will be used - If this call returns an empty string, then auto-repeat is disabled - If this call returns any other string, that will be the repeat command [1] - -[1] This method is optional. - -As a convenience, you can treat the result object as a Python file object, and -say - -.. code-block:: python - - print("my command does lots of cool stuff", file=result) - -SBCommandReturnObject and SBStream both support this file-like behavior by -providing write() and flush() calls at the Python layer. - -The commands that are added using this class definition are what lldb calls -"raw" commands. The command interpreter doesn't attempt to parse the command, -doesn't handle option values, neither generating help for them, or their -completion. Raw commands are useful when the arguments passed to the command -are unstructured, and having to protect them against lldb command parsing would -be onerous. For instance, "expr" is a raw command. - -You can also add scripted commands that implement the "parsed command", where -the options and their types are specified, as well as the argument and argument -types. These commands look and act like the majority of lldb commands, and you -can also add custom completions for the options and/or the arguments if you have -special needs. - -The easiest way to do this is to derive your new command from the lldb.ParsedCommand -class. That responds in the same way to the help & repeat command interfaces, and -provides some convenience methods, and most importantly an LLDBOptionValueParser, -accessed through lldb.ParsedCommand.get_parser(). The parser is used to set -your command definitions, and to retrieve option values in the __call__ method. - -To set up the command definition, implement the ParsedCommand abstract method: - -.. code-block:: python - - def setup_command_definition(self): - -This is called when your command is added to lldb. In this method you add the -options and their types, the option help strings, etc. to the command using the API: - -.. code-block:: python - - def add_option(self, short_option, long_option, help, default, - dest = None, required=False, groups = None, - value_type=lldb.eArgTypeNone, completion_type=None, - enum_values=None): - """ - short_option: one character, must be unique, not required - long_option: no spaces, must be unique, required - help: a usage string for this option, will print in the command help - default: the initial value for this option (if it has a value) - dest: the name of the property that gives you access to the value for - this value. Defaults to the long option if not provided. - required: if true, this option must be provided or the command will error out - groups: Which "option groups" does this option belong to. This can either be - a simple list (e.g. [1, 3, 4, 5]) or you can specify ranges by sublists: - so [1, [3,5]] is the same as [1, 3, 4, 5]. - value_type: one of the lldb.eArgType enum values. Some of the common arg - types also have default completers, which will be applied automatically. - completion_type: currently these are values form the lldb.CompletionType enum. If - you need custom completions, implement handle_option_argument_completion. - enum_values: An array of duples: ["element_name", "element_help"]. If provided, - only one of the enum elements is allowed. The value will be the - element_name for the chosen enum element as a string. - """ - -Similarly, you can add argument types to the command: - -.. code-block:: python - - def make_argument_element(self, arg_type, repeat = "optional", groups = None): - """ - arg_type: The argument type, one of the lldb.eArgType enum values. - repeat: Choose from the following options: - "plain" - one value - "optional" - zero or more values - "plus" - one or more values - groups: As with add_option. - """ - -Then implement the body of the command by defining: - -.. code-block:: python - - def __call__(self, debugger, args_array, exe_ctx, result): - """This is the command callback. The option values are - provided by the 'dest' properties on the parser. - - args_array: This is the list of arguments provided. - exe_ctx: Gives the SBExecutionContext on which the - command should operate. - result: Any results of the command should be - written into this SBCommandReturnObject. - """ - -This differs from the "raw" command's __call__ in that the arguments are already -parsed into the args_array, and the option values are set in the parser, and -can be accessed using their property name. The LLDBOptionValueParser class has -a couple of other handy methods: - -.. code-block:: python - def was_set(self, long_option_name): - -returns True if the option was specified on the command line. - -.. code-block:: python - - def dest_for_option(self, long_option_name): - """ - This will return the value of the dest variable you defined for opt_name. - Mostly useful for handle_completion where you get passed the long option. - """ - -lldb will handle completing your option names, and all your enum values -automatically. If your option or argument types have associated built-in completers, -then lldb will also handle that completion for you. But if you have a need for -custom completions, either in your arguments or option values, you can handle -completion by hand as well. To handle completion of option value arguments, -your lldb.ParsedCommand subclass should implement: - -.. code-block:: python - - def handle_option_argument_completion(self, long_option, cursor_pos): - """ - long_option: The long option name of the option whose value you are - asked to complete. - cursor_pos: The cursor position in the value for that option - which - you can get from the option parser. - """ - -And to handle the completion of arguments: - -.. code-block:: python - - def handle_argument_completion(self, args, arg_pos, cursor_pos): - """ - args: A list of the arguments to the command - arg_pos: An index into the args list of the argument with the cursor - cursor_pos: The cursor position in the arg specified by arg_pos - """ - -When either of these API's is called, the command line will have been parsed up to -the word containing the cursor, and any option values set in that part of the command -string are available from the option value parser. That's useful for instance -if you have a --shared-library option that would constrain the completions for, -say, a symbol name option or argument. - -The return value specifies what the completion options are. You have four -choices: - -- `True`: the completion was handled with no completions. - -- `False`: the completion was not handled, forward it to the regular -completion machinery. - -- A dictionary with the key: "completion": there is one candidate, -whose value is the value of the "completion" key. Optionally you can pass a -"mode" key whose value is either "partial" or "complete". Return partial if -the "completion" string is a prefix for all the completed value. - -For instance, if the string you are completing is "Test" and the available completions are: -"Test1", "Test11" and "Test111", you should return the dictionary: - -.. code-block:: python - - return {"completion": "Test1", "mode" : "partial"} - -and then lldb will add the "1" at the cursor and advance it after the added string, -waiting for more completions. But if "Test1" is the only completion, return: - -.. code-block:: python - - {"completion": "Test1", "mode": "complete"} - -and lldb will add "1 " at the cursor, indicating the command string is complete. - -The default is "complete", you don't need to specify a "mode" in that case. - -- A dictionary with the key: "values" whose value is a list of candidate completion -strings. The command interpreter will present those strings as the available choices. -You can optionally include a "descriptions" key, whose value is a parallel array -of description strings, and the completion will show the description next to -each completion. - - -One other handy convenience when defining lldb command-line commands is the -command "command script import" 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: - -.. code-block python - - def __lldb_init_module(debugger, internal_dict): - # Command Initialization code goes here - -where debugger and internal_dict 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 ``command script import``, it will not get run if anyone imports your -module from another module. - -The standard test for ``__main__``, like many python modules do, is useful for -creating scripts that can be run from the command line. However, for command -line scripts, the debugger instance must be created manually. Sample code would -look like: - -.. code-block:: python - - if __name__ == '__main__': - # Initialize the debugger before making any API calls. - lldb.SBDebugger.Initialize() - # 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 - debugger = lldb.SBDebugger.Create() - - # Next, do whatever work this module should do when run as a command. - # ... - - # Finally, dispose of the debugger you just made. - lldb.SBDebugger.Destroy(debugger) - # Terminate the debug session - lldb.SBDebugger.Terminate() - - -Now we can create a module called ls.py in the file ~/ls.py that will implement -a function that can be used by LLDB's python command code: - -.. code-block:: python - - #!/usr/bin/env python - - import lldb - import commands - import optparse - import shlex - - def ls(debugger, command, result, internal_dict): - print >>result, (commands.getoutput('/bin/ls %s' % command)) - - # And the initialization code to add your commands - 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.') - -Now we can load the module into LLDB and use it - -:: - - $ lldb - (lldb) command script import ~/ls.py - The "ls" python command has been installed and is ready for use. - (lldb) ls -l /tmp/ - 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 - -You can also make "container" commands to organize the commands you are adding to -lldb. Most of the lldb built-in commands structure themselves this way, and using -a tree structure has the benefit of leaving the one-word command space free for user -aliases. It can also make it easier to find commands if you are adding more than -a few of them. Here's a trivial example of adding two "utility" commands into a -"my-utilities" container: - -:: - - #!/usr/bin/env python - - import lldb - - def first_utility(debugger, command, result, internal_dict): - print("I am the first utility") - - def second_utility(debugger, command, result, internal_dict): - print("I am the second utility") - - # And the initialization code to add your commands - def __lldb_init_module(debugger, internal_dict): - debugger.HandleCommand('command container add -h "A container for my utilities" my-utilities') - debugger.HandleCommand('command script add -f my_utilities.first_utility -h "My first utility" my-utilities first') - debugger.HandleCommand('command script add -f my_utilities.second_utility -h "My second utility" my-utilities second') - print('The "my-utilities" python command has been installed and its subcommands are ready for use.') - -Then your new commands are available under the my-utilities node: - -:: - - (lldb) help my-utilities - A container for my utilities - - Syntax: my-utilities - - The following subcommands are supported: - - first -- My first utility Expects 'raw' input (see 'help raw-input'.) - second -- My second utility Expects 'raw' input (see 'help raw-input'.) - - For more help on any particular subcommand, type 'help '. - (lldb) my-utilities first - I am the first utility - - -A more interesting template has been created in the source repository that can -help you to create lldb command quickly: - -https://github.com/llvm/llvm-project/blob/main/lldb/examples/python/cmdtemplate.py - -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: - -:: - - #import - NSString* - ModifyString(NSString* src) - { - return [src stringByAppendingString:@"foobar"]; - } - - int main() - { - NSString* aString = @"Hello world"; - NSString* anotherString = @"Let's be friends"; - return 1; - } - -you may want a pofoo X command, that equates po [ModifyString(X) -capitalizedString]. The following debugger interaction shows how to achieve -that goal: - -:: - - (lldb) script - Python Interactive Interpreter. To exit, type 'quit()', 'exit()' or Ctrl-D. - >>> def pofoo_funct(debugger, command, result, internal_dict): - ... cmd = "po [ModifyString(" + command + ") capitalizedString]" - ... debugger.HandleCommand(cmd) - ... - >>> ^D - (lldb) command script add pofoo -f pofoo_funct - (lldb) pofoo aString - $1 = 0x000000010010aa00 Hello Worldfoobar - (lldb) pofoo anotherString - $2 = 0x000000010010aba0 Let's Be Friendsfoobar - -Using the lldb.py module in Python ----------------------------------- - -LLDB has all of its core code built into a shared library which gets used by -the `lldb` command line application. On macOS this shared library is a -framework: LLDB.framework and on other unix variants the program is a shared -library: lldb.so. LLDB also provides an lldb.py module that contains the -bindings from LLDB into Python. To use the LLDB.framework 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 PYTHONPATH environment -variable, adding a path to the directory that contains the lldb.py 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: - -For csh and tcsh: - -:: - - % setenv PYTHONPATH `lldb -P` - -For sh and bash: - -:: - - $ export PYTHONPATH=`lldb -P` - -Alternatively, you can append the LLDB Python directory to the sys.path list -directly in your Python code before importing the lldb module. - -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: - -.. code-block:: python - - #!/usr/bin/env python3 - - import lldb - import os - - - def disassemble_instructions(insts): - for i in insts: - print(i) - - - # Set the path to the executable to debug - exe = "./a.out" - - # Create a new debugger instance - debugger = lldb.SBDebugger.Create() - - # 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. - debugger.SetAsync(False) - - # Create a target from a file and arch - print("Creating a target for '%s'" % exe) - - target = debugger.CreateTargetWithFileAndArch(exe, lldb.LLDB_ARCH_DEFAULT) - - if target: - # If the target is valid set a breakpoint at main - main_bp = target.BreakpointCreateByName( - "main", target.GetExecutable().GetFilename() - ) - - print(main_bp) - - # Launch the process. Since we specified synchronous mode, we won't return - # from this function until we hit the breakpoint at main - process = target.LaunchSimple(None, None, os.getcwd()) - - # Make sure the launch went ok - if process: - # Print some simple process info - state = process.GetState() - print(process) - if state == lldb.eStateStopped: - # Get the first thread - thread = process.GetThreadAtIndex(0) - if thread: - # Print some simple thread info - print(thread) - # Get the first frame - frame = thread.GetFrameAtIndex(0) - if frame: - # Print some simple frame info - print(frame) - function = frame.GetFunction() - # See if we have debug info (a function) - if function: - # We do have a function, print some info for the function - print(function) - # Now get all instructions for this function and print them - insts = function.GetInstructions(target) - disassemble_instructions(insts) - else: - # See if we have a symbol in the symbol table for where we stopped - symbol = frame.GetSymbol() - if symbol: - # We do have a symbol, print some info for the symbol - print(symbol) - -Writing lldb frame recognizers in Python ----------------------------------------- - -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 inaccessible, or augment existing arguments. - -Adding a custom frame recognizer is done by implementing a Python class and -using the 'frame recognizer add' command. The Python class should have a -'get_recognized_arguments' method and it will receive an argument of type -lldb.SBFrame representing the current frame that we are trying to recognize. -The method should return a (possibly empty) list of lldb.SBValue objects that -represent the recognized arguments. - -An example of a recognizer that retrieves the file descriptor values from libc -functions 'read', 'write' and 'close' follows: - -:: - - class LibcFdRecognizer(object): - def get_recognized_arguments(self, frame): - if frame.name in ["read", "write", "close"]: - fd = frame.EvaluateExpression("$arg1").unsigned - target = frame.thread.process.target - value = target.CreateValueFromExpression("fd", "(int)%d" % fd) - return [value] - return [] - -The file containing this implementation can be imported via ``command script import`` -and then we can register this recognizer with ``frame recognizer add``. -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: - -:: - - (lldb) command script import .../fd_recognizer.py - (lldb) frame recognizer add -l fd_recognizer.LibcFdRecognizer -n read -s libsystem_kernel.dylib - -When the program is stopped at the beginning of the 'read' function in libc, we can view the recognizer arguments in 'frame variable': - -:: - - (lldb) b read - (lldb) r - Process 1234 stopped - * thread #1, queue = 'com.apple.main-thread', stop reason = breakpoint 1.3 - frame #0: 0x00007fff06013ca0 libsystem_kernel.dylib`read - (lldb) frame variable - (int) fd = 3 - -Writing Target Stop-Hooks in Python ------------------------------------ - -Stop hooks fire whenever the process stops just before control is returned to the -user. Stop hooks can either be a set of lldb command-line commands, or can -be implemented by a suitably defined Python class. The Python-based stop-hooks -can also be passed as a set of -key -value pairs when they are added, and those -will get packaged up into a SBStructuredData Dictionary and passed to the -constructor of the Python object managing the stop hook. This allows for -parameterization of the stop hooks. - -To add a Python-based stop hook, first define a class with the following methods: - -+--------------------+---------------------------------------+------------------------------------------------------------------------------------------------------------------+ -| Name | Arguments | Description | -+--------------------+---------------------------------------+------------------------------------------------------------------------------------------------------------------+ -| ``__init__`` | ``target: lldb.SBTarget`` | This is the constructor for the new stop-hook. | -| | ``extra_args: lldb.SBStructuredData`` | | -| | | | -| | | ``target`` is the SBTarget to which the stop hook is added. | -| | | | -| | | ``extra_args`` is an SBStructuredData object that the user can pass in when creating instances of this | -| | | breakpoint. It is not required, but allows for reuse of stop-hook classes. | -+--------------------+---------------------------------------+------------------------------------------------------------------------------------------------------------------+ -| ``handle_stop`` | ``exe_ctx: lldb.SBExecutionContext`` | This is the called when the target stops. | -| | ``stream: lldb.SBStream`` | | -| | | ``exe_ctx`` argument will be filled with the current stop point for which the stop hook is | -| | | being evaluated. | -| | | | -| | | ``stream`` an lldb.SBStream, anything written to this stream will be written to the debugger console. | -| | | | -| | | The return value is a "Should Stop" vote from this thread. If the method returns either True or no return | -| | | this thread votes to stop. If it returns False, then the thread votes to continue after all the stop-hooks | -| | | are evaluated. | -| | | Note, the --auto-continue flag to 'target stop-hook add' overrides a True return value from the method. | -+--------------------+---------------------------------------+------------------------------------------------------------------------------------------------------------------+ - -To use this class in lldb, run the command: - -:: - - (lldb) command script import MyModule.py - (lldb) target stop-hook add -P MyModule.MyStopHook -k first -v 1 -k second -v 2 - -where MyModule.py is the file containing the class definition MyStopHook. +Python Tutorials +----------------- + +The following tutorials and documentation demonstrate various Python capabilities within LLDB: + +.. toctree:: + :maxdepth: 1 + + tutorials/accessing-documentation + tutorials/python-embedded-interpreter + tutorials/script-driven-debugging + tutorials/breakpoint-triggered-scripts + tutorials/creating-custom-breakpoints + tutorials/automating-stepping-logic + tutorials/writing-custom-commands + tutorials/implementing-standalone-scripts + tutorials/custom-frame-recognizers + tutorials/extending-target-stop-hooks \ No newline at end of file diff --git a/lldb/docs/use/python.rst b/lldb/docs/use/python.rst deleted file mode 100644 index 3a919f2a8cdb1..0000000000000 --- a/lldb/docs/use/python.rst +++ /dev/null @@ -1,799 +0,0 @@ -Python Scripting -================ - -LLDB has been structured from the beginning to be scriptable in two -ways -- a Unix Python session can initiate/run a debug session -non-interactively using LLDB; and within the LLDB debugger tool, Python -scripts can be used to help with many tasks, including inspecting -program data, iterating over containers and determining if a breakpoint -should stop execution or continue. This document will show how to do -some of these things by going through an example, explaining how to use -Python scripting to find a bug in a program that searches for text in a -large binary tree. - -The Test Program and Input --------------------------- - -We have a simple C program (dictionary.c) that reads in a text file, -and stores all the words from the file in a Binary Search Tree, sorted -alphabetically. It then enters a loop prompting the user for a word, -searching for the word in the tree (using Binary Search), and reporting -to the user whether or not it found the word in the tree. - -The input text file we are using to test our program contains the text -for William Shakespeare's famous tragedy "Romeo and Juliet". - -The Bug -------- - -When we try running our program, we find there is a problem. While it -successfully finds some of the words we would expect to find, such as -"love" or "sun", it fails to find the word "Romeo", which MUST be in -the input text file: - -:: - - $ ./dictionary Romeo-and-Juliet.txt - Dictionary loaded. - Enter search word: love - Yes! - Enter search word: sun - Yes! - Enter search word: Romeo - No! - Enter search word: ^D - $ - -Using Depth First Search ------------------------- - -Our first job is to determine if the word "Romeo" actually got inserted -into the tree or not. Since "Romeo and Juliet" has thousands of words, -trying to examine our binary search tree by hand is completely -impractical. Therefore we will write a Python script to search the tree -for us. We will write a recursive Depth First Search function that -traverses the entire tree searching for a word, and maintaining -information about the path from the root of the tree to the current -node. If it finds the word in the tree, it returns the path from the -root to the node containing the word. This is what our DFS function in -Python would look like, with line numbers added for easy reference in -later explanations: - -:: - - 1: def DFS (root, word, cur_path): - 2: root_word_ptr = root.GetChildMemberWithName ("word") - 3: left_child_ptr = root.GetChildMemberWithName ("left") - 4: right_child_ptr = root.GetChildMemberWithName ("right") - 5: root_word = root_word_ptr.GetSummary() - 6: end = len (root_word) - 1 - 7: if root_word[0] == '"' and root_word[end] == '"': - 8: root_word = root_word[1:end] - 9: end = len (root_word) - 1 - 10: if root_word[0] == '\'' and root_word[end] == '\'': - 11: root_word = root_word[1:end] - 12: if root_word == word: - 13: return cur_path - 14: elif word < root_word: - 15: if left_child_ptr.GetValue() is None: - 16: return "" - 17: else: - 18: cur_path = cur_path + "L" - 19: return DFS (left_child_ptr, word, cur_path) - 20: else: - 21: if right_child_ptr.GetValue() is None: - 22: return "" - 23: else: - 24: cur_path = cur_path + "R" - 25: return DFS (right_child_ptr, word, cur_path) - - -Accessing & Manipulating Program Variables ------------------------------------------- - -Before we can call any Python function on any of our program's -variables, we need to get the variable into a form that Python can -access. To show you how to do this we will look at the parameters for -the DFS function. The first parameter is going to be a node in our -binary search tree, put into a Python variable. The second parameter is -the word we are searching for (a string), and the third parameter is a -string representing the path from the root of the tree to our current -node. - -The most interesting parameter is the first one, the Python variable -that needs to contain a node in our search tree. How can we take a -variable out of our program and put it into a Python variable? What -kind of Python variable will it be? The answers are to use the LLDB API -functions, provided as part of the LLDB Python module. Running Python -from inside LLDB, LLDB will automatically give us our current frame -object as a Python variable, "lldb.frame". This variable has the type -`SBFrame` (see the LLDB API for more information about `SBFrame` -objects). One of the things we can do with a frame object, is to ask it -to find and return its local variable. We will call the API function -`SBFrame.FindVariable` on the lldb.frame object to give us our dictionary -variable as a Python variable: - -:: - - root = lldb.frame.FindVariable ("dictionary") - -The line above, executed in the Python script interpreter in LLDB, asks the -current frame to find the variable named "dictionary" and return it. We then -store the returned value in the Python variable named "root". This answers the -question of HOW to get the variable, but it still doesn't explain WHAT actually -gets put into "root". If you examine the LLDB API, you will find that the -`SBFrame` method "FindVariable" returns an object of type `SBValue`. `SBValue` -objects are used, among other things, to wrap up program variables and values. -There are many useful methods defined in the `SBValue` class to allow you to get -information or children values out of SBValues. For complete information, see -the header file SBValue.h. The `SBValue` methods that we use in our DFS function -are ``GetChildMemberWithName()``, ``GetSummary()``, and ``GetValue()``. - - -Explaining DFS Script in Detail -------------------------------- - -Before diving into the details of this code, it would be best to give a -high-level overview of what it does. The nodes in our binary search tree were -defined to have type ``tree_node *``, which is defined as: - -:: - - typedef struct tree_node - { - const char *word; - struct tree_node *left; - struct tree_node *right; - } tree_node; - -Lines 2-11 of DFS are getting data out of the current tree node and getting -ready to do the actual search; lines 12-25 are the actual depth-first search. -Lines 2-4 of our DFS function get the word, left and right fields out of the -current node and store them in Python variables. Since root_word_ptr is a -pointer to our word, and we want the actual word, line 5 calls GetSummary() to -get a string containing the value out of the pointer. Since GetSummary() adds -quotes around its result, lines 6-11 strip surrounding quotes off the word. - -Line 12 checks to see if the word in the current node is the one we are -searching for. If so, we are done, and line 13 returns the current path. -Otherwise, line 14 checks to see if we should go left (search word comes before -the current word). If we decide to go left, line 15 checks to see if the left -pointer child is NULL ("None" is the Python equivalent of NULL). If the left -pointer is NULL, then the word is not in this tree and we return an empty path -(line 16). Otherwise, we add an "L" to the end of our current path string, to -indicate we are going left (line 18), and then recurse on the left child (line -19). Lines 20-25 are the same as lines 14-19, except for going right rather -than going left. - -One other note: Typing something as long as our DFS function directly into the -interpreter can be difficult, as making a single typing mistake means having to -start all over. Therefore we recommend doing as we have done: Writing your -longer, more complicated script functions in a separate file (in this case -tree_utils.py) and then importing it into your LLDB Python interpreter. - - -The DFS Script in Action ------------------------- - -At this point we are ready to use the DFS function to see if the word "Romeo" -is in our tree or not. To actually use it in LLDB on our dictionary program, -you would do something like this: - -:: - - $ lldb - (lldb) process attach -n "dictionary" - Architecture set to: x86_64. - Process 521 stopped - * thread #1: tid = 0x2c03, 0x00007fff86c8bea0 libSystem.B.dylib`read$NOCANCEL + 8, stop reason = signal SIGSTOP - frame #0: 0x00007fff86c8bea0 libSystem.B.dylib`read$NOCANCEL + 8 - (lldb) breakpoint set -n find_word - Breakpoint created: 1: name = 'find_word', locations = 1, resolved = 1 - (lldb) continue - Process 521 resuming - Process 521 stopped - * thread #1: tid = 0x2c03, 0x0000000100001830 dictionary`find_word + 16 - at dictionary.c:105, stop reason = breakpoint 1.1 - frame #0: 0x0000000100001830 dictionary`find_word + 16 at dictionary.c:105 - 102 int - 103 find_word (tree_node *dictionary, char *word) - 104 { - -> 105 if (!word || !dictionary) - 106 return 0; - 107 - 108 int compare_value = strcmp (word, dictionary->word); - (lldb) script - Python Interactive Interpreter. To exit, type 'quit()', 'exit()' or Ctrl-D. - >>> import tree_utils - >>> root = lldb.frame.FindVariable ("dictionary") - >>> current_path = "" - >>> path = tree_utils.DFS (root, "Romeo", current_path) - >>> print path - LLRRL - >>> ^D - (lldb) - -The first bit of code above shows starting lldb, attaching to the dictionary -program, and getting to the find_word function in LLDB. The interesting part -(as far as this example is concerned) begins when we enter the script command -and drop into the embedded interactive Python interpreter. We will go over this -Python code line by line. The first line - -:: - - import tree_utils - - -imports the file where we wrote our DFS function, tree_utils.py, into Python. -Notice that to import the file we leave off the ".py" extension. We can now -call any function in that file, giving it the prefix "tree_utils.", so that -Python knows where to look for the function. The line - -:: - - root = lldb.frame.FindVariable ("dictionary") - - -gets our program variable "dictionary" (which contains the binary search tree) -and puts it into the Python variable "root". See Accessing & Manipulating -Program Variables in Python above for more details about how this works. The -next line is - -:: - - current_path = "" - -This line initializes the current_path from the root of the tree to our current -node. Since we are starting at the root of the tree, our current path starts as -an empty string. As we go right and left through the tree, the DFS function -will append an 'R' or an 'L' to the current path, as appropriate. The line - -:: - - path = tree_utils.DFS (root, "Romeo", current_path) - -calls our DFS function (prefixing it with the module name so that Python can -find it). We pass in our binary tree stored in the variable root, the word we -are searching for, and our current path. We assign whatever path the DFS -function returns to the Python variable path. - -Finally, we want to see if the word was found or not, and if so we want to see -the path through the tree to the word. So we do - -:: - - print path - -From this we can see that the word "Romeo" was indeed found in the tree, and -the path from the root of the tree to the node containing "Romeo" is -left-left-right-right-left. - -Using Breakpoint Command Scripts --------------------------------- - -We are halfway to figuring out what the problem is. We know the word we are -looking for is in the binary tree, and we know exactly where it is in the -binary tree. Now we need to figure out why our binary search algorithm is not -finding the word. We will do this using breakpoint command scripts. - -The idea is as follows. The binary search algorithm has two main decision -points: the decision to follow the right branch; and, the decision to follow -the left branch. We will set a breakpoint at each of these decision points, and -attach a Python breakpoint command script to each breakpoint. The breakpoint -commands will use the global path Python variable that we got from our DFS -function. Each time one of these decision breakpoints is hit, the script will -compare the actual decision with the decision the front of the path variable -says should be made (the first character of the path). If the actual decision -and the path agree, then the front character is stripped off the path, and -execution is resumed. In this case the user never even sees the breakpoint -being hit. But if the decision differs from what the path says it should be, -then the script prints out a message and does NOT resume execution, leaving the -user sitting at the first point where a wrong decision is being made. - -Python Breakpoint Command Scripts Are Not What They Seem --------------------------------------------------------- - -What do we mean by that? When you enter a Python breakpoint command in LLDB, it -appears that you are entering one or more plain lines of Python. BUT LLDB then -takes what you entered and wraps it into a Python FUNCTION (just like using the -"def" Python command). It automatically gives the function an obscure, unique, -hard-to-stumble-across function name, and gives it two parameters: frame and -bp_loc. When the breakpoint gets hit, LLDB wraps up the frame object where the -breakpoint was hit, and the breakpoint location object for the breakpoint that -was hit, and puts them into Python variables for you. It then calls the Python -function that was created for the breakpoint command, and passes in the frame -and breakpoint location objects. - -So, being practical, what does this mean for you when you write your Python -breakpoint commands? It means that there are two things you need to keep in -mind: 1. If you want to access any Python variables created outside your -script, you must declare such variables to be global. If you do not declare -them as global, then the Python function will treat them as local variables, -and you will get unexpected behavior. 2. All Python breakpoint command scripts -automatically have a frame and a bp_loc variable. The variables are pre-loaded -by LLDB with the correct context for the breakpoint. You do not have to use -these variables, but they are there if you want them. - -The Decision Point Breakpoint Commands --------------------------------------- - -This is what the Python breakpoint command script would look like for the -decision to go right: - -:: - - global path - if path[0] == 'R': - path = path[1:] - thread = frame.GetThread() - process = thread.GetProcess() - process.Continue() - else: - print "Here is the problem; going right, should go left!" - - -Just as a reminder, LLDB is going to take this script and wrap it up in a function, like this: - -:: - - def some_unique_and_obscure_function_name (frame, bp_loc): - global path - if path[0] == 'R': - path = path[1:] - thread = frame.GetThread() - process = thread.GetProcess() - process.Continue() - else: - print "Here is the problem; going right, should go left!" - -LLDB will call the function, passing in the correct frame and breakpoint -location whenever the breakpoint gets hit. There are several things to notice -about this function. The first one is that we are accessing and updating a -piece of state (the path variable), and actually conditioning our behavior -based upon this variable. Since the variable was defined outside of our script -(and therefore outside of the corresponding function) we need to tell Python -that we are accessing a global variable. That is what the first line of the -script does. Next we check where the path says we should go and compare it to -our decision (recall that we are at the breakpoint for the decision to go -right). If the path agrees with our decision, then we strip the first character -off of the path. - -Since the decision matched the path, we want to resume execution. To do this we -make use of the frame parameter that LLDB guarantees will be there for us. We -use LLDB API functions to get the current thread from the current frame, and -then to get the process from the thread. Once we have the process, we tell it -to resume execution (using the Continue() API function). - -If the decision to go right does not agree with the path, then we do not resume -execution. We allow the breakpoint to remain stopped (by doing nothing), and we -print an informational message telling the user we have found the problem, and -what the problem is. - -Actually Using The Breakpoint Commands --------------------------------------- - -Now we will look at what happens when we actually use these breakpoint commands -on our program. Doing a source list -n find_word shows us the function -containing our two decision points. Looking at the code below, we see that we -want to set our breakpoints on lines 113 and 115: - -:: - - (lldb) source list -n find_word - File: /Volumes/Data/HD2/carolinetice/Desktop/LLDB-Web-Examples/dictionary.c. - 101 - 102 int - 103 find_word (tree_node *dictionary, char *word) - 104 { - 105 if (!word || !dictionary) - 106 return 0; - 107 - 108 int compare_value = strcmp (word, dictionary->word); - 109 - 110 if (compare_value == 0) - 111 return 1; - 112 else if (compare_value < 0) - 113 return find_word (dictionary->left, word); - 114 else - 115 return find_word (dictionary->right, word); - 116 } - 117 - - -So, we set our breakpoints, enter our breakpoint command scripts, and see what happens: - -:: - - (lldb) breakpoint set -l 113 - Breakpoint created: 2: file ='dictionary.c', line = 113, locations = 1, resolved = 1 - (lldb) breakpoint set -l 115 - Breakpoint created: 3: file ='dictionary.c', line = 115, locations = 1, resolved = 1 - (lldb) breakpoint command add -s python 2 - Enter your Python command(s). Type 'DONE' to end. - > global path - > if (path[0] == 'L'): - > path = path[1:] - > thread = frame.GetThread() - > process = thread.GetProcess() - > process.Continue() - > else: - > print "Here is the problem. Going left, should go right!" - > DONE - (lldb) breakpoint command add -s python 3 - Enter your Python command(s). Type 'DONE' to end. - > global path - > if (path[0] == 'R'): - > path = path[1:] - > thread = frame.GetThread() - > process = thread.GetProcess() - > process.Continue() - > else: - > print "Here is the problem. Going right, should go left!" - > DONE - (lldb) continue - Process 696 resuming - Here is the problem. Going right, should go left! - Process 696 stopped - * thread #1: tid = 0x2d03, 0x000000010000189f dictionary`find_word + 127 at dictionary.c:115, stop reason = breakpoint 3.1 - frame #0: 0x000000010000189f dictionary`find_word + 127 at dictionary.c:115 - 112 else if (compare_value < 0) - 113 return find_word (dictionary->left, word); - 114 else - -> 115 return find_word (dictionary->right, word); - 116 } - 117 - 118 void - (lldb) - - -After setting our breakpoints, adding our breakpoint commands and continuing, -we run for a little bit and then hit one of our breakpoints, printing out the -error message from the breakpoint command. Apparently at this point in the -tree, our search algorithm decided to go right, but our path says the node we -want is to the left. Examining the word at the node where we stopped, and our -search word, we see: - -:: - - (lldb) expr dictionary->word - (const char *) $1 = 0x0000000100100080 "dramatis" - (lldb) expr word - (char *) $2 = 0x00007fff5fbff108 "romeo" - -So the word at our current node is "dramatis", and the word we are searching -for is "romeo". "romeo" comes after "dramatis" alphabetically, so it seems like -going right would be the correct decision. Let's ask Python what it thinks the -path from the current node to our word is: - -:: - - (lldb) script print path - LLRRL - -According to Python we need to go left-left-right-right-left from our current -node to find the word we are looking for. Let's double check our tree, and see -what word it has at that node: - -:: - - (lldb) expr dictionary->left->left->right->right->left->word - (const char *) $4 = 0x0000000100100880 "Romeo" - -So the word we are searching for is "romeo" and the word at our DFS location is -"Romeo". Aha! One is uppercase and the other is lowercase: We seem to have a -case conversion problem somewhere in our program (we do). - -This is the end of our example on how you might use Python scripting in LLDB to -help you find bugs in your program. - -Source Files for The Example ----------------------------- - -The complete code for the Dictionary program (with case-conversion bug), the -DFS function and other Python script examples (tree_utils.py) used for this -example are available below. - -tree_utils.py - Example Python functions using LLDB's API, including DFS - -:: - - """ - # ===-- tree_utils.py ---------------------------------------*- Python -*-===// - # - # Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions. - # See https://llvm.org/LICENSE.txt for license information. - # SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception - # - # ===----------------------------------------------------------------------===// - - tree_utils.py - A set of functions for examining binary - search trees, based on the example search tree defined in - dictionary.c. These functions contain calls to LLDB API - functions, and assume that the LLDB Python module has been - imported. - - For a thorough explanation of how the DFS function works, and - for more information about dictionary.c go to - http://lldb.llvm.org/scripting.html - """ - - - def DFS(root, word, cur_path): - """ - Recursively traverse a binary search tree containing - words sorted alphabetically, searching for a particular - word in the tree. Also maintains a string representing - the path from the root of the tree to the current node. - If the word is found in the tree, return the path string. - Otherwise return an empty string. - - This function assumes the binary search tree is - the one defined in dictionary.c It uses LLDB API - functions to examine and traverse the tree nodes. - """ - - # Get pointer field values out of node 'root' - - root_word_ptr = root.GetChildMemberWithName("word") - left_child_ptr = root.GetChildMemberWithName("left") - right_child_ptr = root.GetChildMemberWithName("right") - - # Get the word out of the word pointer and strip off - # surrounding quotes (added by call to GetSummary). - - root_word = root_word_ptr.GetSummary() - end = len(root_word) - 1 - if root_word[0] == '"' and root_word[end] == '"': - root_word = root_word[1:end] - end = len(root_word) - 1 - if root_word[0] == '\'' and root_word[end] == '\'': - root_word = root_word[1:end] - - # Main depth first search - - if root_word == word: - return cur_path - elif word < root_word: - - # Check to see if left child is NULL - - if left_child_ptr.GetValue() is None: - return "" - else: - cur_path = cur_path + "L" - return DFS(left_child_ptr, word, cur_path) - else: - - # Check to see if right child is NULL - - if right_child_ptr.GetValue() is None: - return "" - else: - cur_path = cur_path + "R" - return DFS(right_child_ptr, word, cur_path) - - - def tree_size(root): - """ - Recursively traverse a binary search tree, counting - the nodes in the tree. Returns the final count. - - This function assumes the binary search tree is - the one defined in dictionary.c It uses LLDB API - functions to examine and traverse the tree nodes. - """ - if (root.GetValue is None): - return 0 - - if (int(root.GetValue(), 16) == 0): - return 0 - - left_size = tree_size(root.GetChildAtIndex(1)) - right_size = tree_size(root.GetChildAtIndex(2)) - - total_size = left_size + right_size + 1 - return total_size - - - def print_tree(root): - """ - Recursively traverse a binary search tree, printing out - the words at the nodes in alphabetical order (the - search order for the binary tree). - - This function assumes the binary search tree is - the one defined in dictionary.c It uses LLDB API - functions to examine and traverse the tree nodes. - """ - if (root.GetChildAtIndex(1).GetValue() is not None) and ( - int(root.GetChildAtIndex(1).GetValue(), 16) != 0): - print_tree(root.GetChildAtIndex(1)) - - print root.GetChildAtIndex(0).GetSummary() - - if (root.GetChildAtIndex(2).GetValue() is not None) and ( - int(root.GetChildAtIndex(2).GetValue(), 16) != 0): - print_tree(root.GetChildAtIndex(2)) - - -dictionary.c - Sample dictionary program, with bug - -:: - - //===-- dictionary.c ---------------------------------------------*- C -*-===// - // - // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions. - // See https://llvm.org/LICENSE.txt for license information. - // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception - // - //===----------------------------------------------------------------------===// - #include - #include - #include - #include - - typedef struct tree_node { - const char *word; - struct tree_node *left; - struct tree_node *right; - } tree_node; - - /* Given a char*, returns a substring that starts at the first - alphabet character and ends at the last alphabet character, i.e. it - strips off beginning or ending quotes, punctuation, etc. */ - - char *strip(char **word) { - char *start = *word; - int len = strlen(start); - char *end = start + len - 1; - - while ((start < end) && (!isalpha(start[0]))) - start++; - - while ((end > start) && (!isalpha(end[0]))) - end--; - - if (start > end) - return NULL; - - end[1] = '\0'; - *word = start; - - return start; - } - - /* Given a binary search tree (sorted alphabetically by the word at - each node), and a new word, inserts the word at the appropriate - place in the tree. */ - - void insert(tree_node *root, char *word) { - if (root == NULL) - return; - - int compare_value = strcmp(word, root->word); - - if (compare_value == 0) - return; - - if (compare_value < 0) { - if (root->left != NULL) - insert(root->left, word); - else { - tree_node *new_node = (tree_node *)malloc(sizeof(tree_node)); - new_node->word = strdup(word); - new_node->left = NULL; - new_node->right = NULL; - root->left = new_node; - } - } else { - if (root->right != NULL) - insert(root->right, word); - else { - tree_node *new_node = (tree_node *)malloc(sizeof(tree_node)); - new_node->word = strdup(word); - new_node->left = NULL; - new_node->right = NULL; - root->right = new_node; - } - } - } - - /* Read in a text file and storea all the words from the file in a - binary search tree. */ - - void populate_dictionary(tree_node **dictionary, char *filename) { - FILE *in_file; - char word[1024]; - - in_file = fopen(filename, "r"); - if (in_file) { - while (fscanf(in_file, "%s", word) == 1) { - char *new_word = (strdup(word)); - new_word = strip(&new_word); - if (*dictionary == NULL) { - tree_node *new_node = (tree_node *)malloc(sizeof(tree_node)); - new_node->word = new_word; - new_node->left = NULL; - new_node->right = NULL; - *dictionary = new_node; - } else - insert(*dictionary, new_word); - } - } - } - - /* Given a binary search tree and a word, search for the word - in the binary search tree. */ - - int find_word(tree_node *dictionary, char *word) { - if (!word || !dictionary) - return 0; - - int compare_value = strcmp(word, dictionary->word); - - if (compare_value == 0) - return 1; - else if (compare_value < 0) - return find_word(dictionary->left, word); - else - return find_word(dictionary->right, word); - } - - /* Print out the words in the binary search tree, in sorted order. */ - - void print_tree(tree_node *dictionary) { - if (!dictionary) - return; - - if (dictionary->left) - print_tree(dictionary->left); - - printf("%s\n", dictionary->word); - - if (dictionary->right) - print_tree(dictionary->right); - } - - int main(int argc, char **argv) { - tree_node *dictionary = NULL; - char buffer[1024]; - char *filename; - int done = 0; - - if (argc == 2) - filename = argv[1]; - - if (!filename) - return -1; - - populate_dictionary(&dictionary, filename); - fprintf(stdout, "Dictionary loaded.\nEnter search word: "); - while (!done && fgets(buffer, sizeof(buffer), stdin)) { - char *word = buffer; - int len = strlen(word); - int i; - - for (i = 0; i < len; ++i) - word[i] = tolower(word[i]); - - if ((len > 0) && (word[len - 1] == '\n')) { - word[len - 1] = '\0'; - len = len - 1; - } - - if (find_word(dictionary, word)) - fprintf(stdout, "Yes!\n"); - else - fprintf(stdout, "No!\n"); - - fprintf(stdout, "Enter search word: "); - } - - fprintf(stdout, "\n"); - return 0; - } - - -The text for "Romeo and Juliet" can be obtained from the Gutenberg Project -(http://www.gutenberg.org). - diff --git a/lldb/docs/use/tutorials/accessing-documentation.md b/lldb/docs/use/tutorials/accessing-documentation.md new file mode 100644 index 0000000000000..d14efa5f3c428 --- /dev/null +++ b/lldb/docs/use/tutorials/accessing-documentation.md @@ -0,0 +1,62 @@ +# Accessing Script Documentation + +The LLDB API is contained in a python module named lldb. A useful resource when +writing Python extensions is the lldb Python classes reference guide. + +The documentation is also accessible in an interactive debugger session with +the following command: + +```python3 +(lldb) script help(lldb) + 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 +... +``` + +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: + +```python3 +(lldb) script help(lldb.SBFrame) + Help on class SBFrame in module lldb: + + class SBFrame(builtins.object) + | SBFrame(*args) + | + | 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.''' +... +``` + +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 +currently selected process: + +```python3 +(lldb) script help(lldb.process) + Help on SBProcess in module lldb object: + + class SBProcess(builtins.object) + | SBProcess(*args) + | + | 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 + | # ================================================== +... +``` \ No newline at end of file diff --git a/lldb/docs/use/tutorials/automating-stepping-logic.md b/lldb/docs/use/tutorials/automating-stepping-logic.md new file mode 100644 index 0000000000000..564d3ec1f14d4 --- /dev/null +++ b/lldb/docs/use/tutorials/automating-stepping-logic.md @@ -0,0 +1,42 @@ +# Automating Stepping Logic + +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. + +The base class for the [ScriptedThreadPlan](https://lldb.llvm.org/python_api/lldb.plugins.scripted_thread_plan.ScriptedThreadPlan.html) is provided as part of the lldb python module, making it easy to derive a new class from it. + +There is a longer discussion of scripted thread plans and the state machine, +and several interesting examples of their use in [scripted_step.py](https://github.com/llvm/llvm-project/blob/main/lldb/examples/python/scripted_step.py) +and for a **MUCH** fuller discussion of the whole state machine, see [ThreadPlan.h](https://github.com/llvm/llvm-project/blob/main/lldb/include/lldb/Target/ThreadPlan.h) + +If you are reading those comments it is useful to know that scripted thread +plans are set to be either ***"ControllingPlans"*** or ***"OkayToDiscard"***. + +To implement a scripted step, you define a python class that has the following +methods: + +| Name | Arguments | Description | +|------|-----------|-------------| +| `__init__` | `thread_plan`: `lldb.SBThreadPlan` | 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. | +| `explains_stop` | `event`: `lldb.SBEvent` | Return True if this stop is part of your thread plans logic, false otherwise. | +| `is_stale` | `None` | 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. | +| `should_step` | `None` | Return `True` if you want lldb to instruction step one instruction, or False to continue till the next breakpoint is hit. | +| `should_stop` | `event`: `lldb.SBEvent` | 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. | + +To use this class to implement a step, use the command: + +```python3 +(lldb) thread step-scripted -C MyModule.MyStepPlanClass +``` + +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. \ No newline at end of file diff --git a/lldb/docs/use/tutorials/breakpoint-triggered-scripts.md b/lldb/docs/use/tutorials/breakpoint-triggered-scripts.md new file mode 100644 index 0000000000000..0cd9f945f0d11 --- /dev/null +++ b/lldb/docs/use/tutorials/breakpoint-triggered-scripts.md @@ -0,0 +1,85 @@ +# Breakpoint-Triggered Scripts + +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. + +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: + +```python3 +def breakpoint_function_wrapper(frame, bp_loc, internal_dict): + # Your code goes here +``` + +or: + +```python3 +def breakpoint_function_wrapper(frame, bp_loc, extra_args, internal_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. | +| `internal_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 +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. + +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. + +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 lldb.SBBreakpoint object that contains an +lldb.SBBreakpointLocation 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. + +Note we also have to initialize our counter, which we do with the simple +one-line version of the script command. + +Here is the code: + +```python3 +(lldb) breakpoint set --func-regex=. --shlib=libfoo.dylib +Breakpoint created: 1: regex = '.', module = libfoo.dylib, locations = 223 +(lldb) script counter = 0 +(lldb) breakpoint command add --script-type python 1 +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 +> global counter +> counter += 1 +> # Get the name of the function +> name = frame.GetFunctionName() +> # Print the order and the function name +> print('[%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 +> DONE +``` + +The breakpoint command add command above attaches a python script to breakpoint 1. To remove the breakpoint command: + +```python3 +(lldb) breakpoint command delete 1 +``` \ No newline at end of file diff --git a/lldb/docs/use/tutorials/creating-custom-breakpoints.md b/lldb/docs/use/tutorials/creating-custom-breakpoints.md new file mode 100644 index 0000000000000..e3081c44e3650 --- /dev/null +++ b/lldb/docs/use/tutorials/creating-custom-breakpoints.md @@ -0,0 +1,128 @@ +# Custom Breakpoint Resolvers + +Another use of the Python API's in lldb is to create a custom breakpoint +resolver. + +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. + +In lldb, a breakpoint is composed of three parts: +1. the Searcher +2. the Resolver, +3. 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. + +### Breakpoint Searcher + +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. + +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 -s modulename flag to break set you are creating a Module-based search +filter. When you pass -f filename.c to break set -n 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. + +### Breakpoint Resolver + +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. + +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. + +One other slight subtlety is that the depth at which you get called back is not +necessarily the depth at which 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 SBBreakpoint::AddLocation will only add locations that pass the +Search Filter. This API returns an SBError to inform you whether your location +was added. + +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. + +### Scripted Breakpoint Resolver + +At present, when adding a ScriptedBreakpoint type, you can only provide a +custom Resolver, not a custom SearchFilter. + +The custom Resolver is provided as a Python class with the following methods: + +| Name | Arguments | Description | +|------|-----------|-------------| +| `__init__` | `bkpt`: `lldb.SBBreakpoint` `extra_args`: `lldb.SBStructuredData` | This is the constructor for the new Resolver. `bkpt` is the breakpoint owning this Resolver. `extra_args` 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 | +| `__callback__` | `sym_ctx`: `lldb.SBSymbolContext` | This is the Resolver callback. The `sym_ctx` argument will be filled with the current stage of the search. 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 `sym_ctx` for new locations. If the callback finds an address of interest, it can add it to the breakpoint with the `SBBreakpoint.AddLocation` method, using the breakpoint passed in to the `__init__` method. | +| `__get_depth__` | `None` | Specify the depth at which you wish your callback to get called. The currently supported options are: `lldb.eSearchDepthModule` `lldb.eSearchDepthCompUnit` `lldb.eSearchDepthFunction` 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 `lldb.eSearchDepthModule`. This method is optional. If not provided the search will be done at Module depth. | +| `get_short_help` | `None` | This is an optional method. If provided, the returned string will be printed at the beginning of the description for this breakpoint. | + +To define a new breakpoint command defined by this class from the lldb command +line, use the command: + +``` +(lldb) breakpoint set -P MyModule.MyResolverClass +``` + +You can also populate the extra_args SBStructuredData with a dictionary of +key/value pairs with: + +``` +(lldb) breakpoint set -P MyModule.MyResolverClass -k key_1 -v value_1 -k key_2 -v value_2 +``` + +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 -s ModuleName option - which can be specified multiple times. You +can also specify a SearchFilter restricted to certain compile units by passing +in the -f CompUnitName 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, + +``` +(lldb) breakpoint set -P MyModule.MyResolverClass -s a.out +``` + +will use your resolver, but will only recurse into or accept new locations in +the module a.out. + +Another option for creating scripted breakpoints is to use the +SBTarget.BreakpointCreateFromScript 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. \ No newline at end of file diff --git a/lldb/docs/use/tutorials/custom-frame-recognizers.md b/lldb/docs/use/tutorials/custom-frame-recognizers.md new file mode 100644 index 0000000000000..17bf9637d9a85 --- /dev/null +++ b/lldb/docs/use/tutorials/custom-frame-recognizers.md @@ -0,0 +1,51 @@ +# Detecting Patterns With Recognizers + +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 inaccessible, or augment existing arguments. + +Adding a custom frame recognizer is done by implementing a Python class and +using the `frame recognizer add` command. The Python class should implement the +`get_recognized_arguments` method and it will receive an argument of type +`lldb.SBFrame` representing the current frame that we are trying to recognize. +The method should return a (possibly empty) list of `lldb.SBValue` objects that +represent the recognized arguments. + +An example of a recognizer that retrieves the file descriptor values from libc +functions 'read', 'write' and 'close' follows: + +```python3 +class LibcFdRecognizer: + def get_recognized_arguments(self, frame: lldb.SBFrame): + if frame.name in ["read", "write", "close"]: + fd = frame.EvaluateExpression("$arg1").unsigned + target = frame.thread.process.target + value = target.CreateValueFromExpression("fd", "(int)%d" % fd) + return [value] + return [] +``` + +The file containing this implementation can be imported via `command script import` +and then we can register this recognizer with `frame recognizer add`. + +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: + +```c++ +(lldb) command script import .../fd_recognizer.py +(lldb) frame recognizer add -l fd_recognizer.LibcFdRecognizer -n read -s libsystem_kernel.dylib +``` + +When the program is stopped at the beginning of the 'read' function in libc, we can view the recognizer arguments in 'frame variable': + +```c++ +(lldb) b read +(lldb) r +Process 1234 stopped +* thread #1, queue = 'com.apple.main-thread', stop reason = breakpoint 1.3 + frame #0: 0x00007fff06013ca0 libsystem_kernel.dylib`read +(lldb) frame variable +(int) fd = 3 +``` \ No newline at end of file diff --git a/lldb/docs/use/tutorials/extending-target-stop-hooks.md b/lldb/docs/use/tutorials/extending-target-stop-hooks.md new file mode 100644 index 0000000000000..232187d0dcf11 --- /dev/null +++ b/lldb/docs/use/tutorials/extending-target-stop-hooks.md @@ -0,0 +1,25 @@ +# Extending Target Stop-Hooks + +Stop hooks fire whenever the process stops just before control is returned to the +user. Stop hooks can either be a set of lldb command-line commands, or can +be implemented by a suitably defined Python class. The Python-based stop-hooks +can also be passed as a set of -key -value pairs when they are added, and those +will get packaged up into a `SBStructuredData` Dictionary and passed to the +constructor of the Python object managing the stop hook. This allows for +parameterization of the stop hooks. + +To add a Python-based stop hook, first define a class with the following methods: + +| Name | Arguments | Description | +|------|-----------|-------------| +| `__init__` | `target: lldb.SBTarget` `extra_args: lldb.SBStructuredData` | This is the constructor for the new stop-hook. `target` is the SBTarget to which the stop hook is added. `extra_args` is an SBStructuredData object that the user can pass in when creating instances of this breakpoint. It is not required, but allows for reuse of stop-hook classes. | +| `handle_stop` | `exe_ctx: lldb.SBExecutionContext` `stream: lldb.SBStream` | This is the called when the target stops. `exe_ctx` argument will be filled with the current stop point for which the stop hook is being evaluated. `stream` an lldb.SBStream, anything written to this stream will be written to the debugger console. The return value is a "Should Stop" vote from this thread. If the method returns either True or no return this thread votes to stop. If it returns False, then the thread votes to continue after all the stop-hooks are evaluated. Note, the --auto-continue flag to 'target stop-hook add' overrides a True return value from the method. | + +To use this class in lldb, run the command: + +``` +(lldb) command script import MyModule.py +(lldb) target stop-hook add -P MyModule.MyStopHook -k first -v 1 -k second -v 2 +``` + +where `MyModule.py` is the file containing the class definition `MyStopHook`. \ No newline at end of file diff --git a/lldb/docs/use/tutorials/implementing-standalone-scripts.md b/lldb/docs/use/tutorials/implementing-standalone-scripts.md new file mode 100644 index 0000000000000..b8aaacf22fc2e --- /dev/null +++ b/lldb/docs/use/tutorials/implementing-standalone-scripts.md @@ -0,0 +1,134 @@ +# Implementing Standalone Scripts + +### Configuring `PYTHONPATH` + +LLDB has all of its core code built into a shared library which gets used by +the `lldb` command line application. +- On macOS this shared library is a framework: `LLDB.framework`. +- On other unix variants the program is a shared library: lldb.so. + +LLDB also provides an `lldb.py` module that contains the bindings from LLDB +into Python. To use the `LLDB.framework` 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 `PYTHONPATH` environment variable, +adding a path to the directory that contains the `lldb.py` 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: + +For csh and tcsh: + +```csh +% setenv PYTHONPATH `lldb -P` +``` + +For sh and bash: + +```bash +$ export PYTHONPATH=`lldb -P` +``` + +Alternatively, you can append the LLDB Python directory to the sys.path list +directly in your Python code before importing the lldb module. + +### Initialization + +The standard test for `__main__`, like many python modules do, is useful for +creating scripts that can be run from the command line. However, for command +line scripts, the debugger instance must be created manually. Sample code would +look like: + +```python3 +if __name__ == '__main__': + # Initialize the debugger before making any API calls. + lldb.SBDebugger.Initialize() + # 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 + debugger = lldb.SBDebugger.Create() + + # Next, do whatever work this module should do when run as a command. + # ... + + # Finally, dispose of the debugger you just made. + lldb.SBDebugger.Destroy(debugger) + # Terminate the debug session + lldb.SBDebugger.Terminate() +``` + +### Example + +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: + +```python3 +#!/usr/bin/env python3 + +import lldb +import os + +def disassemble_instructions(insts): + for i in insts: + print(i) + +# Set the path to the executable to debug +exe = "./a.out" + +# Create a new debugger instance +debugger = lldb.SBDebugger.Create() + +# 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. +debugger.SetAsync(False) + +# Create a target from a file and arch +print("Creating a target for '%s'" % exe) + +target = debugger.CreateTargetWithFileAndArch(exe, lldb.LLDB_ARCH_DEFAULT) + +if target: + # If the target is valid set a breakpoint at main + main_bp = target.BreakpointCreateByName( + "main", target.GetExecutable().GetFilename() + ) + + print(main_bp) + + # Launch the process. Since we specified synchronous mode, we won't return + # from this function until we hit the breakpoint at main + process = target.LaunchSimple(None, None, os.getcwd()) + + # Make sure the launch went ok + if process: + # Print some simple process info + state = process.GetState() + print(process) + if state == lldb.eStateStopped: + # Get the first thread + thread = process.GetThreadAtIndex(0) + if thread: + # Print some simple thread info + print(thread) + # Get the first frame + frame = thread.GetFrameAtIndex(0) + if frame: + # Print some simple frame info + print(frame) + function = frame.GetFunction() + # See if we have debug info (a function) + if function: + # We do have a function, print some info for the function + print(function) + # Now get all instructions for this function and print them + insts = function.GetInstructions(target) + disassemble_instructions(insts) + else: + # See if we have a symbol in the symbol table for where we stopped + symbol = frame.GetSymbol() + if symbol: + # We do have a symbol, print some info for the symbol + print(symbol) +``` \ No newline at end of file diff --git a/lldb/docs/use/tutorials/python-embedded-interpreter.md b/lldb/docs/use/tutorials/python-embedded-interpreter.md new file mode 100644 index 0000000000000..719d746b35d43 --- /dev/null +++ b/lldb/docs/use/tutorials/python-embedded-interpreter.md @@ -0,0 +1,66 @@ +# Embedded Python Interpreter + +The embedded python interpreter can be accessed in a variety of ways from +within LLDB. The easiest way is to use the lldb command script with no +arguments at the lldb command prompt: + +```python3 +(lldb) script +Python Interactive Interpreter. To exit, type 'quit()', 'exit()' or Ctrl-D. +>>> 2+3 +5 +>>> hex(12345) +'0x3039' +>>> +``` + +This drops you into the embedded python 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 +state. In each case, if there is no currently selected entity of the +appropriate type, the variable's IsValid method will return false. These +variables are: + +| Variable | Type | Equivalent | Description | +|----------|------|------------|-------------| +| `lldb.debugger` | `lldb.SBDebugger` | `SBTarget.GetDebugger` | Contains the debugger object whose `script` command was invoked. The `lldb.SBDebugger` object owns the command interpreter and all the targets in your debug session. There will always be a Debugger in the embedded interpreter. | +| `lldb.target` | `lldb.SBTarget` | `SBDebugger.GetSelectedTarget` `SBProcess.GetTarget` | Contains the currently selected target - for instance the one made with the `file` or selected by the `target select ` command. The `lldb.SBTarget` manages one running process, and all the executable and debug files for the process. | +| `lldb.process` | `lldb.SBProcess` | `SBTarget.GetProcess` `SBThread.GetProcess` | Contains the process of the currently selected target. The `lldb.SBProcess` object manages the threads and allows access to memory for the process. | +| `lldb.thread` | `lldb.SBThread` | `SBProcess.GetSelectedThread` `SBFrame.GetThread` | Contains the currently selected thread. The `lldb.SBThread` object manages the stack frames in that thread. A thread is always selected in the command interpreter when a target stops. The `thread select ` 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. | +| `lldb.frame` | `lldb.SBFrame` | `SBThread.GetSelectedFrame` | Contains the currently selected stack frame. The `lldb.SBFrame` 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 `frame select ` 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. | + +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. + +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). For the +latter you'll be passed an `SBDebugger`, `SBTarget`, `SBProcess`, `SBThread` or +`SBFrame` instance and you can use the functions from the "Equivalent" column +to navigate between them. + +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. + +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 +pass them to the Python print function: + +```python3 +(lldb) script +Python Interactive Interpreter. To exit, type 'quit()', 'exit()' or Ctrl-D. +>>> print(lldb.debugger) +Debugger (instance: "debugger_1", id: 1) +>>> print(lldb.target) +a.out +>>> print(lldb.process) +SBProcess: pid = 58842, state = stopped, threads = 1, executable = a.out +>>> print(lldb.thread) +thread #1: tid = 0x2265ce3, 0x0000000100000334 a.out`main at t.c:2:3, queue = 'com.apple.main-thread', stop reason = breakpoint 1.1 +>>> print(lldb.frame) +frame #0: 0x0000000100000334 a.out`main at t.c:2:3 +``` \ No newline at end of file diff --git a/lldb/docs/use/tutorials/script-driven-debugging.md b/lldb/docs/use/tutorials/script-driven-debugging.md new file mode 100644 index 0000000000000..55b90b1e25bf5 --- /dev/null +++ b/lldb/docs/use/tutorials/script-driven-debugging.md @@ -0,0 +1,492 @@ +# Script-Driven Debugging + +LLDB has been structured from the beginning to be scriptable in two +ways: +- a Unix Python session can initiate/run a debug session non-interactively +using LLDB; +- and within the LLDB debugger tool, Python scripts can be used to help with +many tasks, including inspecting program data, iterating over containers and +determining if a breakpoint should stop execution or continue. + +This document will show how to do some of these things by going through an +example, explaining how to use Python scripting to find a bug in a program +that searches for text in a large binary tree. + +### The Test Program and Input + +We have a simple C program ([dictionary.c](https://github.com/llvm/llvm-project/blob/main/lldb/examples/scripting/dictionary.c)) +that reads in a text file, and stores all the words from the file in a +Binary Search Tree, sorted alphabetically. It then enters a loop +prompting the user for a word, searching for the word in the tree +(using Binary Search), and reporting to the user whether or not it found +the word in the tree. + +The input text file we are using to test our program contains the text +for William Shakespeare's famous tragedy "Romeo and Juliet". + +### The Bug + +When we try running our program, we find there is a problem. While it +successfully finds some of the words we would expect to find, such as +"love" or "sun", it fails to find the word "Romeo", which **MUST** be in +the input text file: + +```shell +$ ./dictionary Romeo-and-Juliet.txt +Dictionary loaded. +Enter search word: love +Yes! +Enter search word: sun +Yes! +Enter search word: Romeo +No! +Enter search word: ^D +$ +``` + +### Using Depth First Search + +Our first job is to determine if the word "Romeo" actually got inserted +into the tree or not. Since "Romeo and Juliet" has thousands of words, +trying to examine our binary search tree by hand is completely +impractical. Therefore we will write a Python script to search the tree +for us. We will write a recursive Depth First Search function that +traverses the entire tree searching for a word, and maintaining +information about the path from the root of the tree to the current +node. If it finds the word in the tree, it returns the path from the +root to the node containing the word. This is what our DFS function in +Python would look like, with line numbers added for easy reference in +later explanations: + +```python3 +1: def DFS (root, word, cur_path): +2: root_word_ptr = root.GetChildMemberWithName ("word") +3: left_child_ptr = root.GetChildMemberWithName ("left") +4: right_child_ptr = root.GetChildMemberWithName ("right") +5: root_word = root_word_ptr.GetSummary() +6: end = len (root_word) - 1 +7: if root_word[0] == '"' and root_word[end] == '"': +8: root_word = root_word[1:end] +9: end = len (root_word) - 1 +10: if root_word[0] == '\'' and root_word[end] == '\'': +11: root_word = root_word[1:end] +12: if root_word == word: +13: return cur_path +14: elif word < root_word: +15: if left_child_ptr.GetValue() is None: +16: return "" +17: else: +18: cur_path = cur_path + "L" +19: return DFS (left_child_ptr, word, cur_path) +20: else: +21: if right_child_ptr.GetValue() is None: +22: return "" +23: else: +24: cur_path = cur_path + "R" +25: return DFS (right_child_ptr, word, cur_path) +``` + +### Accessing & Manipulating Program Variables + +Before we can call any Python function on any of our program's +variables, we need to get the variable into a form that Python can +access. To show you how to do this we will look at the parameters for +the DFS function. The first parameter is going to be a node in our +binary search tree, put into a Python variable. The second parameter is +the word we are searching for (a string), and the third parameter is a +string representing the path from the root of the tree to our current +node. + +The most interesting parameter is the first one, the Python variable +that needs to contain a node in our search tree. How can we take a +variable out of our program and put it into a Python variable? What +kind of Python variable will it be? The answers are to use the LLDB API +functions, provided as part of the LLDB Python module. Running Python +from inside LLDB, LLDB will automatically give us our current frame +object as a Python variable, "lldb.frame". This variable has the type +`SBFrame` (see the LLDB API for more information about `SBFrame` +objects). One of the things we can do with a frame object, is to ask it +to find and return its local variable. We will call the API function +`SBFrame.FindVariable` on the `lldb.frame` object to give us our +dictionary variable as a Python variable: + +```python3 +root = lldb.frame.FindVariable ("dictionary") +``` + +The line above, executed in the Python script interpreter in LLDB, asks the +current frame to find the variable named "dictionary" and return it. We then +store the returned value in the Python variable named "root". This answers the +question of HOW to get the variable, but it still doesn't explain WHAT actually +gets put into "root". If you examine the LLDB API, you will find that the +`SBFrame` method "FindVariable" returns an object of type `SBValue`. `SBValue` +objects are used, among other things, to wrap up program variables and values. +There are many useful methods defined in the `SBValue` class to allow you to get +information or children values out of SBValues. For complete information, see +the header file SBValue.h. The `SBValue` methods that we use in our DFS function +are `GetChildMemberWithName()`, `GetSummary()`, and `GetValue()`. + +### Explaining DFS Script in Detail + +Before diving into the details of this code, it would be best to give a +high-level overview of what it does. The nodes in our binary search tree were +defined to have type `tree_node *`, which is defined as: + +```c++ +typedef struct tree_node +{ + const char *word; + struct tree_node *left; + struct tree_node *right; +} tree_node; +``` + +Lines 2-11 of DFS are getting data out of the current tree node and getting +ready to do the actual search; lines 12-25 are the actual depth-first search. +Lines 2-4 of our DFS function get the word, left and right fields out of the +current node and store them in Python variables. Since root_word_ptr is a +pointer to our word, and we want the actual word, line 5 calls GetSummary() to +get a string containing the value out of the pointer. Since GetSummary() adds +quotes around its result, lines 6-11 strip surrounding quotes off the word. + +Line 12 checks to see if the word in the current node is the one we are +searching for. If so, we are done, and line 13 returns the current path. +Otherwise, line 14 checks to see if we should go left (search word comes before +the current word). If we decide to go left, line 15 checks to see if the left +pointer child is NULL ("None" is the Python equivalent of NULL). If the left +pointer is NULL, then the word is not in this tree and we return an empty path +(line 16). Otherwise, we add an "L" to the end of our current path string, to +indicate we are going left (line 18), and then recurse on the left child (line +19). Lines 20-25 are the same as lines 14-19, except for going right rather +than going left. + +One other note: Typing something as long as our DFS function directly into the +interpreter can be difficult, as making a single typing mistake means having to +start all over. Therefore we recommend doing as we have done: Writing your +longer, more complicated script functions in a separate file (in this case +tree_utils.py) and then importing it into your LLDB Python interpreter. + +### The DFS Script in Action + +At this point we are ready to use the DFS function to see if the word "Romeo" +is in our tree or not. To actually use it in LLDB on our dictionary program, +you would do something like this: + +```c++ +$ lldb +(lldb) process attach -n "dictionary" +Architecture set to: x86_64. +Process 521 stopped +* thread #1: tid = 0x2c03, 0x00007fff86c8bea0 libSystem.B.dylib`read$NOCANCEL + 8, stop reason = signal SIGSTOP +frame #0: 0x00007fff86c8bea0 libSystem.B.dylib`read$NOCANCEL + 8 +(lldb) breakpoint set -n find_word +Breakpoint created: 1: name = 'find_word', locations = 1, resolved = 1 +(lldb) continue +Process 521 resuming +Process 521 stopped +* thread #1: tid = 0x2c03, 0x0000000100001830 dictionary`find_word + 16 +at dictionary.c:105, stop reason = breakpoint 1.1 +frame #0: 0x0000000100001830 dictionary`find_word + 16 at dictionary.c:105 +102 int +103 find_word (tree_node *dictionary, char *word) +104 { +-> 105 if (!word || !dictionary) +106 return 0; +107 +108 int compare_value = strcmp (word, dictionary->word); +(lldb) script +``` +```python3 +Python Interactive Interpreter. To exit, type 'quit()', 'exit()' or Ctrl-D. +>>> import tree_utils +>>> root = lldb.frame.FindVariable ("dictionary") +>>> current_path = "" +>>> path = tree_utils.DFS (root, "Romeo", current_path) +>>> print path +LLRRL +>>> ^D +(lldb) +``` + +The first bit of code above shows starting lldb, attaching to the dictionary +program, and getting to the find_word function in LLDB. The interesting part +(as far as this example is concerned) begins when we enter the script command +and drop into the embedded interactive Python interpreter. We will go over this +Python code line by line. The first line + +```python3 +import tree_utils +``` + +imports the file where we wrote our DFS function, tree_utils.py, into Python. +Notice that to import the file we leave off the ".py" extension. We can now +call any function in that file, giving it the prefix "tree_utils.", so that +Python knows where to look for the function. The line + +```python3 +root = lldb.frame.FindVariable ("dictionary") +``` + +gets our program variable "dictionary" (which contains the binary search tree) +and puts it into the Python variable "root". See Accessing & Manipulating +Program Variables in Python above for more details about how this works. The +next line is + +```python3 +current_path = "" +``` + +This line initializes the current_path from the root of the tree to our current +node. Since we are starting at the root of the tree, our current path starts as +an empty string. As we go right and left through the tree, the DFS function +will append an 'R' or an 'L' to the current path, as appropriate. The line + +```python3 +path = tree_utils.DFS (root, "Romeo", current_path) +``` + +calls our DFS function (prefixing it with the module name so that Python can +find it). We pass in our binary tree stored in the variable root, the word we +are searching for, and our current path. We assign whatever path the DFS +function returns to the Python variable path. + +Finally, we want to see if the word was found or not, and if so we want to see +the path through the tree to the word. So we do + +```python3 +print path +``` + +From this we can see that the word "Romeo" was indeed found in the tree, and +the path from the root of the tree to the node containing "Romeo" is +left-left-right-right-left. + +### Using Breakpoint Command Scripts + +We are halfway to figuring out what the problem is. We know the word we are +looking for is in the binary tree, and we know exactly where it is in the +binary tree. Now we need to figure out why our binary search algorithm is not +finding the word. We will do this using breakpoint command scripts. + +The idea is as follows. The binary search algorithm has two main decision +points: the decision to follow the right branch; and, the decision to follow +the left branch. We will set a breakpoint at each of these decision points, and +attach a Python breakpoint command script to each breakpoint. The breakpoint +commands will use the global path Python variable that we got from our DFS +function. Each time one of these decision breakpoints is hit, the script will +compare the actual decision with the decision the front of the path variable +says should be made (the first character of the path). If the actual decision +and the path agree, then the front character is stripped off the path, and +execution is resumed. In this case the user never even sees the breakpoint +being hit. But if the decision differs from what the path says it should be, +then the script prints out a message and does NOT resume execution, leaving the +user sitting at the first point where a wrong decision is being made. + +### Python Breakpoint Command Scripts Are Not What They Seem + +What do we mean by that? When you enter a Python breakpoint command in LLDB, it +appears that you are entering one or more plain lines of Python. BUT LLDB then +takes what you entered and wraps it into a Python FUNCTION (just like using the +"def" Python command). It automatically gives the function an obscure, unique, +hard-to-stumble-across function name, and gives it two parameters: frame and +bp_loc. When the breakpoint gets hit, LLDB wraps up the frame object where the +breakpoint was hit, and the breakpoint location object for the breakpoint that +was hit, and puts them into Python variables for you. It then calls the Python +function that was created for the breakpoint command, and passes in the frame +and breakpoint location objects. + +So, being practical, what does this mean for you when you write your Python +breakpoint commands? It means that there are two things you need to keep in +mind: 1. If you want to access any Python variables created outside your +script, you must declare such variables to be global. If you do not declare +them as global, then the Python function will treat them as local variables, +and you will get unexpected behavior. 2. All Python breakpoint command scripts +automatically have a frame and a bp_loc variable. The variables are pre-loaded +by LLDB with the correct context for the breakpoint. You do not have to use +these variables, but they are there if you want them. + +### The Decision Point Breakpoint Commands + +This is what the Python breakpoint command script would look like for the +decision to go right: + +```python3 +global path +if path[0] == 'R': + path = path[1:] + thread = frame.GetThread() + process = thread.GetProcess() + process.Continue() +else: + print "Here is the problem; going right, should go left!" +``` + +Just as a reminder, LLDB is going to take this script and wrap it up in a function, like this: + +```python3 +def some_unique_and_obscure_function_name (frame, bp_loc): + global path + if path[0] == 'R': + path = path[1:] + thread = frame.GetThread() + process = thread.GetProcess() + process.Continue() + else: + print "Here is the problem; going right, should go left!" +``` + +LLDB will call the function, passing in the correct frame and breakpoint +location whenever the breakpoint gets hit. There are several things to notice +about this function. The first one is that we are accessing and updating a +piece of state (the path variable), and actually conditioning our behavior +based upon this variable. Since the variable was defined outside of our script +(and therefore outside of the corresponding function) we need to tell Python +that we are accessing a global variable. That is what the first line of the +script does. Next we check where the path says we should go and compare it to +our decision (recall that we are at the breakpoint for the decision to go +right). If the path agrees with our decision, then we strip the first character +off of the path. + +Since the decision matched the path, we want to resume execution. To do this we +make use of the frame parameter that LLDB guarantees will be there for us. We +use LLDB API functions to get the current thread from the current frame, and +then to get the process from the thread. Once we have the process, we tell it +to resume execution (using the Continue() API function). + +If the decision to go right does not agree with the path, then we do not resume +execution. We allow the breakpoint to remain stopped (by doing nothing), and we +print an informational message telling the user we have found the problem, and +what the problem is. + +### Actually Using The Breakpoint Commands + +Now we will look at what happens when we actually use these breakpoint commands +on our program. Doing a source list -n find_word shows us the function +containing our two decision points. Looking at the code below, we see that we +want to set our breakpoints on lines 113 and 115: + +```c++ +(lldb) source list -n find_word +File: /Volumes/Data/HD2/carolinetice/Desktop/LLDB-Web-Examples/dictionary.c. +101 +102 int +103 find_word (tree_node *dictionary, char *word) +104 { +105 if (!word || !dictionary) +106 return 0; +107 +108 int compare_value = strcmp (word, dictionary->word); +109 +110 if (compare_value == 0) +111 return 1; +112 else if (compare_value < 0) +113 return find_word (dictionary->left, word); +114 else +115 return find_word (dictionary->right, word); +116 } +117 +``` + +So, we set our breakpoints, enter our breakpoint command scripts, and see what happens: + +```c++ +(lldb) breakpoint set -l 113 +Breakpoint created: 2: file ="dictionary.c", line = 113, locations = 1, resolved = 1 +(lldb) breakpoint set -l 115 +Breakpoint created: 3: file ="dictionary.c", line = 115, locations = 1, resolved = 1 +(lldb) breakpoint command add -s python 2 +``` +```python3 +Enter your Python command(s). Type 'DONE' to end. +> global path +> if (path[0] == 'L'): +> path = path[1:] +> thread = frame.GetThread() +> process = thread.GetProcess() +> process.Continue() +> else: +> print "Here is the problem. Going left, should go right!" +> DONE +``` +```c++ +(lldb) breakpoint command add -s python 3 +``` +```python3 +Enter your Python command(s). Type 'DONE' to end. +> global path +> if (path[0] == 'R'): +> path = path[1:] +> thread = frame.GetThread() +> process = thread.GetProcess() +> process.Continue() +> else: +> print "Here is the problem. Going right, should go left!" +> DONE +``` +```c++ +(lldb) continue +Process 696 resuming +Here is the problem. Going right, should go left! +Process 696 stopped +* thread #1: tid = 0x2d03, 0x000000010000189f dictionary`find_word + 127 at dictionary.c:115, stop reason = breakpoint 3.1 +frame #0: 0x000000010000189f dictionary`find_word + 127 at dictionary.c:115 + 112 else if (compare_value < 0) + 113 return find_word (dictionary->left, word); + 114 else +-> 115 return find_word (dictionary->right, word); + 116 } + 117 + 118 void +(lldb) +``` + +After setting our breakpoints, adding our breakpoint commands and continuing, +we run for a little bit and then hit one of our breakpoints, printing out the +error message from the breakpoint command. Apparently at this point in the +tree, our search algorithm decided to go right, but our path says the node we +want is to the left. Examining the word at the node where we stopped, and our +search word, we see: + +```c++ +(lldb) expr dictionary->word +(const char *) $1 = 0x0000000100100080 "dramatis" +(lldb) expr word +(char *) $2 = 0x00007fff5fbff108 "romeo" +``` + +So the word at our current node is "dramatis", and the word we are searching +for is "romeo". "romeo" comes after "dramatis" alphabetically, so it seems like +going right would be the correct decision. Let's ask Python what it thinks the +path from the current node to our word is: + +```c++ +(lldb) script print path +LLRRL +``` + +According to Python we need to go left-left-right-right-left from our current +node to find the word we are looking for. Let's double check our tree, and see +what word it has at that node: + +```c++ +(lldb) expr dictionary->left->left->right->right->left->word +(const char *) $4 = 0x0000000100100880 "Romeo" +``` + +So the word we are searching for is "romeo" and the word at our DFS location is +"Romeo". Aha! One is uppercase and the other is lowercase: We seem to have a +case conversion problem somewhere in our program (we do). + +This is the end of our example on how you might use Python scripting in LLDB to +help you find bugs in your program. + +### Sources + +The complete code for the Dictionary program (with case-conversion bug), the +DFS function and other Python script examples used for this example are +available below. + +- [tree_utils.py](https://github.com/llvm/llvm-project/blob/main/lldb/examples/scripting/tree_utils.py) - Example Python functions using LLDB's API, including DFS +- [dictionary.c](https://github.com/llvm/llvm-project/blob/main/lldb/examples/scripting/dictionary.c) - Sample dictionary program, with bug +- The text for "Romeo and Juliet" can be obtained from [the Gutenberg Project](https://www.gutenberg.org). + diff --git a/lldb/docs/use/tutorials/writing-custom-commands.md b/lldb/docs/use/tutorials/writing-custom-commands.md new file mode 100644 index 0000000000000..d53b7e473a505 --- /dev/null +++ b/lldb/docs/use/tutorials/writing-custom-commands.md @@ -0,0 +1,429 @@ +# Writing Custom Commands + +### Create a new command using a Python function + +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. + +To write a python function that implements a new LLDB command define the +function to take five arguments as follows: + +```python3 +def command_function(debugger, command, exe_ctx, result, internal_dict): + # Your code goes here +``` + +The meaning of the arguments is given in the table below. + +If you provide a Python docstring in your command function LLDB will use it +when providing "long help" for your command, as in: + +```python3 +def command_function(debugger, command, result, internal_dict): + """This command takes a lot of options and does many fancy things""" + # Your code goes here +``` + +though providing help can also be done programmatically (see below). + +Prior to lldb 3.5.2 (April 2015), LLDB Python command definitions didn't take the SBExecutionContext +argument. So you may still see commands where the command definition is: + +```python3 +def command_function(debugger, command, result, internal_dict): + # Your code goes here +``` + +Using this form is strongly discouraged because it can only operate on the "currently selected" +target, process, thread, frame. The command will behave as expected when run +directly on the command line. But if the command is used in a stop-hook, breakpoint +callback, etc. where the response to the callback determines whether we will select +this or that particular process/frame/thread, the global "currently selected" +entity is not necessarily the one the callback is meant to handle. In that case, this +command definition form can't do the right thing. + +| Argument | Type | Description | +|----------|------|-------------| +| `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 try using the `shlex` module's `shlex.split(command)` to properly extract the 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 *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 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). | +| `internal_dict` | `python dict object` | The dictionary for the current embedded script session which contains all variables and functions. | + +### Create a new command using a Python class + +Since lldb 3.7, Python commands can also be implemented by means of a class +which should implement the following interface: + +```python3 +class CommandObjectType: + def __init__(self, debugger, internal_dict): + # this call should initialize the command with respect to the command interpreter for the passed-in debugger + + def __call__(self, debugger, command, exe_ctx, result): + # this is the actual bulk of the command, akin to Python command functions + + def get_short_help(self): + # this call should return the short help text for this command[1] + + def get_long_help(self): + # this call should return the long help text for this command[1] + + def get_flags(self): + # this will be called when the command is added to the command interpreter, + # and should return a flag field made from or-ing together the appropriate + # elements of the lldb.CommandFlags enum to specify the requirements of this command. + # The CommandInterpreter will make sure all these requirements are met, and will + # return the standard lldb error if they are not.[1] + + def get_repeat_command(self, command): + # The auto-repeat command is what will get executed when the user types just + # a return at the next prompt after this command is run. Even if your command + # was run because it was specified as a repeat command, that invocation will still + # get asked for IT'S repeat command, so you can chain a series of repeats, for instance + # to implement a pager. + + # The command argument is the command that is about to be executed. + + # If this call returns None, then the ordinary repeat mechanism will be used + # If this call returns an empty string, then auto-repeat is disabled + # If this call returns any other string, that will be the repeat command [1] +``` + +[1] This method is optional. + +As a convenience, you can treat the result object as a Python file object, and +say + +```python3 +print("my command does lots of cool stuff", file=result) +``` + +`SBCommandReturnObject` and `SBStream` both support this file-like behavior by +providing `write()` and `flush()` calls at the Python layer. + +### Parsed Commands + +The commands that are added using this class definition are what lldb calls +"raw" commands. The command interpreter doesn't attempt to parse the command, +doesn't handle option values, neither generating help for them, or their +completion. Raw commands are useful when the arguments passed to the command +are unstructured, and having to protect them against lldb command parsing would +be onerous. For instance, "expr" is a raw command. + +You can also add scripted commands that implement the "parsed command", where +the options and their types are specified, as well as the argument and argument +types. These commands look and act like the majority of lldb commands, and you +can also add custom completions for the options and/or the arguments if you have +special needs. + +The easiest way to do this is to derive your new command from the lldb.ParsedCommand +class. That responds in the same way to the help & repeat command interfaces, and +provides some convenience methods, and most importantly an LLDBOptionValueParser, +accessed through lldb.ParsedCommand.get_parser(). The parser is used to set +your command definitions, and to retrieve option values in the `__call__` method. + +To set up the command definition, implement the ParsedCommand abstract method: + +```python3 +def setup_command_definition(self): +``` + +This is called when your command is added to lldb. In this method you add the +options and their types, the option help strings, etc. to the command using the API: + +```python3 +def add_option(self, short_option, long_option, help, default, + dest = None, required=False, groups = None, + value_type=lldb.eArgTypeNone, completion_type=None, + enum_values=None): + """ + short_option: one character, must be unique, not required + long_option: no spaces, must be unique, required + help: a usage string for this option, will print in the command help + default: the initial value for this option (if it has a value) + dest: the name of the property that gives you access to the value for + this value. Defaults to the long option if not provided. + required: if true, this option must be provided or the command will error out + groups: Which "option groups" does this option belong to. This can either be + a simple list (e.g. [1, 3, 4, 5]) or you can specify ranges by sublists: + so [1, [3,5]] is the same as [1, 3, 4, 5]. + value_type: one of the lldb.eArgType enum values. Some of the common arg + types also have default completers, which will be applied automatically. + completion_type: currently these are values form the lldb.CompletionType enum. If + you need custom completions, implement handle_option_argument_completion. + enum_values: An array of duples: ["element_name", "element_help"]. If provided, + only one of the enum elements is allowed. The value will be the + element_name for the chosen enum element as a string. + """ +``` + +Similarly, you can add argument types to the command: + +```python3 +def make_argument_element(self, arg_type, repeat = "optional", groups = None): + """ + arg_type: The argument type, one of the lldb.eArgType enum values. + repeat: Choose from the following options: + "plain" - one value + "optional" - zero or more values + "plus" - one or more values + groups: As with add_option. + """ +``` + +Then implement the body of the command by defining: + +```python3 +def __call__(self, debugger, args_array, exe_ctx, result): + """This is the command callback. The option values are + provided by the 'dest' properties on the parser. + + args_array: This is the list of arguments provided. + exe_ctx: Gives the SBExecutionContext on which the + command should operate. + result: Any results of the command should be + written into this SBCommandReturnObject. + """ +``` + +This differs from the "raw" command's `__call__` in that the arguments are already +parsed into the args_array, and the option values are set in the parser, and +can be accessed using their property name. The LLDBOptionValueParser class has +a couple of other handy methods: + +```python3 +def was_set(self, long_option_name): +``` + +returns `True` if the option was specified on the command line. + +```python +def dest_for_option(self, long_option_name): +""" +This will return the value of the dest variable you defined for opt_name. +Mostly useful for handle_completion where you get passed the long option. +""" +``` + +### Completion + +lldb will handle completing your option names, and all your enum values +automatically. If your option or argument types have associated built-in completers, +then lldb will also handle that completion for you. But if you have a need for +custom completions, either in your arguments or option values, you can handle +completion by hand as well. To handle completion of option value arguments, +your lldb.ParsedCommand subclass should implement: + +```python3 +def handle_option_argument_completion(self, long_option, cursor_pos): +""" +long_option: The long option name of the option whose value you are + asked to complete. +cursor_pos: The cursor position in the value for that option - which +you can get from the option parser. +""" +``` + +And to handle the completion of arguments: + +```python3 +def handle_argument_completion(self, args, arg_pos, cursor_pos): +""" +args: A list of the arguments to the command +arg_pos: An index into the args list of the argument with the cursor +cursor_pos: The cursor position in the arg specified by arg_pos +""" +``` + +When either of these API's is called, the command line will have been parsed up to +the word containing the cursor, and any option values set in that part of the command +string are available from the option value parser. That's useful for instance +if you have a --shared-library option that would constrain the completions for, +say, a symbol name option or argument. + +The return value specifies what the completion options are. You have four +choices: + +- `True`: the completion was handled with no completions. + +- `False`: the completion was not handled, forward it to the regular +completion machinery. + +- A dictionary with the key: "completion": there is one candidate, +whose value is the value of the "completion" key. Optionally you can pass a +"mode" key whose value is either "partial" or "complete". Return partial if +the "completion" string is a prefix for all the completed value. + +For instance, if the string you are completing is "Test" and the available completions are: +"Test1", "Test11" and "Test111", you should return the dictionary: + +```python3 +return {"completion": "Test1", "mode" : "partial"} +``` + +and then lldb will add the "1" at the cursor and advance it after the added string, +waiting for more completions. But if "Test1" is the only completion, return: + +```python3 +{"completion": "Test1", "mode": "complete"} +``` + +and lldb will add "1 " at the cursor, indicating the command string is complete. + +The default is "complete", you don't need to specify a "mode" in that case. + +- A dictionary with the key: "values" whose value is a list of candidate completion +strings. The command interpreter will present those strings as the available choices. +You can optionally include a "descriptions" key, whose value is a parallel array +of description strings, and the completion will show the description next to +each completion. + +### Loading Commands + +One other handy convenience when defining lldb command-line commands is the +command "command script import" 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: + +```python +def __lldb_init_module(debugger, internal_dict): + # Command Initialization code goes here +``` + +where debugger and internal_dict 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 `command script import`, it will not get run if anyone imports your +module from another module. + +Another way to load custom commands in lldb is to use the +`@lldb.command(command_name=None, doc=None)` decorator. + +```python3 +@lldb.command() +def goodstuff(debugger, command, ctx, result, internal_dict): + """command help string""" + # Command Implementation code goes here +``` + +### Examples + +Now we can create a module called ls.py in the file ~/ls.py that will implement +a function that can be used by LLDB's python command code: + +```python3 +#!/usr/bin/env python3 + +import lldb +import subprocess + +def ls(debugger, command, result, internal_dict): + output = subprocess.check_output(["/bin/ls"] + command.split(), text=True) + print(output, file=result) + +# And the initialization code to add your commands +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.') +``` + +Now we can load the module into LLDB and use it + +```shell +$ lldb +(lldb) command script import ~/ls.py +The "ls" python command has been installed and is ready for use. +(lldb) ls -l /tmp/ +total 365848 +-rw------- 1 someuser wheel 7331 Jan 19 15:37 crash.log +``` + +You can also make "container" commands to organize the commands you are adding to +lldb. Most of the lldb built-in commands structure themselves this way, and using +a tree structure has the benefit of leaving the one-word command space free for user +aliases. It can also make it easier to find commands if you are adding more than +a few of them. Here's a trivial example of adding two "utility" commands into a +"my-utilities" container: + +```python3 +#!/usr/bin/env python + +import lldb + +def first_utility(debugger, command, result, internal_dict): + print("I am the first utility") + +def second_utility(debugger, command, result, internal_dict): + print("I am the second utility") + +# And the initialization code to add your commands +def __lldb_init_module(debugger, internal_dict): + debugger.HandleCommand('command container add -h "A container for my utilities" my-utilities') + debugger.HandleCommand('command script add -f my_utilities.first_utility -h "My first utility" my-utilities first') + debugger.HandleCommand('command script add -f my_utilities.second_utility -h "My second utility" my-utilities second') + print('The "my-utilities" python command has been installed and its subcommands are ready for use.') +``` + +Then your new commands are available under the my-utilities node: + +``` +(lldb) help my-utilities +A container for my utilities + +Syntax: my-utilities + +The following subcommands are supported: + + first -- My first utility Expects 'raw' input (see 'help raw-input'.) + second -- My second utility Expects 'raw' input (see 'help raw-input'.) + +For more help on any particular subcommand, type 'help '. +(lldb) my-utilities first +I am the first utility +``` + +A more interesting [template](https://github.com/llvm/llvm-project/blob/main/lldb/examples/python/cmdtemplate.py) +has been created in the source repository that can help you to create lldb command quickly. + +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: + +```objc +#import +NSString* +ModifyString(NSString* src) +{ + return [src stringByAppendingString:@"foobar"]; +} + +int main() +{ + NSString* aString = @"Hello world"; + NSString* anotherString = @"Let's be friends"; + return 1; +} +``` + +you may want a `pofoo` X command, that equates po [ModifyString(X) +capitalizedString]. The following debugger interaction shows how to achieve +that goal: + +```python3 +(lldb) script +Python Interactive Interpreter. To exit, type 'quit()', 'exit()' or Ctrl-D. +>>> def pofoo_funct(debugger, command, result, internal_dict): +... cmd = "po [ModifyString(" + command + ") capitalizedString]" +... debugger.HandleCommand(cmd) +... +>>> ^D +(lldb) command script add pofoo -f pofoo_funct +(lldb) pofoo aString +$1 = 0x000000010010aa00 Hello Worldfoobar +(lldb) pofoo anotherString +$2 = 0x000000010010aba0 Let's Be Friendsfoobar +``` \ No newline at end of file