1#############################################################################
2# This script contains two trivial examples of simple "scripted step" classes.
3# To fully understand how the lldb "Thread Plan" architecture works, read the
4# comments at the beginning of ThreadPlan.h in the lldb sources.  The python
5# interface is a reduced version of the full internal mechanism, but captures
6# most of the power with a much simpler interface.
7#
8# But I'll attempt a brief summary here.
9# Stepping in lldb is done independently for each thread.  Moreover, the stepping
10# operations are stackable.  So for instance if you did a "step over", and in
11# the course of stepping over you hit a breakpoint, stopped and stepped again,
12# the first "step-over" would be suspended, and the new step operation would
13# be enqueued.  Then if that step over caused the program to hit another breakpoint,
14# lldb would again suspend the second step and return control to the user, so
15# now there are two pending step overs.  Etc. with all the other stepping
16# operations.  Then if you hit "continue" the bottom-most step-over would complete,
17# and another continue would complete the first "step-over".
18#
19# lldb represents this system with a stack of "Thread Plans".  Each time a new
20# stepping operation is requested, a new plan is pushed on the stack.  When the
21# operation completes, it is pushed off the stack.
22#
23# The bottom-most plan in the stack is the immediate controller of stepping,
24# most importantly, when the process resumes, the bottom most plan will get
25# asked whether to set the program running freely, or to instruction-single-step
26# the current thread.  In the scripted interface, you indicate this by returning
27# False or True respectively from the should_step method.
28#
29# Each time the process stops the thread plan stack for each thread that stopped
30# "for a reason", Ii.e. a single-step completed on that thread, or a breakpoint
31# was hit), is queried to determine how to proceed, starting from the most
32# recently pushed plan, in two stages:
33#
34# 1) Each plan is asked if it "explains" the stop.  The first plan to claim the
35#    stop wins.  In scripted Thread Plans, this is done by returning True from
36#    the "explains_stop method.  This is how, for instance, control is returned
37#    to the User when the "step-over" plan hits a breakpoint.  The step-over
38#    plan doesn't explain the breakpoint stop, so it returns false, and the
39#    breakpoint hit is propagated up the stack to the "base" thread plan, which
40#    is the one that handles random breakpoint hits.
41#
42# 2) Then the plan that won the first round is asked if the process should stop.
43#    This is done in the "should_stop" method.  The scripted plans actually do
44#    three jobs in should_stop:
45#      a) They determine if they have completed their job or not.  If they have
46#         they indicate that by calling SetPlanComplete on their thread plan.
47#      b) They decide whether they want to return control to the user or not.
48#         They do this by returning True or False respectively.
49#      c) If they are not done, they set up whatever machinery they will use
50#         the next time the thread continues.
51#
52#    Note that deciding to return control to the user, and deciding your plan
53#    is done, are orthgonal operations.  You could set up the next phase of
54#    stepping, and then return True from should_stop, and when the user next
55#    "continued" the process your plan would resume control.  Of course, the
56#    user might also "step-over" or some other operation that would push a
57#    different plan, which would take control till it was done.
58#
59#    One other detail you should be aware of, if the plan below you on the
60#    stack was done, then it will be popped and the next plan will take control
61#    and its "should_stop" will be called.
62#
63#    Note also, there should be another method called when your plan is popped,
64#    to allow you to do whatever cleanup is required.  I haven't gotten to that
65#    yet.  For now you should do that at the same time you mark your plan complete.
66#
67# 3) After the round of negotiation over whether to stop or not is done, all the
68#    plans get asked if they are "stale".  If they are say they are stale
69#    then they will get popped.  This question is asked with the "is_stale" method.
70#
71#    This is useful, for instance, in the FinishPrintAndContinue plan.  What might
72#    happen here is that after continuing but before the finish is done, the program
73#    could hit another breakpoint and stop.  Then the user could use the step
74#    command repeatedly until they leave the frame of interest by stepping.
75#    In that case, the step plan is the one that will be responsible for stopping,
76#    and the finish plan won't be asked should_stop, it will just be asked if it
77#    is stale.  In this case, if the step_out plan that the FinishPrintAndContinue
78#    plan is driving is stale, so is ours, and it is time to do our printing.
79#
80# Both examples show stepping through an address range for 20 bytes from the
81# current PC.  The first one does it by single stepping and checking a condition.
82# It doesn't, however handle the case where you step into another frame while
83# still in the current range in the starting frame.
84#
85# That is better handled in the second example by using the built-in StepOverRange
86# thread plan.
87#
88# To use these stepping modes, you would do:
89#
90#     (lldb) command script import scripted_step.py
91#     (lldb) thread step-scripted -C scripted_step.SimpleStep
92# or
93#
94#     (lldb) thread step-scripted -C scripted_step.StepWithPlan
95
96from __future__ import print_function
97
98import lldb
99
100
101class SimpleStep:
102
103    def __init__(self, thread_plan, dict):
104        self.thread_plan = thread_plan
105        self.start_address = thread_plan.GetThread().GetFrameAtIndex(0).GetPC()
106
107    def explains_stop(self, event):
108        # We are stepping, so if we stop for any other reason, it isn't
109        # because of us.
110        if self.thread_plan.GetThread().GetStopReason() == lldb.eStopReasonTrace:
111            return True
112        else:
113            return False
114
115    def should_stop(self, event):
116        cur_pc = self.thread_plan.GetThread().GetFrameAtIndex(0).GetPC()
117
118        if cur_pc < self.start_address or cur_pc >= self.start_address + 20:
119            self.thread_plan.SetPlanComplete(True)
120            return True
121        else:
122            return False
123
124    def should_step(self):
125        return True
126
127
128class StepWithPlan:
129
130    def __init__(self, thread_plan, dict):
131        self.thread_plan = thread_plan
132        self.start_address = thread_plan.GetThread().GetFrameAtIndex(0).GetPCAddress()
133        self.step_thread_plan = thread_plan.QueueThreadPlanForStepOverRange(
134            self.start_address, 20)
135
136    def explains_stop(self, event):
137        # Since all I'm doing is running a plan, I will only ever get askedthis
138        # if myplan doesn't explain the stop, and in that caseI don'teither.
139        return False
140
141    def should_stop(self, event):
142        if self.step_thread_plan.IsPlanComplete():
143            self.thread_plan.SetPlanComplete(True)
144            return True
145        else:
146            return False
147
148    def should_step(self):
149        return False
150
151# Here's another example which does "step over" through the current function,
152# and when it stops at each line, it checks some condition (in this example the
153# value of a variable) and stops if that condition is true.
154
155
156class StepCheckingCondition:
157
158    def __init__(self, thread_plan, dict):
159        self.thread_plan = thread_plan
160        self.start_frame = thread_plan.GetThread().GetFrameAtIndex(0)
161        self.queue_next_plan()
162
163    def queue_next_plan(self):
164        cur_frame = self.thread_plan.GetThread().GetFrameAtIndex(0)
165        cur_line_entry = cur_frame.GetLineEntry()
166        start_address = cur_line_entry.GetStartAddress()
167        end_address = cur_line_entry.GetEndAddress()
168        line_range = end_address.GetFileAddress() - start_address.GetFileAddress()
169        self.step_thread_plan = self.thread_plan.QueueThreadPlanForStepOverRange(
170            start_address, line_range)
171
172    def explains_stop(self, event):
173        # We are stepping, so if we stop for any other reason, it isn't
174        # because of us.
175        return False
176
177    def should_stop(self, event):
178        if not self.step_thread_plan.IsPlanComplete():
179            return False
180
181        frame = self.thread_plan.GetThread().GetFrameAtIndex(0)
182        if not self.start_frame.IsEqual(frame):
183            self.thread_plan.SetPlanComplete(True)
184            return True
185
186        # This part checks the condition.  In this case we are expecting
187        # some integer variable called "a", and will stop when it is 20.
188        a_var = frame.FindVariable("a")
189
190        if not a_var.IsValid():
191            print("A was not valid.")
192            return True
193
194        error = lldb.SBError()
195        a_value = a_var.GetValueAsSigned(error)
196        if not error.Success():
197            print("A value was not good.")
198            return True
199
200        if a_value == 20:
201            self.thread_plan.SetPlanComplete(True)
202            return True
203        else:
204            self.queue_next_plan()
205            return False
206
207    def should_step(self):
208        return True
209
210# Here's an example that steps out of the current frame, gathers some information
211# and then continues.  The information in this case is rax.  Currently the thread
212# plans are not a safe place to call lldb command-line commands, so the information
213# is gathered through SB API calls.
214
215
216class FinishPrintAndContinue:
217
218    def __init__(self, thread_plan, dict):
219        self.thread_plan = thread_plan
220        self.step_out_thread_plan = thread_plan.QueueThreadPlanForStepOut(
221            0, True)
222        self.thread = self.thread_plan.GetThread()
223
224    def is_stale(self):
225        if self.step_out_thread_plan.IsPlanStale():
226            self.do_print()
227            return True
228        else:
229            return False
230
231    def explains_stop(self, event):
232        return False
233
234    def should_stop(self, event):
235        if self.step_out_thread_plan.IsPlanComplete():
236            self.do_print()
237            self.thread_plan.SetPlanComplete(True)
238        return False
239
240    def do_print(self):
241        frame_0 = self.thread.frames[0]
242        rax_value = frame_0.FindRegister("rax")
243        if rax_value.GetError().Success():
244            print("RAX on exit: ", rax_value.GetValue())
245        else:
246            print("Couldn't get rax value:", rax_value.GetError().GetCString())
247