lldb/packages/Python/lldbsuite/test/lldbutil.py

   1 """
   2 This LLDB module contains miscellaneous utilities.
   3 Some of the test suite takes advantage of the utility functions defined here.
   4 They can also be useful for general purpose lldb scripting.
   5 """
   6
   7 from __future__ import print_function
   8 from __future__ import absolute_import
   9
  10 # System modules
  11 import errno
  12 import os
  13 import re
  14 import sys
  15
  16 # Third-party modules
  17 from six import StringIO as SixStringIO
  18 import six
  19
  20 # LLDB modules
  21 import lldb
  22 from . import lldbtest_config
  23
  24
  25 # ===================================================
  26 # Utilities for locating/checking executable programs
  27 # ===================================================
  28
  29 def is_exe(fpath):
  30     """Returns True if fpath is an executable."""
  31     return os.path.isfile(fpath) and os.access(fpath, os.X_OK)
  32
  33
  34 def which(program):
  35     """Returns the full path to a program; None otherwise."""
  36     fpath, fname = os.path.split(program)
  37     if fpath:
  38         if is_exe(program):
  39             return program
  40     else:
  41         for path in os.environ["PATH"].split(os.pathsep):
  42             exe_file = os.path.join(path, program)
  43             if is_exe(exe_file):
  44                 return exe_file
  45     return None
  46
  47 def mkdir_p(path):
  48     try:
  49         os.makedirs(path)
  50     except OSError as e:
  51         if e.errno != errno.EEXIST:
  52             raise
  53     if not os.path.isdir(path):
  54         raise OSError(errno.ENOTDIR, "%s is not a directory"%path)
  55 # ===================================================
  56 # Disassembly for an SBFunction or an SBSymbol object
  57 # ===================================================
  58
  59
  60 def disassemble(target, function_or_symbol):
  61     """Disassemble the function or symbol given a target.
  62
  63     It returns the disassembly content in a string object.
  64     """
  65     buf = SixStringIO()
  66     insts = function_or_symbol.GetInstructions(target)
  67     for i in insts:
  68         print(i, file=buf)
  69     return buf.getvalue()
  70
  71 # ==========================================================
  72 # Integer (byte size 1, 2, 4, and 8) to bytearray conversion
  73 # ==========================================================
  74
  75
  76 def int_to_bytearray(val, bytesize):
  77     """Utility function to convert an integer into a bytearray.
  78
  79     It returns the bytearray in the little endian format.  It is easy to get the
  80     big endian format, just do ba.reverse() on the returned object.
  81     """
  82     import struct
  83
  84     if bytesize == 1:
  85         return bytearray([val])
  86
  87     # Little endian followed by a format character.
  88     template = "<%c"
  89     if bytesize == 2:
  90         fmt = template % 'h'
  91     elif bytesize == 4:
  92         fmt = template % 'i'
  93     elif bytesize == 4:
  94         fmt = template % 'q'
  95     else:
  96         return None
  97
  98     packed = struct.pack(fmt, val)
  99     return bytearray(packed)
 100
 101
 102 def bytearray_to_int(bytes, bytesize):
 103     """Utility function to convert a bytearray into an integer.
 104
 105     It interprets the bytearray in the little endian format. For a big endian
 106     bytearray, just do ba.reverse() on the object before passing it in.
 107     """
 108     import struct
 109
 110     if bytesize == 1:
 111         return bytes[0]
 112
 113     # Little endian followed by a format character.
 114     template = "<%c"
 115     if bytesize == 2:
 116         fmt = template % 'h'
 117     elif bytesize == 4:
 118         fmt = template % 'i'
 119     elif bytesize == 4:
 120         fmt = template % 'q'
 121     else:
 122         return None
 123
 124     unpacked = struct.unpack_from(fmt, bytes)
 125     return unpacked[0]
 126
 127
 128 # ==============================================================
 129 # Get the description of an lldb object or None if not available
 130 # ==============================================================
 131 def get_description(obj, option=None):
 132     """Calls lldb_obj.GetDescription() and returns a string, or None.
 133
 134     For SBTarget, SBBreakpointLocation, and SBWatchpoint lldb objects, an extra
 135     option can be passed in to describe the detailed level of description
 136     desired:
 137         o lldb.eDescriptionLevelBrief
 138         o lldb.eDescriptionLevelFull
 139         o lldb.eDescriptionLevelVerbose
 140     """
 141     method = getattr(obj, 'GetDescription')
 142     if not method:
 143         return None
 144     tuple = (lldb.SBTarget, lldb.SBBreakpointLocation, lldb.SBWatchpoint)
 145     if isinstance(obj, tuple):
 146         if option is None:
 147             option = lldb.eDescriptionLevelBrief
 148
 149     stream = lldb.SBStream()
 150     if option is None:
 151         success = method(stream)
 152     else:
 153         success = method(stream, option)
 154     if not success:
 155         return None
 156     return stream.GetData()
 157
 158
 159 # =================================================
 160 # Convert some enum value to its string counterpart
 161 # =================================================
 162
 163 def state_type_to_str(enum):
 164     """Returns the stateType string given an enum."""
 165     if enum == lldb.eStateInvalid:
 166         return "invalid"
 167     elif enum == lldb.eStateUnloaded:
 168         return "unloaded"
 169     elif enum == lldb.eStateConnected:
 170         return "connected"
 171     elif enum == lldb.eStateAttaching:
 172         return "attaching"
 173     elif enum == lldb.eStateLaunching:
 174         return "launching"
 175     elif enum == lldb.eStateStopped:
 176         return "stopped"
 177     elif enum == lldb.eStateRunning:
 178         return "running"
 179     elif enum == lldb.eStateStepping:
 180         return "stepping"
 181     elif enum == lldb.eStateCrashed:
 182         return "crashed"
 183     elif enum == lldb.eStateDetached:
 184         return "detached"
 185     elif enum == lldb.eStateExited:
 186         return "exited"
 187     elif enum == lldb.eStateSuspended:
 188         return "suspended"
 189     else:
 190         raise Exception("Unknown StateType enum")
 191
 192
 193 def stop_reason_to_str(enum):
 194     """Returns the stopReason string given an enum."""
 195     if enum == lldb.eStopReasonInvalid:
 196         return "invalid"
 197     elif enum == lldb.eStopReasonNone:
 198         return "none"
 199     elif enum == lldb.eStopReasonTrace:
 200         return "trace"
 201     elif enum == lldb.eStopReasonBreakpoint:
 202         return "breakpoint"
 203     elif enum == lldb.eStopReasonWatchpoint:
 204         return "watchpoint"
 205     elif enum == lldb.eStopReasonExec:
 206         return "exec"
 207     elif enum == lldb.eStopReasonSignal:
 208         return "signal"
 209     elif enum == lldb.eStopReasonException:
 210         return "exception"
 211     elif enum == lldb.eStopReasonPlanComplete:
 212         return "plancomplete"
 213     elif enum == lldb.eStopReasonThreadExiting:
 214         return "threadexiting"
 215     else:
 216         raise Exception("Unknown StopReason enum")
 217
 218
 219 def symbol_type_to_str(enum):
 220     """Returns the symbolType string given an enum."""
 221     if enum == lldb.eSymbolTypeInvalid:
 222         return "invalid"
 223     elif enum == lldb.eSymbolTypeAbsolute:
 224         return "absolute"
 225     elif enum == lldb.eSymbolTypeCode:
 226         return "code"
 227     elif enum == lldb.eSymbolTypeData:
 228         return "data"
 229     elif enum == lldb.eSymbolTypeTrampoline:
 230         return "trampoline"
 231     elif enum == lldb.eSymbolTypeRuntime:
 232         return "runtime"
 233     elif enum == lldb.eSymbolTypeException:
 234         return "exception"
 235     elif enum == lldb.eSymbolTypeSourceFile:
 236         return "sourcefile"
 237     elif enum == lldb.eSymbolTypeHeaderFile:
 238         return "headerfile"
 239     elif enum == lldb.eSymbolTypeObjectFile:
 240         return "objectfile"
 241     elif enum == lldb.eSymbolTypeCommonBlock:
 242         return "commonblock"
 243     elif enum == lldb.eSymbolTypeBlock:
 244         return "block"
 245     elif enum == lldb.eSymbolTypeLocal:
 246         return "local"
 247     elif enum == lldb.eSymbolTypeParam:
 248         return "param"
 249     elif enum == lldb.eSymbolTypeVariable:
 250         return "variable"
 251     elif enum == lldb.eSymbolTypeVariableType:
 252         return "variabletype"
 253     elif enum == lldb.eSymbolTypeLineEntry:
 254         return "lineentry"
 255     elif enum == lldb.eSymbolTypeLineHeader:
 256         return "lineheader"
 257     elif enum == lldb.eSymbolTypeScopeBegin:
 258         return "scopebegin"
 259     elif enum == lldb.eSymbolTypeScopeEnd:
 260         return "scopeend"
 261     elif enum == lldb.eSymbolTypeAdditional:
 262         return "additional"
 263     elif enum == lldb.eSymbolTypeCompiler:
 264         return "compiler"
 265     elif enum == lldb.eSymbolTypeInstrumentation:
 266         return "instrumentation"
 267     elif enum == lldb.eSymbolTypeUndefined:
 268         return "undefined"
 269
 270
 271 def value_type_to_str(enum):
 272     """Returns the valueType string given an enum."""
 273     if enum == lldb.eValueTypeInvalid:
 274         return "invalid"
 275     elif enum == lldb.eValueTypeVariableGlobal:
 276         return "global_variable"
 277     elif enum == lldb.eValueTypeVariableStatic:
 278         return "static_variable"
 279     elif enum == lldb.eValueTypeVariableArgument:
 280         return "argument_variable"
 281     elif enum == lldb.eValueTypeVariableLocal:
 282         return "local_variable"
 283     elif enum == lldb.eValueTypeRegister:
 284         return "register"
 285     elif enum == lldb.eValueTypeRegisterSet:
 286         return "register_set"
 287     elif enum == lldb.eValueTypeConstResult:
 288         return "constant_result"
 289     else:
 290         raise Exception("Unknown ValueType enum")
 291
 292
 293 # ==================================================
 294 # Get stopped threads due to each stop reason.
 295 # ==================================================
 296
 297 def sort_stopped_threads(process,
 298                          breakpoint_threads=None,
 299                          crashed_threads=None,
 300                          watchpoint_threads=None,
 301                          signal_threads=None,
 302                          exiting_threads=None,
 303                          other_threads=None):
 304     """ Fills array *_threads with threads stopped for the corresponding stop
 305         reason.
 306     """
 307     for lst in [breakpoint_threads,
 308                 watchpoint_threads,
 309                 signal_threads,
 310                 exiting_threads,
 311                 other_threads]:
 312         if lst is not None:
 313             lst[:] = []
 314
 315     for thread in process:
 316         dispatched = False
 317         for (reason, list) in [(lldb.eStopReasonBreakpoint, breakpoint_threads),
 318                                (lldb.eStopReasonException, crashed_threads),
 319                                (lldb.eStopReasonWatchpoint, watchpoint_threads),
 320                                (lldb.eStopReasonSignal, signal_threads),
 321                                (lldb.eStopReasonThreadExiting, exiting_threads),
 322                                (None, other_threads)]:
 323             if not dispatched and list is not None:
 324                 if thread.GetStopReason() == reason or reason is None:
 325                     list.append(thread)
 326                     dispatched = True
 327
 328 # ==================================================
 329 # Utility functions for setting breakpoints
 330 # ==================================================
 331
 332 def run_break_set_by_script(
 333         test,
 334         class_name,
 335         extra_options=None,
 336         num_expected_locations=1):
 337     """Set a scripted breakpoint.  Check that it got the right number of locations."""
 338     test.assertTrue(class_name is not None, "Must pass in a class name.")
 339     command = "breakpoint set -P " + class_name
 340     if extra_options is not None:
 341         command += " " + extra_options
 342
 343     break_results = run_break_set_command(test, command)
 344     check_breakpoint_result(test, break_results, num_locations=num_expected_locations)
 345     return get_bpno_from_match(break_results)
 346
 347 def run_break_set_by_file_and_line(
 348         test,
 349         file_name,
 350         line_number,
 351         extra_options=None,
 352         num_expected_locations=1,
 353         loc_exact=False,
 354         module_name=None):
 355     """Set a breakpoint by file and line, returning the breakpoint number.
 356
 357     If extra_options is not None, then we append it to the breakpoint set command.
 358
 359     If num_expected_locations is -1, we check that we got AT LEAST one location. If num_expected_locations is -2, we don't
 360     check the actual number at all. Otherwise, we check that num_expected_locations equals the number of locations.
 361
 362     If loc_exact is true, we check that there is one location, and that location must be at the input file and line number."""
 363
 364     if file_name is None:
 365         command = 'breakpoint set -l %d' % (line_number)
 366     else:
 367         command = 'breakpoint set -f "%s" -l %d' % (file_name, line_number)
 368
 369     if module_name:
 370         command += " --shlib '%s'" % (module_name)
 371
 372     if extra_options:
 373         command += " " + extra_options
 374
 375     break_results = run_break_set_command(test, command)
 376
 377     if num_expected_locations == 1 and loc_exact:
 378         check_breakpoint_result(
 379             test,
 380             break_results,
 381             num_locations=num_expected_locations,
 382             file_name=file_name,
 383             line_number=line_number,
 384             module_name=module_name)
 385     else:
 386         check_breakpoint_result(
 387             test,
 388             break_results,
 389             num_locations=num_expected_locations)
 390
 391     return get_bpno_from_match(break_results)
 392
 393
 394 def run_break_set_by_symbol(
 395         test,
 396         symbol,
 397         extra_options=None,
 398         num_expected_locations=-1,
 399         sym_exact=False,
 400         module_name=None):
 401     """Set a breakpoint by symbol name.  Common options are the same as run_break_set_by_file_and_line.
 402
 403     If sym_exact is true, then the output symbol must match the input exactly, otherwise we do a substring match."""
 404     command = 'breakpoint set -n "%s"' % (symbol)
 405
 406     if module_name:
 407         command += " --shlib '%s'" % (module_name)
 408
 409     if extra_options:
 410         command += " " + extra_options
 411
 412     break_results = run_break_set_command(test, command)
 413
 414     if num_expected_locations == 1 and sym_exact:
 415         check_breakpoint_result(
 416             test,
 417             break_results,
 418             num_locations=num_expected_locations,
 419             symbol_name=symbol,
 420             module_name=module_name)
 421     else:
 422         check_breakpoint_result(
 423             test,
 424             break_results,
 425             num_locations=num_expected_locations)
 426
 427     return get_bpno_from_match(break_results)
 428
 429
 430 def run_break_set_by_selector(
 431         test,
 432         selector,
 433         extra_options=None,
 434         num_expected_locations=-1,
 435         module_name=None):
 436     """Set a breakpoint by selector.  Common options are the same as run_break_set_by_file_and_line."""
 437
 438     command = 'breakpoint set -S "%s"' % (selector)
 439
 440     if module_name:
 441         command += ' --shlib "%s"' % (module_name)
 442
 443     if extra_options:
 444         command += " " + extra_options
 445
 446     break_results = run_break_set_command(test, command)
 447
 448     if num_expected_locations == 1:
 449         check_breakpoint_result(
 450             test,
 451             break_results,
 452             num_locations=num_expected_locations,
 453             symbol_name=selector,
 454             symbol_match_exact=False,
 455             module_name=module_name)
 456     else:
 457         check_breakpoint_result(
 458             test,
 459             break_results,
 460             num_locations=num_expected_locations)
 461
 462     return get_bpno_from_match(break_results)
 463
 464
 465 def run_break_set_by_regexp(
 466         test,
 467         regexp,
 468         extra_options=None,
 469         num_expected_locations=-1):
 470     """Set a breakpoint by regular expression match on symbol name.  Common options are the same as run_break_set_by_file_and_line."""
 471
 472     command = 'breakpoint set -r "%s"' % (regexp)
 473     if extra_options:
 474         command += " " + extra_options
 475
 476     break_results = run_break_set_command(test, command)
 477
 478     check_breakpoint_result(
 479         test,
 480         break_results,
 481         num_locations=num_expected_locations)
 482
 483     return get_bpno_from_match(break_results)
 484
 485
 486 def run_break_set_by_source_regexp(
 487         test,
 488         regexp,
 489         extra_options=None,
 490         num_expected_locations=-1):
 491     """Set a breakpoint by source regular expression.  Common options are the same as run_break_set_by_file_and_line."""
 492     command = 'breakpoint set -p "%s"' % (regexp)
 493     if extra_options:
 494         command += " " + extra_options
 495
 496     break_results = run_break_set_command(test, command)
 497
 498     check_breakpoint_result(
 499         test,
 500         break_results,
 501         num_locations=num_expected_locations)
 502
 503     return get_bpno_from_match(break_results)
 504
 505
 506 def run_break_set_command(test, command):
 507     """Run the command passed in - it must be some break set variant - and analyze the result.
 508     Returns a dictionary of information gleaned from the command-line results.
 509     Will assert if the breakpoint setting fails altogether.
 510
 511     Dictionary will contain:
 512         bpno          - breakpoint of the newly created breakpoint, -1 on error.
 513         num_locations - number of locations set for the breakpoint.
 514
 515     If there is only one location, the dictionary MAY contain:
 516         file          - source file name
 517         line_no       - source line number
 518         symbol        - symbol name
 519         inline_symbol - inlined symbol name
 520         offset        - offset from the original symbol
 521         module        - module
 522         address       - address at which the breakpoint was set."""
 523
 524     patterns = [
 525         r"^Breakpoint (?P<bpno>[0-9]+): (?P<num_locations>[0-9]+) locations\.$",
 526         r"^Breakpoint (?P<bpno>[0-9]+): (?P<num_locations>no) locations \(pending\)\.",
 527         r"^Breakpoint (?P<bpno>[0-9]+): where = (?P<module>.*)`(?P<symbol>[+\-]{0,1}[^+]+)( \+ (?P<offset>[0-9]+)){0,1}( \[inlined\] (?P<inline_symbol>.*)){0,1} at (?P<file>[^:]+):(?P<line_no>[0-9]+)(?P<column>(:[0-9]+)?), address = (?P<address>0x[0-9a-fA-F]+)$",
 528         r"^Breakpoint (?P<bpno>[0-9]+): where = (?P<module>.*)`(?P<symbol>.*)( \+ (?P<offset>[0-9]+)){0,1}, address = (?P<address>0x[0-9a-fA-F]+)$"]
 529     match_object = test.match(command, patterns)
 530     break_results = match_object.groupdict()
 531
 532     # We always insert the breakpoint number, setting it to -1 if we couldn't find it
 533     # Also, make sure it gets stored as an integer.
 534     if not 'bpno' in break_results:
 535         break_results['bpno'] = -1
 536     else:
 537         break_results['bpno'] = int(break_results['bpno'])
 538
 539     # We always insert the number of locations
 540     # If ONE location is set for the breakpoint, then the output doesn't mention locations, but it has to be 1...
 541     # We also make sure it is an integer.
 542
 543     if not 'num_locations' in break_results:
 544         num_locations = 1
 545     else:
 546         num_locations = break_results['num_locations']
 547         if num_locations == 'no':
 548             num_locations = 0
 549         else:
 550             num_locations = int(break_results['num_locations'])
 551
 552     break_results['num_locations'] = num_locations
 553
 554     if 'line_no' in break_results:
 555         break_results['line_no'] = int(break_results['line_no'])
 556
 557     return break_results
 558
 559
 560 def get_bpno_from_match(break_results):
 561     return int(break_results['bpno'])
 562
 563
 564 def check_breakpoint_result(
 565         test,
 566         break_results,
 567         file_name=None,
 568         line_number=-1,
 569         symbol_name=None,
 570         symbol_match_exact=True,
 571         module_name=None,
 572         offset=-1,
 573         num_locations=-1):
 574
 575     out_num_locations = break_results['num_locations']
 576
 577     if num_locations == -1:
 578         test.assertTrue(out_num_locations > 0,
 579                         "Expecting one or more locations, got none.")
 580     elif num_locations != -2:
 581         test.assertTrue(
 582             num_locations == out_num_locations,
 583             "Expecting %d locations, got %d." %
 584             (num_locations,
 585              out_num_locations))
 586
 587     if file_name:
 588         out_file_name = ""
 589         if 'file' in break_results:
 590             out_file_name = break_results['file']
 591         test.assertTrue(
 592             file_name.endswith(out_file_name),
 593             "Breakpoint file name '%s' doesn't match resultant name '%s'." %
 594             (file_name,
 595              out_file_name))
 596
 597     if line_number != -1:
 598         out_line_number = -1
 599         if 'line_no' in break_results:
 600             out_line_number = break_results['line_no']
 601
 602         test.assertTrue(
 603             line_number == out_line_number,
 604             "Breakpoint line number %s doesn't match resultant line %s." %
 605             (line_number,
 606              out_line_number))
 607
 608     if symbol_name:
 609         out_symbol_name = ""
 610         # Look first for the inlined symbol name, otherwise use the symbol
 611         # name:
 612         if 'inline_symbol' in break_results and break_results['inline_symbol']:
 613             out_symbol_name = break_results['inline_symbol']
 614         elif 'symbol' in break_results:
 615             out_symbol_name = break_results['symbol']
 616
 617         if symbol_match_exact:
 618             test.assertTrue(
 619                 symbol_name == out_symbol_name,
 620                 "Symbol name '%s' doesn't match resultant symbol '%s'." %
 621                 (symbol_name,
 622                  out_symbol_name))
 623         else:
 624             test.assertTrue(
 625                 out_symbol_name.find(symbol_name) != -
 626                 1,
 627                 "Symbol name '%s' isn't in resultant symbol '%s'." %
 628                 (symbol_name,
 629                  out_symbol_name))
 630
 631     if module_name:
 632         out_module_name = None
 633         if 'module' in break_results:
 634             out_module_name = break_results['module']
 635
 636         test.assertTrue(
 637             module_name.find(out_module_name) != -
 638             1,
 639             "Symbol module name '%s' isn't in expected module name '%s'." %
 640             (out_module_name,
 641              module_name))
 642
 643 # ==================================================
 644 # Utility functions related to Threads and Processes
 645 # ==================================================
 646
 647
 648 def get_stopped_threads(process, reason):
 649     """Returns the thread(s) with the specified stop reason in a list.
 650
 651     The list can be empty if no such thread exists.
 652     """
 653     threads = []
 654     for t in process:
 655         if t.GetStopReason() == reason:
 656             threads.append(t)
 657     return threads
 658
 659
 660 def get_stopped_thread(process, reason):
 661     """A convenience function which returns the first thread with the given stop
 662     reason or None.
 663
 664     Example usages:
 665
 666     1. Get the stopped thread due to a breakpoint condition
 667
 668     ...
 669         from lldbutil import get_stopped_thread
 670         thread = get_stopped_thread(process, lldb.eStopReasonPlanComplete)
 671         self.assertTrue(thread.IsValid(), "There should be a thread stopped due to breakpoint condition")
 672     ...
 673
 674     2. Get the thread stopped due to a breakpoint
 675
 676     ...
 677         from lldbutil import get_stopped_thread
 678         thread = get_stopped_thread(process, lldb.eStopReasonBreakpoint)
 679         self.assertTrue(thread.IsValid(), "There should be a thread stopped due to breakpoint")
 680     ...
 681
 682     """
 683     threads = get_stopped_threads(process, reason)
 684     if len(threads) == 0:
 685         return None
 686     return threads[0]
 687
 688
 689 def get_threads_stopped_at_breakpoint_id(process, bpid):
 690     """ For a stopped process returns the thread stopped at the breakpoint passed in bkpt"""
 691     stopped_threads = []
 692     threads = []
 693
 694     stopped_threads = get_stopped_threads(process, lldb.eStopReasonBreakpoint)
 695
 696     if len(stopped_threads) == 0:
 697         return threads
 698
 699     for thread in stopped_threads:
 700         # Make sure we've hit our breakpoint...
 701         break_id = thread.GetStopReasonDataAtIndex(0)
 702         if break_id == bpid:
 703             threads.append(thread)
 704
 705     return threads
 706
 707
 708 def get_threads_stopped_at_breakpoint(process, bkpt):
 709     return get_threads_stopped_at_breakpoint_id(process, bkpt.GetID())
 710
 711
 712 def get_one_thread_stopped_at_breakpoint_id(
 713         process, bpid, require_exactly_one=True):
 714     threads = get_threads_stopped_at_breakpoint_id(process, bpid)
 715     if len(threads) == 0:
 716         return None
 717     if require_exactly_one and len(threads) != 1:
 718         return None
 719
 720     return threads[0]
 721
 722
 723 def get_one_thread_stopped_at_breakpoint(
 724         process, bkpt, require_exactly_one=True):
 725     return get_one_thread_stopped_at_breakpoint_id(
 726         process, bkpt.GetID(), require_exactly_one)
 727
 728
 729 def is_thread_crashed(test, thread):
 730     """In the test suite we dereference a null pointer to simulate a crash. The way this is
 731     reported depends on the platform."""
 732     if test.platformIsDarwin():
 733         return thread.GetStopReason(
 734         ) == lldb.eStopReasonException and "EXC_BAD_ACCESS" in thread.GetStopDescription(100)
 735     elif test.getPlatform() == "linux":
 736         return thread.GetStopReason() == lldb.eStopReasonSignal and thread.GetStopReasonDataAtIndex(
 737             0) == thread.GetProcess().GetUnixSignals().GetSignalNumberFromName("SIGSEGV")
 738     elif test.getPlatform() == "windows":
 739         return "Exception 0xc0000005" in thread.GetStopDescription(200)
 740     else:
 741         return "invalid address" in thread.GetStopDescription(100)
 742
 743
 744 def get_crashed_threads(test, process):
 745     threads = []
 746     if process.GetState() != lldb.eStateStopped:
 747         return threads
 748     for thread in process:
 749         if is_thread_crashed(test, thread):
 750             threads.append(thread)
 751     return threads
 752
 753 # Helper functions for run_to_{source,name}_breakpoint:
 754
 755 def run_to_breakpoint_make_target(test, exe_name = "a.out", in_cwd = True):
 756     if in_cwd:
 757         exe = test.getBuildArtifact(exe_name)
 758
 759     # Create the target
 760     target = test.dbg.CreateTarget(exe)
 761     test.assertTrue(target, "Target: %s is not valid."%(exe_name))
 762
 763     # Set environment variables for the inferior.
 764     if lldbtest_config.inferior_env:
 765         test.runCmd('settings set target.env-vars {}'.format(
 766             lldbtest_config.inferior_env))
 767
 768     return target
 769
 770 def run_to_breakpoint_do_run(test, target, bkpt, launch_info = None,
 771                              only_one_thread = True, extra_images = None):
 772
 773     # Launch the process, and do not stop at the entry point.
 774     if not launch_info:
 775         launch_info = target.GetLaunchInfo()
 776         launch_info.SetWorkingDirectory(test.get_process_working_directory())
 777
 778     if extra_images:
 779         environ = test.registerSharedLibrariesWithTarget(target, extra_images)
 780         launch_info.SetEnvironmentEntries(environ, True)
 781
 782     error = lldb.SBError()
 783     process = target.Launch(launch_info, error)
 784
 785     test.assertTrue(process,
 786                     "Could not create a valid process for %s: %s"%(target.GetExecutable().GetFilename(),
 787                     error.GetCString()))
 788     test.assertFalse(error.Fail(),
 789                      "Process launch failed: %s" % (error.GetCString()))
 790
 791     test.assertEqual(process.GetState(), lldb.eStateStopped)
 792
 793     # Frame #0 should be at our breakpoint.
 794     threads = get_threads_stopped_at_breakpoint(
 795                 process, bkpt)
 796
 797     num_threads = len(threads)
 798     if only_one_thread:
 799         test.assertEqual(num_threads, 1, "Expected 1 thread to stop at breakpoint, %d did."%(num_threads))
 800     else:
 801         test.assertGreater(num_threads, 0, "No threads stopped at breakpoint")
 802
 803     thread = threads[0]
 804     return (target, process, thread, bkpt)
 805
 806 def run_to_name_breakpoint (test, bkpt_name, launch_info = None,
 807                             exe_name = "a.out",
 808                             bkpt_module = None,
 809                             in_cwd = True,
 810                             only_one_thread = True,
 811                             extra_images = None):
 812     """Start up a target, using exe_name as the executable, and run it to
 813        a breakpoint set by name on bkpt_name restricted to bkpt_module.
 814
 815        If you want to pass in launch arguments or environment
 816        variables, you can optionally pass in an SBLaunchInfo.  If you
 817        do that, remember to set the working directory as well.
 818
 819        If your executable isn't called a.out, you can pass that in.
 820        And if your executable isn't in the CWD, pass in the absolute
 821        path to the executable in exe_name, and set in_cwd to False.
 822
 823        If you need to restrict the breakpoint to a particular module,
 824        pass the module name (a string not a FileSpec) in bkpt_module.  If
 825        nothing is passed in setting will be unrestricted.
 826
 827        If the target isn't valid, the breakpoint isn't found, or hit, the
 828        function will cause a testsuite failure.
 829
 830        If successful it returns a tuple with the target process and
 831        thread that hit the breakpoint, and the breakpoint that we set
 832        for you.
 833
 834        If only_one_thread is true, we require that there be only one
 835        thread stopped at the breakpoint.  Otherwise we only require one
 836        or more threads stop there.  If there are more than one, we return
 837        the first thread that stopped.
 838     """
 839
 840     target = run_to_breakpoint_make_target(test, exe_name, in_cwd)
 841
 842     breakpoint = target.BreakpointCreateByName(bkpt_name, bkpt_module)
 843
 844
 845     test.assertTrue(breakpoint.GetNumLocations() > 0,
 846                     "No locations found for name breakpoint: '%s'."%(bkpt_name))
 847     return run_to_breakpoint_do_run(test, target, breakpoint, launch_info,
 848                                     only_one_thread, extra_images)
 849
 850 def run_to_source_breakpoint(test, bkpt_pattern, source_spec,
 851                              launch_info = None, exe_name = "a.out",
 852                              bkpt_module = None,
 853                              in_cwd = True,
 854                              only_one_thread = True,
 855                              extra_images = None):
 856     """Start up a target, using exe_name as the executable, and run it to
 857        a breakpoint set by source regex bkpt_pattern.
 858
 859        The rest of the behavior is the same as run_to_name_breakpoint.
 860     """
 861
 862     target = run_to_breakpoint_make_target(test, exe_name, in_cwd)
 863     # Set the breakpoints
 864     breakpoint = target.BreakpointCreateBySourceRegex(
 865             bkpt_pattern, source_spec, bkpt_module)
 866     test.assertTrue(breakpoint.GetNumLocations() > 0,
 867         'No locations found for source breakpoint: "%s", file: "%s", dir: "%s"'
 868         %(bkpt_pattern, source_spec.GetFilename(), source_spec.GetDirectory()))
 869     return run_to_breakpoint_do_run(test, target, breakpoint, launch_info,
 870                                     only_one_thread, extra_images)
 871
 872 def run_to_line_breakpoint(test, source_spec, line_number, column = 0,
 873                            launch_info = None, exe_name = "a.out",
 874                            bkpt_module = None,
 875                            in_cwd = True,
 876                            only_one_thread = True,
 877                            extra_images = None):
 878     """Start up a target, using exe_name as the executable, and run it to
 879        a breakpoint set by (source_spec, line_number(, column)).
 880
 881        The rest of the behavior is the same as run_to_name_breakpoint.
 882     """
 883
 884     target = run_to_breakpoint_make_target(test, exe_name, in_cwd)
 885     # Set the breakpoints
 886     breakpoint = target.BreakpointCreateByLocation(
 887         source_spec, line_number, column, 0, lldb.SBFileSpecList())
 888     test.assertTrue(breakpoint.GetNumLocations() > 0,
 889         'No locations found for line breakpoint: "%s:%d(:%d)", dir: "%s"'
 890         %(source_spec.GetFilename(), line_number, column,
 891           source_spec.GetDirectory()))
 892     return run_to_breakpoint_do_run(test, target, breakpoint, launch_info,
 893                                     only_one_thread, extra_images)
 894
 895
 896 def continue_to_breakpoint(process, bkpt):
 897     """ Continues the process, if it stops, returns the threads stopped at bkpt; otherwise, returns None"""
 898     process.Continue()
 899     if process.GetState() != lldb.eStateStopped:
 900         return None
 901     else:
 902         return get_threads_stopped_at_breakpoint(process, bkpt)
 903
 904
 905 def get_caller_symbol(thread):
 906     """
 907     Returns the symbol name for the call site of the leaf function.
 908     """
 909     depth = thread.GetNumFrames()
 910     if depth <= 1:
 911         return None
 912     caller = thread.GetFrameAtIndex(1).GetSymbol()
 913     if caller:
 914         return caller.GetName()
 915     else:
 916         return None
 917
 918
 919 def get_function_names(thread):
 920     """
 921     Returns a sequence of function names from the stack frames of this thread.
 922     """
 923     def GetFuncName(i):
 924         return thread.GetFrameAtIndex(i).GetFunctionName()
 925
 926     return list(map(GetFuncName, list(range(thread.GetNumFrames()))))
 927
 928
 929 def get_symbol_names(thread):
 930     """
 931     Returns a sequence of symbols for this thread.
 932     """
 933     def GetSymbol(i):
 934         return thread.GetFrameAtIndex(i).GetSymbol().GetName()
 935
 936     return list(map(GetSymbol, list(range(thread.GetNumFrames()))))
 937
 938
 939 def get_pc_addresses(thread):
 940     """
 941     Returns a sequence of pc addresses for this thread.
 942     """
 943     def GetPCAddress(i):
 944         return thread.GetFrameAtIndex(i).GetPCAddress()
 945
 946     return list(map(GetPCAddress, list(range(thread.GetNumFrames()))))
 947
 948
 949 def get_filenames(thread):
 950     """
 951     Returns a sequence of file names from the stack frames of this thread.
 952     """
 953     def GetFilename(i):
 954         return thread.GetFrameAtIndex(
 955             i).GetLineEntry().GetFileSpec().GetFilename()
 956
 957     return list(map(GetFilename, list(range(thread.GetNumFrames()))))
 958
 959
 960 def get_line_numbers(thread):
 961     """
 962     Returns a sequence of line numbers from the stack frames of this thread.
 963     """
 964     def GetLineNumber(i):
 965         return thread.GetFrameAtIndex(i).GetLineEntry().GetLine()
 966
 967     return list(map(GetLineNumber, list(range(thread.GetNumFrames()))))
 968
 969
 970 def get_module_names(thread):
 971     """
 972     Returns a sequence of module names from the stack frames of this thread.
 973     """
 974     def GetModuleName(i):
 975         return thread.GetFrameAtIndex(
 976             i).GetModule().GetFileSpec().GetFilename()
 977
 978     return list(map(GetModuleName, list(range(thread.GetNumFrames()))))
 979
 980
 981 def get_stack_frames(thread):
 982     """
 983     Returns a sequence of stack frames for this thread.
 984     """
 985     def GetStackFrame(i):
 986         return thread.GetFrameAtIndex(i)
 987
 988     return list(map(GetStackFrame, list(range(thread.GetNumFrames()))))
 989
 990
 991 def print_stacktrace(thread, string_buffer=False):
 992     """Prints a simple stack trace of this thread."""
 993
 994     output = SixStringIO() if string_buffer else sys.stdout
 995     target = thread.GetProcess().GetTarget()
 996
 997     depth = thread.GetNumFrames()
 998
 999     mods = get_module_names(thread)
1000     funcs = get_function_names(thread)
1001     symbols = get_symbol_names(thread)
1002     files = get_filenames(thread)
1003     lines = get_line_numbers(thread)
1004     addrs = get_pc_addresses(thread)
1005
1006     if thread.GetStopReason() != lldb.eStopReasonInvalid:
1007         desc = "stop reason=" + stop_reason_to_str(thread.GetStopReason())
1008     else:
1009         desc = ""
1010     print(
1011         "Stack trace for thread id={0:#x} name={1} queue={2} ".format(
1012             thread.GetThreadID(),
1013             thread.GetName(),
1014             thread.GetQueueName()) + desc,
1015         file=output)
1016
1017     for i in range(depth):
1018         frame = thread.GetFrameAtIndex(i)
1019         function = frame.GetFunction()
1020
1021         load_addr = addrs[i].GetLoadAddress(target)
1022         if not function:
1023             file_addr = addrs[i].GetFileAddress()
1024             start_addr = frame.GetSymbol().GetStartAddress().GetFileAddress()
1025             symbol_offset = file_addr - start_addr
1026             print(
1027                 "  frame #{num}: {addr:#016x} {mod}`{symbol} + {offset}".format(
1028                     num=i,
1029                     addr=load_addr,
1030                     mod=mods[i],
1031                     symbol=symbols[i],
1032                     offset=symbol_offset),
1033                 file=output)
1034         else:
1035             print(
1036                 "  frame #{num}: {addr:#016x} {mod}`{func} at {file}:{line} {args}".format(
1037                     num=i,
1038                     addr=load_addr,
1039                     mod=mods[i],
1040                     func='%s [inlined]' %
1041                     funcs[i] if frame.IsInlined() else funcs[i],
1042                     file=files[i],
1043                     line=lines[i],
1044                     args=get_args_as_string(
1045                         frame,
1046                         showFuncName=False) if not frame.IsInlined() else '()'),
1047                 file=output)
1048
1049     if string_buffer:
1050         return output.getvalue()
1051
1052
1053 def print_stacktraces(process, string_buffer=False):
1054     """Prints the stack traces of all the threads."""
1055
1056     output = SixStringIO() if string_buffer else sys.stdout
1057
1058     print("Stack traces for " + str(process), file=output)
1059
1060     for thread in process:
1061         print(print_stacktrace(thread, string_buffer=True), file=output)
1062
1063     if string_buffer:
1064         return output.getvalue()
1065
1066
1067 def expect_state_changes(test, listener, process, states, timeout=30):
1068     """Listens for state changed events on the listener and makes sure they match what we
1069     expect. Stop-and-restart events (where GetRestartedFromEvent() returns true) are ignored."""
1070
1071     for expected_state in states:
1072         def get_next_event():
1073             event = lldb.SBEvent()
1074             if not listener.WaitForEventForBroadcasterWithType(
1075                     timeout,
1076                     process.GetBroadcaster(),
1077                     lldb.SBProcess.eBroadcastBitStateChanged,
1078                     event):
1079                 test.fail(
1080                     "Timed out while waiting for a transition to state %s" %
1081                     lldb.SBDebugger.StateAsCString(expected_state))
1082             return event
1083
1084         event = get_next_event()
1085         while (lldb.SBProcess.GetStateFromEvent(event) == lldb.eStateStopped and
1086                 lldb.SBProcess.GetRestartedFromEvent(event)):
1087             # Ignore restarted event and the subsequent running event.
1088             event = get_next_event()
1089             test.assertEqual(
1090                 lldb.SBProcess.GetStateFromEvent(event),
1091                 lldb.eStateRunning,
1092                 "Restarted event followed by a running event")
1093             event = get_next_event()
1094
1095         test.assertEqual(
1096             lldb.SBProcess.GetStateFromEvent(event),
1097             expected_state)
1098
1099 # ===================================
1100 # Utility functions related to Frames
1101 # ===================================
1102
1103
1104 def get_parent_frame(frame):
1105     """
1106     Returns the parent frame of the input frame object; None if not available.
1107     """
1108     thread = frame.GetThread()
1109     parent_found = False
1110     for f in thread:
1111         if parent_found:
1112             return f
1113         if f.GetFrameID() == frame.GetFrameID():
1114             parent_found = True
1115
1116     # If we reach here, no parent has been found, return None.
1117     return None
1118
1119
1120 def get_args_as_string(frame, showFuncName=True):
1121     """
1122     Returns the args of the input frame object as a string.
1123     """
1124     # arguments     => True
1125     # locals        => False
1126     # statics       => False
1127     # in_scope_only => True
1128     vars = frame.GetVariables(True, False, False, True)  # type of SBValueList
1129     args = []  # list of strings
1130     for var in vars:
1131         args.append("(%s)%s=%s" % (var.GetTypeName(),
1132                                    var.GetName(),
1133                                    var.GetValue()))
1134     if frame.GetFunction():
1135         name = frame.GetFunction().GetName()
1136     elif frame.GetSymbol():
1137         name = frame.GetSymbol().GetName()
1138     else:
1139         name = ""
1140     if showFuncName:
1141         return "%s(%s)" % (name, ", ".join(args))
1142     else:
1143         return "(%s)" % (", ".join(args))
1144
1145
1146 def print_registers(frame, string_buffer=False):
1147     """Prints all the register sets of the frame."""
1148
1149     output = SixStringIO() if string_buffer else sys.stdout
1150
1151     print("Register sets for " + str(frame), file=output)
1152
1153     registerSet = frame.GetRegisters()  # Return type of SBValueList.
1154     print("Frame registers (size of register set = %d):" %
1155           registerSet.GetSize(), file=output)
1156     for value in registerSet:
1157         #print(value, file=output)
1158         print("%s (number of children = %d):" %
1159               (value.GetName(), value.GetNumChildren()), file=output)
1160         for child in value:
1161             print(
1162                 "Name: %s, Value: %s" %
1163                 (child.GetName(),
1164                  child.GetValue()),
1165                 file=output)
1166
1167     if string_buffer:
1168         return output.getvalue()
1169
1170
1171 def get_registers(frame, kind):
1172     """Returns the registers given the frame and the kind of registers desired.
1173
1174     Returns None if there's no such kind.
1175     """
1176     registerSet = frame.GetRegisters()  # Return type of SBValueList.
1177     for value in registerSet:
1178         if kind.lower() in value.GetName().lower():
1179             return value
1180
1181     return None
1182
1183
1184 def get_GPRs(frame):
1185     """Returns the general purpose registers of the frame as an SBValue.
1186
1187     The returned SBValue object is iterable.  An example:
1188         ...
1189         from lldbutil import get_GPRs
1190         regs = get_GPRs(frame)
1191         for reg in regs:
1192             print("%s => %s" % (reg.GetName(), reg.GetValue()))
1193         ...
1194     """
1195     return get_registers(frame, "general purpose")
1196
1197
1198 def get_FPRs(frame):
1199     """Returns the floating point registers of the frame as an SBValue.
1200
1201     The returned SBValue object is iterable.  An example:
1202         ...
1203         from lldbutil import get_FPRs
1204         regs = get_FPRs(frame)
1205         for reg in regs:
1206             print("%s => %s" % (reg.GetName(), reg.GetValue()))
1207         ...
1208     """
1209     return get_registers(frame, "floating point")
1210
1211
1212 def get_ESRs(frame):
1213     """Returns the exception state registers of the frame as an SBValue.
1214
1215     The returned SBValue object is iterable.  An example:
1216         ...
1217         from lldbutil import get_ESRs
1218         regs = get_ESRs(frame)
1219         for reg in regs:
1220             print("%s => %s" % (reg.GetName(), reg.GetValue()))
1221         ...
1222     """
1223     return get_registers(frame, "exception state")
1224
1225 # ======================================
1226 # Utility classes/functions for SBValues
1227 # ======================================
1228
1229
1230 class BasicFormatter(object):
1231     """The basic formatter inspects the value object and prints the value."""
1232
1233     def format(self, value, buffer=None, indent=0):
1234         if not buffer:
1235             output = SixStringIO()
1236         else:
1237             output = buffer
1238         # If there is a summary, it suffices.
1239         val = value.GetSummary()
1240         # Otherwise, get the value.
1241         if val is None:
1242             val = value.GetValue()
1243         if val is None and value.GetNumChildren() > 0:
1244             val = "%s (location)" % value.GetLocation()
1245         print("{indentation}({type}) {name} = {value}".format(
1246             indentation=' ' * indent,
1247             type=value.GetTypeName(),
1248             name=value.GetName(),
1249             value=val), file=output)
1250         return output.getvalue()
1251
1252
1253 class ChildVisitingFormatter(BasicFormatter):
1254     """The child visiting formatter prints the value and its immediate children.
1255
1256     The constructor takes a keyword arg: indent_child, which defaults to 2.
1257     """
1258
1259     def __init__(self, indent_child=2):
1260         """Default indentation of 2 SPC's for the children."""
1261         self.cindent = indent_child
1262
1263     def format(self, value, buffer=None):
1264         if not buffer:
1265             output = SixStringIO()
1266         else:
1267             output = buffer
1268
1269         BasicFormatter.format(self, value, buffer=output)
1270         for child in value:
1271             BasicFormatter.format(
1272                 self, child, buffer=output, indent=self.cindent)
1273
1274         return output.getvalue()
1275
1276
1277 class RecursiveDecentFormatter(BasicFormatter):
1278     """The recursive decent formatter prints the value and the decendents.
1279
1280     The constructor takes two keyword args: indent_level, which defaults to 0,
1281     and indent_child, which defaults to 2.  The current indentation level is
1282     determined by indent_level, while the immediate children has an additional
1283     indentation by inden_child.
1284     """
1285
1286     def __init__(self, indent_level=0, indent_child=2):
1287         self.lindent = indent_level
1288         self.cindent = indent_child
1289
1290     def format(self, value, buffer=None):
1291         if not buffer:
1292             output = SixStringIO()
1293         else:
1294             output = buffer
1295
1296         BasicFormatter.format(self, value, buffer=output, indent=self.lindent)
1297         new_indent = self.lindent + self.cindent
1298         for child in value:
1299             if child.GetSummary() is not None:
1300                 BasicFormatter.format(
1301                     self, child, buffer=output, indent=new_indent)
1302             else:
1303                 if child.GetNumChildren() > 0:
1304                     rdf = RecursiveDecentFormatter(indent_level=new_indent)
1305                     rdf.format(child, buffer=output)
1306                 else:
1307                     BasicFormatter.format(
1308                         self, child, buffer=output, indent=new_indent)
1309
1310         return output.getvalue()
1311
1312 # ===========================================================
1313 # Utility functions for path manipulation on remote platforms
1314 # ===========================================================
1315
1316
1317 def join_remote_paths(*paths):
1318     # TODO: update with actual platform name for remote windows once it exists
1319     if lldb.remote_platform.GetName() == 'remote-windows':
1320         return os.path.join(*paths).replace(os.path.sep, '\\')
1321     return os.path.join(*paths).replace(os.path.sep, '/')
1322
1323
1324 def append_to_process_working_directory(test, *paths):
1325     remote = lldb.remote_platform
1326     if remote:
1327         return join_remote_paths(remote.GetWorkingDirectory(), *paths)
1328     return os.path.join(test.getBuildDir(), *paths)
1329
1330 # ==================================================
1331 # Utility functions to get the correct signal number
1332 # ==================================================
1333
1334 import signal
1335
1336
1337 def get_signal_number(signal_name):
1338     platform = lldb.remote_platform
1339     if platform and platform.IsValid():
1340         signals = platform.GetUnixSignals()
1341         if signals.IsValid():
1342             signal_number = signals.GetSignalNumberFromName(signal_name)
1343             if signal_number > 0:
1344                 return signal_number
1345     # No remote platform; fall back to using local python signals.
1346     return getattr(signal, signal_name)
1347
1348
1349 class PrintableRegex(object):
1350
1351     def __init__(self, text):
1352         self.regex = re.compile(text)
1353         self.text = text
1354
1355     def match(self, str):
1356         return self.regex.match(str)
1357
1358     def __str__(self):
1359         return "%s" % (self.text)
1360
1361     def __repr__(self):
1362         return "re.compile(%s) -> %s" % (self.text, self.regex)
1363
1364
1365 def skip_if_callable(test, mycallable, reason):
1366     if six.callable(mycallable):
1367         if mycallable(test):
1368             test.skipTest(reason)
1369             return True
1370     return False
1371
1372
1373 def skip_if_library_missing(test, target, library):
1374     def find_library(target, library):
1375         for module in target.modules:
1376             filename = module.file.GetFilename()
1377             if isinstance(library, str):
1378                 if library == filename:
1379                     return False
1380             elif hasattr(library, 'match'):
1381                 if library.match(filename):
1382                     return False
1383         return True
1384
1385     def find_library_callable(test):
1386         return find_library(target, library)
1387     return skip_if_callable(
1388         test,
1389         find_library_callable,
1390         "could not find library matching '%s' in target %s" %
1391         (library,
1392          target))
1393
1394
1395 def read_file_on_target(test, remote):
1396     if lldb.remote_platform:
1397         local = test.getBuildArtifact("file_from_target")
1398         error = lldb.remote_platform.Get(lldb.SBFileSpec(remote, False),
1399                     lldb.SBFileSpec(local, True))
1400         test.assertTrue(error.Success(), "Reading file {0} failed: {1}".format(remote, error))
1401     else:
1402         local = remote
1403     with open(local, 'r') as f:
1404         return f.read()
1405
1406 def read_file_from_process_wd(test, name):
1407     path = append_to_process_working_directory(test, name)
1408     return read_file_on_target(test, path)
1409
1410 def wait_for_file_on_target(testcase, file_path, max_attempts=6):
1411     for i in range(max_attempts):
1412         err, retcode, msg = testcase.run_platform_command("ls %s" % file_path)
1413         if err.Success() and retcode == 0:
1414             break
1415         if i < max_attempts:
1416             # Exponential backoff!
1417             import time
1418             time.sleep(pow(2, i) * 0.25)
1419     else:
1420         testcase.fail(
1421             "File %s not found even after %d attempts." %
1422             (file_path, max_attempts))
1423
1424     return read_file_on_target(testcase, file_path)