]> git.saurik.com Git - apple/xnu.git/blob - tools/lldbmacros/core/kernelcore.py
da145a437dd2c1a237088f55b8dc5266306df181
[apple/xnu.git] / tools / lldbmacros / core / kernelcore.py
1
2 """ Please make sure you read the README COMPLETELY BEFORE reading anything below.
3 It is very critical that you read coding guidelines in Section E in README file.
4 """
5
6 from cvalue import *
7 from lazytarget import *
8 from configuration import *
9 import caching
10 import lldb
11
12 def IterateTAILQ_HEAD(headval, element_name):
13 """ iterate over a TAILQ_HEAD in kernel. refer to bsd/sys/queue.h
14 params:
15 headval - value : value object representing the head of the list
16 element_name- str : string name of the field which holds the list links.
17 returns:
18 A generator does not return. It is used for iterating.
19 value : an object that is of type as headval->tqh_first. Always a pointer object
20 example usage:
21 list_head = kern.GetGlobalVariable('mountlist')
22 for entryobj in IterateTAILQ_HEAD(list_head, 'mnt_list'):
23 print GetEntrySummary(entryobj)
24 """
25 iter_val = headval.tqh_first
26 while unsigned(iter_val) != 0 :
27 yield iter_val
28 iter_val = iter_val.__getattr__(element_name).tqe_next
29 #end of yield loop
30
31 def IterateLinkedList(element, field_name):
32 """ iterate over a linked list.
33 This is equivalent to elt = element; while(elt) { do_work(elt); elt = elt-><field_name>; }
34 params:
35 element - value : value object representing element in the list.
36 field_name - str : name of field that holds pointer to next element
37 returns: Nothing. This is used as iterable
38 example usage:
39 first_zone = kern.GetGlobalVariable('first_zone')
40 for zone in IterateLinkedList(first_zone, 'next_zone'):
41 print GetZoneSummary(zone)
42 """
43 elt = element
44 while unsigned(elt) != 0:
45 yield elt
46 elt = elt.__getattr__(field_name)
47 #end of while loop
48
49 def IterateSListEntry(element, element_type, field_name, slist_prefix=''):
50 """ iterate over a list as defined with SLIST_HEAD in bsd/sys/queue.h
51 params:
52 element - value : Value object for slh_first
53 element_type - str : Type of the next element
54 field_name - str : Name of the field in next element's structure
55 returns:
56 A generator does not return. It is used for iterating
57 value : an object thats of type (element_type) head->sle_next. Always a pointer object
58 """
59 elt = element.__getattr__(slist_prefix + 'slh_first')
60 if type(element_type) == str:
61 element_type = gettype(element_type)
62 while unsigned(elt) != 0:
63 yield elt
64 next_el = elt.__getattr__(field_name).__getattr__(slist_prefix + 'sle_next')
65 elt = cast(next_el, element_type)
66
67 def IterateListEntry(element, element_type, field_name, list_prefix=''):
68 """ iterate over a list as defined with LIST_HEAD in bsd/sys/queue.h
69 params:
70 element - value : Value object for lh_first
71 element_type - str : Type of the next element
72 field_name - str : Name of the field in next element's structure
73 returns:
74 A generator does not return. It is used for iterating
75 value : an object thats of type (element_type) head->le_next. Always a pointer object
76 example usage:
77 headp = kern.globals.initproc.p_children
78 for pp in IterateListEntry(headp, 'struct proc *', 'p_sibling'):
79 print GetProcInfo(pp)
80 """
81 elt = element.__getattr__(list_prefix + 'lh_first')
82 if type(element_type) == str:
83 element_type = gettype(element_type)
84 while unsigned(elt) != 0:
85 yield elt
86 next_el = elt.__getattr__(field_name).__getattr__(list_prefix + 'le_next')
87 elt = cast(next_el, element_type)
88
89 def IterateLinkageChain(queue_head, element_type, field_name, field_ofst=0):
90 """ Iterate over a Linkage Chain queue in kernel of type queue_head_t. (osfmk/kern/queue.h method 1)
91 This is equivalent to the qe_foreach_element() macro
92 params:
93 queue_head - value : Value object for queue_head.
94 element_type - lldb.SBType : pointer type of the element which contains the queue_chain_t. Typically its structs like thread, task etc..
95 - str : OR a string describing the type. ex. 'task *'
96 field_name - str : Name of the field (in element) which holds a queue_chain_t
97 field_ofst - int : offset from the 'field_name' (in element) which holds a queue_chain_t
98 This is mostly useful if a particular element contains an array of queue_chain_t
99 returns:
100 A generator does not return. It is used for iterating.
101 value : An object thats of type (element_type). Always a pointer object
102 example usage:
103 coalq = kern.GetGlobalVariable('coalitions_q')
104 for coal in IterateLinkageChain(coalq, 'struct coalition *', 'coalitions'):
105 print GetCoalitionInfo(coal)
106 """
107 global kern
108 if type(element_type) == str:
109 element_type = gettype(element_type)
110
111 if unsigned(queue_head) == 0:
112 return
113
114 if element_type.IsPointerType():
115 elem_ofst = getfieldoffset(element_type.GetPointeeType(), field_name) + field_ofst
116 else:
117 elem_ofst = getfieldoffset(element_type, field_name) + field_ofst
118
119 link = queue_head.next
120 while (unsigned(link) != unsigned(queue_head)):
121 addr = unsigned(link) - elem_ofst;
122 # I can't use the GetValueFromAddress function of the kernel class
123 # because I have no instance of that class!
124 obj = value(link.GetSBValue().CreateValueFromExpression(None,'(void *)'+str(addr)))
125 obj = cast(obj, element_type)
126 yield obj
127 link = link.next
128
129
130 def IterateQueue(queue_head, element_ptr_type, element_field_name, backwards=False, unpack_ptr_fn=None):
131 """ Iterate over an Element Chain queue in kernel of type queue_head_t. (osfmk/kern/queue.h method 2)
132 params:
133 queue_head - value : Value object for queue_head.
134 element_ptr_type - lldb.SBType : a pointer type of the element 'next' points to. Typically its structs like thread, task etc..
135 - str : OR a string describing the type. ex. 'task *'
136 element_field_name - str : name of the field in target struct.
137 backwards - backwards : traverse the queue backwards
138 unpack_ptr_fn - function : a function ptr of signature def unpack_ptr(long v) which returns long.
139 returns:
140 A generator does not return. It is used for iterating.
141 value : an object thats of type (element_type) queue_head->next. Always a pointer object
142 example usage:
143 for page_meta in IterateQueue(kern.globals.first_zone.pages.all_free, 'struct zone_page_metadata *', 'pages'):
144 print page_meta
145 """
146 if type(element_ptr_type) == str :
147 element_ptr_type = gettype(element_ptr_type)
148
149 queue_head = queue_head.GetSBValue()
150 queue_head_addr = 0x0
151 if queue_head.TypeIsPointerType():
152 queue_head_addr = queue_head.GetValueAsUnsigned()
153 else:
154 queue_head_addr = queue_head.GetAddress().GetLoadAddress(LazyTarget.GetTarget())
155
156 def unpack_ptr_and_recast(v):
157 if unpack_ptr_fn is None:
158 return v
159 v_unpacked = unpack_ptr_fn(v.GetValueAsUnsigned())
160 obj = v.CreateValueFromExpression(None,'(void *)'+str(v_unpacked))
161 obj.Cast(element_ptr_type)
162 return obj
163
164 if backwards:
165 cur_elt = unpack_ptr_and_recast(queue_head.GetChildMemberWithName('prev'))
166 else:
167 cur_elt = unpack_ptr_and_recast(queue_head.GetChildMemberWithName('next'))
168
169 while True:
170
171 if not cur_elt.IsValid() or cur_elt.GetValueAsUnsigned() == 0 or cur_elt.GetValueAsUnsigned() == queue_head_addr:
172 break
173 elt = cur_elt.Cast(element_ptr_type)
174 yield value(elt)
175 if backwards:
176 cur_elt = unpack_ptr_and_recast(elt.GetChildMemberWithName(element_field_name).GetChildMemberWithName('prev'))
177 else:
178 cur_elt = unpack_ptr_and_recast(elt.GetChildMemberWithName(element_field_name).GetChildMemberWithName('next'))
179
180
181 class KernelTarget(object):
182 """ A common kernel object that provides access to kernel objects and information.
183 The class holds global lists for task, terminated_tasks, procs, zones, zombroc etc.
184 It also provides a way to symbolicate an address or create a value from an address.
185 """
186 def __init__(self, debugger):
187 """ Initialize the kernel debugging environment.
188 Target properties like architecture and connectedness are lazy-evaluted.
189 """
190 self._debugger = debugger # This holds an lldb.SBDebugger object for debugger state
191 self._threads_list = []
192 self._tasks_list = []
193 self._coalitions_list = []
194 self._thread_groups = []
195 self._allproc = []
196 self._terminated_tasks_list = []
197 self._zones_list = []
198 self._zombproc_list = []
199 self._kernel_types_cache = {} #this will cache the Type objects as and when requested.
200 self._version = None
201 self._arch = None
202 self._ptrsize = None # pointer size of kernel, not userspace
203 self.symbolicator = None
204 class _GlobalVariableFind(object):
205 def __init__(self, kern):
206 self._xnu_kernobj_12obscure12 = kern
207 def __getattr__(self, name):
208 v = self._xnu_kernobj_12obscure12.GetGlobalVariable(name)
209 if not v.GetSBValue().IsValid():
210 raise ValueError('No such global variable by name: %s '%str(name))
211 return v
212 self.globals = _GlobalVariableFind(self)
213 LazyTarget.Initialize(debugger)
214
215 def _GetSymbolicator(self):
216 """ Internal function: To initialize the symbolication from lldb.utils
217 """
218 if not self.symbolicator is None:
219 return self.symbolicator
220
221 from lldb.utils import symbolication
222 symbolicator = symbolication.Symbolicator()
223 symbolicator.target = LazyTarget.GetTarget()
224 self.symbolicator = symbolicator
225 return self.symbolicator
226
227 def Symbolicate(self, addr):
228 """ simple method to get name of function/variable from an address. this is equivalent of gdb 'output /a 0xaddress'
229 params:
230 addr - int : typically hex value like 0xffffff80002c0df0
231 returns:
232 str - '' if no symbol found else the symbol name.
233 Note: this function only finds the first symbol. If you expect multiple symbol conflict please use SymbolicateFromAddress()
234 """
235 ret_str = ''
236 syms = self.SymbolicateFromAddress(addr)
237 if len(syms) > 0:
238 ret_str +=syms[0].GetName()
239 return ret_str
240
241 def SymbolicateFromAddress(self, addr):
242 """ symbolicates any given address based on modules loaded in the target.
243 params:
244 addr - int : typically hex value like 0xffffff80002c0df0
245 returns:
246 [] of SBSymbol: In case we don't find anything than empty array is returned.
247 Note: a type of symbol can be figured out by gettype() function of SBSymbol.
248 example usage:
249 syms = kern.Symbolicate(0xffffff80002c0df0)
250 for s in syms:
251 if s.GetType() == lldb.eSymbolTypeCode:
252 print "Function", s.GetName()
253 if s.GetType() == lldb.eSymbolTypeData:
254 print "Variable", s.GetName()
255 """
256 if type(int(1)) != type(addr):
257 if str(addr).strip().find("0x") == 0 :
258 addr = int(addr, 16)
259 else:
260 addr = int(addr)
261 ret_array = []
262 symbolicator = self._GetSymbolicator()
263 syms = symbolicator.symbolicate(addr)
264 if not syms:
265 return ret_array
266 for s in syms:
267 ret_array.append(s.get_symbol_context().symbol)
268 return ret_array
269
270 def IsDebuggerConnected(self):
271 proc_state = LazyTarget.GetProcess().state
272 if proc_state == lldb.eStateInvalid : return False
273 if proc_state in [lldb.eStateStopped, lldb.eStateSuspended] : return True
274
275 def GetGlobalVariable(self, name):
276 """ Get the value object representation for a kernel global variable
277 params:
278 name : str - name of the variable. ex. version
279 returns: value - python object representing global variable.
280 raises : Exception in case the variable is not found.
281 """
282 self._globals_cache_dict = caching.GetDynamicCacheData("kern._globals_cache_dict", {})
283 if name not in self._globals_cache_dict:
284 self._globals_cache_dict[name] = value(LazyTarget.GetTarget().FindGlobalVariables(name, 1).GetValueAtIndex(0))
285 return self._globals_cache_dict[name]
286
287 def GetLoadAddressForSymbol(self, name):
288 """ Get the load address of a symbol in the kernel.
289 params:
290 name : str - name of the symbol to lookup
291 returns: int - the load address as an integer. Use GetValueFromAddress to cast to a value.
292 raises : LookupError - if the symbol is not found.
293 """
294 name = str(name)
295 target = LazyTarget.GetTarget()
296 syms_arr = target.FindSymbols(name)
297 if syms_arr.IsValid() and len(syms_arr) > 0:
298 symbol = syms_arr[0].GetSymbol()
299 if symbol.IsValid():
300 return int(symbol.GetStartAddress().GetLoadAddress(target))
301
302 raise LookupError("Symbol not found: " + name)
303
304 def GetValueFromAddress(self, addr, type_str = 'void *'):
305 """ convert a address to value
306 params:
307 addr - int : typically hex value like 0xffffff80008dc390
308 type_str - str: type to cast to. Default type will be void *
309 returns:
310 value : a value object which has address as addr and type is type_str
311 """
312 obj = value(self.globals.version.GetSBValue().CreateValueFromExpression(None,'(void *)'+str(addr)))
313 obj = cast(obj, type_str)
314 return obj
315
316 def GetValueAsType(self, v, t):
317 """ Retrieves a global variable 'v' of type 't' wrapped in a vue object.
318 If 'v' is an address, creates a vue object of the appropriate type.
319 If 'v' is a name, looks for the global variable and asserts its type.
320 Throws:
321 NameError - If 'v' cannot be found
322 TypeError - If 'v' is of the wrong type
323 """
324 if islong(v):
325 return self.GetValueFromAddress(v, t)
326 else:
327 var = LazyTarget.GetTarget().FindGlobalVariables(v, 1)[0]
328 if not var:
329 raise NameError("Failed to find global variable '{0}'".format(v))
330 if var.GetTypeName() != t:
331 raise TypeError("{0} must be of type '{1}', not '{2}'".format(v, t, var.GetTypeName()))
332 return value(var)
333
334 def _GetIterator(self, iter_head_name, next_element_name='next', iter_head_type=None):
335 """ returns an iterator for a collection in kernel memory.
336 params:
337 iter_head_name - str : name of queue_head or list head variable.
338 next_element_name - str : name of the element that leads to next element.
339 for ex. in struct zone list 'next_zone' is the linking element.
340 returns:
341 iterable : typically used in conjunction with "for varname in iterable:"
342 """
343 head_element = self.GetGlobalVariable(iter_head_name)
344 return head_element.GetSBValue().linked_list_iter(next_element_name)
345
346 def TruncPage(self, addr):
347 return (addr & ~(unsigned(self.GetGlobalVariable("page_size")) - 1))
348
349 def RoundPage(self, addr):
350 return trunc_page(addr + unsigned(self.GetGlobalVariable("page_size")) - 1)
351
352 def StraddlesPage(self, addr, size):
353 if size > unsigned(self.GetGlobalVariable("page_size")):
354 return True
355 val = ((addr + size) & (unsigned(self.GetGlobalVariable("page_size"))-1))
356 return (val < size and val > 0)
357
358 def PhysToKernelVirt(self, addr):
359 if self.arch == 'x86_64':
360 return (addr + unsigned(self.GetGlobalVariable('physmap_base')))
361 elif self.arch.startswith('arm'):
362 return (addr - unsigned(self.GetGlobalVariable("gPhysBase")) + unsigned(self.GetGlobalVariable("gVirtBase")))
363 else:
364 raise ValueError("PhysToVirt does not support {0}".format(self.arch))
365
366 def GetNanotimeFromAbstime(self, abstime):
367 """ convert absolute time (which is in MATUs) to nano seconds.
368 Since based on architecture the conversion may differ.
369 params:
370 abstime - int absolute time as shown by mach_absolute_time
371 returns:
372 int - nanosecs of time
373 """
374 usec_divisor = caching.GetStaticCacheData("kern.rtc_usec_divisor", None)
375 if not usec_divisor:
376 if self.arch == 'x86_64':
377 usec_divisor = 1000
378 else:
379 rtclockdata_addr = self.GetLoadAddressForSymbol('RTClockData')
380 rtc = self.GetValueFromAddress(rtclockdata_addr, 'struct _rtclock_data_ *')
381 usec_divisor = unsigned(rtc.rtc_usec_divisor)
382 usec_divisor = int(usec_divisor)
383 caching.SaveStaticCacheData('kern.rtc_usec_divisor', usec_divisor)
384 nsecs = (abstime * 1000)/usec_divisor
385 return nsecs
386
387 def __getattribute__(self, name):
388 if name == 'zones' :
389 self._zones_list = caching.GetDynamicCacheData("kern._zones_list", [])
390 if len(self._zones_list) > 0: return self._zones_list
391 zone_array = self.GetGlobalVariable('zone_array')
392 for i in range(0, self.GetGlobalVariable('num_zones')):
393 self._zones_list.append(addressof(zone_array[i]))
394 caching.SaveDynamicCacheData("kern._zones_list", self._zones_list)
395 return self._zones_list
396
397 if name == 'threads' :
398 self._threads_list = caching.GetDynamicCacheData("kern._threads_list", [])
399 if len(self._threads_list) > 0 : return self._threads_list
400 thread_queue_head = self.GetGlobalVariable('threads')
401 thread_type = LazyTarget.GetTarget().FindFirstType('thread')
402 thread_ptr_type = thread_type.GetPointerType()
403 for th in IterateQueue(thread_queue_head, thread_ptr_type, 'threads'):
404 self._threads_list.append(th)
405 caching.SaveDynamicCacheData("kern._threads_list", self._threads_list)
406 return self._threads_list
407
408 if name == 'tasks' :
409 self._tasks_list = caching.GetDynamicCacheData("kern._tasks_list", [])
410 if len(self._tasks_list) > 0 : return self._tasks_list
411 task_queue_head = self.GetGlobalVariable('tasks')
412 task_type = LazyTarget.GetTarget().FindFirstType('task')
413 task_ptr_type = task_type.GetPointerType()
414 for tsk in IterateQueue(task_queue_head, task_ptr_type, 'tasks'):
415 self._tasks_list.append(tsk)
416 caching.SaveDynamicCacheData("kern._tasks_list", self._tasks_list)
417 return self._tasks_list
418
419 if name == 'coalitions' :
420 self._coalitions_list = caching.GetDynamicCacheData("kern._coalitions_list", [])
421 if len(self._coalitions_list) > 0 : return self._coalitions_list
422 coalition_queue_head = self.GetGlobalVariable('coalitions_q')
423 coalition_type = LazyTarget.GetTarget().FindFirstType('coalition')
424 coalition_ptr_type = coalition_type.GetPointerType()
425 for coal in IterateLinkageChain(addressof(coalition_queue_head), coalition_ptr_type, 'coalitions'):
426 self._coalitions_list.append(coal)
427 caching.SaveDynamicCacheData("kern._coalitions_list", self._coalitions_list)
428 return self._coalitions_list
429
430 if name == 'thread_groups' :
431 self._thread_groups_list = caching.GetDynamicCacheData("kern._thread_groups_list", [])
432 if len(self._thread_groups_list) > 0 : return self._thread_groups_list
433 thread_groups_queue_head = self.GetGlobalVariable('tg_queue')
434 thread_group_type = LazyTarget.GetTarget().FindFirstType('thread_group')
435 thread_groups_ptr_type = thread_group_type.GetPointerType()
436 for coal in IterateLinkageChain(addressof(thread_groups_queue_head), thread_groups_ptr_type, 'tg_queue_chain'):
437 self._thread_groups_list.append(coal)
438 caching.SaveDynamicCacheData("kern._thread_groups_list", self._thread_groups_list)
439 return self._thread_groups_list
440
441 if name == 'terminated_tasks' :
442 self._terminated_tasks_list = caching.GetDynamicCacheData("kern._terminated_tasks_list", [])
443 if len(self._terminated_tasks_list) > 0 : return self._terminated_tasks_list
444 task_queue_head = self.GetGlobalVariable('terminated_tasks')
445 task_type = LazyTarget.GetTarget().FindFirstType('task')
446 task_ptr_type = task_type.GetPointerType()
447 for tsk in IterateQueue(task_queue_head, task_ptr_type, 'tasks'):
448 self._terminated_tasks_list.append(tsk)
449 caching.SaveDynamicCacheData("kern._terminated_tasks_list", self._terminated_tasks_list)
450 return self._terminated_tasks_list
451
452 if name == 'procs' :
453 self._allproc = caching.GetDynamicCacheData("kern._allproc", [])
454 if len(self._allproc) > 0 : return self._allproc
455 all_proc_head = self.GetGlobalVariable('allproc')
456 proc_val = cast(all_proc_head.lh_first, 'proc *')
457 while proc_val != 0:
458 self._allproc.append(proc_val)
459 proc_val = cast(proc_val.p_list.le_next, 'proc *')
460 caching.SaveDynamicCacheData("kern._allproc", self._allproc)
461 return self._allproc
462
463 if name == 'interrupt_stats' :
464 self._interrupt_stats_list = caching.GetDynamicCacheData("kern._interrupt_stats_list", [])
465 if len(self._interrupt_stats_list) > 0 : return self._interrupt_stats_list
466 interrupt_stats_head = self.GetGlobalVariable('gInterruptAccountingDataList')
467 interrupt_stats_type = LazyTarget.GetTarget().FindFirstType('IOInterruptAccountingData')
468 interrupt_stats_ptr_type = interrupt_stats_type.GetPointerType()
469 for interrupt_stats_obj in IterateQueue(interrupt_stats_head, interrupt_stats_ptr_type, 'chain'):
470 self._interrupt_stats_list.append(interrupt_stats_obj)
471 caching.SaveDynamicCacheData("kern._interrupt_stats", self._interrupt_stats_list)
472 return self._interrupt_stats_list
473
474 if name == 'zombprocs' :
475 self._zombproc_list = caching.GetDynamicCacheData("kern._zombproc_list", [])
476 if len(self._zombproc_list) > 0 : return self._zombproc_list
477 zproc_head = self.GetGlobalVariable('zombproc')
478 proc_val = cast(zproc_head.lh_first, 'proc *')
479 while proc_val != 0:
480 self._zombproc_list.append(proc_val)
481 proc_val = cast(proc_val.p_list.le_next, 'proc *')
482 caching.SaveDynamicCacheData("kern._zombproc_list", self._zombproc_list)
483 return self._zombproc_list
484
485 if name == 'version' :
486 self._version = caching.GetStaticCacheData("kern.version", None)
487 if self._version != None : return self._version
488 self._version = str(self.GetGlobalVariable('version'))
489 caching.SaveStaticCacheData("kern.version", self._version)
490 return self._version
491
492 if name == 'arch' :
493 self._arch = caching.GetStaticCacheData("kern.arch", None)
494 if self._arch != None : return self._arch
495 arch = LazyTarget.GetTarget().triple.split('-')[0]
496 if arch in ('armv7', 'armv7s', 'armv7k'):
497 self._arch = 'arm'
498 else:
499 self._arch = arch
500 caching.SaveStaticCacheData("kern.arch", self._arch)
501 return self._arch
502
503 if name == 'ptrsize' :
504 self._ptrsize = caching.GetStaticCacheData("kern.ptrsize", None)
505 if self._ptrsize != None : return self._ptrsize
506 arch = LazyTarget.GetTarget().triple.split('-')[0]
507 if arch in ('x86_64', 'arm64'):
508 self._ptrsize = 8
509 else:
510 self._ptrsize = 4
511 caching.SaveStaticCacheData("kern.ptrsize", self._ptrsize)
512 return self._ptrsize
513
514 if name == 'VM_MIN_KERNEL_ADDRESS':
515 if self.arch == 'x86_64':
516 return unsigned(0xFFFFFF8000000000)
517 elif self.arch == 'arm64':
518 return unsigned(0xffffffe000000000)
519 else:
520 return unsigned(0x80000000)
521
522 if name == 'VM_MIN_KERNEL_AND_KEXT_ADDRESS':
523 if self.arch == 'x86_64':
524 return self.VM_MIN_KERNEL_ADDRESS - 0x80000000
525 else:
526 return self.VM_MIN_KERNEL_ADDRESS
527
528 return object.__getattribute__(self, name)