Gitiles
Code Review Sign In
gerrit-public.fairphone.software / fp2-dev / platform / external / lldb / f9ab5ea6d278b75462464cc0e45b8a11e9da1bf9 / . / www / python-faq.html
blob: 6b319804d9f85cb2dea390f8f1827feb80a02041 [file] [log] [blame]
Greg Claytonf9ab5ea2012-01-22 02:55:08 +0000[diff] [blame^]1<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
2<html xmlns="http://www.w3.org/1999/xhtml">
3<head>
4<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
5<link href="style.css" rel="stylesheet" type="text/css" />
6<title>LLDB Python FAQ</title>
7</head>
8
9<body>
10 <div class="www_title">
11 LLDB Python FAQ
12 </div>
13
14<div id="container">
15 <div id="content">
16 <!--#include virtual="sidebar.incl"-->
17 <div id="middle">
18 <div class="post">
19 <h1 class ="postheader">Introduction</h1>
20 <div class="postcontent">
21
22 <p>The entire LLDB API is available through a script bridging interface in Python. Python can be used
23 as an embedded script interpreter, or it can be used directly from python at the command line.</p>
24
25 </div>
26 <div class="postfooter"></div>
27
28 <div class="post">
29 <h1 class ="postheader">Embedded Python Interpreter</h1>
30 <div class="postcontent">
31
32 <p>The embedded python interpreter can be accessed in a variety of way from within LLDB. The
33 easiest way is to type <b>script</b> command prompt:</p>
34<code><pre><tt>(lldb) <strong>script</strong>
35Python Interactive Interpreter. To exit, type 'quit()', 'exit()' or Ctrl-D.
36>>> 2+3
375
38>>> hex(12345)
39'0x3039'
40>>>
41</tt></pre></code>
42
43 <p>This drops you into the embedded python interpreter. There are a some convenience variables
44 that are set for you in the <b>lldb</b> python module that refer to the current program
45 and debugger state:</p>
46 <table class="stats" width="620" cellspacing="0">
47 <tr>
48 <td class="hed" width="20%">Variable</td>
49 <td class="hed" width="10%">Type</td>
50 <td class="hed" width="70%">Description</td>
51 </tr>
52
53 <tr>
54 <td class="content">
55 <b>lldb.debugger</b>
56 </td>
57 <td class="content">
58 <b>lldb.SBDebugger</b>
59 </td>
60 <td class="content">
61 A module global variable containing the current debugger object.
62 The type is a <b>lldb.SBDebugger</b> object and it contains a reference to the debegger
63 object that owns the command interpreter and all targets in your debug session.
64 </td>
65 </tr>
66 <tr>
67 <td class="content">
68 <b>lldb.target</b>
69 </td>
70 <td class="content">
71 <b>lldb.SBTarget</b>
72 </td>
73 <td class="content">
74 A module global variable containing the currently selected target.
75 The type is a <b>lldb.SBTarget</b> object and the object will only be valid if there is a current target.
76 The <b>target select &lt;target-index&gt;</b> commmand can be used to change the
77 currently selected target.
78 </td>
79 </tr>
80 <tr>
81 <td class="content">
82 <b>lldb.process</b>
83 </td>
84 <td class="content">
85 <b>lldb.SBProcess</b>
86 </td>
87 <td class="content">
88 A module global variable containing the current process.
89 The type is a <b>lldb.SBProcess</b> object and the object will only be
90 valid if there is a current target and that target has a process.
91 </td>
92 </tr>
93 <tr>
94 <td class="content">
95 <b>lldb.thread</b>
96 </td>
97 <td class="content">
98 <b>lldb.SBThread</b>
99 </td>
100 <td class="content">
101 A module global variable containing the current thread.
102 The type is a <b>lldb.SBThread</b> object and the object will only be valid if
103 the process has threads, and if the process has a thread selected.
104 A thread is always selected in the command interpreter when a target stops.
105 The <b>thread select &lt;thread-index&gt;</b> commmand can be used to change the
106 currently selected thread.
107 </td>
108 </tr>
109 <tr>
110 <td class="content">
111 <b>lldb.frame</b>
112 </td>
113 <td class="content">
114 <b>lldb.SBFrame</b>
115 </td>
116 <td class="content">
117 A module global variable containing the current stack frame.
118 The type is a <b>lldb.SBFrame</b> object and the object will only be valid if
119 the thread is stopped and has a frame selected.
120 A stack frame is always selected in the command interpreter when a target stops.
121 The <b>frame select &lt;frame-index&gt;</b> commmand can be used to change the
122 currently selected thread.
123 </td>
124 </tr>
125 </table>
126
127 <p>One in the embedded interpreter, these objects can be used. Almost all of the <b>lldb.SB</b> objects
128 are able to briefly describe themselves by printing them:
129<code><pre><tt>(lldb) <b>script</b>
130Python Interactive Interpreter. To exit, type 'quit()', 'exit()' or Ctrl-D.
131>>> <strong>print lldb.debugger</strong>
132Debugger (instance: "debugger_1", id: 1)
133>>> <strong>print lldb.target</strong>
134a.out
135>>> <strong>print lldb.process</strong>
136SBProcess: pid = 59289, state = stopped, threads = 1, executable = a.out
137>>> <strong>print lldb.thread</strong>
138SBThread: tid = 0x1f03
139>>> <strong>print lldb.frame</strong>
140frame #0: 0x0000000100000bb6 a.out main + 54 at main.c:16
141</tt></pre></code>
142
143 </div>
144 <div class="postfooter"></div>
145
146 </div>
147 <div class="post">
148 <h1 class ="postheader">Running a Python script when a breakpoint gets hit</h1>
149 <div class="postcontent">
150
151 <p>A python script can be run when a breakpoint gets hit. Adding python
152 scripts to breakpoints provides a way to create complex breakpoint
153 conditions and also allows for smart logging and data gathering.</p>
154 <p>A python function gets run when a breakpoint, and this function has
155 two arguments:</p>
156 <p>
157<code><pre><tt>def breakpoint_function(<b>frame</b>, <b>bp_loc</b>):
158 <font color=green># Your code goes here</font>
159</tt></pre></code>
160 <p><table class="stats" width="620" cellspacing="0">
161 <tr>
162 <td class="hed" width="10%">Argument</td>
163 <td class="hed" width="10%">Type</td>
164 <td class="hed" width="80%">Description</td>
165 </tr>
166
167 <tr>
168 <td class="content">
169 <b>frame</b>
170 </td>
171 <td class="content">
172 <b>lldb.SBFrame</b>
173 </td>
174 <td class="content">
175 The current stack frame where the breakpoint got hit.
176 The type is a <b>lldb.SBFrame</b> object and the object will always be valid.
177 This <b>frame</b> argument might <i>not</i> match the currently selected stack frame found in the <b>lldb</b> module global variable <b>lldb.frame</b>.
178 </td>
179 </tr>
180 <tr>
181 <td class="content">
182 <b>bp_loc</b>
183 </td>
184 <td class="content">
185 <b>lldb.SBBreakpointLocation</b>
186 </td>
187 <td class="content">
188 The breakpoint location that just got hit. Breakpoints are represented by <b>lldb.SBBreakpoint</b>
189 objects. These breakpoint objects can have one or more locations. These locations
190 are represented by <b>lldb.SBBreakpointLocation</b> objects.
191 </td>
192 </tr>
193 </table>
194 <p>Now we are ready to create a python function and attach it to a breakpoint. The following example will wllow you to
195 create an order file for a shared library. We do this by setting a regular exprsssion breakpoint
196 at every function in a shared library. The regular expression we will use is '.' which will match
197 any function that has at least any character in the function name.
198 This will result in one <b>lldb.SBBreakpoint</b> object
199 that contains many <b>lldb.SBBreakpointLocation</b> objects. As the breakpoint continually gets
200 hit, we use the hit count on the main <b>lldb.SBBreakpoint</b> to tell us the breakpoint hit
201 number, and we disable the location (not the main breakpoint) on the <b>lldb.SBBreakpointLocation</b>
202 object. Then we log some info and continue the process.
203<code><pre><tt>(lldb) <strong>breakpoint set --func-regex=. --shlib=libfoo.dylib</strong>
204Breakpoint created: 1: regex = '.', module = libfoo.dylib, locations = 223
205(lldb) <strong>breakpoint command add --script-type python 1</strong>
206Enter your Python command(s). Type 'DONE' to end.
207> <font color=green># Get the hit count of the main breakpoint</font>
208> <strong>hit_count = bp_loc.GetBreakpoint().GetHitCount()</strong>
209> <font color=green># Get the name of the function</font>
210> <strong>name = frame.GetFunctionName()</strong>
211> <font color=green># Print the order and the function name</font>
212> <strong>print '[%i] %s' % (hit_count, name)</strong>
213> <font color=green># Disable the current breakpoint location so it doesn't get hit again</font>
214> <strong>bp_loc.SetEnabled(False)</strong>
215> <font color=green># How continue the process</font>
216> <strong>frame.GetThread().GetProcess().Continue()</strong>
217> <strong>DONE</strong>
218</tt></pre></code>
219 <p>The <b>breakpoint command add</b> command above attaches a python script to breakpoint 1.
220 To remove the breakpoint command:
221 <p><code>(lldb) <strong>breakpoint command delete 1</strong></code>
222 </div>
223 </div>
224 <div class="post">
225 <h1 class ="postheader">Create a new LLDB command using a python function</h1>
226 <div class="postcontent">
227
228 <p>Python functions can be used to create new commands that the LLDB command interpreter
229 doesn't have. This provides a very flexible and easy way to extend LLDB to meet your
230 debugging requirements. </p>
231 <p>A python function that implements a new LDB command has four arguments:</p>
232 <p>
233 def Symbolicate(debugger, command, result, dict):
234 SymbolicateCrashLog (command.split())
235
236 <code><pre><tt>def command_function(<b>debugger</b>, <b>command</b>, <b>result</b>, <b>dict</b>):
237 <font color=green># Your code goes here</font>
238 </tt></pre></code>
239 <p><table class="stats" width="620" cellspacing="0">
240 <tr>
241 <td class="hed" width="10%">Argument</td>
242 <td class="hed" width="10%">Type</td>
243 <td class="hed" width="80%">Description</td>
244 </tr>
245
246 <tr>
247 <td class="content">
248 <b>debugger</b>
249 </td>
250 <td class="content">
251 <b>lldb.SBDebugger</b>
252 </td>
253 <td class="content">
254 The current debugger object.
255 </td>
256 </tr>
257 <tr>
258 <td class="content">
259 <b>command</b>
260 </td>
261 <td class="content">
262 <b>python string</b>
263 </td>
264 <td class="content">
265 A python string containing all arguments for your command. If you need to chop up the arguments
266 try using the <b>shlex</b> module's <code>shlex.split(command)</code> to properly extract the
267 arguments.
268 </td>
269 </tr>
270 <tr>
271 <td class="content">
272 <b>result</b>
273 </td>
274 <td class="content">
275 <b>lldb.SBCommandReturnObject</b>
276 </td>
277 <td class="content">
278 A return object where you can indicate the success or failure of your command. You can also
279 provide information for the command result by printing data into it. You can also just print
280 data as you normally would in a python script and the outout will show up.
281 </td>
282 </tr>
283 <tr>
284 <td class="content">
285 <b>dict</b>
286 </td>
287 <td class="content">
288 <b>python dict object</b>
289 </td>
290 <td class="content">
291 The dictionary for the current embedded script session which contains all variables
292 and functions.
293 </td>
294 </tr>
295 </table>
296 <p>Now we can create a module called <b>ls.py</b> that will implement a function that
297 can be used by LLDB's python command code:</p>
298
299<code><pre><tt><font color=green>#!/usr/bin/python</font>
300
301import lldb
302import commands
303import optparse
304import shlex
305
306def ls(debugger, command, result, dict):
307 print commands.getoutput('/bin/ls %s' % command)
308
309<font color=green># Any code that isn't in a function in python gets run when the module is loaded</font>
310if lldb.debugger:
311 <font color=green># This script is being run from LLDB in the emabedded command interpreter
312 # lets register the 'ls' command with the command interpreter automatically!</font>
313 lldb.debugger.HandleCommand('command script add -f ls.ls ls')
314 print 'The "ls" python command has been installed and is ready for use.'
315</tt></pre></code>
316 <p>Now we can load the module into LLDB and use it</p>
317<code><pre><tt>% lldb
318(lldb) <strong>script import ls</strong>
319The "ls" python command has been installed and is ready for use.
320(lldb) <strong>ls -l /tmp/</strong>
321total 365848
322-rw-r--r--@ 1 someuser wheel 6148 Jan 19 17:27 .DS_Store
323-rw------- 1 someuser wheel 7331 Jan 19 15:37 crash.log
324</tt></pre></code>
325 <p>A template has been created in the source repository that can help you to create
326 lldb command quickly:</p>
327 <a href="http://llvm.org/svn/llvm-project/lldb/trunk/examples/python/cmdtemplate.py">cmdtemplate.py</a>
328 </div>
329 <div class="post">
330 <h1 class ="postheader">Using the lldb.py module in python</h1>
331 <div class="postcontent">
332
333 <p>LLDB has all of its core code build into a shared library which gets
334 used by the <b>lldb</b> command line application. On Mac OS X this
335 shared library is a framework: <b>LLDB.framework</b> and on other
336 unix variants the program is a shared library <b>lldb.so</b>. The
337 <b>LLDB.framework</b> contains the <b>lldb.py</b> module and you will
338 need to tell python where to look in order to find this module. This
339 is done by setting the <b>PYTHONPATH</b> environment variable contain
340 a path to the directory that contains the <b>lldb.py</b> python module:
341
342 <p>For csh and tcsh:</p>
343 <p><code>% <b>setenv PYTHONPATH /Developer/Library/PrivateFrameworks/LLDB.framework/Resources/Python</b></code></p>
344 <p>For sh and bash:
345 <p><code>% <b>export PYTHONPATH=/Developer/Library/PrivateFrameworks/LLDB.framework/Resources/Python</b></code></p>
346
347 <p>
348 Now your python scripts are ready to import the lldb module. Below is a
349 python script that will launch a program from the current working directory
350 called "a.out", set a breakpoint at "main", and then run and hit the breakpoint,
351 and print the process, thread and frame objects if the process stopped:
352
353 </p>
354<code><pre><tt><font color=green>#!/usr/bin/python</font>
355
356import lldb
357
358<font color=green># Set the path to the executable to debug</font>
359exe = "./a.out"
360
361<font color=green># Create a new debugger instance</font>
362debugger = lldb.SBDebugger.Create()
363
364<font color=green># When we step or continue, don't return from the function until the process
365# stops. We do this by setting the async mode to false.</font>
366debugger.SetAsync (False)
367
368<font color=green># Create a target from a file and arch</font>
369print "Creating a target for '%s'" % exe
370
371target = debugger.CreateTargetWithFileAndArch (exe, lldb.LLDB_ARCH_DEFAULT)
372
373if target:
374 <font color=green># If the target is valid set a breakpoint at main</font>
375 main_bp = target.BreakpointCreateByName ("main", target.GetExecutable().GetFilename());
376
377 print main_bp
378
379 <font color=green># Launch the process. Since we specified synchronous mode, we won't return
380 # from this function until we hit the breakpoint at main</font>
381 process = target.LaunchSimple (None, None, os.getcwd())
382
383 <font color=green># Make sure the launch went ok</font>
384 if process:
385 <font color=green># Print some simple process info</font>
386 state = process.GetState ()
387 print process
388 if state == lldb.eStateStopped:
389 <font color=green># Get the first thread</font>
390 thread = process.GetThreadAtIndex (0)
391 if thread:
392 <font color=green># Print some simple thread info</font>
393 print thread
394 <font color=green># Get the first frame</font>
395 frame = thread.GetFrameAtIndex (0)
396 if frame:
397 <font color=green># Print some simple frame info</font>
398 print frame
399 function = frame.GetFunction()
400 <font color=green># See if we have debug info (a function)</font>
401 if function:
402 <font color=green># We do have a function, print some info for the function</font>
403 print function
404 <font color=green># Now get all instructions for this function and print them</font>
405 insts = function.GetInstructions(target)
406 disassemble_instructions (insts)
407 else:
408 <font color=green># See if we have a symbol in the symbol table for where we stopped</font>
409 symbol = frame.GetSymbol();
410 if symbol:
411 <font color=green># We do have a symbol, print some info for the symbol</font>
412 print symbol
413</tt></pre></code>
414 </div>
415 <div class="postfooter"></div>
416
417 </div>
418 </div>
419</div>
420</body>
421</html>