]>
git.saurik.com Git - apple/xnu.git/blob - tools/lldbmacros/core/kernelcore.py
da145a437dd2c1a237088f55b8dc5266306df181
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.
7 from lazytarget
import *
8 from configuration
import *
12 def IterateTAILQ_HEAD(headval
, element_name
):
13 """ iterate over a TAILQ_HEAD in kernel. refer to bsd/sys/queue.h
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.
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
21 list_head = kern.GetGlobalVariable('mountlist')
22 for entryobj in IterateTAILQ_HEAD(list_head, 'mnt_list'):
23 print GetEntrySummary(entryobj)
25 iter_val
= headval
.tqh_first
26 while unsigned(iter_val
) != 0 :
28 iter_val
= iter_val
.__getattr
__(element_name
).tqe_next
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>; }
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
39 first_zone = kern.GetGlobalVariable('first_zone')
40 for zone in IterateLinkedList(first_zone, 'next_zone'):
41 print GetZoneSummary(zone)
44 while unsigned(elt
) != 0:
46 elt
= elt
.__getattr
__(field_name
)
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
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
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
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:
64 next_el
= elt
.__getattr
__(field_name
).__getattr
__(slist_prefix
+ 'sle_next')
65 elt
= cast(next_el
, element_type
)
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
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
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
77 headp = kern.globals.initproc.p_children
78 for pp in IterateListEntry(headp, 'struct proc *', 'p_sibling'):
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:
86 next_el
= elt
.__getattr
__(field_name
).__getattr
__(list_prefix
+ 'le_next')
87 elt
= cast(next_el
, element_type
)
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
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
100 A generator does not return. It is used for iterating.
101 value : An object thats of type (element_type). Always a pointer object
103 coalq = kern.GetGlobalVariable('coalitions_q')
104 for coal in IterateLinkageChain(coalq, 'struct coalition *', 'coalitions'):
105 print GetCoalitionInfo(coal)
108 if type(element_type
) == str:
109 element_type
= gettype(element_type
)
111 if unsigned(queue_head
) == 0:
114 if element_type
.IsPointerType():
115 elem_ofst
= getfieldoffset(element_type
.GetPointeeType(), field_name
) + field_ofst
117 elem_ofst
= getfieldoffset(element_type
, field_name
) + field_ofst
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
)
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)
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.
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
143 for page_meta in IterateQueue(kern.globals.first_zone.pages.all_free, 'struct zone_page_metadata *', 'pages'):
146 if type(element_ptr_type
) == str :
147 element_ptr_type
= gettype(element_ptr_type
)
149 queue_head
= queue_head
.GetSBValue()
150 queue_head_addr
= 0x0
151 if queue_head
.TypeIsPointerType():
152 queue_head_addr
= queue_head
.GetValueAsUnsigned()
154 queue_head_addr
= queue_head
.GetAddress().GetLoadAddress(LazyTarget
.GetTarget())
156 def unpack_ptr_and_recast(v
):
157 if unpack_ptr_fn
is None:
159 v_unpacked
= unpack_ptr_fn(v
.GetValueAsUnsigned())
160 obj
= v
.CreateValueFromExpression(None,'(void *)'+str(v_unpacked
))
161 obj
.Cast(element_ptr_type
)
165 cur_elt
= unpack_ptr_and_recast(queue_head
.GetChildMemberWithName('prev'))
167 cur_elt
= unpack_ptr_and_recast(queue_head
.GetChildMemberWithName('next'))
171 if not cur_elt
.IsValid() or cur_elt
.GetValueAsUnsigned() == 0 or cur_elt
.GetValueAsUnsigned() == queue_head_addr
:
173 elt
= cur_elt
.Cast(element_ptr_type
)
176 cur_elt
= unpack_ptr_and_recast(elt
.GetChildMemberWithName(element_field_name
).GetChildMemberWithName('prev'))
178 cur_elt
= unpack_ptr_and_recast(elt
.GetChildMemberWithName(element_field_name
).GetChildMemberWithName('next'))
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.
186 def __init__(self
, debugger
):
187 """ Initialize the kernel debugging environment.
188 Target properties like architecture and connectedness are lazy-evaluted.
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
= []
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.
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
_12obscure
12 = kern
207 def __getattr__(self
, name
):
208 v
= self
._xnu
_kernobj
_12obscure
12.GetGlobalVariable(name
)
209 if not v
.GetSBValue().IsValid():
210 raise ValueError('No such global variable by name: %s '%str
(name
))
212 self
.globals = _GlobalVariableFind(self
)
213 LazyTarget
.Initialize(debugger
)
215 def _GetSymbolicator(self
):
216 """ Internal function: To initialize the symbolication from lldb.utils
218 if not self
.symbolicator
is None:
219 return self
.symbolicator
221 from lldb
.utils
import symbolication
222 symbolicator
= symbolication
.Symbolicator()
223 symbolicator
.target
= LazyTarget
.GetTarget()
224 self
.symbolicator
= symbolicator
225 return self
.symbolicator
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'
230 addr - int : typically hex value like 0xffffff80002c0df0
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()
236 syms
= self
.SymbolicateFromAddress(addr
)
238 ret_str
+=syms
[0].GetName()
241 def SymbolicateFromAddress(self
, addr
):
242 """ symbolicates any given address based on modules loaded in the target.
244 addr - int : typically hex value like 0xffffff80002c0df0
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.
249 syms = kern.Symbolicate(0xffffff80002c0df0)
251 if s.GetType() == lldb.eSymbolTypeCode:
252 print "Function", s.GetName()
253 if s.GetType() == lldb.eSymbolTypeData:
254 print "Variable", s.GetName()
256 if type(int(1)) != type(addr
):
257 if str(addr
).strip().find("0x") == 0 :
262 symbolicator
= self
._GetSymbolicator
()
263 syms
= symbolicator
.symbolicate(addr
)
267 ret_array
.append(s
.get_symbol_context().symbol
)
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
275 def GetGlobalVariable(self
, name
):
276 """ Get the value object representation for a kernel global variable
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.
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
]
287 def GetLoadAddressForSymbol(self
, name
):
288 """ Get the load address of a symbol in the kernel.
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.
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()
300 return int(symbol
.GetStartAddress().GetLoadAddress(target
))
302 raise LookupError("Symbol not found: " + name
)
304 def GetValueFromAddress(self
, addr
, type_str
= 'void *'):
305 """ convert a address to value
307 addr - int : typically hex value like 0xffffff80008dc390
308 type_str - str: type to cast to. Default type will be void *
310 value : a value object which has address as addr and type is type_str
312 obj
= value(self
.globals.version
.GetSBValue().CreateValueFromExpression(None,'(void *)'+str(addr
)))
313 obj
= cast(obj
, type_str
)
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.
321 NameError - If 'v' cannot be found
322 TypeError - If 'v' is of the wrong type
325 return self
.GetValueFromAddress(v
, t
)
327 var
= LazyTarget
.GetTarget().FindGlobalVariables(v
, 1)[0]
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()))
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.
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.
341 iterable : typically used in conjunction with "for varname in iterable:"
343 head_element
= self
.GetGlobalVariable(iter_head_name
)
344 return head_element
.GetSBValue().linked_list_iter(next_element_name
)
346 def TruncPage(self
, addr
):
347 return (addr
& ~
(unsigned(self
.GetGlobalVariable("page_size")) - 1))
349 def RoundPage(self
, addr
):
350 return trunc_page(addr
+ unsigned(self
.GetGlobalVariable("page_size")) - 1)
352 def StraddlesPage(self
, addr
, size
):
353 if size
> unsigned(self
.GetGlobalVariable("page_size")):
355 val
= ((addr
+ size
) & (unsigned(self
.GetGlobalVariable("page_size"))-1))
356 return (val
< size
and val
> 0)
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")))
364 raise ValueError("PhysToVirt does not support {0}".format(self
.arch
))
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.
370 abstime - int absolute time as shown by mach_absolute_time
372 int - nanosecs of time
374 usec_divisor
= caching
.GetStaticCacheData("kern.rtc_usec_divisor", None)
376 if self
.arch
== 'x86_64':
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
387 def __getattribute__(self
, name
):
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
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
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
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
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
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
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 *')
458 self
._allproc
.append(proc_val
)
459 proc_val
= cast(proc_val
.p_list
.le_next
, 'proc *')
460 caching
.SaveDynamicCacheData("kern._allproc", self
._allproc
)
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
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 *')
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
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
)
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'):
500 caching
.SaveStaticCacheData("kern.arch", self
._arch
)
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'):
511 caching
.SaveStaticCacheData("kern.ptrsize", self
._ptrsize
)
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)
520 return unsigned(0x80000000)
522 if name
== 'VM_MIN_KERNEL_AND_KEXT_ADDRESS':
523 if self
.arch
== 'x86_64':
524 return self
.VM_MIN_KERNEL_ADDRESS
- 0x80000000
526 return self
.VM_MIN_KERNEL_ADDRESS
528 return object.__getattribute
__(self
, name
)