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

99

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

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

102

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

103

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

Greg Clayton

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

[diff] [blame]

104

105

<tr>

106

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

107

108

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

119

Contains the debugger object whose script command was invoked.

120

The lldb.SBDebugger object owns the command interpreter

121

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

122

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]

133

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

134

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

135

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

136

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]

147

Contains the process of the currently selected target.

148

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

149

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]

160

Contains the currently selected thread.

161

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

Greg Clayton

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

[diff] [blame]

162

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

163

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

Jim Ingham

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

[diff] [blame]

164

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

165

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]

176

Contains the currently selected stack frame.

177

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

178

that stack.

Greg Clayton

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

[diff] [blame]

179

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

180

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

Jim Ingham

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

[diff] [blame]

181

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

182

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]

187

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

188

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

189

to the Python print function:

Greg Clayton

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

[diff] [blame]

190

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

191

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

192

>>> print lldb.debugger

193

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

194

>>> print lldb.target

195

a.out

196

>>> print lldb.process

197

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

198

>>> print lldb.thread

199

SBThread: tid = 0x1f03

200

>>> print lldb.frame

201

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>

210

211

Jim Ingham

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

[diff] [blame]

212

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]

213

scripts to breakpoints provides a way to create complex breakpoint

214

conditions and also allows for smart logging and data gathering.

Jim Ingham

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

[diff] [blame]

215

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

216

body of a function which takes three arguments:

Greg Clayton

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

[diff] [blame]

217

Greg Clayton

b34ca85

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

[diff] [blame^]

218

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

Greg Clayton

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

[diff] [blame]

219

# Your code goes here

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

<tr>

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

224

225

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

237

The object will always be valid.

Greg Clayton

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

[diff] [blame]

238

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

247

</td>

248

249

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

250

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

251

are represented by lldb.SBBreakpointLocation objects.

252

</td>

253

</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.

263

</td>

264

</tr>

Greg Clayton

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

[diff] [blame]

265

</table>

Jim Ingham

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

[diff] [blame]

266

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

267

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

268

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

269

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

270

We do this by setting a regular expression breakpoint

271

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

272

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]

273

This will result in one lldb.SBBreakpoint object

Jim Ingham

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

[diff] [blame]

274

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

275

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

276

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

277

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

278

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]

282

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

283

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

Jim Ingham

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

[diff] [blame]

284

(lldb) script counter = 0

Greg Clayton

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

[diff] [blame]

285

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

286

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

Jim Ingham

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

[diff] [blame]

287

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

288

> global counter

289

> counter += 1

Greg Clayton

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

[diff] [blame]

290

> # Get the name of the function

291

> name = frame.GetFunctionName()

292

> # Print the order and the function name

Jim Ingham

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

[diff] [blame]

293

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

Greg Clayton

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

[diff] [blame]

294

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

295

> bp_loc.SetEnabled(False)

296

> # How continue the process

297

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

298

> DONE

299

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

300

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

301

To remove the breakpoint command:

302

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

</div>

</div>

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

307

308

Jim Ingham

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

[diff] [blame]

309

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

310

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]

311

debugging requirements.

Jim Ingham

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

[diff] [blame]

312

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]

313

Enrico Granata

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

[diff] [blame]

314

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

Greg Clayton

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

[diff] [blame]

315

# Your code goes here

316

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

Enrico Granata

c0791aa

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

[diff] [blame]

317

318

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]

319

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

Enrico Granata

c0791aa

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

[diff] [blame]

320

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

321

# Your code goes here

322

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

323

Greg Clayton

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

[diff] [blame]

324

325

<tr>

326

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

327

328

<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

351

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

arguments.

</td>

</tr>

<tr>

result

</td>

lldb.SBCommandReturnObject

361

</td>

362

363

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

364

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]

365

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

366

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]

371

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]

382

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

383

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

384

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

385

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

386

Enrico Granata

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

[diff] [blame]

387

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

Greg Clayton

261c974

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

[diff] [blame]

388

# Command Initialization code goes here

389

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

Jim Ingham

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

[diff] [blame]

390

Enrico Granata

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

[diff] [blame]

391

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]

392

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

393

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

394

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

395

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

396

or when loaded via an import statement in python code

397

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

398

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

399

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

400

just like the standard test for __main__ like all python modules

401

usally do. Sample code would look like:

402

403

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

404

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

405

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

406

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

407

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

408

lldb.debugger = lldb.SBDebugger.Create()

409

elif lldb.debugger:

410

# Module is being run inside the LLDB interpreter

411

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

412

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

413

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

414

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]

415

can be used by LLDB's python command code:

Greg Clayton

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

[diff] [blame]

416

417

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

424

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

Jim Ingham

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

[diff] [blame]

425

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

Greg Clayton

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

[diff] [blame]

426

Jim Ingham

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

[diff] [blame]

427

# And the initialization code to add your commands

Enrico Granata

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

[diff] [blame]

428

def __lldb_init_module(debugger, internal_dict):

Jim Ingham

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

[diff] [blame]

429

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

Greg Clayton

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

[diff] [blame]

430

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

431

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

432

Now we can load the module into LLDB and use it

433

<code><pre><tt>% lldb

Greg Clayton

261c974

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

[diff] [blame]

434

(lldb) command script import ~/ls.py

Greg Clayton

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

[diff] [blame]

435

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

436

(lldb) ls -l /tmp/

437

total 365848

438

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

439

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

440

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

441

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

442

lldb command quickly:

443

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

444

445

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

446

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

447

448

#import <Foundation/Foundation.h>

449

NSString*

450

ModifyString(NSString* src)

451

{

452

return [src stringByAppendingString:@"foobar"];

}

int main()

{

NSString* aString = @"Hello world";

458

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

return 1;

}

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

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

463

The following debugger interaction shows how to achieve that goal:

464

465

(lldb) script

466

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

467

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

468

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

469

... lldb.debugger.HandleCommand(cmd)

470

...

471

>>> ^D

472

(lldb) command script add pofoo -f pofoo_funct

473

(lldb) pofoo aString

474

$1 = 0x000000010010aa00 Hello Worldfoobar

475

(lldb) pofoo anotherString

476

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

Greg Clayton

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

[diff] [blame]

477

</div>

478

479

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

480

481

482

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

483

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

484

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

Jim Ingham

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

[diff] [blame]

485

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

486

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

487

To use the

488

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

Greg Clayton

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

[diff] [blame]

489

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]

490

is done by setting the PYTHONPATH environment variable, adding

491

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

492

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]

493

494

For csh and tcsh:

495

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

496

For sh and bash:

497

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

498

Jim Ingham

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

[diff] [blame]

499

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

500

your Python code before importing the lldb module.

501

Greg Clayton

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

[diff] [blame]

502

503

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

504

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

505

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

506

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

507

508

509

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

import lldb

# Set the path to the executable to debug

514

exe = "./a.out"

515

516

# Create a new debugger instance

517

debugger = lldb.SBDebugger.Create()

518

519

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

520

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

521

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

Greg Clayton