Blame - www/python-reference.html - fp2-dev/platform/external/lldb

Greg Clayton

2012-01-22 02:55:08 +0000

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<head>

Greg Clayton

2012-01-26 00:32:22 +0000

[diff] [blame]

6

<title>LLDB Python Reference</title>

Greg Clayton

f9ab5ea

2012-01-22 02:55:08 +0000

[diff] [blame]

</head>

<body>

Greg Clayton

2012-01-26 00:32:22 +0000

[diff] [blame]

11

LLDB Python Reference

Greg Clayton

f9ab5ea

2012-01-22 02:55:08 +0000

[diff] [blame]

</div>

17

18

19

<h1 class ="postheader">Introduction</h1>

20

21

Jim Ingham

062a836

2012-01-24 02:40:42 +0000

[diff] [blame]

22

The entire LLDB API is available as Python functions through a script bridging interface.

23

This means the LLDB API's can be used directly from python either interactively or to build python apps that

24

provide debugger features.

25

Additionally, Python can be used as a programmatic interface within the

26

lldb command interpreter (we refer to this for brevity as the embedded interpreter). Of course,

27

in this context it has full access to the LLDB API - with some additional conveniences we will

28

call out in the FAQ.

Greg Clayton

f9ab5ea

2012-01-22 02:55:08 +0000

[diff] [blame]

</div>

<h1 class ="postheader">Embedded Python Interpreter</h1>

35

36

Jim Ingham

062a836

2012-01-24 02:40:42 +0000

[diff] [blame]

37

The embedded python interpreter can be accessed in a variety of ways from within LLDB. The

38

easiest way is to use the lldb command script with no arguments at the lldb command prompt:

Greg Clayton

f9ab5ea

2012-01-22 02:55:08 +0000

[diff] [blame]

39

<code><pre><tt>(lldb) script

40

Python Interactive Interpreter. To exit, type 'quit()', 'exit()' or Ctrl-D.

>>> 2+3

5

>>> hex(12345)

'0x3039'

>>>

</tt></pre></code>

Jim Ingham

2012-01-24 02:40:42 +0000

[diff] [blame]

48

This drops you into the embedded python interpreter. When running under the script command,

49

lldb sets some convenience variables that give you quick access to the currently selected entities that characterize

50

the program and debugger state. In each case, if there is no currently selected entity of the appropriate

51

type, the variable's IsValid method will return false.

52

Note also, these variables hold the values

53

of the selected objects on entry to the embedded interpreter. They do not update as you use the LLDB

54

API's to change, for example, the currently selected stack frame or thread.

55

These are all global variables contained in the lldb python namespace :

Greg Clayton

f9ab5ea

2012-01-22 02:55:08 +0000

[diff] [blame]

56

57

<tr>

58

<td class="hed" width="20%">Variable</td>

59

60

<td class="hed" width="70%">Description</td>

</tr>

<tr>

lldb.debugger

</td>

lldb.SBDebugger

</td>

Jim Ingham

2012-01-24 02:40:42 +0000

[diff] [blame]

71

Contains the debugger object whose script command was invoked.

72

The lldb.SBDebugger object owns the command interpreter

73

and all the targets in your debug session. There will always be a

74

Debugger in the embedded interpreter.

Greg Clayton

f9ab5ea

2012-01-22 02:55:08 +0000

[diff] [blame]

</td>

</tr>

<tr>

lldb.target

</td>

lldb.SBTarget

</td>

Jim Ingham

2012-01-24 02:40:42 +0000

[diff] [blame]

85

Contains the currently selected target - for instance the one made with the

86

file or selected by the target select <target-index> command.

87

The lldb.SBTarget manages one running process, and all the executable

88

and debug files for the process.

Greg Clayton

f9ab5ea

2012-01-22 02:55:08 +0000

[diff] [blame]

</td>

</tr>

<tr>

lldb.process

</td>

lldb.SBProcess

</td>

Jim Ingham

2012-01-24 02:40:42 +0000

[diff] [blame]

99

Contains the process of the currently selected target.

100

The lldb.SBProcess object manages the threads and allows access to

101

memory for the process.

Greg Clayton

f9ab5ea

2012-01-22 02:55:08 +0000

[diff] [blame]

</td>

</tr>

<tr>

lldb.thread

</td>

lldb.SBThread

</td>

Jim Ingham

2012-01-24 02:40:42 +0000

[diff] [blame]

112

Contains the currently selected thread.

113

The lldb.SBThread object manages the stack frames in that thread.

Greg Clayton

f9ab5ea

2012-01-22 02:55:08 +0000

[diff] [blame]

114

A thread is always selected in the command interpreter when a target stops.

115

The thread select <thread-index> commmand can be used to change the

Jim Ingham

062a836

2012-01-24 02:40:42 +0000

[diff] [blame]

116

currently selected thread. So as long as you have a stopped process, there will be

117

some selected thread.

Greg Clayton

f9ab5ea

2012-01-22 02:55:08 +0000

[diff] [blame]

</td>

</tr>

<tr>

lldb.frame

</td>

lldb.SBFrame

</td>

Jim Ingham

2012-01-24 02:40:42 +0000

[diff] [blame]

128

Contains the currently selected stack frame.

129

The lldb.SBFrame object manage the stack locals and the register set for

130

that stack.

Greg Clayton

f9ab5ea

2012-01-22 02:55:08 +0000

[diff] [blame]

131

A stack frame is always selected in the command interpreter when a target stops.

132

The frame select <frame-index> commmand can be used to change the

Jim Ingham

062a836

2012-01-24 02:40:42 +0000

[diff] [blame]

133

currently selected frame. So as long as you have a stopped process, there will

134

be some selected frame.

Greg Clayton

f9ab5ea

2012-01-22 02:55:08 +0000

[diff] [blame]

</td>

</tr>

</table>

Jim Ingham

2012-01-24 02:40:42 +0000

[diff] [blame]

139

Once in the embedded interpreter, these objects can be used. To get started, note that almost

140

all of the lldb Python objects are able to briefly describe themselves when you pass them

141

to the Python print function:

Greg Clayton

f9ab5ea

2012-01-22 02:55:08 +0000

[diff] [blame]

142

<code><pre><tt>(lldb) script

143

Python Interactive Interpreter. To exit, type 'quit()', 'exit()' or Ctrl-D.

144

>>> print lldb.debugger

145

Debugger (instance: "debugger_1", id: 1)

146

>>> print lldb.target

147

a.out

148

>>> print lldb.process

149

SBProcess: pid = 59289, state = stopped, threads = 1, executable = a.out

150

>>> print lldb.thread

151

SBThread: tid = 0x1f03

152

>>> print lldb.frame

153

frame #0: 0x0000000100000bb6 a.out main + 54 at main.c:16

</tt></pre></code>

</div>

</div>

<h1 class ="postheader">Running a Python script when a breakpoint gets hit</h1>

162

163

Jim Ingham

062a836

2012-01-24 02:40:42 +0000

[diff] [blame]

164

One very powerful use of the lldb Python API is to have a python script run when a breakpoint gets hit. Adding python

Greg Clayton

f9ab5ea

2012-01-22 02:55:08 +0000

[diff] [blame]

165

scripts to breakpoints provides a way to create complex breakpoint

166

conditions and also allows for smart logging and data gathering.

Jim Ingham

062a836

2012-01-24 02:40:42 +0000

[diff] [blame]

167

When your process hits a breakpoint to which you have attached some python code, the code is executed as the

168

body of a function which takes two arguments:

Greg Clayton

f9ab5ea

2012-01-22 02:55:08 +0000

[diff] [blame]

169

Jim Ingham

062a836

2012-01-24 02:40:42 +0000

[diff] [blame]

170

<code><pre><tt>def breakpoint_function_wrapper(frame, bp_loc):

Greg Clayton

f9ab5ea

2012-01-22 02:55:08 +0000

[diff] [blame]

171

# Your code goes here

</tt></pre></code>

<tr>

<td class="hed" width="10%">Argument</td>

176

177

<td class="hed" width="80%">Description</td>

</tr>

<tr>

frame

</td>

lldb.SBFrame

</td>

The current stack frame where the breakpoint got hit.

Jim Ingham

062a836

2012-01-24 02:40:42 +0000

[diff] [blame]

189

The object will always be valid.

Greg Clayton

f9ab5ea

2012-01-22 02:55:08 +0000

[diff] [blame]

190

This frame argument might not match the currently selected stack frame found in the lldb module global variable lldb.frame.

</td>

</tr>

<tr>

bp_loc

</td>

lldb.SBBreakpointLocation

199

</td>

200

201

The breakpoint location that just got hit. Breakpoints are represented by lldb.SBBreakpoint

202

objects. These breakpoint objects can have one or more locations. These locations

203

are represented by lldb.SBBreakpointLocation objects.

204

</td>

205

</tr>

206

</table>

Jim Ingham

062a836

2012-01-24 02:40:42 +0000

[diff] [blame]

207

An example will show how simple it is to write some python code and attach it to a breakpoint.

208

The following example will allow you to track the order in which the functions in a given shared library

209

are first executed during one run of your program. This is a simple method to gather an order file which

210

can be used to optimize function placement within a binary for execution locality.

211

We do this by setting a regular expression breakpoint

212

that will match every function in the shared library. The regular expression '.' will match

213

any string that has at least one character in it, so we will use that.

Greg Clayton

f9ab5ea

2012-01-22 02:55:08 +0000

[diff] [blame]

214

This will result in one lldb.SBBreakpoint object

Jim Ingham

062a836

2012-01-24 02:40:42 +0000

[diff] [blame]

215

that contains an lldb.SBBreakpointLocation object for each function. As the breakpoint gets

216

hit, we use a counter to track the order in which the function at this particular breakpoint location got hit.

217

Since our code is passed the location that was hit, we can get the name of the function from the location,

218

disable the location so we won't count this function again; then log some info and continue the process.

219

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:

Greg Clayton

2012-01-22 02:55:08 +0000

[diff] [blame]

223

<code><pre><tt>(lldb) breakpoint set --func-regex=. --shlib=libfoo.dylib

224

Breakpoint created: 1: regex = '.', module = libfoo.dylib, locations = 223

Jim Ingham

062a836

2012-01-24 02:40:42 +0000

[diff] [blame]

225

(lldb) script counter = 0

Greg Clayton

f9ab5ea

2012-01-22 02:55:08 +0000

[diff] [blame]

226

(lldb) breakpoint command add --script-type python 1

227

Enter your Python command(s). Type 'DONE' to end.

Jim Ingham

062a836

2012-01-24 02:40:42 +0000

[diff] [blame]

228

> # Increment our counter. Since we are in a function, this must be a global python variable

229

> global counter

230

> counter += 1

Greg Clayton

f9ab5ea

2012-01-22 02:55:08 +0000

[diff] [blame]

231

> # Get the name of the function

232

> name = frame.GetFunctionName()

233

> # Print the order and the function name

Jim Ingham

062a836

2012-01-24 02:40:42 +0000

[diff] [blame]

234

> print '[%i] %s' % (counter, name)

Greg Clayton

f9ab5ea

2012-01-22 02:55:08 +0000

[diff] [blame]

235

> # Disable the current breakpoint location so it doesn't get hit again

236

> bp_loc.SetEnabled(False)

237

> # How continue the process

238

> frame.GetThread().GetProcess().Continue()

239

> DONE

240

</tt></pre></code>

241

The breakpoint command add command above attaches a python script to breakpoint 1.

242

To remove the breakpoint command:

243

<code>(lldb) breakpoint command delete 1</code>

</div>

</div>

<h1 class ="postheader">Create a new LLDB command using a python function</h1>

248

249

Jim Ingham

062a836

2012-01-24 02:40:42 +0000

[diff] [blame]

250

Python functions can be used to create new LLDB command interpreter commands, which will work

251

like all the natively defined lldb commands. This provides a very flexible and easy way to extend LLDB to meet your

Greg Clayton

f9ab5ea

2012-01-22 02:55:08 +0000

[diff] [blame]

252

debugging requirements.

Jim Ingham

062a836

2012-01-24 02:40:42 +0000

[diff] [blame]

253

To write a python function that implements a new LDB command define the function to take four arguments as follows:

Greg Clayton

f9ab5ea

2012-01-22 02:55:08 +0000

[diff] [blame]

254

255

<code><pre><tt>def command_function(debugger, command, result, dict):

256

# Your code goes here

257

</tt></pre></code>

Enrico Granata

c0791aa

2012-05-02 21:00:41 +0000

[diff] [blame^]

258

259

Optionally, you can also provide a Python docstring, and LLDB will use it when providing help for your command, as in:

260

<code><pre><tt>def command_function(debugger, command, result, dict):

261

"""This command takes a lot of options and does many fancy things"""

262

# Your code goes here

263

</tt></pre></code>

264

Greg Clayton

f9ab5ea

2012-01-22 02:55:08 +0000

[diff] [blame]

265

266

<tr>

267

<td class="hed" width="10%">Argument</td>

268

269

<td class="hed" width="80%">Description</td>

</tr>

<tr>

debugger

</td>

lldb.SBDebugger

</td>

The current debugger object.

</td>

</tr>

<tr>

command

</td>

python string

</td>

A python string containing all arguments for your command. If you need to chop up the arguments

292

try using the shlex module's <code>shlex.split(command)</code> to properly extract the

arguments.

</td>

</tr>

<tr>

result

</td>

lldb.SBCommandReturnObject

302

</td>

303

304

A return object where you can indicate the success or failure of your command. You can also

305

provide information for the command result by printing data into it. You can also just print

Jim Ingham

062a836

2012-01-24 02:40:42 +0000

[diff] [blame]

306

data as you normally would in a python script and the output will show up; this is useful for

307

logging, but the real output for your command should go in the result object.

Greg Clayton

f9ab5ea

2012-01-22 02:55:08 +0000

[diff] [blame]

</td>

</tr>

<tr>

dict

</td>

python dict object

</td>

The dictionary for the current embedded script session which contains all variables

and functions.

</td>

</tr>

</table>

Jim Ingham

062a836

2012-01-24 02:40:42 +0000

[diff] [blame]

323

One other handy convenience when defining lldb command-line commands is the command

324

command script import which will import a module specified by file path - so you

325

don't have to change your PYTHONPATH for temporary scripts. It also has another convenience

326

that if your new script module has a function of the form:

327

Enrico Granata

8e1d33f

2012-02-20 22:05:47 +0000

[diff] [blame]

328

<code><pre><tt>def __lldb_init_module(debugger, dict):

Greg Clayton

261c974

2012-01-26 05:36:07 +0000

[diff] [blame]

329

# Command Initialization code goes here

330

</tt></pre></code>

Jim Ingham

062a836

2012-01-24 02:40:42 +0000

[diff] [blame]

331

332

where debugger and dict are as above, that function will get run when the module is loaded

Greg Clayton

261c974

2012-01-26 05:36:07 +0000

[diff] [blame]

333

allowing you to add whatever commands you want into the current debugger. Note that

334

this function will only be run when using the LLDB comand command script import,

335

it will not get run if anyone imports your module from another module.

336

If you want to always run code when your module is loaded from LLDB

337

or when loaded via an import statement in python code

338

you can test the lldb.debugger object, since you imported the

339

<lldb> module at the top of the python ls.py module. This test

340

must be in code that isn't contained inside of any function or class,

341

just like the standard test for __main__ like all python modules

342

usally do. Sample code would look like:

343

344

<code><pre><tt>if __name__ == '__main__':

345

# Create a new debugger instance in your module if your module

346

# can be run from the command line. When we run a script from

347

# the command line, we won't have any debugger object in

348

# lldb.debugger, so we can just create it if it will be needed

349

lldb.debugger = lldb.SBDebugger.Create()

350

elif lldb.debugger:

351

# Module is being run inside the LLDB interpreter

352

lldb.debugger.HandleCommand('command script add -f ls.ls ls')

353

print 'The "ls" python command has been installed and is ready for use.'

354

</tt></pre></code>

355

Now we can create a module called ls.py in the file ~/ls.py that will implement a function that

Jim Ingham

062a836

2012-01-24 02:40:42 +0000

[diff] [blame]

356

can be used by LLDB's python command code:

Greg Clayton

f9ab5ea

2012-01-22 02:55:08 +0000

[diff] [blame]

357

358

<code><pre><tt>#!/usr/bin/python

import lldb

import commands

import optparse

import shlex

def ls(debugger, command, result, dict):

Jim Ingham

062a836

2012-01-24 02:40:42 +0000

[diff] [blame]

366

result.PutCString(commands.getoutput('/bin/ls %s' % command))

Greg Clayton

f9ab5ea

2012-01-22 02:55:08 +0000

[diff] [blame]

367

Jim Ingham

062a836

2012-01-24 02:40:42 +0000

[diff] [blame]

368

# And the initialization code to add your commands

Enrico Granata

8e1d33f

2012-02-20 22:05:47 +0000

[diff] [blame]

369

def __lldb_init_module(debugger, dict):

Jim Ingham

062a836

2012-01-24 02:40:42 +0000

[diff] [blame]

370

debugger.HandleCommand('command script add -f ls.ls ls')

Greg Clayton

f9ab5ea

2012-01-22 02:55:08 +0000

[diff] [blame]

371

print 'The "ls" python command has been installed and is ready for use.'

372

</tt></pre></code>

373

Now we can load the module into LLDB and use it

374

<code><pre><tt>% lldb

Greg Clayton

261c974

2012-01-26 05:36:07 +0000

[diff] [blame]

375

(lldb) command script import ~/ls.py

Greg Clayton

f9ab5ea

2012-01-22 02:55:08 +0000

[diff] [blame]

376

The "ls" python command has been installed and is ready for use.

377

(lldb) ls -l /tmp/

378

total 365848

379

-rw-r--r--@ 1 someuser wheel 6148 Jan 19 17:27 .DS_Store

380

-rw------- 1 someuser wheel 7331 Jan 19 15:37 crash.log

381

</tt></pre></code>

382

A template has been created in the source repository that can help you to create

383

lldb command quickly:

384

<a href="http://llvm.org/svn/llvm-project/lldb/trunk/examples/python/cmdtemplate.py">cmdtemplate.py</a>

385

</div>

386

387

<h1 class ="postheader">Using the lldb.py module in python</h1>

388

389

390

LLDB has all of its core code build into a shared library which gets

391

used by the lldb command line application. On Mac OS X this

392

shared library is a framework: LLDB.framework and on other

Jim Ingham

062a836

2012-01-24 02:40:42 +0000

[diff] [blame]

393

unix variants the program is a shared library: lldb.so. LLDB also

394

provides an lldb.py module that contains the bindings from LLDB into Python.

395

To use the

396

LLDB.framework to create your own stand-alone python programs, you will

Greg Clayton

f9ab5ea

2012-01-22 02:55:08 +0000

[diff] [blame]

397

need to tell python where to look in order to find this module. This

Jim Ingham

062a836

2012-01-24 02:40:42 +0000

[diff] [blame]

398

is done by setting the PYTHONPATH environment variable, adding

399

a path to the directory that contains the lldb.py python module. On

400

Mac OS X, this is contained inside the LLDB.framework, so you would do:

Greg Clayton

f9ab5ea

2012-01-22 02:55:08 +0000

[diff] [blame]

401

402

For csh and tcsh:

403

<code>% setenv PYTHONPATH /Developer/Library/PrivateFrameworks/LLDB.framework/Resources/Python</code>

404

For sh and bash:

405

<code>% export PYTHONPATH=/Developer/Library/PrivateFrameworks/LLDB.framework/Resources/Python</code>

406

Jim Ingham

062a836

2012-01-24 02:40:42 +0000

[diff] [blame]

407

Alternately, you can append the LLDB Python directory to the sys.path list directly in

408

your Python code before importing the lldb module.

409

Greg Clayton

f9ab5ea

2012-01-22 02:55:08 +0000

[diff] [blame]

410

411

Now your python scripts are ready to import the lldb module. Below is a

412

python script that will launch a program from the current working directory

413

called "a.out", set a breakpoint at "main", and then run and hit the breakpoint,

414

and print the process, thread and frame objects if the process stopped:

415

416

417

<code><pre><tt>#!/usr/bin/python

import lldb

# Set the path to the executable to debug

422

exe = "./a.out"

423

424

# Create a new debugger instance

425

debugger = lldb.SBDebugger.Create()

426

427

# When we step or continue, don't return from the function until the process

Jim Ingham

062a836

2012-01-24 02:40:42 +0000

[diff] [blame]

428

# stops. Otherwise we would have to handle the process events ourselves which, while doable is

429

#a little tricky. We do this by setting the async mode to false.

Greg Clayton

f9ab5ea

2012-01-22 02:55:08 +0000

[diff] [blame]

430

debugger.SetAsync (False)

431

432

# Create a target from a file and arch

433

print "Creating a target for '%s'" % exe

434

435

target = debugger.CreateTargetWithFileAndArch (exe, lldb.LLDB_ARCH_DEFAULT)

436

437

if target:

438

# If the target is valid set a breakpoint at main

439

main_bp = target.BreakpointCreateByName ("main", target.GetExecutable().GetFilename());

print main_bp

# Launch the process. Since we specified synchronous mode, we won't return

444

# from this function until we hit the breakpoint at main

445

process = target.LaunchSimple (None, None, os.getcwd())

446

447

# Make sure the launch went ok

448

if process:

449

# Print some simple process info

450

state = process.GetState ()

451

print process

452

if state == lldb.eStateStopped:

453

# Get the first thread

454

thread = process.GetThreadAtIndex (0)

455

if thread:

456

# Print some simple thread info

457

print thread

458

# Get the first frame

459

frame = thread.GetFrameAtIndex (0)

460

if frame:

461

# Print some simple frame info

462

print frame

463

function = frame.GetFunction()

464

# See if we have debug info (a function)

465

if function:

466

# We do have a function, print some info for the function

467

print function

468

# Now get all instructions for this function and print them

469

insts = function.GetInstructions(target)

470

disassemble_instructions (insts)

471

else:

472

# See if we have a symbol in the symbol table for where we stopped

473

symbol = frame.GetSymbol();

474

if symbol:

475

# We do have a symbol, print some info for the symbol

print symbol

</tt></pre></code>

</div>

</div>

</div>

</div>

</body>

</html>