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

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

[diff] [blame]

85

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

86

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

Greg Clayton

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

[diff] [blame]

87

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

88

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]

96

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

97

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

98

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

Jim Ingham

8e013df

2012-12-12 20:23:52 +0000

[diff] [blame]

99

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

Jim Ingham

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

[diff] [blame]

100

Note also, these variables hold the values

101

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

Jim Ingham

8e013df

2012-12-12 20:23:52 +0000

[diff] [blame]

102

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

103

As a corollary to this, because they get reset every time the script interpreter is entered, you should not

104

use these variables in general purpose python code that you write using the lldb module. After all, lldb can

105

run in a multithreaded environment, and another thread might call the "script" command, changing the value out

106

from under you.

Jim Ingham

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

[diff] [blame]

107

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

Greg Clayton

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

[diff] [blame]

108

109

<tr>

110

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

111

112

<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]

123

Contains the debugger object whose script command was invoked.

124

The lldb.SBDebugger object owns the command interpreter

125

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

126

Debugger in the embedded interpreter.

Greg Clayton

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]

137

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

138

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

139

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

140

and debug files for the process.

Greg Clayton

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]

151

Contains the process of the currently selected target.

152

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

153

memory for the process.

Greg Clayton

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]

164

Contains the currently selected thread.

165

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

Greg Clayton

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

[diff] [blame]

166

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

167

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

Jim Ingham

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

[diff] [blame]

168

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

169

some selected thread.

Greg Clayton

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]

180

Contains the currently selected stack frame.

181

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

182

that stack.

Greg Clayton

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

[diff] [blame]

183

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

184

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

Jim Ingham

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

[diff] [blame]

185

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

186

be some selected frame.

Greg Clayton

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

[diff] [blame]

</td>

</tr>

</table>

Jim Ingham

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

[diff] [blame]

191

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

192

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

193

to the Python print function:

Greg Clayton

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

[diff] [blame]

194

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

195

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

196

>>> print lldb.debugger

197

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

198

>>> print lldb.target

199

a.out

200

>>> print lldb.process

201

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

202

>>> print lldb.thread

203

SBThread: tid = 0x1f03

204

>>> print lldb.frame

205

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>

214

215

Jim Ingham

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

[diff] [blame]

216

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

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

[diff] [blame]

217

scripts to breakpoints provides a way to create complex breakpoint

218

conditions and also allows for smart logging and data gathering.

Jim Ingham

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

[diff] [blame]

219

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

Greg Clayton

b34ca85

2012-10-26 17:53:21 +0000

[diff] [blame]

220

body of a function which takes three arguments:

Greg Clayton

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

[diff] [blame]

221

Greg Clayton

b34ca85

2012-10-26 17:53:21 +0000

[diff] [blame]

222

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

Greg Clayton

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

[diff] [blame]

223

# Your code goes here

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

<tr>

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

228

229

<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

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

[diff] [blame]

241

The object will always be valid.

Greg Clayton

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

[diff] [blame]

242

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

251

</td>

252

253

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

254

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

255

are represented by lldb.SBBreakpointLocation objects.

256

</td>

257

</tr>

Greg Clayton

b34ca85

2012-10-26 17:53:21 +0000

[diff] [blame]

<tr>

dict

</td>

dict

</td>

The python session dictionary as a standard python dictionary object.

267

</td>

268

</tr>

Greg Clayton

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

[diff] [blame]

269

</table>

Jim Ingham

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

[diff] [blame]

270

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

271

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

272

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

273

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

274

We do this by setting a regular expression breakpoint

275

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

276

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

Greg Clayton

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

[diff] [blame]

277

This will result in one lldb.SBBreakpoint object

Jim Ingham

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

[diff] [blame]

278

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

279

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

280

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

281

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

282

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]

286

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

287

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

Jim Ingham

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

[diff] [blame]

288

(lldb) script counter = 0

Greg Clayton

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

[diff] [blame]

289

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

290

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

Jim Ingham

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

[diff] [blame]

291

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

292

> global counter

293

> counter += 1

Greg Clayton

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

[diff] [blame]

294

> # Get the name of the function

295

> name = frame.GetFunctionName()

296

> # Print the order and the function name

Jim Ingham

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

[diff] [blame]

297

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

Greg Clayton

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

[diff] [blame]

298

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

299

> bp_loc.SetEnabled(False)

300

> # How continue the process

301

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

302

> DONE

303

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

304

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

305

To remove the breakpoint command:

306

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

</div>

</div>

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

311

312

Jim Ingham

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

[diff] [blame]

313

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

314

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

Greg Clayton

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

[diff] [blame]

315

debugging requirements.

Jim Ingham

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

[diff] [blame]

316

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

Greg Clayton

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

[diff] [blame]

317

Enrico Granata

2012-08-08 02:06:30 +0000

[diff] [blame]

318

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

Greg Clayton

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

[diff] [blame]

319

# Your code goes here

320

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

Enrico Granata

c0791aa

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

[diff] [blame]

321

322

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

Enrico Granata

2012-08-08 02:06:30 +0000

[diff] [blame]

323

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

Enrico Granata

c0791aa

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

[diff] [blame]

324

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

325

# Your code goes here

326

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

327

Greg Clayton

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

[diff] [blame]

328

329

<tr>

330

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

331

332

<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

355

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

arguments.

</td>

</tr>

<tr>

result

</td>

lldb.SBCommandReturnObject

365

</td>

366

367

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

368

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

Jim Ingham

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

[diff] [blame]

369

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

370

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

Greg Clayton

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

[diff] [blame]

</td>

</tr>

<tr>

Enrico Granata

2012-08-08 02:06:30 +0000

[diff] [blame]

375

internal_dict

Greg Clayton

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

[diff] [blame]

</td>

python dict object

</td>

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

and functions.

</td>

</tr>

</table>

Jim Ingham

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

[diff] [blame]

386

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

387

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

388

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

389

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

390

Enrico Granata

2012-08-08 02:06:30 +0000

[diff] [blame]

391

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

Greg Clayton

261c974

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

[diff] [blame]

392

# Command Initialization code goes here

393

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

Jim Ingham

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

[diff] [blame]

394

Enrico Granata

2012-08-08 02:06:30 +0000

[diff] [blame]

395

where debugger and internal_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]

396

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

397

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

398

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

399

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

400

or when loaded via an import statement in python code

401

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

402

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

403

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

404

just like the standard test for __main__ like all python modules

405

usally do. Sample code would look like:

406

407

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

408

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

409

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

410

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

411

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

412

lldb.debugger = lldb.SBDebugger.Create()

413

elif lldb.debugger:

414

# Module is being run inside the LLDB interpreter

415

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

416

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

417

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

418

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

Jim Ingham

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

[diff] [blame]

419

can be used by LLDB's python command code:

Greg Clayton

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

[diff] [blame]

420

421

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

import lldb

import commands

import optparse

import shlex

Enrico Granata

2012-08-08 02:06:30 +0000

[diff] [blame]

428

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

Jim Ingham

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

[diff] [blame]

429

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

Greg Clayton

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

[diff] [blame]

430

Jim Ingham

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

[diff] [blame]

431

# And the initialization code to add your commands

Enrico Granata

2012-08-08 02:06:30 +0000

[diff] [blame]

432

def __lldb_init_module(debugger, internal_dict):

Jim Ingham

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

[diff] [blame]

433

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

Greg Clayton

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

[diff] [blame]

434

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

435

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

436

Now we can load the module into LLDB and use it

437

<code><pre><tt>% lldb

Greg Clayton

261c974

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

[diff] [blame]

438

(lldb) command script import ~/ls.py

Greg Clayton

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

[diff] [blame]

439

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

440

(lldb) ls -l /tmp/

441

total 365848

442

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

443

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

444

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

445

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

446

lldb command quickly:

447

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

Enrico Granata

74566c9

2012-08-24 21:20:14 +0000

[diff] [blame]

448

449

A commonly required facility is being able to create a command that does some token substitution, and then runs a different debugger command

450

(usually, it po'es the result of an expression evaluated on its argument). For instance, given the following program:

451

452

#import <Foundation/Foundation.h>

453

NSString*

454

ModifyString(NSString* src)

455

{

456

return [src stringByAppendingString:@"foobar"];

}

int main()

{

NSString* aString = @"Hello world";

462

NSString* anotherString = @"Let's be friends";

return 1;

}

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

you may want a pofoo X command, that equates po [ModifyString(X) capitalizedString].

467

The following debugger interaction shows how to achieve that goal:

468

469

(lldb) script

470

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

471

>>> def pofoo_funct(debugger, command, result, internal_dict):

472

... cmd = "po [ModifyString(" + command + ") capitalizedString]"

473

... lldb.debugger.HandleCommand(cmd)

474

...

475

>>> ^D

476

(lldb) command script add pofoo -f pofoo_funct

477

(lldb) pofoo aString

478

$1 = 0x000000010010aa00 Hello Worldfoobar

479

(lldb) pofoo anotherString

480

$2 = 0x000000010010aba0 Let's Be Friendsfoobar</tt></pre></code>

Greg Clayton

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

[diff] [blame]

481

</div>

482

483

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

484

485

486

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

487

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

488

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

Jim Ingham

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

[diff] [blame]

489

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

490

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

491

To use the

492

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

Greg Clayton

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

[diff] [blame]

493

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

Jim Ingham

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

[diff] [blame]

494

is done by setting the PYTHONPATH environment variable, adding

495

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

496

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

Greg Clayton

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

[diff] [blame]

497

498

For csh and tcsh:

499

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

500

For sh and bash:

501

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

502

Jim Ingham

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

[diff] [blame]

503

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

504

your Python code before importing the lldb module.

505

Greg Clayton

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

[diff] [blame]

506

507

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

508

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

509

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

510

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

511

512

513

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

import lldb

# Set the path to the executable to debug

518

exe = "./a.out"

519

520

# Create a new debugger instance

521

debugger = lldb.SBDebugger.Create()

522

523

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

Jim Ingham

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

[diff] [blame]

524

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

525

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

Greg Clayton