lldbutil.py

"""
This LLDB module contains miscellaneous utilities.
Some of the test suite takes advantage of the utility functions defined here.
They can also be useful for general purpose lldb scripting.
"""

# System modules
importerrno
importio
importos
importre
importsys
importsubprocess
fromtypingimportDict

# LLDB modules
importlldb
from . importlldbtest_config
from . importconfiguration

# How often failed simulator process launches are retried.
SIMULATOR_RETRY=3

# ===================================================
# Utilities for locating/checking executable programs
# ===================================================


defis_exe(fpath):
"""Returns True if fpath is an executable."""
returnos.path.isfile(fpath) andos.access(fpath, os.X_OK)


defwhich(program):
"""Returns the full path to a program; None otherwise."""
fpath, fname=os.path.split(program)
iffpath:
ifis_exe(program):
returnprogram
else:
forpathinos.environ["PATH"].split(os.pathsep):
exe_file=os.path.join(path, program)
ifis_exe(exe_file):
returnexe_file
returnNone


defmkdir_p(path):
try:
os.makedirs(path)
exceptOSErrorase:
ife.errno!=errno.EEXIST:
raise
ifnotos.path.isdir(path):
raiseOSError(errno.ENOTDIR, "%s is not a directory"%path)


# ============================
# Dealing with SDK and triples
# ============================


defget_xcode_sdk(os, env):
# Respect --apple-sdk <path> if it's specified. If the SDK is simply
# mounted from some disk image, and not actually installed, this is the
# only way to use it.
ifconfiguration.apple_sdk:
returnconfiguration.apple_sdk
ifos=="ios":
ifenv=="simulator":
return"iphonesimulator"
ifenv=="macabi":
return"macosx"
return"iphoneos"
elifos=="tvos":
ifenv=="simulator":
return"appletvsimulator"
return"appletvos"
elifos=="watchos":
ifenv=="simulator":
return"watchsimulator"
return"watchos"
returnos


defget_xcode_sdk_version(sdk):
return (
subprocess.check_output(["xcrun", "--sdk", sdk, "--show-sdk-version"])
 .rstrip()
 .decode("utf-8")
 )


defget_xcode_sdk_root(sdk):
return (
subprocess.check_output(["xcrun", "--sdk", sdk, "--show-sdk-path"])
 .rstrip()
 .decode("utf-8")
 )


defget_xcode_clang(sdk):
return (
subprocess.check_output(["xcrun", "-sdk", sdk, "-f", "clang"])
 .rstrip()
 .decode("utf-8")
 )


# ===================================================
# Disassembly for an SBFunction or an SBSymbol object
# ===================================================


defdisassemble(target, function_or_symbol):
"""Disassemble the function or symbol given a target.

 It returns the disassembly content in a string object.
 """
buf=io.StringIO()
insts=function_or_symbol.GetInstructions(target)
foriininsts:
print(i, file=buf)
returnbuf.getvalue()


# ==========================================================
# Integer (byte size 1, 2, 4, and 8) to bytearray conversion
# ==========================================================


defint_to_bytearray(val, bytesize):
"""Utility function to convert an integer into a bytearray.

 It returns the bytearray in the little endian format. It is easy to get the
 big endian format, just do ba.reverse() on the returned object.
 """
importstruct

ifbytesize==1:
returnbytearray([val])

# Little endian followed by a format character.
template="<%c"
ifbytesize==2:
fmt=template%"h"
elifbytesize==4:
fmt=template%"i"
elifbytesize==4:
fmt=template%"q"
else:
returnNone

packed=struct.pack(fmt, val)
returnbytearray(packed)


defbytearray_to_int(bytes, bytesize):
"""Utility function to convert a bytearray into an integer.

 It interprets the bytearray in the little endian format. For a big endian
 bytearray, just do ba.reverse() on the object before passing it in.
 """
importstruct

ifbytesize==1:
returnbytes[0]

# Little endian followed by a format character.
template="<%c"
ifbytesize==2:
fmt=template%"h"
elifbytesize==4:
fmt=template%"i"
elifbytesize==4:
fmt=template%"q"
else:
returnNone

unpacked=struct.unpack_from(fmt, bytes)
returnunpacked[0]


# ==============================================================
# Get the description of an lldb object or None if not available
# ==============================================================
defget_description(obj, option=None):
"""Calls lldb_obj.GetDescription() and returns a string, or None.

 For SBTarget, SBBreakpointLocation, and SBWatchpoint lldb objects, an extra
 option can be passed in to describe the detailed level of description
 desired:
 o lldb.eDescriptionLevelBrief
 o lldb.eDescriptionLevelFull
 o lldb.eDescriptionLevelVerbose
 """
method=getattr(obj, "GetDescription")
ifnotmethod:
returnNone
tuple= (lldb.SBTarget, lldb.SBBreakpointLocation, lldb.SBWatchpoint)
ifisinstance(obj, tuple):
ifoptionisNone:
option=lldb.eDescriptionLevelBrief

stream=lldb.SBStream()
ifoptionisNone:
success=method(stream)
else:
success=method(stream, option)
ifnotsuccess:
returnNone
returnstream.GetData()


# =================================================
# Convert some enum value to its string counterpart
# =================================================


def_enum_names(prefix: str) ->Dict[int, str]:
"""Generate a mapping of enum value to name, for the enum prefix."""
suffix_start=len(prefix)
return {
getattr(lldb, attr): attr[suffix_start:].lower()
forattrindir(lldb)
ifattr.startswith(prefix)
 }


_STATE_NAMES=_enum_names(prefix="eState")


defstate_type_to_str(enum: int) ->str:
"""Returns the stateType string given an enum."""
name=_STATE_NAMES.get(enum)
ifname:
returnname
raiseException(f"Unknown StateType enum: {enum}")


_STOP_REASON_NAMES=_enum_names(prefix="eStopReason")


defstop_reason_to_str(enum: int) ->str:
"""Returns the stopReason string given an enum."""
name=_STOP_REASON_NAMES.get(enum)
ifname:
returnname
raiseException(f"Unknown StopReason enum: {enum}")


_SYMBOL_TYPE_NAMES=_enum_names(prefix="eSymbolType")


defsymbol_type_to_str(enum: int) ->str:
"""Returns the symbolType string given an enum."""
name=_SYMBOL_TYPE_NAMES.get(enum)
ifname:
returnname
raiseException(f"Unknown SymbolType enum: {enum}")


_VALUE_TYPE_NAMES=_enum_names(prefix="eValueType")


defvalue_type_to_str(enum: int) ->str:
"""Returns the valueType string given an enum."""
name=_VALUE_TYPE_NAMES.get(enum)
ifname:
returnname
raiseException(f"Unknown ValueType enum: {enum}")


# ==================================================
# Get stopped threads due to each stop reason.
# ==================================================


defsort_stopped_threads(
process,
breakpoint_threads=None,
crashed_threads=None,
watchpoint_threads=None,
signal_threads=None,
exiting_threads=None,
other_threads=None,
):
"""Fills array *_threads with threads stopped for the corresponding stop
 reason.
 """
forlstin [
breakpoint_threads,
watchpoint_threads,
signal_threads,
exiting_threads,
other_threads,
 ]:
iflstisnotNone:
lst[:] = []

forthreadinprocess:
dispatched=False
forreason, listin [
 (lldb.eStopReasonBreakpoint, breakpoint_threads),
 (lldb.eStopReasonException, crashed_threads),
 (lldb.eStopReasonWatchpoint, watchpoint_threads),
 (lldb.eStopReasonSignal, signal_threads),
 (lldb.eStopReasonThreadExiting, exiting_threads),
 (None, other_threads),
 ]:
ifnotdispatchedandlistisnotNone:
ifthread.GetStopReason() ==reasonorreasonisNone:
list.append(thread)
dispatched=True


# ==================================================
# Utility functions for setting breakpoints
# ==================================================


defrun_break_set_by_script(
test, class_name, extra_options=None, num_expected_locations=1
):
"""Set a scripted breakpoint. Check that it got the right number of locations."""
test.assertTrue(class_nameisnotNone, "Must pass in a class name.")
command="breakpoint set -P "+class_name
ifextra_optionsisnotNone:
command+=" "+extra_options

break_results=run_break_set_command(test, command)
check_breakpoint_result(test, break_results, num_locations=num_expected_locations)
returnget_bpno_from_match(break_results)


defrun_break_set_by_file_and_line(
test,
file_name,
line_number,
extra_options=None,
num_expected_locations=1,
loc_exact=False,
module_name=None,
):
"""Set a breakpoint by file and line, returning the breakpoint number.

 If extra_options is not None, then we append it to the breakpoint set command.

 If num_expected_locations is -1, we check that we got AT LEAST one location. If num_expected_locations is -2, we don't
 check the actual number at all. Otherwise, we check that num_expected_locations equals the number of locations.

 If loc_exact is true, we check that there is one location, and that location must be at the input file and line number.
 """

iffile_nameisNone:
command="breakpoint set -l %d"% (line_number)
else:
command='breakpoint set -f "%s" -l %d'% (file_name, line_number)

ifmodule_name:
command+=" --shlib '%s'"% (module_name)

ifextra_options:
command+=" "+extra_options

break_results=run_break_set_command(test, command)

ifnum_expected_locations==1andloc_exact:
check_breakpoint_result(
test,
break_results,
num_locations=num_expected_locations,
file_name=file_name,
line_number=line_number,
module_name=module_name,
 )
else:
check_breakpoint_result(
test, break_results, num_locations=num_expected_locations
 )

returnget_bpno_from_match(break_results)


defrun_break_set_by_symbol(
test,
symbol,
extra_options=None,
num_expected_locations=-1,
sym_exact=False,
module_name=None,
):
"""Set a breakpoint by symbol name. Common options are the same as run_break_set_by_file_and_line.

 If sym_exact is true, then the output symbol must match the input exactly, otherwise we do a substring match.
 """
command='breakpoint set -n "%s"'% (symbol)

ifmodule_name:
command+=" --shlib '%s'"% (module_name)

ifextra_options:
command+=" "+extra_options

break_results=run_break_set_command(test, command)

ifnum_expected_locations==1andsym_exact:
check_breakpoint_result(
test,
break_results,
num_locations=num_expected_locations,
symbol_name=symbol,
module_name=module_name,
 )
else:
check_breakpoint_result(
test, break_results, num_locations=num_expected_locations
 )

returnget_bpno_from_match(break_results)


defrun_break_set_by_selector(
test, selector, extra_options=None, num_expected_locations=-1, module_name=None
):
"""Set a breakpoint by selector. Common options are the same as run_break_set_by_file_and_line."""

command='breakpoint set -S "%s"'% (selector)

ifmodule_name:
command+=' --shlib "%s"'% (module_name)

ifextra_options:
command+=" "+extra_options

break_results=run_break_set_command(test, command)

ifnum_expected_locations==1:
check_breakpoint_result(
test,
break_results,
num_locations=num_expected_locations,
symbol_name=selector,
symbol_match_exact=False,
module_name=module_name,
 )
else:
check_breakpoint_result(
test, break_results, num_locations=num_expected_locations
 )

returnget_bpno_from_match(break_results)


defrun_break_set_by_regexp(
test, regexp, extra_options=None, num_expected_locations=-1
):
"""Set a breakpoint by regular expression match on symbol name. Common options are the same as run_break_set_by_file_and_line."""

command='breakpoint set -r "%s"'% (regexp)
ifextra_options:
command+=" "+extra_options

break_results=run_break_set_command(test, command)

check_breakpoint_result(test, break_results, num_locations=num_expected_locations)

returnget_bpno_from_match(break_results)


defrun_break_set_by_source_regexp(
test, regexp, extra_options=None, num_expected_locations=-1
):
"""Set a breakpoint by source regular expression. Common options are the same as run_break_set_by_file_and_line."""
command='breakpoint set -p "%s"'% (regexp)
ifextra_options:
command+=" "+extra_options

break_results=run_break_set_command(test, command)

check_breakpoint_result(test, break_results, num_locations=num_expected_locations)

returnget_bpno_from_match(break_results)


defrun_break_set_by_file_colon_line(
test,
specifier,
path,
line_number,
column_number=0,
extra_options=None,
num_expected_locations=-1,
):
command='breakpoint set -y "%s"'% (specifier)
ifextra_options:
command+=" "+extra_options

print("About to run: '%s'", command)
break_results=run_break_set_command(test, command)
check_breakpoint_result(
test,
break_results,
num_locations=num_expected_locations,
file_name=path,
line_number=line_number,
column_number=column_number,
 )

returnget_bpno_from_match(break_results)


defrun_break_set_by_exception(test, language, exception_typename=None):
command="breakpoint set -E "+language
ifexception_typename:
command+=" --exception-typename "+exception_typename

break_results=run_break_set_command(test, command)
# No call to check_breakpoint_result as there's nothing to check. In
# particular, the exception breakpoint isn't yet guaranteed to be resolved.
returnget_bpno_from_match(break_results)


defrun_break_set_command(test, command):
"""Run the command passed in - it must be some break set variant - and analyze the result.
 Returns a dictionary of information gleaned from the command-line results.
 Will assert if the breakpoint setting fails altogether.

 Dictionary will contain:
 bpno - breakpoint of the newly created breakpoint, -1 on error.
 num_locations - number of locations set for the breakpoint.

 If there is only one location, the dictionary MAY contain:
 file - source file name
 line_no - source line number
 column - source column number
 symbol - symbol name
 inline_symbol - inlined symbol name
 offset - offset from the original symbol
 module - module
 address - address at which the breakpoint was set."""

patterns= [
r"^Breakpoint (?P<bpno>[0-9]+): (?P<num_locations>[0-9]+) locations\.$",
r"^Breakpoint (?P<bpno>[0-9]+): (?P<num_locations>no) locations \(pending\)\.",
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]+)$",
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]+)$",
 ]
match_object=test.match(command, patterns)
break_results=match_object.groupdict()

# We always insert the breakpoint number, setting it to -1 if we couldn't find it
# Also, make sure it gets stored as an integer.
ifnot"bpno"inbreak_results:
break_results["bpno"] =-1
else:
break_results["bpno"] =int(break_results["bpno"])

# We always insert the number of locations
# If ONE location is set for the breakpoint, then the output doesn't mention locations, but it has to be 1...
# We also make sure it is an integer.

ifnot"num_locations"inbreak_results:
num_locations=1
else:
num_locations=break_results["num_locations"]
ifnum_locations=="no":
num_locations=0
else:
num_locations=int(break_results["num_locations"])

break_results["num_locations"] =num_locations

if"line_no"inbreak_results:
break_results["line_no"] =int(break_results["line_no"])

returnbreak_results


defget_bpno_from_match(break_results):
returnint(break_results["bpno"])


defcheck_breakpoint_result(
test,
break_results,
file_name=None,
line_number=-1,
column_number=0,
symbol_name=None,
symbol_match_exact=True,
module_name=None,
offset=-1,
num_locations=-1,
):
out_num_locations=break_results["num_locations"]

ifnum_locations==-1:
test.assertTrue(
out_num_locations>0, "Expecting one or more locations, got none."
 )
elifnum_locations!=-2:
test.assertTrue(
num_locations==out_num_locations,
"Expecting %d locations, got %d."% (num_locations, out_num_locations),
 )

iffile_name:
out_file_name=""
if"file"inbreak_results:
out_file_name=break_results["file"]
test.assertTrue(
file_name.endswith(out_file_name),
"Breakpoint file name '%s' doesn't match resultant name '%s'."
% (file_name, out_file_name),
 )

ifline_number!=-1:
out_line_number=-1
if"line_no"inbreak_results:
out_line_number=break_results["line_no"]

test.assertTrue(
line_number==out_line_number,
"Breakpoint line number %s doesn't match resultant line %s."
% (line_number, out_line_number),
 )

ifcolumn_number!=0:
out_column_number=0
if"column"inbreak_results:
out_column_number=break_results["column"]

test.assertTrue(
column_number==out_column_number,
"Breakpoint column number %s doesn't match resultant column %s."
% (column_number, out_column_number),
 )

ifsymbol_name:
out_symbol_name=""
# Look first for the inlined symbol name, otherwise use the symbol
# name:
if"inline_symbol"inbreak_resultsandbreak_results["inline_symbol"]:
out_symbol_name=break_results["inline_symbol"]
elif"symbol"inbreak_results:
out_symbol_name=break_results["symbol"]

ifsymbol_match_exact:
test.assertTrue(
symbol_name==out_symbol_name,
"Symbol name '%s' doesn't match resultant symbol '%s'."
% (symbol_name, out_symbol_name),
 )
else:
test.assertTrue(
out_symbol_name.find(symbol_name) !=-1,
"Symbol name '%s' isn't in resultant symbol '%s'."
% (symbol_name, out_symbol_name),
 )

ifmodule_name:
out_module_name=None
if"module"inbreak_results:
out_module_name=break_results["module"]

test.assertTrue(
module_name.find(out_module_name) !=-1,
"Symbol module name '%s' isn't in expected module name '%s'."
% (out_module_name, module_name),
 )


defcheck_breakpoint(
test,
bpno,
expected_locations=None,
expected_resolved_count=None,
expected_hit_count=None,
location_id=None,
expected_location_resolved=True,
expected_location_hit_count=None,
):
"""
 Test breakpoint or breakpoint location.
 Breakpoint resolved count is always checked. If not specified the assumption is that all locations
 should be resolved.
 To test a breakpoint location, breakpoint number (bpno) and location_id must be set. In this case
 the resolved count for a breakpoint is not tested by default. The location is expected to be resolved,
 unless expected_location_resolved is set to False.
 test - test context
 bpno - breakpoint number to test
 expected_locations - expected number of locations for this breakpoint. If 'None' this parameter is not tested.
 expected_resolved_count - expected resolved locations number for the breakpoint. If 'None' - all locations should be resolved.
 expected_hit_count - expected hit count for this breakpoint. If 'None' this parameter is not tested.
 location_id - If not 'None' sets the location ID for the breakpoint to test.
 expected_location_resolved - Extected resolved status for the location_id (True/False). Default - True.
 expected_location_hit_count - Expected hit count for the breakpoint at location_id. Must be set if the location_id parameter is set.
 """

ifisinstance(test.target, lldb.SBTarget):
target=test.target
else:
target=test.target()
bkpt=target.FindBreakpointByID(bpno)

test.assertTrue(bkpt.IsValid(), "Breakpoint is not valid.")

ifexpected_locationsisnotNone:
test.assertEqual(expected_locations, bkpt.GetNumLocations())

ifexpected_resolved_countisnotNone:
test.assertEqual(expected_resolved_count, bkpt.GetNumResolvedLocations())
else:
expected_resolved_count=bkpt.GetNumLocations()
iflocation_idisNone:
test.assertEqual(expected_resolved_count, bkpt.GetNumResolvedLocations())

ifexpected_hit_countisnotNone:
test.assertEqual(expected_hit_count, bkpt.GetHitCount())

iflocation_idisnotNone:
loc_bkpt=bkpt.FindLocationByID(location_id)
test.assertTrue(loc_bkpt.IsValid(), "Breakpoint location is not valid.")
test.assertEqual(loc_bkpt.IsResolved(), expected_location_resolved)
ifexpected_location_hit_countisnotNone:
test.assertEqual(expected_location_hit_count, loc_bkpt.GetHitCount())


# ==================================================
# Utility functions related to Threads and Processes
# ==================================================


defget_stopped_threads(process, reason):
"""Returns the thread(s) with the specified stop reason in a list.

 The list can be empty if no such thread exists.
 """
threads= []
fortinprocess:
ift.GetStopReason() ==reason:
threads.append(t)
returnthreads


defget_stopped_thread(process, reason):
"""A convenience function which returns the first thread with the given stop
 reason or None.

 Example usages:

 1. Get the stopped thread due to a breakpoint condition

 ...
 from lldbutil import get_stopped_thread
 thread = get_stopped_thread(process, lldb.eStopReasonPlanComplete)
 self.assertTrue(thread.IsValid(), "There should be a thread stopped due to breakpoint condition")
 ...

 2. Get the thread stopped due to a breakpoint

 ...
 from lldbutil import get_stopped_thread
 thread = get_stopped_thread(process, lldb.eStopReasonBreakpoint)
 self.assertTrue(thread.IsValid(), "There should be a thread stopped due to breakpoint")
 ...

 """
threads=get_stopped_threads(process, reason)
iflen(threads) ==0:
returnNone
returnthreads[0]


defget_threads_stopped_at_breakpoint_id(process, bpid):
"""For a stopped process returns the thread stopped at the breakpoint passed in bkpt"""
stopped_threads= []
threads= []

stopped_threads=get_stopped_threads(process, lldb.eStopReasonBreakpoint)

iflen(stopped_threads) ==0:
returnthreads

forthreadinstopped_threads:
# Make sure we've hit our breakpoint.
# From the docs of GetStopReasonDataAtIndex: "Breakpoint stop reasons
# will have data that consists of pairs of breakpoint IDs followed by
# the breakpoint location IDs".
# Iterate over all such pairs looking for `bpid`.
break_ids= [
thread.GetStopReasonDataAtIndex(idx)
foridxinrange(0, thread.GetStopReasonDataCount(), 2)
 ]
ifbpidinbreak_ids:
threads.append(thread)

returnthreads


defget_threads_stopped_at_breakpoint(process, bkpt):
returnget_threads_stopped_at_breakpoint_id(process, bkpt.GetID())


defget_one_thread_stopped_at_breakpoint_id(process, bpid, require_exactly_one=True):
threads=get_threads_stopped_at_breakpoint_id(process, bpid)
iflen(threads) ==0:
returnNone
ifrequire_exactly_oneandlen(threads) !=1:
returnNone

returnthreads[0]


defget_one_thread_stopped_at_breakpoint(process, bkpt, require_exactly_one=True):
returnget_one_thread_stopped_at_breakpoint_id(
process, bkpt.GetID(), require_exactly_one
 )


defis_thread_crashed(test, thread):
"""In the test suite we dereference a null pointer to simulate a crash. The way this is
 reported depends on the platform."""
iftest.platformIsDarwin():
return (
thread.GetStopReason() ==lldb.eStopReasonException
and"EXC_BAD_ACCESS"inthread.GetStopDescription(100)
 )
eliftest.getPlatform() in ["linux", "freebsd"]:
return (
thread.GetStopReason() ==lldb.eStopReasonSignal
andthread.GetStopReasonDataAtIndex(0)
==thread.GetProcess().GetUnixSignals().GetSignalNumberFromName("SIGSEGV")
 )
eliftest.getPlatform() =="windows":
return"Exception 0xc0000005"inthread.GetStopDescription(200)
else:
return"invalid address"inthread.GetStopDescription(100)


defget_crashed_threads(test, process):
threads= []
ifprocess.GetState() !=lldb.eStateStopped:
returnthreads
forthreadinprocess:
ifis_thread_crashed(test, thread):
threads.append(thread)
returnthreads


# Helper functions for run_to_{source,name}_breakpoint:


defrun_to_breakpoint_make_target(test, exe_name="a.out", in_cwd=True):
exe=test.getBuildArtifact(exe_name) ifin_cwdelseexe_name

# Create the target
target=test.dbg.CreateTarget(exe)
test.assertTrue(target, "Target: %s is not valid."% (exe_name))

# Set environment variables for the inferior.
iflldbtest_config.inferior_env:
test.runCmd(
"settings set target.env-vars {}".format(lldbtest_config.inferior_env)
 )

returntarget


defrun_to_breakpoint_do_run(
test, target, bkpt, launch_info=None, only_one_thread=True, extra_images=None
):
# Launch the process, and do not stop at the entry point.
ifnotlaunch_info:
launch_info=target.GetLaunchInfo()
launch_info.SetWorkingDirectory(test.get_process_working_directory())

ifextra_images:
environ=test.registerSharedLibrariesWithTarget(target, extra_images)
launch_info.SetEnvironmentEntries(environ, True)

error=lldb.SBError()
process=target.Launch(launch_info, error)

# Unfortunate workaround for the iPhone simulator.
retry=SIMULATOR_RETRY
while (
retry
anderror.Fail()
anderror.GetCString()
and"Unable to boot the Simulator"inerror.GetCString()
 ):
retry-=1
print("** Simulator is unresponsive. Retrying %d more time(s)"%retry)
importtime

time.sleep(60)
error=lldb.SBError()
process=target.Launch(launch_info, error)

test.assertTrue(
process,
"Could not create a valid process for %s: %s"
% (target.GetExecutable().GetFilename(), error.GetCString()),
 )
test.assertFalse(error.Fail(), "Process launch failed: %s"% (error.GetCString()))

defprocessStateInfo(process):
info="state: {}".format(state_type_to_str(process.state))
ifprocess.state==lldb.eStateExited:
info+=", exit code: {}".format(process.GetExitStatus())
ifprocess.exit_description:
info+=", exit description: '{}'".format(process.exit_description)
stdout=process.GetSTDOUT(999)
ifstdout:
info+=", stdout: '{}'".format(stdout)
stderr=process.GetSTDERR(999)
ifstderr:
info+=", stderr: '{}'".format(stderr)
returninfo

ifprocess.state!=lldb.eStateStopped:
test.fail(
"Test process is not stopped at breakpoint: {}".format(
processStateInfo(process)
 )
 )

# Frame #0 should be at our breakpoint.
threads=get_threads_stopped_at_breakpoint(process, bkpt)

num_threads=len(threads)
ifonly_one_thread:
test.assertEqual(
num_threads,
1,
"Expected 1 thread to stop at breakpoint, %d did."% (num_threads),
 )
else:
test.assertGreater(num_threads, 0, "No threads stopped at breakpoint")

thread=threads[0]
return (target, process, thread, bkpt)


defrun_to_name_breakpoint(
test,
bkpt_name,
launch_info=None,
exe_name="a.out",
bkpt_module=None,
in_cwd=True,
only_one_thread=True,
extra_images=None,
):
"""Start up a target, using exe_name as the executable, and run it to
 a breakpoint set by name on bkpt_name restricted to bkpt_module.

 If you want to pass in launch arguments or environment
 variables, you can optionally pass in an SBLaunchInfo. If you
 do that, remember to set the working directory as well.

 If your executable isn't called a.out, you can pass that in.
 And if your executable isn't in the CWD, pass in the absolute
 path to the executable in exe_name, and set in_cwd to False.

 If you need to restrict the breakpoint to a particular module,
 pass the module name (a string not a FileSpec) in bkpt_module. If
 nothing is passed in setting will be unrestricted.

 If the target isn't valid, the breakpoint isn't found, or hit, the
 function will cause a testsuite failure.

 If successful it returns a tuple with the target process and
 thread that hit the breakpoint, and the breakpoint that we set
 for you.

 If only_one_thread is true, we require that there be only one
 thread stopped at the breakpoint. Otherwise we only require one
 or more threads stop there. If there are more than one, we return
 the first thread that stopped.
 """

target=run_to_breakpoint_make_target(test, exe_name, in_cwd)

breakpoint=target.BreakpointCreateByName(bkpt_name, bkpt_module)

test.assertTrue(
breakpoint.GetNumLocations() >0,
"No locations found for name breakpoint: '%s'."% (bkpt_name),
 )
returnrun_to_breakpoint_do_run(
test, target, breakpoint, launch_info, only_one_thread, extra_images
 )


defrun_to_source_breakpoint(
test,
bkpt_pattern,