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

Enrico Granata

b1052dc

2013-01-16 22:25:17 +0000

[diff] [blame]

99

type, the variable's IsValid method will return false. These variables are:

100

Greg Clayton

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

[diff] [blame]

101

102

<tr>

103

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

104

105

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

116

Contains the debugger object whose script command was invoked.

117

The lldb.SBDebugger object owns the command interpreter

118

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

119

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]

130

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

131

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

132

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

133

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]

144

Contains the process of the currently selected target.

145

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

146

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]

157

Contains the currently selected thread.

158

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

Greg Clayton

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

[diff] [blame]

159

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

Enrico Granata

b1052dc

2013-01-16 22:25:17 +0000

[diff] [blame]

160

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

Jim Ingham

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

[diff] [blame]

161

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

162

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]

173

Contains the currently selected stack frame.

174

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

175

that stack.

Greg Clayton

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

[diff] [blame]

176

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

Enrico Granata

b1052dc

2013-01-16 22:25:17 +0000

[diff] [blame]

177

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

Jim Ingham

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

[diff] [blame]

178

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

179

be some selected frame.

Greg Clayton

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

[diff] [blame]

</td>

</tr>

</table>

Enrico Granata

2013-01-16 22:25:17 +0000

[diff] [blame]

184

While extremely convenient, these variables have a couple caveats that you should be aware of.

185

First of all, they hold the values

186

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

187

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

188

Moreover, they are only defined and meaningful while in the interactive Python interpreter.

189

There is no guarantee on their value in any other situation, hence you should not use them when defining

190

Python formatters, breakpoint scripts and commands (or any other Python extension point that LLDB provides).

191

As a rationale for such behavior, consider that lldb can

192

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

193

from under you.

194

195

To get started with these objects and LLDB scripting, please note that almost

Jim Ingham

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

[diff] [blame]

196

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

197

to the Python print function:

Greg Clayton

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

[diff] [blame]

198

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

199

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

200

>>> print lldb.debugger

201

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

202

>>> print lldb.target

203

a.out

204

>>> print lldb.process

205

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

206

>>> print lldb.thread

207

SBThread: tid = 0x1f03

208

>>> print lldb.frame

209

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>

218

219

Jim Ingham

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

[diff] [blame]

220

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]

221

scripts to breakpoints provides a way to create complex breakpoint

222

conditions and also allows for smart logging and data gathering.

Jim Ingham

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

[diff] [blame]

223

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]

224

body of a function which takes three arguments:

Greg Clayton

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

[diff] [blame]

225

Greg Clayton

b34ca85

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

[diff] [blame]

226

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

Greg Clayton

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

[diff] [blame]

227

# Your code goes here

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

<tr>

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

232

233

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

245

The object will always be valid.

Greg Clayton

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

[diff] [blame]

246

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

255

</td>

256

257

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

258

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

259

are represented by lldb.SBBreakpointLocation objects.

260

</td>

261

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

271

</td>

272

</tr>

Greg Clayton

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

[diff] [blame]

273

</table>

Enrico Granata

5c7c781

2013-05-16 23:17:25 +0000

[diff] [blame^]

274

Optionally, a Python breakpoint command can return a value. Returning False tells LLDB that you do not want to stop at the breakpoint.

275

Any other return value (including None or leaving out the return statement altogether) is akin to telling LLDB to actually stop at the breakpoint.

276

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

277

program state manually at every stop and then continue.

Jim Ingham

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

[diff] [blame]

278

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

279

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

280

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

281

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

282

We do this by setting a regular expression breakpoint

283

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

284

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]

285

This will result in one lldb.SBBreakpoint object

Jim Ingham

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

[diff] [blame]

286

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

287

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

288

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

289

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

290

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]

294

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

295

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

Jim Ingham

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

[diff] [blame]

296

(lldb) script counter = 0

Greg Clayton

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

[diff] [blame]

297

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

298

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

Jim Ingham

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

[diff] [blame]

299

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

300

> global counter

301

> counter += 1

Greg Clayton

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

[diff] [blame]

302

> # Get the name of the function

303

> name = frame.GetFunctionName()

304

> # Print the order and the function name

Jim Ingham

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

[diff] [blame]

305

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

Greg Clayton

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

[diff] [blame]

306

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

307

> bp_loc.SetEnabled(False)

308

> # How continue the process

309

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

310

> DONE

311

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

312

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

313

To remove the breakpoint command:

314

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

</div>

</div>

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

319

320

Jim Ingham

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

[diff] [blame]

321

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

322

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]

323

debugging requirements.

Jim Ingham

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

[diff] [blame]

324

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]

325

Enrico Granata

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

[diff] [blame]

326

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

Greg Clayton

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

[diff] [blame]

327

# Your code goes here

328

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

Enrico Granata

c0791aa

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

[diff] [blame]

329

330

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]

331

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

Enrico Granata

c0791aa

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

[diff] [blame]

332

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

333

# Your code goes here

334

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

335

Greg Clayton

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

[diff] [blame]

336

337

<tr>

338

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

339

340

<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

363

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

arguments.

</td>

</tr>

<tr>

result

</td>

lldb.SBCommandReturnObject

373

</td>

374

Enrico Granata

f734066

2013-03-25 17:37:39 +0000

[diff] [blame]

375

A return object which encapsulates success/failure information for the command and output text

376

that needs to be printed as a result of the command. The plain Python "print" command also works but

377

text won't go in the result by default (it is useful as a temporary logging facility).

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]

382

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>

Enrico Granata

f734066

2013-03-25 17:37:39 +0000

[diff] [blame]

393

As a convenience, you can treat the result object as a Python file object, and say

394

print >>result, "my command does lots of cool stuff". SBCommandReturnObject and SBStream

395

both support this file-like behavior by providing write() and flush() calls at the Python layer.

Jim Ingham

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

[diff] [blame]

396

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

397

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

398

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

399

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

400

Enrico Granata

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

[diff] [blame]

401

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

Greg Clayton

261c974

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

[diff] [blame]

402

# Command Initialization code goes here

403

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

Jim Ingham

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

[diff] [blame]

404

Enrico Granata

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

[diff] [blame]

405

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]

406

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

407

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

408

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

409

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

410

or when loaded via an import statement in python code

411

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

412

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

413

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

414

just like the standard test for __main__ like all python modules

415

usally do. Sample code would look like:

416

417

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

418

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

419

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

420

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

421

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

422

lldb.debugger = lldb.SBDebugger.Create()

423

elif lldb.debugger:

424

# Module is being run inside the LLDB interpreter

425

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

426

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

427

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

428

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]

429

can be used by LLDB's python command code:

Greg Clayton

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

[diff] [blame]

430

431

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

438

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

Jim Ingham

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

[diff] [blame]

439

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

Greg Clayton

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

[diff] [blame]

440

Jim Ingham

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

[diff] [blame]

441

# And the initialization code to add your commands

Enrico Granata

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

[diff] [blame]

442

def __lldb_init_module(debugger, internal_dict):

Jim Ingham

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

[diff] [blame]

443

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

Greg Clayton

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

[diff] [blame]

444

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

445

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

446

Now we can load the module into LLDB and use it

447

<code><pre><tt>% lldb

Greg Clayton

261c974

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

[diff] [blame]

448

(lldb) command script import ~/ls.py

Greg Clayton

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

[diff] [blame]

449

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

450

(lldb) ls -l /tmp/

451

total 365848

452

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

453

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

454

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

Enrico Granata

ac39f3c

2013-05-09 01:32:24 +0000

[diff] [blame]

455

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

Greg Clayton

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

[diff] [blame]

456

lldb command quickly:

457

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

458

459

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

460

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

461

462

#import <Foundation/Foundation.h>

463

NSString*

464

ModifyString(NSString* src)

465

{

466

return [src stringByAppendingString:@"foobar"];

}

int main()

{

NSString* aString = @"Hello world";

472

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

return 1;

}

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

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

477

The following debugger interaction shows how to achieve that goal:

478

479

(lldb) script

480

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

481

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

482

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

483

... lldb.debugger.HandleCommand(cmd)

484

...

485

>>> ^D

486

(lldb) command script add pofoo -f pofoo_funct

487

(lldb) pofoo aString

488

$1 = 0x000000010010aa00 Hello Worldfoobar

489

(lldb) pofoo anotherString

490

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

Greg Clayton

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

[diff] [blame]

491

</div>

492

493

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

494

495

496

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

497

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

498

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

Jim Ingham

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

[diff] [blame]

499

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

500

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

501

To use the

502

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

Greg Clayton

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

[diff] [blame]

503

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]

504

is done by setting the PYTHONPATH environment variable, adding

505

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

506

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]

507

508

For csh and tcsh:

509

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

510

For sh and bash:

511

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

512

Jim Ingham

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

[diff] [blame]

513

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

514

your Python code before importing the lldb module.

515

Greg Clayton

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

[diff] [blame]

516

517

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

518

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

519

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

520

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

521

522

523

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

524

525

import lldb

Daniel Malea

7a87d52

2013-02-12 20:01:49 +0000

[diff] [blame]

526

import os

527

528

def disassemble_instructions(insts):

529

for i in insts:

530

print i

Greg Clayton

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

[diff] [blame]

531

532

# Set the path to the executable to debug

533

exe = "./a.out"

534

535

# Create a new debugger instance

536

debugger = lldb.SBDebugger.Create()

537

538

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

539

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

540

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

Greg Clayton

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

[diff] [blame]

541

debugger.SetAsync (False)

542

543

# Create a target from a file and arch

544

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

545

546

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

547

548

if target:

549

# If the target is valid set a breakpoint at main

550

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

print main_bp

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

555

# from this function until we hit the breakpoint at main

556

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

557

558

# Make sure the launch went ok

559

if process:

560

# Print some simple process info

561

state = process.GetState ()

562

print process

563

if state == lldb.eStateStopped:

Daniel Malea

7a87d52

2013-02-12 20:01:49 +0000

[diff] [blame]

564

# Get the first thread

565

thread = process.GetThreadAtIndex (0)

566

if thread:

567

# Print some simple thread info

568

print thread

569

# Get the first frame

570

frame = thread.GetFrameAtIndex (0)

571

if frame:

572

# Print some simple frame info

573

print frame

574

function = frame.GetFunction()

575

# See if we have debug info (a function)

576

if function:

577

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

578

print function

579

# Now get all instructions for this function and print them

580

insts = function.GetInstructions(target)

581

disassemble_instructions (insts)

582

else:

583

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

584

symbol = frame.GetSymbol();

585

if symbol:

586

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

587

print symbol

Greg Clayton