1#!/usr/bin/env python 2# 3# Copyright (C) 2015 The Android Open Source Project 4# 5# Licensed under the Apache License, Version 2.0 (the "License"); 6# you may not use this file except in compliance with the License. 7# You may obtain a copy of the License at 8# 9# http://www.apache.org/licenses/LICENSE-2.0 10# 11# Unless required by applicable law or agreed to in writing, software 12# distributed under the License is distributed on an "AS IS" BASIS, 13# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14# See the License for the specific language governing permissions and 15# limitations under the License. 16# 17 18import adb 19import argparse 20import json 21import logging 22import os 23import posixpath 24import re 25import shutil 26import subprocess 27import sys 28import tempfile 29import textwrap 30 31# Shared functions across gdbclient.py and ndk-gdb.py. 32import gdbrunner 33 34g_temp_dirs = [] 35 36 37def read_toolchain_config(root): 38 """Finds out current toolchain path and version.""" 39 def get_value(str): 40 return str[str.index('"') + 1:str.rindex('"')] 41 42 config_path = os.path.join(root, 'build', 'soong', 'cc', 'config', 43 'global.go') 44 with open(config_path) as f: 45 contents = f.readlines() 46 clang_base = "" 47 clang_version = "" 48 for line in contents: 49 line = line.strip() 50 if line.startswith('ClangDefaultBase'): 51 clang_base = get_value(line) 52 elif line.startswith('ClangDefaultVersion'): 53 clang_version = get_value(line) 54 return (clang_base, clang_version) 55 56 57def get_gdbserver_path(root, arch): 58 path = "{}/prebuilts/misc/gdbserver/android-{}/gdbserver{}" 59 if arch.endswith("64"): 60 return path.format(root, arch, "64") 61 else: 62 return path.format(root, arch, "") 63 64 65def get_lldb_path(toolchain_path): 66 for lldb_name in ['lldb.sh', 'lldb.cmd', 'lldb', 'lldb.exe']: 67 debugger_path = os.path.join(toolchain_path, "bin", lldb_name) 68 if os.path.isfile(debugger_path): 69 return debugger_path 70 return None 71 72 73def get_lldb_server_path(root, clang_base, clang_version, arch): 74 arch = { 75 'arm': 'arm', 76 'arm64': 'aarch64', 77 'x86': 'i386', 78 'x86_64': 'x86_64', 79 }[arch] 80 return os.path.join(root, clang_base, "linux-x86", 81 clang_version, "runtimes_ndk_cxx", arch, "lldb-server") 82 83 84def get_tracer_pid(device, pid): 85 if pid is None: 86 return 0 87 88 line, _ = device.shell(["grep", "-e", "^TracerPid:", "/proc/{}/status".format(pid)]) 89 tracer_pid = re.sub('TracerPid:\t(.*)\n', r'\1', line) 90 return int(tracer_pid) 91 92 93def parse_args(): 94 parser = gdbrunner.ArgumentParser() 95 96 group = parser.add_argument_group(title="attach target") 97 group = group.add_mutually_exclusive_group(required=True) 98 group.add_argument( 99 "-p", dest="target_pid", metavar="PID", type=int, 100 help="attach to a process with specified PID") 101 group.add_argument( 102 "-n", dest="target_name", metavar="NAME", 103 help="attach to a process with specified name") 104 group.add_argument( 105 "-r", dest="run_cmd", metavar="CMD", nargs=argparse.REMAINDER, 106 help="run a binary on the device, with args") 107 108 parser.add_argument( 109 "--port", nargs="?", default="5039", 110 help="override the port used on the host [default: 5039]") 111 parser.add_argument( 112 "--user", nargs="?", default="root", 113 help="user to run commands as on the device [default: root]") 114 parser.add_argument( 115 "--setup-forwarding", default=None, 116 choices=["gdb", "lldb", "vscode", "vscode-gdb", "vscode-lldb"], 117 help=("Setup the gdbserver/lldb-server and port forwarding. Prints commands or " + 118 ".vscode/launch.json configuration needed to connect the debugging " + 119 "client to the server. If 'gdb' and 'vscode-gdb' are only valid if " + 120 "'--no-lldb' is passed. 'vscode' with llbd and 'vscode-lldb' both " + 121 "require the 'vadimcn.vscode-lldb' extension. 'vscode' with '--no-lldb' " + 122 "and 'vscode-gdb' require the 'ms-vscode.cpptools' extension.")) 123 124 lldb_group = parser.add_mutually_exclusive_group() 125 lldb_group.add_argument("--lldb", action="store_true", help="Use lldb.") 126 lldb_group.add_argument("--no-lldb", action="store_true", help="Do not use lldb.") 127 128 parser.add_argument( 129 "--env", nargs=1, action="append", metavar="VAR=VALUE", 130 help="set environment variable when running a binary") 131 132 return parser.parse_args() 133 134 135def verify_device(root, device): 136 names = set([device.get_prop("ro.build.product"), device.get_prop("ro.product.name")]) 137 target_device = os.environ["TARGET_PRODUCT"] 138 if target_device not in names: 139 msg = "TARGET_PRODUCT ({}) does not match attached device ({})" 140 sys.exit(msg.format(target_device, ", ".join(names))) 141 142 143def get_remote_pid(device, process_name): 144 processes = gdbrunner.get_processes(device) 145 if process_name not in processes: 146 msg = "failed to find running process {}".format(process_name) 147 sys.exit(msg) 148 pids = processes[process_name] 149 if len(pids) > 1: 150 msg = "multiple processes match '{}': {}".format(process_name, pids) 151 sys.exit(msg) 152 153 # Fetch the binary using the PID later. 154 return pids[0] 155 156 157def make_temp_dir(prefix): 158 global g_temp_dirs 159 result = tempfile.mkdtemp(prefix='gdbclient-linker-') 160 g_temp_dirs.append(result) 161 return result 162 163 164def ensure_linker(device, sysroot, interp): 165 """Ensure that the device's linker exists on the host. 166 167 PT_INTERP is usually /system/bin/linker[64], but on the device, that file is 168 a symlink to /apex/com.android.runtime/bin/linker[64]. The symbolized linker 169 binary on the host is located in ${sysroot}/apex, not in ${sysroot}/system, 170 so add the ${sysroot}/apex path to the solib search path. 171 172 PT_INTERP will be /system/bin/bootstrap/linker[64] for executables using the 173 non-APEX/bootstrap linker. No search path modification is needed. 174 175 For a tapas build, only an unbundled app is built, and there is no linker in 176 ${sysroot} at all, so copy the linker from the device. 177 178 Returns: 179 A directory to add to the soinfo search path or None if no directory 180 needs to be added. 181 """ 182 183 # Static executables have no interpreter. 184 if interp is None: 185 return None 186 187 # gdb will search for the linker using the PT_INTERP path. First try to find 188 # it in the sysroot. 189 local_path = os.path.join(sysroot, interp.lstrip("/")) 190 if os.path.exists(local_path): 191 return None 192 193 # If the linker on the device is a symlink, search for the symlink's target 194 # in the sysroot directory. 195 interp_real, _ = device.shell(["realpath", interp]) 196 interp_real = interp_real.strip() 197 local_path = os.path.join(sysroot, interp_real.lstrip("/")) 198 if os.path.exists(local_path): 199 if posixpath.basename(interp) == posixpath.basename(interp_real): 200 # Add the interpreter's directory to the search path. 201 return os.path.dirname(local_path) 202 else: 203 # If PT_INTERP is linker_asan[64], but the sysroot file is 204 # linker[64], then copy the local file to the name gdb expects. 205 result = make_temp_dir('gdbclient-linker-') 206 shutil.copy(local_path, os.path.join(result, posixpath.basename(interp))) 207 return result 208 209 # Pull the system linker. 210 result = make_temp_dir('gdbclient-linker-') 211 device.pull(interp, os.path.join(result, posixpath.basename(interp))) 212 return result 213 214 215def handle_switches(args, sysroot): 216 """Fetch the targeted binary and determine how to attach gdb. 217 218 Args: 219 args: Parsed arguments. 220 sysroot: Local sysroot path. 221 222 Returns: 223 (binary_file, attach_pid, run_cmd). 224 Precisely one of attach_pid or run_cmd will be None. 225 """ 226 227 device = args.device 228 binary_file = None 229 pid = None 230 run_cmd = None 231 232 args.su_cmd = ["su", args.user] if args.user else [] 233 234 if args.target_pid: 235 # Fetch the binary using the PID later. 236 pid = args.target_pid 237 elif args.target_name: 238 # Fetch the binary using the PID later. 239 pid = get_remote_pid(device, args.target_name) 240 elif args.run_cmd: 241 if not args.run_cmd[0]: 242 sys.exit("empty command passed to -r") 243 run_cmd = args.run_cmd 244 if not run_cmd[0].startswith("/"): 245 try: 246 run_cmd[0] = gdbrunner.find_executable_path(device, args.run_cmd[0], 247 run_as_cmd=args.su_cmd) 248 except RuntimeError: 249 sys.exit("Could not find executable '{}' passed to -r, " 250 "please provide an absolute path.".format(args.run_cmd[0])) 251 252 binary_file, local = gdbrunner.find_file(device, run_cmd[0], sysroot, 253 run_as_cmd=args.su_cmd) 254 if binary_file is None: 255 assert pid is not None 256 try: 257 binary_file, local = gdbrunner.find_binary(device, pid, sysroot, 258 run_as_cmd=args.su_cmd) 259 except adb.ShellError: 260 sys.exit("failed to pull binary for PID {}".format(pid)) 261 262 if not local: 263 logging.warning("Couldn't find local unstripped executable in {}," 264 " symbols may not be available.".format(sysroot)) 265 266 return (binary_file, pid, run_cmd) 267 268def generate_vscode_lldb_script(root, sysroot, binary_name, port, solib_search_path): 269 # TODO It would be nice if we didn't need to copy this or run the 270 # gdbclient.py program manually. Doing this would probably require 271 # writing a vscode extension or modifying an existing one. 272 # TODO: https://code.visualstudio.com/api/references/vscode-api#debug and 273 # https://code.visualstudio.com/api/extension-guides/debugger-extension and 274 # https://github.com/vadimcn/vscode-lldb/blob/6b775c439992b6615e92f4938ee4e211f1b060cf/extension/pickProcess.ts#L6 275 res = { 276 "name": "(lldbclient.py) Attach {} (port: {})".format(binary_name.split("/")[-1], port), 277 "type": "lldb", 278 "request": "custom", 279 "relativePathBase": root, 280 "sourceMap": { "/b/f/w" : root, '': root, '.': root }, 281 "initCommands": ['settings append target.exec-search-paths {}'.format(' '.join(solib_search_path))], 282 "targetCreateCommands": ["target create {}".format(binary_name), 283 "target modules search-paths add / {}/".format(sysroot)], 284 "processCreateCommands": ["gdb-remote {}".format(port)] 285 } 286 return json.dumps(res, indent=4) 287 288def generate_vscode_gdb_script(gdbpath, root, sysroot, binary_name, port, dalvik_gdb_script, solib_search_path): 289 # TODO It would be nice if we didn't need to copy this or run the 290 # gdbclient.py program manually. Doing this would probably require 291 # writing a vscode extension or modifying an existing one. 292 res = { 293 "name": "(gdbclient.py) Attach {} (port: {})".format(binary_name.split("/")[-1], port), 294 "type": "cppdbg", 295 "request": "launch", # Needed for gdbserver. 296 "cwd": root, 297 "program": binary_name, 298 "MIMode": "gdb", 299 "miDebuggerServerAddress": "localhost:{}".format(port), 300 "miDebuggerPath": gdbpath, 301 "setupCommands": [ 302 { 303 # Required for vscode. 304 "description": "Enable pretty-printing for gdb", 305 "text": "-enable-pretty-printing", 306 "ignoreFailures": True, 307 }, 308 { 309 "description": "gdb command: dir", 310 "text": "-environment-directory {}".format(root), 311 "ignoreFailures": False 312 }, 313 { 314 "description": "gdb command: set solib-search-path", 315 "text": "-gdb-set solib-search-path {}".format(":".join(solib_search_path)), 316 "ignoreFailures": False 317 }, 318 { 319 "description": "gdb command: set solib-absolute-prefix", 320 "text": "-gdb-set solib-absolute-prefix {}".format(sysroot), 321 "ignoreFailures": False 322 }, 323 ] 324 } 325 if dalvik_gdb_script: 326 res["setupCommands"].append({ 327 "description": "gdb command: source art commands", 328 "text": "-interpreter-exec console \"source {}\"".format(dalvik_gdb_script), 329 "ignoreFailures": False, 330 }) 331 return json.dumps(res, indent=4) 332 333def generate_gdb_script(root, sysroot, binary_name, port, dalvik_gdb_script, solib_search_path, connect_timeout): 334 solib_search_path = ":".join(solib_search_path) 335 336 gdb_commands = "" 337 gdb_commands += "file '{}'\n".format(binary_name) 338 gdb_commands += "directory '{}'\n".format(root) 339 gdb_commands += "set solib-absolute-prefix {}\n".format(sysroot) 340 gdb_commands += "set solib-search-path {}\n".format(solib_search_path) 341 if dalvik_gdb_script: 342 gdb_commands += "source {}\n".format(dalvik_gdb_script) 343 344 # Try to connect for a few seconds, sometimes the device gdbserver takes 345 # a little bit to come up, especially on emulators. 346 gdb_commands += """ 347python 348 349def target_remote_with_retry(target, timeout_seconds): 350 import time 351 end_time = time.time() + timeout_seconds 352 while True: 353 try: 354 gdb.execute("target extended-remote " + target) 355 return True 356 except gdb.error as e: 357 time_left = end_time - time.time() 358 if time_left < 0 or time_left > timeout_seconds: 359 print("Error: unable to connect to device.") 360 print(e) 361 return False 362 time.sleep(min(0.25, time_left)) 363 364target_remote_with_retry(':{}', {}) 365 366end 367""".format(port, connect_timeout) 368 369 return gdb_commands 370 371 372def generate_lldb_script(root, sysroot, binary_name, port, solib_search_path): 373 commands = [] 374 commands.append( 375 'settings append target.exec-search-paths {}'.format(' '.join(solib_search_path))) 376 377 commands.append('target create {}'.format(binary_name)) 378 # For RBE support. 379 commands.append("settings append target.source-map '/b/f/w' '{}'".format(root)) 380 commands.append("settings append target.source-map '' '{}'".format(root)) 381 commands.append('target modules search-paths add / {}/'.format(sysroot)) 382 commands.append('gdb-remote {}'.format(port)) 383 return '\n'.join(commands) 384 385 386def generate_setup_script(debugger_path, sysroot, linker_search_dir, binary_file, is64bit, port, debugger, connect_timeout=5): 387 # Generate a setup script. 388 # TODO: Detect the zygote and run 'art-on' automatically. 389 root = os.environ["ANDROID_BUILD_TOP"] 390 symbols_dir = os.path.join(sysroot, "system", "lib64" if is64bit else "lib") 391 vendor_dir = os.path.join(sysroot, "vendor", "lib64" if is64bit else "lib") 392 393 solib_search_path = [] 394 symbols_paths = ["", "hw", "ssl/engines", "drm", "egl", "soundfx"] 395 vendor_paths = ["", "hw", "egl"] 396 solib_search_path += [os.path.join(symbols_dir, x) for x in symbols_paths] 397 solib_search_path += [os.path.join(vendor_dir, x) for x in vendor_paths] 398 if linker_search_dir is not None: 399 solib_search_path += [linker_search_dir] 400 401 dalvik_gdb_script = os.path.join(root, "development", "scripts", "gdb", "dalvik.gdb") 402 if not os.path.exists(dalvik_gdb_script): 403 logging.warning(("couldn't find {} - ART debugging options will not " + 404 "be available").format(dalvik_gdb_script)) 405 dalvik_gdb_script = None 406 407 if debugger == "vscode-gdb": 408 return generate_vscode_gdb_script( 409 debugger_path, root, sysroot, binary_file.name, port, dalvik_gdb_script, solib_search_path) 410 if debugger == "vscode-lldb": 411 return generate_vscode_lldb_script( 412 root, sysroot, binary_file.name, port, solib_search_path) 413 elif debugger == "gdb": 414 return generate_gdb_script(root, sysroot, binary_file.name, port, dalvik_gdb_script, solib_search_path, connect_timeout) 415 elif debugger == 'lldb': 416 return generate_lldb_script( 417 root, sysroot, binary_file.name, port, solib_search_path) 418 else: 419 raise Exception("Unknown debugger type " + debugger) 420 421 422def do_main(): 423 required_env = ["ANDROID_BUILD_TOP", 424 "ANDROID_PRODUCT_OUT", "TARGET_PRODUCT"] 425 for env in required_env: 426 if env not in os.environ: 427 sys.exit( 428 "Environment variable '{}' not defined, have you run lunch?".format(env)) 429 430 args = parse_args() 431 device = args.device 432 433 if device is None: 434 sys.exit("ERROR: Failed to find device.") 435 436 use_lldb = not args.no_lldb 437 # Error check forwarding. 438 if args.setup_forwarding: 439 if use_lldb and (args.setup_forwarding == "gdb" or args.setup_forwarding == "vscode-gdb"): 440 sys.exit("Error: --setup-forwarding={} requires '--no-lldb'.".format( 441 args.setup_forwarding)) 442 elif (not use_lldb) and (args.setup_forwarding == 'lldb' or args.setup_forwarding == 'vscode-lldb'): 443 sys.exit("Error: --setup-forwarding={} requires '--lldb'.".format( 444 args.setup_forwarding)) 445 # Pick what vscode-debugger type to use. 446 if args.setup_forwarding == 'vscode': 447 args.setup_forwarding = 'vscode-lldb' if use_lldb else 'vscode-gdb' 448 449 root = os.environ["ANDROID_BUILD_TOP"] 450 sysroot = os.path.join(os.environ["ANDROID_PRODUCT_OUT"], "symbols") 451 452 # Make sure the environment matches the attached device. 453 verify_device(root, device) 454 455 debug_socket = "/data/local/tmp/debug_socket" 456 pid = None 457 run_cmd = None 458 459 # Fetch binary for -p, -n. 460 binary_file, pid, run_cmd = handle_switches(args, sysroot) 461 462 with binary_file: 463 if sys.platform.startswith("linux"): 464 platform_name = "linux-x86" 465 elif sys.platform.startswith("darwin"): 466 platform_name = "darwin-x86" 467 else: 468 sys.exit("Unknown platform: {}".format(sys.platform)) 469 470 arch = gdbrunner.get_binary_arch(binary_file) 471 is64bit = arch.endswith("64") 472 473 # Make sure we have the linker 474 clang_base, clang_version = read_toolchain_config(root) 475 toolchain_path = os.path.join(root, clang_base, platform_name, 476 clang_version) 477 llvm_readobj_path = os.path.join(toolchain_path, "bin", "llvm-readobj") 478 interp = gdbrunner.get_binary_interp(binary_file.name, llvm_readobj_path) 479 linker_search_dir = ensure_linker(device, sysroot, interp) 480 481 tracer_pid = get_tracer_pid(device, pid) 482 if os.path.basename(__file__) == 'gdbclient.py' and not args.lldb: 483 print("gdb is deprecated in favor of lldb. " 484 "If you can't use lldb, please set --no-lldb and file a bug asap.") 485 if tracer_pid == 0: 486 cmd_prefix = args.su_cmd 487 if args.env: 488 cmd_prefix += ['env'] + [v[0] for v in args.env] 489 490 # Start gdbserver. 491 if use_lldb: 492 server_local_path = get_lldb_server_path( 493 root, clang_base, clang_version, arch) 494 server_remote_path = "/data/local/tmp/{}-lldb-server".format( 495 arch) 496 else: 497 server_local_path = get_gdbserver_path(root, arch) 498 server_remote_path = "/data/local/tmp/{}-gdbserver".format( 499 arch) 500 gdbrunner.start_gdbserver( 501 device, server_local_path, server_remote_path, 502 target_pid=pid, run_cmd=run_cmd, debug_socket=debug_socket, 503 port=args.port, run_as_cmd=cmd_prefix, lldb=use_lldb) 504 else: 505 print( 506 "Connecting to tracing pid {} using local port {}".format( 507 tracer_pid, args.port)) 508 gdbrunner.forward_gdbserver_port(device, local=args.port, 509 remote="tcp:{}".format(args.port)) 510 511 if use_lldb: 512 debugger_path = get_lldb_path(toolchain_path) 513 debugger = args.setup_forwarding or 'lldb' 514 else: 515 debugger_path = os.path.join( 516 root, "prebuilts", "gdb", platform_name, "bin", "gdb") 517 debugger = args.setup_forwarding or "gdb" 518 519 # Generate a gdb/lldb script. 520 setup_commands = generate_setup_script(debugger_path=debugger_path, 521 sysroot=sysroot, 522 linker_search_dir=linker_search_dir, 523 binary_file=binary_file, 524 is64bit=is64bit, 525 port=args.port, 526 debugger=debugger) 527 528 if not args.setup_forwarding: 529 # Print a newline to separate our messages from the GDB session. 530 print("") 531 532 # Start gdb. 533 gdbrunner.start_gdb(debugger_path, setup_commands, lldb=use_lldb) 534 else: 535 debugger_name = "lldb" if use_lldb else "gdb" 536 print("") 537 print(setup_commands) 538 print("") 539 if args.setup_forwarding == "vscode-{}".format(debugger_name): 540 print(textwrap.dedent(""" 541 Paste the above json into .vscode/launch.json and start the debugger as 542 normal. Press enter in this terminal once debugging is finished to shutdown 543 the gdbserver and close all the ports.""")) 544 else: 545 print(textwrap.dedent(""" 546 Paste the above {name} commands into the {name} frontend to setup the 547 gdbserver connection. Press enter in this terminal once debugging is 548 finished to shutdown the gdbserver and close all the ports.""".format(name=debugger_name))) 549 print("") 550 raw_input("Press enter to shutdown gdbserver") 551 552 553def main(): 554 try: 555 do_main() 556 finally: 557 global g_temp_dirs 558 for temp_dir in g_temp_dirs: 559 shutil.rmtree(temp_dir) 560 561 562if __name__ == "__main__": 563 main() 564