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