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
96import lldb
97
98
99class SimpleStep:
100
101    def __init__(self, thread_plan, dict):
102        self.thread_plan = thread_plan
103        self.start_address = thread_plan.GetThread().GetFrameAtIndex(0).GetPC()
104
105    def explains_stop(self, event):
106        # We are stepping, so if we stop for any other reason, it isn't
107        # because of us.
108        if self.thread_plan.GetThread().GetStopReason() == lldb.eStopReasonTrace:
109            return True
110        else:
111            return False
112
113    def should_stop(self, event):
114        cur_pc = self.thread_plan.GetThread().GetFrameAtIndex(0).GetPC()
115
116        if cur_pc < self.start_address or cur_pc >= self.start_address + 20:
117            self.thread_plan.SetPlanComplete(True)
118            return True
119        else:
120            return False
121
122    def should_step(self):
123        return True
124
125
126class StepWithPlan:
127
128    def __init__(self, thread_plan, dict):
129        self.thread_plan = thread_plan
130        self.start_address = thread_plan.GetThread().GetFrameAtIndex(0).GetPCAddress()
131        self.step_thread_plan = thread_plan.QueueThreadPlanForStepOverRange(
132            self.start_address, 20)
133
134    def explains_stop(self, event):
135        # Since all I'm doing is running a plan, I will only ever get askedthis
136        # if myplan doesn't explain the stop, and in that caseI don'teither.
137        return False
138
139    def should_stop(self, event):
140        if self.step_thread_plan.IsPlanComplete():
141            self.thread_plan.SetPlanComplete(True)
142            return True
143        else:
144            return False
145
146    def should_step(self):
147        return False
148
149# Here's another example which does "step over" through the current function,
150# and when it stops at each line, it checks some condition (in this example the
151# value of a variable) and stops if that condition is true.
152
153
154class StepCheckingCondition:
155
156    def __init__(self, thread_plan, dict):
157        self.thread_plan = thread_plan
158        self.start_frame = thread_plan.GetThread().GetFrameAtIndex(0)
159        self.queue_next_plan()
160
161    def queue_next_plan(self):
162        cur_frame = self.thread_plan.GetThread().GetFrameAtIndex(0)
163        cur_line_entry = cur_frame.GetLineEntry()
164        start_address = cur_line_entry.GetStartAddress()
165        end_address = cur_line_entry.GetEndAddress()
166        line_range = end_address.GetFileAddress() - start_address.GetFileAddress()
167        self.step_thread_plan = self.thread_plan.QueueThreadPlanForStepOverRange(
168            start_address, line_range)
169
170    def explains_stop(self, event):
171        # We are stepping, so if we stop for any other reason, it isn't
172        # because of us.
173        return False
174
175    def should_stop(self, event):
176        if not self.step_thread_plan.IsPlanComplete():
177            return False
178
179        frame = self.thread_plan.GetThread().GetFrameAtIndex(0)
180        if not self.start_frame.IsEqual(frame):
181            self.thread_plan.SetPlanComplete(True)
182            return True
183
184        # This part checks the condition.  In this case we are expecting
185        # some integer variable called "a", and will stop when it is 20.
186        a_var = frame.FindVariable("a")
187
188        if not a_var.IsValid():
189            print("A was not valid.")
190            return True
191
192        error = lldb.SBError()
193        a_value = a_var.GetValueAsSigned(error)
194        if not error.Success():
195            print("A value was not good.")
196            return True
197
198        if a_value == 20:
199            self.thread_plan.SetPlanComplete(True)
200            return True
201        else:
202            self.queue_next_plan()
203            return False
204
205    def should_step(self):
206        return True
207
208# Here's an example that steps out of the current frame, gathers some information
209# and then continues.  The information in this case is rax.  Currently the thread
210# plans are not a safe place to call lldb command-line commands, so the information
211# is gathered through SB API calls.
212
213
214class FinishPrintAndContinue:
215
216    def __init__(self, thread_plan, dict):
217        self.thread_plan = thread_plan
218        self.step_out_thread_plan = thread_plan.QueueThreadPlanForStepOut(
219            0, True)
220        self.thread = self.thread_plan.GetThread()
221
222    def is_stale(self):
223        if self.step_out_thread_plan.IsPlanStale():
224            self.do_print()
225            return True
226        else:
227            return False
228
229    def explains_stop(self, event):
230        return False
231
232    def should_stop(self, event):
233        if self.step_out_thread_plan.IsPlanComplete():
234            self.do_print()
235            self.thread_plan.SetPlanComplete(True)
236        return False
237
238    def do_print(self):
239        frame_0 = self.thread.frames[0]
240        rax_value = frame_0.FindRegister("rax")
241        if rax_value.GetError().Success():
242            print("RAX on exit: ", rax_value.GetValue())
243        else:
244            print("Couldn't get rax value:", rax_value.GetError().GetCString())
245