1#!/usr/bin/python
2
3#----------------------------------------------------------------------
4# Be sure to add the python path that points to the LLDB shared library.
5#
6# To use this in the embedded python interpreter using "lldb":
7#
8#   cd /path/containing/crashlog.py
9#   lldb
10#   (lldb) script import crashlog
11#   "crashlog" command installed, type "crashlog --help" for detailed help
12#   (lldb) crashlog ~/Library/Logs/DiagnosticReports/a.crash
13#
14# The benefit of running the crashlog command inside lldb in the
15# embedded python interpreter is when the command completes, there
16# will be a target with all of the files loaded at the locations
17# described in the crash log. Only the files that have stack frames
18# in the backtrace will be loaded unless the "--load-all" option
19# has been specified. This allows users to explore the program in the
20# state it was in right at crash time.
21#
22# On MacOSX csh, tcsh:
23#   ( setenv PYTHONPATH /path/to/LLDB.framework/Resources/Python ; ./crashlog.py ~/Library/Logs/DiagnosticReports/a.crash )
24#
25# On MacOSX sh, bash:
26#   PYTHONPATH=/path/to/LLDB.framework/Resources/Python ./crashlog.py ~/Library/Logs/DiagnosticReports/a.crash
27#----------------------------------------------------------------------
28
29import lldb
30import commands
31import optparse
32import os
33import plistlib
34import re
35import shlex
36import sys
37import time
38import uuid
39
40class Address:
41    """Class that represents an address that will be symbolicated"""
42    def __init__(self, target, load_addr):
43        self.target = target
44        self.load_addr = load_addr # The load address that this object represents
45        self.so_addr = None # the resolved lldb.SBAddress (if any), named so_addr for section/offset address
46        self.sym_ctx = None # The cached symbol context for this address
47        self.description = None # Any original textual description of this address to be used as a backup in case symbolication fails
48        self.symbolication = None # The cached symbolicated string that describes this address
49        self.inlined = False
50    def __str__(self):
51        s = "%#16.16x" % (self.load_addr)
52        if self.symbolication:
53            s += " %s" % (self.symbolication)
54        elif self.description:
55            s += " %s" % (self.description)
56        elif self.so_addr:
57            s += " %s" % (self.so_addr)
58        return s
59
60    def resolve_addr(self):
61        if self.so_addr == None:
62            self.so_addr = self.target.ResolveLoadAddress (self.load_addr)
63        return self.so_addr
64
65    def is_inlined(self):
66        return self.inlined
67
68    def get_symbol_context(self):
69        if self.sym_ctx == None:
70            sb_addr = self.resolve_addr()
71            if sb_addr:
72                self.sym_ctx = self.target.ResolveSymbolContextForAddress (sb_addr, lldb.eSymbolContextEverything)
73            else:
74                self.sym_ctx = lldb.SBSymbolContext()
75        return self.sym_ctx
76
77    def get_instructions(self):
78        sym_ctx = self.get_symbol_context()
79        if sym_ctx:
80            function = sym_ctx.GetFunction()
81            if function:
82                return function.GetInstructions(self.target)
83            return sym_ctx.GetSymbol().GetInstructions(self.target)
84        return None
85
86    def symbolicate(self, verbose = False):
87        if self.symbolication == None:
88            self.symbolication = ''
89            self.inlined = False
90            sym_ctx = self.get_symbol_context()
91            if sym_ctx:
92                module = sym_ctx.GetModule()
93                if module:
94                    # Print full source file path in verbose mode
95                    if verbose:
96                        self.symbolication += str(module.GetFileSpec()) + '`'
97                    else:
98                        self.symbolication += module.GetFileSpec().GetFilename() + '`'
99                    function_start_load_addr = -1
100                    function = sym_ctx.GetFunction()
101                    block = sym_ctx.GetBlock()
102                    line_entry = sym_ctx.GetLineEntry()
103                    symbol = sym_ctx.GetSymbol()
104                    inlined_block = block.GetContainingInlinedBlock();
105                    if function:
106                        self.symbolication += function.GetName()
107
108                        if inlined_block:
109                            self.inlined = True
110                            self.symbolication += ' [inlined] ' + inlined_block.GetInlinedName();
111                            block_range_idx = inlined_block.GetRangeIndexForBlockAddress (self.so_addr)
112                            if block_range_idx < lldb.UINT32_MAX:
113                                block_range_start_addr = inlined_block.GetRangeStartAddress (block_range_idx)
114                                function_start_load_addr = block_range_start_addr.GetLoadAddress (self.target)
115                        if function_start_load_addr == -1:
116                            function_start_load_addr = function.GetStartAddress().GetLoadAddress (self.target)
117                    elif symbol:
118                        self.symbolication += symbol.GetName()
119                        function_start_load_addr = symbol.GetStartAddress().GetLoadAddress (self.target)
120                    else:
121                        self.symbolication = ''
122                        return False
123
124                    # Dump the offset from the current function or symbol if it is non zero
125                    function_offset = self.load_addr - function_start_load_addr
126                    if function_offset > 0:
127                        self.symbolication += " + %u" % (function_offset)
128                    elif function_offset < 0:
129                        self.symbolication += " %i (invalid negative offset, file a bug) " % function_offset
130
131                    # Print out any line information if any is available
132                    if line_entry.GetFileSpec():
133                        # Print full source file path in verbose mode
134                        if verbose:
135                            self.symbolication += ' at %s' % line_entry.GetFileSpec()
136                        else:
137                            self.symbolication += ' at %s' % line_entry.GetFileSpec().GetFilename()
138                        self.symbolication += ':%u' % line_entry.GetLine ()
139                        column = line_entry.GetColumn()
140                        if column > 0:
141                            self.symbolication += ':%u' % column
142                    return True
143        return False
144
145class Section:
146    """Class that represents an load address range"""
147    sect_info_regex = re.compile('(?P<name>[^=]+)=(?P<range>.*)')
148    addr_regex = re.compile('^\s*(?P<start>0x[0-9A-Fa-f]+)\s*$')
149    range_regex = re.compile('^\s*(?P<start>0x[0-9A-Fa-f]+)\s*(?P<op>[-+])\s*(?P<end>0x[0-9A-Fa-f]+)\s*$')
150
151    def __init__(self, start_addr = None, end_addr = None, name = None):
152        self.start_addr = start_addr
153        self.end_addr = end_addr
154        self.name = name
155
156    @classmethod
157    def InitWithSBTargetAndSBSection(cls, target, section):
158        sect_load_addr = section.GetLoadAddress(target)
159        if sect_load_addr != lldb.LLDB_INVALID_ADDRESS:
160            obj = cls(sect_load_addr, sect_load_addr + section.size, section.name)
161            return obj
162        else:
163            return None
164
165    def contains(self, addr):
166        return self.start_addr <= addr and addr < self.end_addr;
167
168    def set_from_string(self, s):
169        match = self.sect_info_regex.match (s)
170        if match:
171            self.name = match.group('name')
172            range_str = match.group('range')
173            addr_match = self.addr_regex.match(range_str)
174            if addr_match:
175                self.start_addr = int(addr_match.group('start'), 16)
176                self.end_addr = None
177                return True
178
179            range_match = self.range_regex.match(range_str)
180            if range_match:
181                self.start_addr = int(range_match.group('start'), 16)
182                self.end_addr = int(range_match.group('end'), 16)
183                op = range_match.group('op')
184                if op == '+':
185                    self.end_addr += self.start_addr
186                return True
187        print 'error: invalid section info string "%s"' % s
188        print 'Valid section info formats are:'
189        print 'Format                Example                    Description'
190        print '--------------------- -----------------------------------------------'
191        print '<name>=<base>        __TEXT=0x123000             Section from base address only'
192        print '<name>=<base>-<end>  __TEXT=0x123000-0x124000    Section from base address and end address'
193        print '<name>=<base>+<size> __TEXT=0x123000+0x1000      Section from base address and size'
194        return False
195
196    def __str__(self):
197        if self.name:
198            if self.end_addr != None:
199                if self.start_addr != None:
200                    return "%s=[0x%16.16x - 0x%16.16x)" % (self.name, self.start_addr, self.end_addr)
201            else:
202                if self.start_addr != None:
203                    return "%s=0x%16.16x" % (self.name, self.start_addr)
204            return self.name
205        return "<invalid>"
206
207class Image:
208    """A class that represents an executable image and any associated data"""
209
210    def __init__(self, path, uuid = None):
211        self.path = path
212        self.resolved_path = None
213        self.resolved = False
214        self.unavailable = False
215        self.uuid = uuid
216        self.section_infos = list()
217        self.identifier = None
218        self.version = None
219        self.arch = None
220        self.module = None
221        self.symfile = None
222        self.slide = None
223
224    @classmethod
225    def InitWithSBTargetAndSBModule(cls, target, module):
226        '''Initalize this Image object with a module from a target.'''
227        obj = cls(module.file.fullpath, module.uuid)
228        obj.resolved_path = module.platform_file.fullpath
229        obj.resolved = True
230        obj.arch = module.triple
231        for section in module.sections:
232            symb_section = Section.InitWithSBTargetAndSBSection(target, section)
233            if symb_section:
234                obj.section_infos.append (symb_section)
235        obj.arch = module.triple
236        obj.module = module
237        obj.symfile = None
238        obj.slide = None
239        return obj
240
241    def dump(self, prefix):
242        print "%s%s" % (prefix, self)
243
244    def debug_dump(self):
245        print 'path = "%s"' % (self.path)
246        print 'resolved_path = "%s"' % (self.resolved_path)
247        print 'resolved = %i' % (self.resolved)
248        print 'unavailable = %i' % (self.unavailable)
249        print 'uuid = %s' % (self.uuid)
250        print 'section_infos = %s' % (self.section_infos)
251        print 'identifier = "%s"' % (self.identifier)
252        print 'version = %s' % (self.version)
253        print 'arch = %s' % (self.arch)
254        print 'module = %s' % (self.module)
255        print 'symfile = "%s"' % (self.symfile)
256        print 'slide = %i (0x%x)' % (self.slide, self.slide)
257
258    def __str__(self):
259        s = ''
260        if self.uuid:
261            s += "%s " % (self.get_uuid())
262        if self.arch:
263            s += "%s " % (self.arch)
264        if self.version:
265            s += "%s " % (self.version)
266        resolved_path = self.get_resolved_path()
267        if resolved_path:
268            s += "%s " % (resolved_path)
269        for section_info in self.section_infos:
270            s += ", %s" % (section_info)
271        if self.slide != None:
272            s += ', slide = 0x%16.16x' % self.slide
273        return s
274
275    def add_section(self, section):
276        #print "added '%s' to '%s'" % (section, self.path)
277        self.section_infos.append (section)
278
279    def get_section_containing_load_addr (self, load_addr):
280        for section_info in self.section_infos:
281            if section_info.contains(load_addr):
282                return section_info
283        return None
284
285    def get_resolved_path(self):
286        if self.resolved_path:
287            return self.resolved_path
288        elif self.path:
289            return self.path
290        return None
291
292    def get_resolved_path_basename(self):
293        path = self.get_resolved_path()
294        if path:
295            return os.path.basename(path)
296        return None
297
298    def symfile_basename(self):
299        if self.symfile:
300            return os.path.basename(self.symfile)
301        return None
302
303    def has_section_load_info(self):
304        return self.section_infos or self.slide != None
305
306    def load_module(self, target):
307        if self.unavailable:
308            return None # We already warned that we couldn't find this module, so don't return an error string
309        # Load this module into "target" using the section infos to
310        # set the section load addresses
311        if self.has_section_load_info():
312            if target:
313                if self.module:
314                    if self.section_infos:
315                        num_sections_loaded = 0
316                        for section_info in self.section_infos:
317                            if section_info.name:
318                                section = self.module.FindSection (section_info.name)
319                                if section:
320                                    error = target.SetSectionLoadAddress (section, section_info.start_addr)
321                                    if error.Success():
322                                        num_sections_loaded += 1
323                                    else:
324                                        return 'error: %s' % error.GetCString()
325                                else:
326                                    return 'error: unable to find the section named "%s"' % section_info.name
327                            else:
328                                return 'error: unable to find "%s" section in "%s"' % (range.name, self.get_resolved_path())
329                        if num_sections_loaded == 0:
330                            return 'error: no sections were successfully loaded'
331                    else:
332                        err = target.SetModuleLoadAddress(self.module, self.slide)
333                        if err.Fail():
334                            return err.GetCString()
335                    return None
336                else:
337                    return 'error: invalid module'
338            else:
339                return 'error: invalid target'
340        else:
341            return 'error: no section infos'
342
343    def add_module(self, target):
344        '''Add the Image described in this object to "target" and load the sections if "load" is True.'''
345        if target:
346            # Try and find using UUID only first so that paths need not match up
347            uuid_str = self.get_normalized_uuid_string()
348            if uuid_str:
349                self.module = target.AddModule (None, None, uuid_str)
350            if not self.module:
351                self.locate_module_and_debug_symbols ()
352                if self.unavailable:
353                    return None
354                resolved_path = self.get_resolved_path()
355                self.module = target.AddModule (resolved_path, self.arch, uuid_str, self.symfile)
356            if not self.module:
357                return 'error: unable to get module for (%s) "%s"' % (self.arch, self.get_resolved_path())
358            if self.has_section_load_info():
359                return self.load_module(target)
360            else:
361                return None # No sections, the module was added to the target, so success
362        else:
363            return 'error: invalid target'
364
365    def locate_module_and_debug_symbols (self):
366        # By default, just use the paths that were supplied in:
367        # self.path
368        # self.resolved_path
369        # self.module
370        # self.symfile
371        # Subclasses can inherit from this class and override this function
372        self.resolved = True
373        return True
374
375    def get_uuid(self):
376        if not self.uuid and self.module:
377            self.uuid = uuid.UUID(self.module.GetUUIDString())
378        return self.uuid
379
380    def get_normalized_uuid_string(self):
381        if self.uuid:
382            return str(self.uuid).upper()
383        return None
384
385    def create_target(self):
386        '''Create a target using the information in this Image object.'''
387        if self.unavailable:
388            return None
389
390        if self.locate_module_and_debug_symbols ():
391            resolved_path = self.get_resolved_path();
392            path_spec = lldb.SBFileSpec (resolved_path)
393            #result.PutCString ('plist[%s] = %s' % (uuid, self.plist))
394            error = lldb.SBError()
395            target = lldb.debugger.CreateTarget (resolved_path, self.arch, None, False, error);
396            if target:
397                self.module = target.FindModule(path_spec)
398                if self.has_section_load_info():
399                    err = self.load_module(target)
400                    if err:
401                        print 'ERROR: ', err
402                return target
403            else:
404                print 'error: unable to create a valid target for (%s) "%s"' % (self.arch, self.path)
405        else:
406            print 'error: unable to locate main executable (%s) "%s"' % (self.arch, self.path)
407        return None
408
409class Symbolicator:
410
411    def __init__(self):
412        """A class the represents the information needed to symbolicate addresses in a program"""
413        self.target = None
414        self.images = list() # a list of images to be used when symbolicating
415        self.addr_mask = 0xffffffffffffffff
416
417    @classmethod
418    def InitWithSBTarget(cls, target):
419        obj = cls()
420        obj.target = target
421        obj.images = list();
422        triple = target.triple
423        if triple:
424            arch = triple.split('-')[0]
425            if "arm" in arch:
426                obj.addr_mask = 0xfffffffffffffffe
427
428        for module in target.modules:
429            image = Image.InitWithSBTargetAndSBModule(target, module)
430            obj.images.append(image)
431        return obj
432
433    def __str__(self):
434        s = "Symbolicator:\n"
435        if self.target:
436            s += "Target = '%s'\n" % (self.target)
437            s += "Target modules:\n"
438            for m in self.target.modules:
439                s += str(m) + "\n"
440        s += "Images:\n"
441        for image in self.images:
442            s += '    %s\n' % (image)
443        return s
444
445    def find_images_with_identifier(self, identifier):
446        images = list()
447        for image in self.images:
448            if image.identifier == identifier:
449                images.append(image)
450        return images
451
452    def find_image_containing_load_addr(self, load_addr):
453        for image in self.images:
454            if image.get_section_containing_load_addr (load_addr):
455                return image
456        return None
457
458    def create_target(self):
459        if self.target:
460            return self.target
461
462        if self.images:
463            for image in self.images:
464                self.target = image.create_target ()
465                if self.target:
466                    if self.target.GetAddressByteSize() == 4:
467                        triple = self.target.triple
468                        if triple:
469                            arch = triple.split('-')[0]
470                            if "arm" in arch:
471                                self.addr_mask = 0xfffffffffffffffe
472                    return self.target
473        return None
474
475
476    def symbolicate(self, load_addr, verbose = False):
477        if not self.target:
478            self.create_target()
479        if self.target:
480            live_process = False
481            process = self.target.process
482            if process:
483                state = process.state
484                if state > lldb.eStateUnloaded and state < lldb.eStateDetached:
485                    live_process = True
486            # If we don't have a live process, we can attempt to find the image
487            # that a load address belongs to and lazily load its module in the
488            # target, but we shouldn't do any of this if we have a live process
489            if not live_process:
490                image = self.find_image_containing_load_addr (load_addr)
491                if image:
492                    image.add_module (self.target)
493            symbolicated_address = Address(self.target, load_addr)
494            if symbolicated_address.symbolicate (verbose):
495                if symbolicated_address.so_addr:
496                    symbolicated_addresses = list()
497                    symbolicated_addresses.append(symbolicated_address)
498                    # See if we were able to reconstruct anything?
499                    while 1:
500                        inlined_parent_so_addr = lldb.SBAddress()
501                        inlined_parent_sym_ctx = symbolicated_address.sym_ctx.GetParentOfInlinedScope (symbolicated_address.so_addr, inlined_parent_so_addr)
502                        if not inlined_parent_sym_ctx:
503                            break
504                        if not inlined_parent_so_addr:
505                            break
506
507                        symbolicated_address = Address(self.target, inlined_parent_so_addr.GetLoadAddress(self.target))
508                        symbolicated_address.sym_ctx = inlined_parent_sym_ctx
509                        symbolicated_address.so_addr = inlined_parent_so_addr
510                        symbolicated_address.symbolicate (verbose)
511
512                        # push the new frame onto the new frame stack
513                        symbolicated_addresses.append (symbolicated_address)
514
515                    if symbolicated_addresses:
516                        return symbolicated_addresses
517        else:
518            print 'error: no target in Symbolicator'
519        return None
520
521
522def disassemble_instructions (target, instructions, pc, insts_before_pc, insts_after_pc, non_zeroeth_frame):
523    lines = list()
524    pc_index = -1
525    comment_column = 50
526    for inst_idx, inst in enumerate(instructions):
527        inst_pc = inst.GetAddress().GetLoadAddress(target);
528        if pc == inst_pc:
529            pc_index = inst_idx
530        mnemonic = inst.GetMnemonic (target)
531        operands =  inst.GetOperands (target)
532        comment =  inst.GetComment (target)
533        #data = inst.GetData (target)
534        lines.append ("%#16.16x: %8s %s" % (inst_pc, mnemonic, operands))
535        if comment:
536            line_len = len(lines[-1])
537            if line_len < comment_column:
538                lines[-1] += ' ' * (comment_column - line_len)
539                lines[-1] += "; %s" % comment
540
541    if pc_index >= 0:
542        # If we are disassembling the non-zeroeth frame, we need to backup the PC by 1
543        if non_zeroeth_frame and pc_index > 0:
544            pc_index = pc_index - 1
545        if insts_before_pc == -1:
546            start_idx = 0
547        else:
548            start_idx = pc_index - insts_before_pc
549        if start_idx < 0:
550            start_idx = 0
551        if insts_before_pc == -1:
552            end_idx = inst_idx
553        else:
554            end_idx = pc_index + insts_after_pc
555        if end_idx > inst_idx:
556            end_idx = inst_idx
557        for i in range(start_idx, end_idx+1):
558            if i == pc_index:
559                print ' -> ', lines[i]
560            else:
561                print '    ', lines[i]
562
563def print_module_section_data (section):
564    print section
565    section_data = section.GetSectionData()
566    if section_data:
567        ostream = lldb.SBStream()
568        section_data.GetDescription (ostream, section.GetFileAddress())
569        print ostream.GetData()
570
571def print_module_section (section, depth):
572    print section
573    if depth > 0:
574        num_sub_sections = section.GetNumSubSections()
575        for sect_idx in range(num_sub_sections):
576            print_module_section (section.GetSubSectionAtIndex(sect_idx), depth - 1)
577
578def print_module_sections (module, depth):
579    for sect in module.section_iter():
580        print_module_section (sect, depth)
581
582def print_module_symbols (module):
583    for sym in module:
584        print sym
585
586def Symbolicate(command_args):
587
588    usage = "usage: %prog [options] <addr1> [addr2 ...]"
589    description='''Symbolicate one or more addresses using LLDB's python scripting API..'''
590    parser = optparse.OptionParser(description=description, prog='crashlog.py',usage=usage)
591    parser.add_option('-v', '--verbose', action='store_true', dest='verbose', help='display verbose debug info', default=False)
592    parser.add_option('-p', '--platform', type='string', metavar='platform', dest='platform', help='Specify the platform to use when creating the debug target. Valid values include "localhost", "darwin-kernel", "ios-simulator", "remote-freebsd", "remote-macosx", "remote-ios", "remote-linux".')
593    parser.add_option('-f', '--file', type='string', metavar='file', dest='file', help='Specify a file to use when symbolicating')
594    parser.add_option('-a', '--arch', type='string', metavar='arch', dest='arch', help='Specify a architecture to use when symbolicating')
595    parser.add_option('-s', '--slide', type='int', metavar='slide', dest='slide', help='Specify the slide to use on the file specified with the --file option', default=None)
596    parser.add_option('--section', type='string', action='append', dest='section_strings', help='specify <sect-name>=<start-addr> or <sect-name>=<start-addr>-<end-addr>')
597    try:
598        (options, args) = parser.parse_args(command_args)
599    except:
600        return
601    symbolicator = Symbolicator()
602    images = list();
603    if options.file:
604        image = Image(options.file);
605        image.arch = options.arch
606        # Add any sections that were specified with one or more --section options
607        if options.section_strings:
608            for section_str in options.section_strings:
609                section = Section()
610                if section.set_from_string (section_str):
611                    image.add_section (section)
612                else:
613                    sys.exit(1)
614        if options.slide != None:
615            image.slide = options.slide
616        symbolicator.images.append(image)
617
618    target = symbolicator.create_target()
619    if options.verbose:
620        print symbolicator
621    if target:
622        for addr_str in args:
623            addr = int(addr_str, 0)
624            symbolicated_addrs = symbolicator.symbolicate(addr, options.verbose)
625            for symbolicated_addr in symbolicated_addrs:
626                print symbolicated_addr
627            print
628    else:
629        print 'error: no target for %s' % (symbolicator)
630
631if __name__ == '__main__':
632    # Create a new debugger instance
633    lldb.debugger = lldb.SBDebugger.Create()
634    Symbolicate (sys.argv[1:])
635