1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<link href="style.css" rel="stylesheet" type="text/css" />
<title>LLDB Python Reference</title>
</head>
<body>
<div class="www_title">
LLDB Python Reference
</div>
<div id="container">
<div id="content">
<!--#include virtual="sidebar.incl"-->
<div id="middle">
<div class="post">
<h1 class ="postheader">Introduction</h1>
<div class="postcontent">
<p>The entire LLDB API is available as Python functions through a script bridging interface.
This means the LLDB API's can be used directly from python either interactively or to build python apps that
provide debugger features. </p>
<p>Additionally, Python can be used as a programmatic interface within the
lldb command interpreter (we refer to this for brevity as the embedded interpreter). Of course,
in this context it has full access to the LLDB API - with some additional conveniences we will
call out in the FAQ.</p>
</div>
<div class="postfooter"></div>
<div class="post">
<h1 class ="postheader">Documentation</h1>
<div class="postcontent">
<p>The LLDB API is contained in a python module named <b>lldb</b>. A useful resource when writing Python extensions is the <a href="python_reference/index.html">lldb Python classes reference guide</a>.</p>
<p>The documentation is also accessible in an interactive debugger session with the following command:</p>
<code><pre><tt>(lldb) <b>script help(lldb)</b>
Help on package lldb:
NAME
lldb - The lldb module contains the public APIs for Python binding.
FILE
/System/Library/PrivateFrameworks/LLDB.framework/Versions/A/Resources/Python/lldb/__init__.py
DESCRIPTION
...
</tt></pre></code>
<p>You can also get help using a module class name. The full API that is exposed for that class will be displayed in a man page style window. Below we want to get help on the lldb.SBFrame class:</p>
<code><pre><tt>(lldb) <b>script help(lldb.SBFrame)</b>
Help on class SBFrame in module lldb:
class SBFrame(__builtin__.object)
| Represents one of the stack frames associated with a thread.
| SBThread contains SBFrame(s). For example (from test/lldbutil.py),
|
| def print_stacktrace(thread, string_buffer = False):
| '''Prints a simple stack trace of this thread.'''
|
...
</tt></pre></code>
<p>Or you can get help using any python object, here we use the <b>lldb.process</b> object which is a global variable in the <b>lldb</b> module which represents the currently selected process:</p>
<code><pre><tt>(lldb) <b>script help(lldb.process)</b>
Help on SBProcess in module lldb object:
class SBProcess(__builtin__.object)
| Represents the process associated with the target program.
|
| SBProcess supports thread iteration. For example (from test/lldbutil.py),
|
| # ==================================================
| # Utility functions related to Threads and Processes
| # ==================================================
|
...
</tt></pre></code>
</div>
<div class="postfooter"></div>
<div class="post">
<h1 class ="postheader">Embedded Python Interpreter</h1>
<div class="postcontent">
<p>The embedded python interpreter can be accessed in a variety of ways from within LLDB. The
easiest way is to use the lldb command <b>script</b> with no arguments at the lldb command prompt:</p>
<code><pre><tt>(lldb) <strong>script</strong>
Python Interactive Interpreter. To exit, type 'quit()', 'exit()' or Ctrl-D.
>>> 2+3
5
>>> hex(12345)
'0x3039'
>>>
</tt></pre></code>
<p>This drops you into the embedded python interpreter. When running under the <b>script</b> command,
lldb sets some convenience variables that give you quick access to the currently selected entities that characterize
the program and debugger state. In each case, if there is no currently selected entity of the appropriate
type, the variable's <b>IsValid</b> method will return false. These variables are:</p>
<table class="stats" width="620" cellspacing="0">
<tr>
<td class="hed" width="20%">Variable</td>
<td class="hed" width="10%">Type</td>
<td class="hed" width="70%">Description</td>
</tr>
<tr>
<td class="content">
<b>lldb.debugger</b>
</td>
<td class="content">
<b>lldb.SBDebugger</b>
</td>
<td class="content">
Contains the debugger object whose <b>script</b> command was invoked.
The <b>lldb.SBDebugger</b> object owns the command interpreter
and all the targets in your debug session. There will always be a
Debugger in the embedded interpreter.
</td>
</tr>
<tr>
<td class="content">
<b>lldb.target</b>
</td>
<td class="content">
<b>lldb.SBTarget</b>
</td>
<td class="content">
Contains the currently selected target - for instance the one made with the
<b>file</b> or selected by the <b>target select <target-index></b> command.
The <b>lldb.SBTarget</b> manages one running process, and all the executable
and debug files for the process.
</td>
</tr>
<tr>
<td class="content">
<b>lldb.process</b>
</td>
<td class="content">
<b>lldb.SBProcess</b>
</td>
<td class="content">
Contains the process of the currently selected target.
The <b>lldb.SBProcess</b> object manages the threads and allows access to
memory for the process.
</td>
</tr>
<tr>
<td class="content">
<b>lldb.thread</b>
</td>
<td class="content">
<b>lldb.SBThread</b>
</td>
<td class="content">
Contains the currently selected thread.
The <b>lldb.SBThread</b> object manages the stack frames in that thread.
A thread is always selected in the command interpreter when a target stops.
The <b>thread select <thread-index></b> command can be used to change the
currently selected thread. So as long as you have a stopped process, there will be
some selected thread.
</td>
</tr>
<tr>
<td class="content">
<b>lldb.frame</b>
</td>
<td class="content">
<b>lldb.SBFrame</b>
</td>
<td class="content">
Contains the currently selected stack frame.
The <b>lldb.SBFrame</b> object manage the stack locals and the register set for
that stack.
A stack frame is always selected in the command interpreter when a target stops.
The <b>frame select <frame-index></b> command can be used to change the
currently selected frame. So as long as you have a stopped process, there will
be some selected frame.
</td>
</tr>
</table>
<p>While extremely convenient, these variables have a couple caveats that you should be aware of.
First of all, they hold the values
of the selected objects on entry to the embedded interpreter. They do not update as you use the LLDB
API's to change, for example, the currently selected stack frame or thread.
<p>Moreover, they are only defined and meaningful while in the interactive Python interpreter.
There is no guarantee on their value in any other situation, hence you should not use them when defining
Python formatters, breakpoint scripts and commands (or any other Python extension point that LLDB provides).
As a rationale for such behavior, consider that lldb can
run in a multithreaded environment, and another thread might call the "script" command, changing the value out
from under you.</p>
<p>To get started with these objects and LLDB scripting, please note that almost
all of the <b>lldb</b> Python objects are able to briefly describe themselves when you pass them
to the Python <b>print</b> function:
<code><pre><tt>(lldb) <b>script</b>
Python Interactive Interpreter. To exit, type 'quit()', 'exit()' or Ctrl-D.
>>> <strong>print lldb.debugger</strong>
Debugger (instance: "debugger_1", id: 1)
>>> <strong>print lldb.target</strong>
a.out
>>> <strong>print lldb.process</strong>
SBProcess: pid = 59289, state = stopped, threads = 1, executable = a.out
>>> <strong>print lldb.thread</strong>
SBThread: tid = 0x1f03
>>> <strong>print lldb.frame</strong>
frame #0: 0x0000000100000bb6 a.out main + 54 at main.c:16
</tt></pre></code>
</div>
<div class="postfooter"></div>
</div>
<div class="post">
<h1 class ="postheader">Running a Python script when a breakpoint gets hit</h1>
<div class="postcontent">
<p>One very powerful use of the lldb Python API is to have a python script run when a breakpoint gets hit. Adding python
scripts to breakpoints provides a way to create complex breakpoint
conditions and also allows for smart logging and data gathering.</p>
<p>When your process hits a breakpoint to which you have attached some python code, the code is executed as the
body of a function which takes three arguments:</p>
<p>
<code><pre><tt>def breakpoint_function_wrapper(<b>frame</b>, <b>bp_loc</b>, <b>dict</b>):
<font color=green># Your code goes here</font>
</tt></pre></code>
<p><table class="stats" width="620" cellspacing="0">
<tr>
<td class="hed" width="10%">Argument</td>
<td class="hed" width="10%">Type</td>
<td class="hed" width="80%">Description</td>
</tr>
<tr>
<td class="content">
<b>frame</b>
</td>
<td class="content">
<b>lldb.SBFrame</b>
</td>
<td class="content">
The current stack frame where the breakpoint got hit.
The object will always be valid.
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>.
</td>
</tr>
<tr>
<td class="content">
<b>bp_loc</b>
</td>
<td class="content">
<b>lldb.SBBreakpointLocation</b>
</td>
<td class="content">
The breakpoint location that just got hit. Breakpoints are represented by <b>lldb.SBBreakpoint</b>
objects. These breakpoint objects can have one or more locations. These locations
are represented by <b>lldb.SBBreakpointLocation</b> objects.
</td>
</tr>
<tr>
<td class="content">
<b>dict</b>
</td>
<td class="content">
<b>dict</b>
</td>
<td class="content">
The python session dictionary as a standard python dictionary object.
</td>
</tr>
</table>
<p>Optionally, a Python breakpoint command can return a value. Returning False tells LLDB that you do not want to stop at the breakpoint.
Any other return value (including None or leaving out the return statement altogether) is akin to telling LLDB to actually stop at the breakpoint.
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
program state manually at every stop and then continue.
<p>An example will show how simple it is to write some python code and attach it to a breakpoint.
The following example will allow you to track the order in which the functions in a given shared library
are first executed during one run of your program. This is a simple method to gather an order file which
can be used to optimize function placement within a binary for execution locality.</p>
<p>We do this by setting a regular expression breakpoint
that will match every function in the shared library. The regular expression '.' will match
any string that has at least one character in it, so we will use that.
This will result in one <b>lldb.SBBreakpoint</b> object
that contains an <b>lldb.SBBreakpointLocation</b> object for each function. As the breakpoint gets
hit, we use a counter to track the order in which the function at this particular breakpoint location got hit.
Since our code is passed the location that was hit, we can get the name of the function from the location,
disable the location so we won't count this function again; then log some info and continue the process.</p>
<p>Note we also have to initialize our counter, which we do with the simple one-line version of the <b>script</b>
command.
<p>Here is the code:
<code><pre><tt>(lldb) <strong>breakpoint set --func-regex=. --shlib=libfoo.dylib</strong>
Breakpoint created: 1: regex = '.', module = libfoo.dylib, locations = 223
(lldb) <strong>script counter = 0</strong>
(lldb) <strong>breakpoint command add --script-type python 1</strong>
Enter your Python command(s). Type 'DONE' to end.
> <font color=green># Increment our counter. Since we are in a function, this must be a global python variable</font>
> <strong>global counter</strong>
> <strong>counter += 1</strong>
> <font color=green># Get the name of the function</font>
> <strong>name = frame.GetFunctionName()</strong>
> <font color=green># Print the order and the function name</font>
> <strong>print '[%i] %s' % (counter, name)</strong>
> <font color=green># Disable the current breakpoint location so it doesn't get hit again</font>
> <strong>bp_loc.SetEnabled(False)</strong>
> <font color=green># No need to stop here</font>
> <strong>return False</strong>
> <strong>DONE</strong>
</tt></pre></code>
<p>The <b>breakpoint command add</b> command above attaches a python script to breakpoint 1.
To remove the breakpoint command:
<p><code>(lldb) <strong>breakpoint command delete 1</strong></code>
</div>
</div>
</div>
<div class="post">
<h1 class ="postheader">Using the Python API's to create custom breakpoints</h1>
<div class="postcontent">
<p>Another use of the Python API's in lldb is to create a custom breakpoint resolver. This facility
was added in r342259.
</p>
<p>
It allows you to provide the algorithm which will be used in the breakpoint's
search of the space of the code in a given Target
to determine where to set the breakpoint locations - the actual places where the breakpoint will trigger.
To understand how this works you need to know a little about how lldb handles breakpoints.
</p>
<p>
In lldb, a breakpoint is composed of three parts: the Searcher, the Resolver, and the Stop Options. The Searcher and
Resolver cooperate to determine how breakpoint locations are set and differ between each breakpoint type.
Stop options determine what happens when a location triggers and includes the commands, conditions, ignore counts, etc.
Stop options are common between all breakpoint types, so for our purposes only the Searcher and Resolver are relevant.
</p>
<p>
The Searcher's job is to traverse in a structured way the code in the current target. It
proceeds from the Target, to search all the Modules in the Target, in each Module it can recurse
into the Compile Units in that module, and within each Compile Unit it can recurse over the Functions
it contains.
</p>
<p>
The Searcher can be provided with a SearchFilter that it will use to restrict this search. For instance, if the
SearchFilter specifies a list of Modules, the Searcher will not recurse into Modules that aren't on the list.
When you pass the <b>-s modulename</b> flag to <b>break set</b> you are creating a Module-based search filter.
When you pass <b>-f filename.c</b> to <b>break set -n</b> you are creating a file based search filter. If neither
of these is specified, the breakpoint will have a no-op search filter, so all parts of the program are searched
and all locations accepted.
</p>
<p>
The Resolver has two functions. The most important one is the callback it provides. This will get called at the appropriate time
in the course of the search. The callback is where the job of adding locations to the breakpoint gets done.
</p>
<p>
The other function is specifying to the Searcher at what depth in the above described recursion it wants to be
called. Setting a search depth also provides a stop for the recursion. For instance, if you request a Module depth
search, then the callback will be called for each Module as it gets added to the Target, but the searcher will not recurse into the
Compile Units in the module.
</p>
<p>
One other slight sublety is that the depth at which you get called back is not necessarily the depth at which the
the SearchFilter is specified. For instance, if you are doing symbol searches, it is convenient to use the Module
depth for the search, since symbols are stored in the module.
But the SearchFilter might specify some subset of CompileUnits, so not all the symbols you might find in each module
will pass the search. You don't need to
handle this situation yourself, since <b>SBBreakpoint::AddLocation</b> will only add locations that pass the Search Filter.
This API returns an SBError to inform you whether your location was added.
</p>
<p>
When the breakpoint is originally created, its Searcher will process all the currently loaded modules.
The Searcher will also visit any new modules as they are added to the target. This happens, for instance, when
a new shared library gets added to the target in the course of running, or on rerunning if any of the currently
loaded modules have been changed. Note, in the latter case, all the locations set in the old module will get
deleted and you will be asked to recreate them in the new version of the module when your callback gets called
with that module. For this reason, you shouldn't
try to manage the locations you add to the breakpoint yourself. Note that the Breakpoint takes care of
deduplicating equal addresses in AddLocation, so you shouldn't need to worry about that anyway.
</p>
<p>
At present, when adding a scripted Breakpoint type, you can only provide a custom Resolver, not a custom SearchFilter.
</p>
<p>
The custom Resolver is provided as a Python class with the following methods:
</p>
</tt></pre></code>
<p><table class="stats" width="620" cellspacing="0">
<tr>
<td class="hed" width="10%">Name</td>
<td class="hed" width="10%">Arguments</td>
<td class="hed" width="80%">Description</td>
</tr>
<tr>
<td class="content">
<b>__init__</b>
</td>
<td class="content">
<b>bkpt: lldb.SBBreakpoint</b>
<b>extra_args: lldb.SBStructuredData</b>
</td>
<td class="content">
<p>
This is the constructor for the new Resolver.
</p>
<p>
<b>bkpt</b> is the breakpoint owning this Resolver.
</p>
<p>
<b>extra_args</b> is an SBStructuredData object that the user can pass in when creating instances of this
breakpoint. It is not required, but is quite handy. For instance if you were implementing a breakpoint on some
symbol name, you could write a generic symbol name based Resolver, and then allow the user to pass
in the particular symbol in the extra_args
</td>
</tr>
<tr>
<td class="content">
<b>__callback__</b>
</td>
<td class="content">
<b>sym_ctx: lldb.SBSymbolContext</b>
</td>
<td class="content">
This is the Resolver callback.
The <b>sym_ctx</b> argument will be filled with the current stage
of the search.
</p>
<p>
For instance, if you asked for a search depth of lldb.eSearchDepthCompUnit, then the
target, module and compile_unit fields of the sym_ctx will be filled. The callback should look just in the
context passed in <b>sym_ctx</b> for new locations. If the callback finds an address of interest, it
can add it to the breakpoint with the <b>SBBreakpoint::AddLocation</b> method, using the breakpoint passed
in to the <b>__init__</b> method.
</td>
</tr>
<tr>
<td class="content">
<b>__get_depth__</b>
</td>
<td class="content">
<b>None</b>
</td>
<td class="content">
Specify the depth at which you wish your callback to get called. The currently supported options are:
<dl>
<dt>lldb.eSearchDepthModule</dt>
<dt>lldb.eSearchDepthCompUnit</dt>
<dt>lldb.eSearchDepthFunction</dt>
</dl>
For instance, if you are looking
up symbols, which are stored at the Module level, you will want to get called back module by module.
So you would want to return <b>lldb.eSearchDepthModule</b>. This method is optional. If not provided the search
will be done at Module depth.
</td>
</tr>
<tr>
<td class="content">
<b>get_short_help</b>
</td>
<td class="content">
<b>None</b>
</td>
<td class="content">
This is an optional method. If provided, the returned string will be printed at the beginning of
the description for this breakpoint.
</td>
</tr>
</table>
<p>To define a new breakpoint command defined by this class from the lldb command line, use the command:</p>
<code><pre><tt>(lldb) <strong>breakpoint set -P MyModule.MyResolverClass</strong>
</tt></pre></code>
<p>You can also populate the extra_args SBStructuredData with a dictionary of key/value pairs with:</p>
<code><pre><tt>(lldb) <strong>breakpoint set -P MyModule.MyResolverClass -k key_1 -v value_1 -k key_2 -v value_2</strong>
</tt></pre></code>
<p>Although you can't write a scripted SearchFilter, both the command line and the SB API's for adding a
scripted resolver allow you to specify a SearchFilter restricted to certain modules or certain compile
units. When using the command line to create the resolver, you can specify a Module specific SearchFilter
by passing the <b>-s ModuleName</b> option - which can be specified multiple times.
You can also specify a SearchFilter restricted to certain
compile units by passing in the <b>-f CompUnitName</b> option. This can also be specified more than
once. And you can mix the two to specify "this comp unit in this module". So, for instance,
</p>
<code><pre><tt>(lldb) <strong>breakpoint set -P MyModule.MyResolverClass -s a.out</strong>
</tt></pre></code>
<p>
will use your resolver, but will only recurse into or accept new locations in the module a.out.
</p>
<p>Another option for creating scripted breakpoints is to use the <b>SBTarget.CreateBreakpointFromScript</b> API.
This one has the advantage that you can pass in an arbitrary SBStructuredData object, so you can
create more complex parametrizations.
SBStructuredData has a handy SetFromJSON method which you can use for this purpose.
Your __init__ function gets passed this SBStructuredData object.
This API also allows you to directly provide the list of Modules and the list of CompileUnits that will
make up the SearchFilter. If you pass in empty lists, the breakpoint will use the default "search everywhere,accept
everything" filter.
</p>
</div>
<div class="post">
<h1 class ="postheader">Using the Python API's to create custom stepping logic</h1>
<div class="postcontent">
<p>A slightly esoteric use of the Python API's is to construct custom stepping types. LLDB's stepping is
driven by a stack of "thread plans" and a fairly simple state machine that runs the plans. You can create
a Python class that works as a thread plan, and responds to the requests the state machine makes to run
its operations. </p>
<p>There is a longer discussion of scripted thread plans and the state machine, and several interesting examples
of their use in:</p>
<a href="http://llvm.org/svn/llvm-project/lldb/trunk/examples/python/scripted_step.py">scripted_step.py</a>
<p> And for a MUCH fuller discussion of the whole state machine, see:</p>
<a href="http://llvm.org/svn/llvm-project/lldb/trunk/include/lldb/Target/ThreadPlan.h">ThreadPlan.h</a>
<p>If you are reading those comments it is useful to know that scripted thread plans are set to be
"MasterPlans", and not "OkayToDiscard".
<p>To implement a scripted step, you define a python class that has the following methods:</p>
</tt></pre></code>
<p><table class="stats" width="620" cellspacing="0">
<tr>
<td class="hed" width="10%">Name</td>
<td class="hed" width="10%">Arguments</td>
<td class="hed" width="80%">Description</td>
</tr>
<tr>
<td class="content">
<b>__init__</b>
</td>
<td class="content">
<b>thread_plan: lldb.SBThreadPlan</b>
</td>
<td class="content">
This is the underlying SBThreadPlan that is pushed onto the plan stack.
You will want to store this away in an ivar. Also, if you are going to
use one of the canned thread plans, you can queue it at this point.
</td>
</tr>
<tr>
<td class="content">
<b>explains_stop</b>
</td>
<td class="content">
<b>event: lldb.SBEvent</b>
</td>
<td class="content">
Return True if this stop is part of your thread plans logic, false otherwise.
</td>
</tr>
<tr>
<td class="content">
<b>is_stale</b>
</td>
<td class="content">
<b>None</b>
</td>
<td class="content">
If your plan is no longer relevant (for instance, you were
stepping in a particular stack frame, but some other operation
pushed that frame off the stack) return True and your plan will
get popped.
</td>
</tr>
<tr>
<td class="content">
<b>should_step</b>
</td>
<td class="content">
<b>None</b>
</td>
<td class="content">
Return True if you want lldb to instruction step one instruction,
or False to continue till the next breakpoint is hit.
</td>
</tr>
<tr>
<td class="content">
<b>should_stop</b>
</td>
<td class="content">
<b>event: lldb.SBEvent</b>
</td>
<td class="content">
If your plan wants to stop and return control to the user at this point, return True.
If your plan is done at this point, call SetPlanComplete on your
thread plan instance.
Also, do any work you need here to set up the next stage of stepping.
</td>
</tr>
</table>
<p>To use this class to implement a step, use the command:</p>
<code><pre><tt>(lldb) <strong>thread step-scripted -C MyModule.MyStepPlanClass</strong>
</tt></pre></code>
<p>Or use the SBThread.StepUsingScriptedThreadPlan API. The SBThreadPlan passed into
your __init__ function can also push several common plans (step in/out/over and run-to-address)
in front of itself on the stack, which can be used to compose more complex stepping operations.
When you use subsidiary plans your explains_stop and should_stop methods won't get called until
the subsidiary plan is done, or the process stops for an event the subsidiary plan doesn't
explain. For instance, step over plans don't explain a breakpoint hit while performing the
step-over.</p>
</div>
</div>
<div class="post">
<h1 class ="postheader">Create a new LLDB command using a python function</h1>
<div class="postcontent">
<p>Python functions can be used to create new LLDB command interpreter commands, which will work
like all the natively defined lldb commands. This provides a very flexible and easy way to extend LLDB to meet your
debugging requirements. </p>
<p>To write a python function that implements a new LLDB command define the function to take four arguments as follows:</p>
<code><pre><tt>def command_function(<b>debugger</b>, <b>command</b>, <b>result</b>, <b>internal_dict</b>):
<font color=green># Your code goes here</font>
</tt></pre></code>
Optionally, you can also provide a Python docstring, and LLDB will use it when providing help for your command, as in:
<code><pre><tt>def command_function(<b>debugger</b>, <b>command</b>, <b>result</b>, <b>internal_dict</b>):
<font color=green>"""This command takes a lot of options and does many fancy things"""</font>
<font color=green># Your code goes here</font>
</tt></pre></code>
Starting with SVN revision 218834, LLDB Python commands can also take an SBExecutionContext as an argument.
This is useful in cases where the command's notion of <i>where to act</i> is independent of the currently-selected entities in the debugger.<br/>
This feature is enabled if the command-implementing function can be recognized as taking 5 arguments, or a variable number of arguments, and it alters the signature as such:
<code><pre><tt>def command_function(<b>debugger</b>, <b>command</b>, <b>exe_ctx</b>, <b>result</b>, <b>internal_dict</b>):
<font color=green># Your code goes here</font>
</tt></pre></code>
<p><table class="stats" width="620" cellspacing="0">
<tr>
<td class="hed" width="10%">Argument</td>
<td class="hed" width="10%">Type</td>
<td class="hed" width="80%">Description</td>
</tr>
<tr>
<td class="content">
<b>debugger</b>
</td>
<td class="content">
<b>lldb.SBDebugger</b>
</td>
<td class="content">
The current debugger object.
</td>
</tr>
<tr>
<td class="content">
<b>command</b>
</td>
<td class="content">
<b>python string</b>
</td>
<td class="content">
A python string containing all arguments for your command. If you need to chop up the arguments
try using the <b>shlex</b> module's <code>shlex.split(command)</code> to properly extract the
arguments.
</td>
</tr>
<tr>
<td class="content">
<b>exe_ctx</b>
</td>
<td class="content">
<b>lldb.SBExecutionContext</b>
</td>
<td class="content">
An execution context object carrying around information on the inferior process' context in which the command is expected to act
<br/><i>Optional since SVN r218834, unavailable before</i>
</td>
</tr>
<tr>
<td class="content">
<b>result</b>
</td>
<td class="content">
<b>lldb.SBCommandReturnObject</b>
</td>
<td class="content">
A return object which encapsulates success/failure information for the command and output text
that needs to be printed as a result of the command. The plain Python "print" command also works but
text won't go in the result by default (it is useful as a temporary logging facility).
</td>
</tr>
<tr>
<td class="content">
<b>internal_dict</b>
</td>
<td class="content">
<b>python dict object</b>
</td>
<td class="content">
The dictionary for the current embedded script session which contains all variables
and functions.
</td>
</tr>
</table>
<p>Starting with SVN revision 232224, Python commands can also be implemented by means of a class
which should implement the following interface:</p>
<code>
<font color=blue>class</font> CommandObjectType:<br/>
<font color=blue>def</font> __init__(self, debugger, session_dict):<br/>
<i>this call should initialize the command with respect to the command interpreter for the passed-in debugger</i> <br/>
<font color=blue>def</font> __call__(self, debugger, command, exe_ctx, result): <br/>
<i>this is the actual bulk of the command, akin to Python command functions</i> <br/>
<font color=blue>def</font> get_short_help(self): <br/>
<i>this call should return the short help text for this command</i><sup>[1]</sup><br/>
<font color=blue>def</font> get_long_help(self): <br/>
<i>this call should return the long help text for this command</i><sup>[1]</sup><br/>
</code>
<sup>[1]</sup> This method is optional.
<p>As a convenience, you can treat the result object as a Python file object, and say
<code><pre><tt>print >>result, "my command does lots of cool stuff"</tt></pre></code>
SBCommandReturnObject and SBStream
both support this file-like behavior by providing write() and flush() calls at the Python layer.</p>
<p>One other handy convenience when defining lldb command-line commands is the command
<b>command script import</b> which will import a module specified by file path - so you
don't have to change your PYTHONPATH for temporary scripts. It also has another convenience
that if your new script module has a function of the form:</p>
<code><pre><tt>def __lldb_init_module(<b>debugger</b>, <b>internal_dict</b>):
<font color=green># Command Initialization code goes here</font>
</tt></pre></code>
<p>where <b>debugger</b> and <b>internal_dict</b> are as above, that function will get run when the module is loaded
allowing you to add whatever commands you want into the current debugger. Note that
this function will only be run when using the LLDB command <b>command script import</b>,
it will not get run if anyone imports your module from another module.
If you want to always run code when your module is loaded from LLDB
<u>or</u> when loaded via an <b>import</b> statement in python code
you can test the <b>lldb.debugger</b> object, since you imported the
<lldb> module at the top of the python <b>ls.py</b> module. This test
must be in code that isn't contained inside of any function or class,
just like the standard test for <b>__main__</b> like all python modules
usually do. Sample code would look like:
<code><pre><tt>if __name__ == '__main__':
<font color=green># Create a new debugger instance in your module if your module
# can be run from the command line. When we run a script from
# the command line, we won't have any debugger object in
# lldb.debugger, so we can just create it if it will be needed</font>
lldb.debugger = lldb.SBDebugger.Create()
elif lldb.debugger:
<font color=green># Module is being run inside the LLDB interpreter</font>
lldb.debugger.HandleCommand('command script add -f ls.ls ls')
print 'The "ls" python command has been installed and is ready for use.'
</tt></pre></code>
<p>Now we can create a module called <b>ls.py</b> in the file <b>~/ls.py</b> that will implement a function that
can be used by LLDB's python command code:</p>
<code><pre><tt><font color=green>#!/usr/bin/python</font>
import lldb
import commands
import optparse
import shlex
def ls(debugger, command, result, internal_dict):
print >>result, (commands.getoutput('/bin/ls %s' % command))
<font color=green># And the initialization code to add your commands </font>
def __lldb_init_module(debugger, internal_dict):
debugger.HandleCommand('command script add -f ls.ls ls')
print 'The "ls" python command has been installed and is ready for use.'
</tt></pre></code>
<p>Now we can load the module into LLDB and use it</p>
<code><pre><tt>% lldb
(lldb) <strong>command script import ~/ls.py</strong>
The "ls" python command has been installed and is ready for use.
(lldb) <strong>ls -l /tmp/</strong>
total 365848
-rw-r--r--@ 1 someuser wheel 6148 Jan 19 17:27 .DS_Store
-rw------- 1 someuser wheel 7331 Jan 19 15:37 crash.log
</tt></pre></code>
<p>A more interesting template has been created in the source repository that can help you to create
lldb command quickly:</p>
<a href="http://llvm.org/svn/llvm-project/lldb/trunk/examples/python/cmdtemplate.py">cmdtemplate.py</a>
<p>
A commonly required facility is being able to create a command that does some token substitution, and then runs a different debugger command
(usually, it po'es the result of an expression evaluated on its argument). For instance, given the following program:
<code><pre><tt>
#import <Foundation/Foundation.h>
NSString*
ModifyString(NSString* src)
{
return [src stringByAppendingString:@"foobar"];
}
int main()
{
NSString* aString = @"Hello world";
NSString* anotherString = @"Let's be friends";
return 1;
}
</tt></pre></code>
you may want a pofoo X command, that equates po [ModifyString(X) capitalizedString].
The following debugger interaction shows how to achieve that goal:
<code><pre><tt>
(lldb) <b>script</b>
Python Interactive Interpreter. To exit, type 'quit()', 'exit()' or Ctrl-D.
>>> <b>def pofoo_funct(debugger, command, result, internal_dict):</b>
... <b>cmd = "po [ModifyString(" + command + ") capitalizedString]"</b>
... <b>lldb.debugger.HandleCommand(cmd)</b>
...
>>> ^D
(lldb) <b>command script add pofoo -f pofoo_funct</b>
(lldb) <b>pofoo aString</b>
$1 = 0x000000010010aa00 Hello Worldfoobar
(lldb) <b>pofoo anotherString</b>
$2 = 0x000000010010aba0 Let's Be Friendsfoobar</tt></pre></code>
</div>
<div class="post">
<h1 class ="postheader">Using the lldb.py module in python</h1>
<div class="postcontent">
<p>LLDB has all of its core code build into a shared library which gets
used by the <b>lldb</b> command line application. On Mac OS X this
shared library is a framework: <b>LLDB.framework</b> and on other
unix variants the program is a shared library: <b>lldb.so</b>. LLDB also
provides an lldb.py module that contains the bindings from LLDB into Python.
To use the
<b>LLDB.framework</b> to create your own stand-alone python programs, you will
need to tell python where to look in order to find this module. This
is done by setting the <b>PYTHONPATH</b> environment variable, adding
a path to the directory that contains the <b>lldb.py</b> python module. The
lldb driver program has an option to report the path to the lldb module.
You can use that to point to correct lldb.py:
<p>For csh and tcsh:</p>
<p><code>% <b>setenv PYTHONPATH `lldb -P`</b></p>
<p>For sh and bash:
<p><code>% <b>export PYTHONPATH=`lldb -P`</b></p>
<p> Alternately, you can append the LLDB Python directory to the <b>sys.path</b> list directly in
your Python code before importing the lldb module.</p>
<p>
Now your python scripts are ready to import the lldb module. Below is a
python script that will launch a program from the current working directory
called "a.out", set a breakpoint at "main", and then run and hit the breakpoint,
and print the process, thread and frame objects if the process stopped:
</p>
<code><pre><tt><font color=green>#!/usr/bin/python</font>
import lldb
import os
def disassemble_instructions(insts):
for i in insts:
print i
<font color=green># Set the path to the executable to debug</font>
exe = "./a.out"
<font color=green># Create a new debugger instance</font>
debugger = lldb.SBDebugger.Create()
<font color=green># When we step or continue, don't return from the function until the process
# stops. Otherwise we would have to handle the process events ourselves which, while doable is
#a little tricky. We do this by setting the async mode to false.</font>
debugger.SetAsync (False)
<font color=green># Create a target from a file and arch</font>
print "Creating a target for '%s'" % exe
target = debugger.CreateTargetWithFileAndArch (exe, lldb.LLDB_ARCH_DEFAULT)
if target:
<font color=green># If the target is valid set a breakpoint at main</font>
main_bp = target.BreakpointCreateByName ("main", target.GetExecutable().GetFilename());
print main_bp
<font color=green># Launch the process. Since we specified synchronous mode, we won't return
# from this function until we hit the breakpoint at main</font>
process = target.LaunchSimple (None, None, os.getcwd())
<font color=green># Make sure the launch went ok</font>
if process:
<font color=green># Print some simple process info</font>
state = process.GetState ()
print process
if state == lldb.eStateStopped:
<font color=green># Get the first thread</font>
thread = process.GetThreadAtIndex (0)
if thread:
<font color=green># Print some simple thread info</font>
print thread
<font color=green># Get the first frame</font>
frame = thread.GetFrameAtIndex (0)
if frame:
<font color=green># Print some simple frame info</font>
print frame
function = frame.GetFunction()
<font color=green># See if we have debug info (a function)</font>
if function:
<font color=green># We do have a function, print some info for the function</font>
print function
<font color=green># Now get all instructions for this function and print them</font>
insts = function.GetInstructions(target)
disassemble_instructions (insts)
else:
<font color=green># See if we have a symbol in the symbol table for where we stopped</font>
symbol = frame.GetSymbol();
if symbol:
<font color=green># We do have a symbol, print some info for the symbol</font>
print symbol
</tt></pre></code>
</div>
<div class="postfooter"></div>
</div>
</div>
</div>
</body>
</html>
|
