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    def contains(self, addr):
157        return self.start_addr <= addr and addr < self.end_addr;
158
159    def set_from_string(self, s):
160        match = self.sect_info_regex.match (s)
161        if match:
162            self.name = match.group('name')
163            range_str = match.group('range')
164            addr_match = self.addr_regex.match(range_str)
165            if addr_match:
166                self.start_addr = int(addr_match.group('start'), 16)
167                self.end_addr = None
168                return True
169
170            range_match = self.range_regex.match(range_str)
171            if range_match:
172                self.start_addr = int(range_match.group('start'), 16)
173                self.end_addr = int(range_match.group('end'), 16)
174                op = range_match.group('op')
175                if op == '+':
176                    self.end_addr += self.start_addr
177                return True
178        print 'error: invalid section info string "%s"' % s
179        print 'Valid section info formats are:'
180        print 'Format                Example                    Description'
181        print '--------------------- -----------------------------------------------'
182        print '<name>=<base>        __TEXT=0x123000             Section from base address only'
183        print '<name>=<base>-<end>  __TEXT=0x123000-0x124000    Section from base address and end address'
184        print '<name>=<base>+<size> __TEXT=0x123000+0x1000      Section from base address and size'
185        return False
186
187    def __str__(self):
188        if self.name:
189            if self.end_addr != None:
190                if self.start_addr != None:
191                    return "%s=[0x%16.16x - 0x%16.16x)" % (self.name, self.start_addr, self.end_addr)
192            else:
193                if self.start_addr != None:
194                    return "%s=0x%16.16x" % (self.name, self.start_addr)
195            return self.name
196        return "<invalid>"
197
198class Image:
199    """A class that represents an executable image and any associated data"""
200
201    def __init__(self, path, uuid = None):
202        self.path = path
203        self.resolved_path = None
204        self.resolved = False
205        self.unavailable = False
206        self.uuid = uuid
207        self.section_infos = list()
208        self.identifier = None
209        self.version = None
210        self.arch = None
211        self.module = None
212        self.symfile = None
213        self.slide = None
214
215    def dump(self, prefix):
216        print "%s%s" % (prefix, self)
217
218    def __str__(self):
219        s = "%s %s %s" % (self.get_uuid(), self.version, self.get_resolved_path())
220        for section_info in self.section_infos:
221            s += ", %s" % (section_info)
222        if self.slide != None:
223            s += ', slide = 0x%16.16x' % self.slide
224        return s
225
226    def add_section(self, section):
227        #print "added '%s' to '%s'" % (section, self.path)
228        self.section_infos.append (section)
229
230    def get_section_containing_load_addr (self, load_addr):
231        for section_info in self.section_infos:
232            if section_info.contains(load_addr):
233                return section_info
234        return None
235
236    def get_resolved_path(self):
237        if self.resolved_path:
238            return self.resolved_path
239        elif self.path:
240            return self.path
241        return None
242
243    def get_resolved_path_basename(self):
244        path = self.get_resolved_path()
245        if path:
246            return os.path.basename(path)
247        return None
248
249    def symfile_basename(self):
250        if self.symfile:
251            return os.path.basename(self.symfile)
252        return None
253
254    def has_section_load_info(self):
255        return self.section_infos or self.slide != None
256
257    def load_module(self, target):
258        if self.unavailable:
259            return None # We already warned that we couldn't find this module, so don't return an error string
260        # Load this module into "target" using the section infos to
261        # set the section load addresses
262        if self.has_section_load_info():
263            if target:
264                if self.module:
265                    if self.section_infos:
266                        num_sections_loaded = 0
267                        for section_info in self.section_infos:
268                            if section_info.name:
269                                section = self.module.FindSection (section_info.name)
270                                if section:
271                                    error = target.SetSectionLoadAddress (section, section_info.start_addr)
272                                    if error.Success():
273                                        num_sections_loaded += 1
274                                    else:
275                                        return 'error: %s' % error.GetCString()
276                                else:
277                                    return 'error: unable to find the section named "%s"' % section_info.name
278                            else:
279                                return 'error: unable to find "%s" section in "%s"' % (range.name, self.get_resolved_path())
280                        if num_sections_loaded == 0:
281                            return 'error: no sections were successfully loaded'
282                    else:
283                        err = target.SetModuleLoadAddress(self.module, self.slide)
284                        if err.Fail():
285                            return err.GetCString()
286                    return None
287                else:
288                    return 'error: invalid module'
289            else:
290                return 'error: invalid target'
291        else:
292            return 'error: no section infos'
293
294    def add_module(self, target):
295        '''Add the Image described in this object to "target" and load the sections if "load" is True.'''
296        if target:
297            # Try and find using UUID only first so that paths need not match up
298            uuid_str = self.get_normalized_uuid_string()
299            if uuid_str:
300                self.module = target.AddModule (None, None, uuid_str)
301            if not self.module:
302                self.locate_module_and_debug_symbols ()
303                if self.unavailable:
304                    return None
305                resolved_path = self.get_resolved_path()
306                self.module = target.AddModule (resolved_path, self.arch, uuid_str, self.symfile)
307            if not self.module:
308                return 'error: unable to get module for (%s) "%s"' % (self.arch, self.get_resolved_path())
309            if self.has_section_load_info():
310                return self.load_module(target)
311            else:
312                return None # No sections, the module was added to the target, so success
313        else:
314            return 'error: invalid target'
315
316    def locate_module_and_debug_symbols (self):
317        # By default, just use the paths that were supplied in:
318        # self.path
319        # self.resolved_path
320        # self.module
321        # self.symfile
322        # Subclasses can inherit from this class and override this function
323        self.resolved = True
324        return True
325
326    def get_uuid(self):
327        if not self.uuid and self.module:
328            self.uuid = uuid.UUID(self.module.GetUUIDString())
329        return self.uuid
330
331    def get_normalized_uuid_string(self):
332        if self.uuid:
333            return str(self.uuid).upper()
334        return None
335
336    def create_target(self):
337        '''Create a target using the information in this Image object.'''
338        if self.unavailable:
339            return None
340
341        if self.locate_module_and_debug_symbols ():
342            resolved_path = self.get_resolved_path();
343            path_spec = lldb.SBFileSpec (resolved_path)
344            #result.PutCString ('plist[%s] = %s' % (uuid, self.plist))
345            error = lldb.SBError()
346            target = lldb.debugger.CreateTarget (resolved_path, self.arch, None, False, error);
347            if target:
348                self.module = target.FindModule(path_spec)
349                if self.has_section_load_info():
350                    err = self.load_module(target)
351                    if err:
352                        print 'ERROR: ', err
353                return target
354            else:
355                print 'error: unable to create a valid target for (%s) "%s"' % (self.arch, self.path)
356        else:
357            print 'error: unable to locate main executable (%s) "%s"' % (self.arch, self.path)
358        return None
359
360class Symbolicator:
361
362    def __init__(self):
363        """A class the represents the information needed to symbolicate addresses in a program"""
364        self.target = None
365        self.images = list() # a list of images to be used when symbolicating
366
367
368    def __str__(self):
369        s = "Symbolicator:\n"
370        if self.target:
371            s += "Target = '%s'\n" % (self.target)
372            s += "Target modules:'\n"
373            for m in self.target.modules:
374                print m
375        s += "Images:\n"
376        for image in self.images:
377            s += '    %s\n' % (image)
378        return s
379
380    def find_images_with_identifier(self, identifier):
381        images = list()
382        for image in self.images:
383            if image.identifier == identifier:
384                images.append(image)
385        return images
386
387    def find_image_containing_load_addr(self, load_addr):
388        for image in self.images:
389            if image.get_section_containing_load_addr (load_addr):
390                return image
391        return None
392
393    def create_target(self):
394        if self.target:
395            return self.target
396
397        if self.images:
398            for image in self.images:
399                self.target = image.create_target ()
400                if self.target:
401                    return self.target
402        return None
403
404    def symbolicate(self, load_addr, verbose = False):
405        if not self.target:
406            self.create_target()
407        if self.target:
408            image = self.find_image_containing_load_addr (load_addr)
409            if image:
410                image.add_module (self.target)
411            symbolicated_address = Address(self.target, load_addr)
412            if symbolicated_address.symbolicate (verbose):
413                if symbolicated_address.so_addr:
414                    symbolicated_addresses = list()
415                    symbolicated_addresses.append(symbolicated_address)
416                    # See if we were able to reconstruct anything?
417                    while 1:
418                        inlined_parent_so_addr = lldb.SBAddress()
419                        inlined_parent_sym_ctx = symbolicated_address.sym_ctx.GetParentOfInlinedScope (symbolicated_address.so_addr, inlined_parent_so_addr)
420                        if not inlined_parent_sym_ctx:
421                            break
422                        if not inlined_parent_so_addr:
423                            break
424
425                        symbolicated_address = Address(self.target, inlined_parent_so_addr.GetLoadAddress(self.target))
426                        symbolicated_address.sym_ctx = inlined_parent_sym_ctx
427                        symbolicated_address.so_addr = inlined_parent_so_addr
428                        symbolicated_address.symbolicate (verbose)
429
430                        # push the new frame onto the new frame stack
431                        symbolicated_addresses.append (symbolicated_address)
432
433                    if symbolicated_addresses:
434                        return symbolicated_addresses
435        else:
436            print 'error: no target in Symbolicator'
437        return None
438
439
440def disassemble_instructions (target, instructions, pc, insts_before_pc, insts_after_pc, non_zeroeth_frame):
441    lines = list()
442    pc_index = -1
443    comment_column = 50
444    for inst_idx, inst in enumerate(instructions):
445        inst_pc = inst.GetAddress().GetLoadAddress(target);
446        if pc == inst_pc:
447            pc_index = inst_idx
448        mnemonic = inst.GetMnemonic (target)
449        operands =  inst.GetOperands (target)
450        comment =  inst.GetComment (target)
451        #data = inst.GetData (target)
452        lines.append ("%#16.16x: %8s %s" % (inst_pc, mnemonic, operands))
453        if comment:
454            line_len = len(lines[-1])
455            if line_len < comment_column:
456                lines[-1] += ' ' * (comment_column - line_len)
457                lines[-1] += "; %s" % comment
458
459    if pc_index >= 0:
460        # If we are disassembling the non-zeroeth frame, we need to backup the PC by 1
461        if non_zeroeth_frame and pc_index > 0:
462            pc_index = pc_index - 1
463        if insts_before_pc == -1:
464            start_idx = 0
465        else:
466            start_idx = pc_index - insts_before_pc
467        if start_idx < 0:
468            start_idx = 0
469        if insts_before_pc == -1:
470            end_idx = inst_idx
471        else:
472            end_idx = pc_index + insts_after_pc
473        if end_idx > inst_idx:
474            end_idx = inst_idx
475        for i in range(start_idx, end_idx+1):
476            if i == pc_index:
477                print ' -> ', lines[i]
478            else:
479                print '    ', lines[i]
480
481def print_module_section_data (section):
482    print section
483    section_data = section.GetSectionData()
484    if section_data:
485        ostream = lldb.SBStream()
486        section_data.GetDescription (ostream, section.GetFileAddress())
487        print ostream.GetData()
488
489def print_module_section (section, depth):
490    print section
491    if depth > 0:
492        num_sub_sections = section.GetNumSubSections()
493        for sect_idx in range(num_sub_sections):
494            print_module_section (section.GetSubSectionAtIndex(sect_idx), depth - 1)
495
496def print_module_sections (module, depth):
497    for sect in module.section_iter():
498        print_module_section (sect, depth)
499
500def print_module_symbols (module):
501    for sym in module:
502        print sym
503
504def Symbolicate(command_args):
505
506    usage = "usage: %prog [options] <addr1> [addr2 ...]"
507    description='''Symbolicate one or more addresses using LLDB's python scripting API..'''
508    parser = optparse.OptionParser(description=description, prog='crashlog.py',usage=usage)
509    parser.add_option('-v', '--verbose', action='store_true', dest='verbose', help='display verbose debug info', default=False)
510    parser.add_option('-p', '--platform', type='string', metavar='platform', dest='platform', help='specify one platform by name')
511    parser.add_option('-f', '--file', type='string', metavar='file', dest='file', help='Specify a file to use when symbolicating')
512    parser.add_option('-a', '--arch', type='string', metavar='arch', dest='arch', help='Specify a architecture to use when symbolicating')
513    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)
514    parser.add_option('--section', type='string', action='append', dest='section_strings', help='specify <sect-name>=<start-addr> or <sect-name>=<start-addr>-<end-addr>')
515    try:
516        (options, args) = parser.parse_args(command_args)
517    except:
518        return
519    symbolicator = Symbolicator()
520    images = list();
521    if options.file:
522        image = Image(options.file);
523        image.arch = options.arch
524        # Add any sections that were specified with one or more --section options
525        if options.section_strings:
526            for section_str in options.section_strings:
527                section = Section()
528                if section.set_from_string (section_str):
529                    image.add_section (section)
530                else:
531                    sys.exit(1)
532        if options.slide != None:
533            image.slide = options.slide
534        symbolicator.images.append(image)
535
536    target = symbolicator.create_target()
537    if options.verbose:
538        print symbolicator
539    if target:
540        for addr_str in args:
541            addr = int(addr_str, 0)
542            symbolicated_addrs = symbolicator.symbolicate(addr, options.verbose)
543            for symbolicated_addr in symbolicated_addrs:
544                print symbolicated_addr
545            print
546    else:
547        print 'error: no target for %s' % (symbolicator)
548
549if __name__ == '__main__':
550    # Create a new debugger instance
551    lldb.debugger = lldb.SBDebugger.Create()
552    Symbolicate (sys.argv[1:])
553