1#!/usr/bin/env python3 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 version.""" 39 version_output = subprocess.check_output( 40 f'{root}/build/soong/scripts/get_clang_version.py', 41 text=True) 42 return version_output.strip() 43 44 45def get_lldb_path(toolchain_path): 46 for lldb_name in ['lldb.sh', 'lldb.cmd', 'lldb', 'lldb.exe']: 47 debugger_path = os.path.join(toolchain_path, "bin", lldb_name) 48 if os.path.isfile(debugger_path): 49 return debugger_path 50 return None 51 52 53def get_lldb_server_path(root, clang_base, clang_version, arch): 54 arch = { 55 'arm': 'arm', 56 'arm64': 'aarch64', 57 'x86': 'i386', 58 'x86_64': 'x86_64', 59 }[arch] 60 return os.path.join(root, clang_base, "linux-x86", 61 clang_version, "runtimes_ndk_cxx", arch, "lldb-server") 62 63 64def get_tracer_pid(device, pid): 65 if pid is None: 66 return 0 67 68 line, _ = device.shell(["grep", "-e", "^TracerPid:", "/proc/{}/status".format(pid)]) 69 tracer_pid = re.sub('TracerPid:\t(.*)\n', r'\1', line) 70 return int(tracer_pid) 71 72 73def parse_args(): 74 parser = gdbrunner.ArgumentParser() 75 76 group = parser.add_argument_group(title="attach target") 77 group = group.add_mutually_exclusive_group(required=True) 78 group.add_argument( 79 "-p", dest="target_pid", metavar="PID", type=int, 80 help="attach to a process with specified PID") 81 group.add_argument( 82 "-n", dest="target_name", metavar="NAME", 83 help="attach to a process with specified name") 84 group.add_argument( 85 "-r", dest="run_cmd", metavar="CMD", nargs=argparse.REMAINDER, 86 help="run a binary on the device, with args") 87 88 parser.add_argument( 89 "--port", nargs="?", default="5039", 90 help="override the port used on the host [default: 5039]") 91 parser.add_argument( 92 "--user", nargs="?", default="root", 93 help="user to run commands as on the device [default: root]") 94 parser.add_argument( 95 "--setup-forwarding", default=None, 96 choices=["lldb", "vscode-lldb"], 97 help=("Set up lldb-server and port forwarding. Prints commands or " + 98 ".vscode/launch.json configuration needed to connect the debugging " + 99 "client to the server. 'vscode' with llbd and 'vscode-lldb' both " + 100 "require the 'vadimcn.vscode-lldb' extension.")) 101 102 parser.add_argument( 103 "--env", nargs=1, action="append", metavar="VAR=VALUE", 104 help="set environment variable when running a binary") 105 parser.add_argument( 106 "--chroot", nargs='?', default="", metavar="PATH", 107 help="run command in a chroot in the given directory") 108 109 return parser.parse_args() 110 111 112def verify_device(root, device): 113 names = set([device.get_prop("ro.build.product"), device.get_prop("ro.product.name")]) 114 target_device = os.environ["TARGET_PRODUCT"] 115 if target_device not in names: 116 msg = "TARGET_PRODUCT ({}) does not match attached device ({})" 117 sys.exit(msg.format(target_device, ", ".join(names))) 118 119 120def get_remote_pid(device, process_name): 121 processes = gdbrunner.get_processes(device) 122 if process_name not in processes: 123 msg = "failed to find running process {}".format(process_name) 124 sys.exit(msg) 125 pids = processes[process_name] 126 if len(pids) > 1: 127 msg = "multiple processes match '{}': {}".format(process_name, pids) 128 sys.exit(msg) 129 130 # Fetch the binary using the PID later. 131 return pids[0] 132 133 134def make_temp_dir(prefix): 135 global g_temp_dirs 136 result = tempfile.mkdtemp(prefix='lldbclient-linker-') 137 g_temp_dirs.append(result) 138 return result 139 140 141def ensure_linker(device, sysroot, interp): 142 """Ensure that the device's linker exists on the host. 143 144 PT_INTERP is usually /system/bin/linker[64], but on the device, that file is 145 a symlink to /apex/com.android.runtime/bin/linker[64]. The symbolized linker 146 binary on the host is located in ${sysroot}/apex, not in ${sysroot}/system, 147 so add the ${sysroot}/apex path to the solib search path. 148 149 PT_INTERP will be /system/bin/bootstrap/linker[64] for executables using the 150 non-APEX/bootstrap linker. No search path modification is needed. 151 152 For a tapas build, only an unbundled app is built, and there is no linker in 153 ${sysroot} at all, so copy the linker from the device. 154 155 Returns: 156 A directory to add to the soinfo search path or None if no directory 157 needs to be added. 158 """ 159 160 # Static executables have no interpreter. 161 if interp is None: 162 return None 163 164 # lldb will search for the linker using the PT_INTERP path. First try to find 165 # it in the sysroot. 166 local_path = os.path.join(sysroot, interp.lstrip("/")) 167 if os.path.exists(local_path): 168 return None 169 170 # If the linker on the device is a symlink, search for the symlink's target 171 # in the sysroot directory. 172 interp_real, _ = device.shell(["realpath", interp]) 173 interp_real = interp_real.strip() 174 local_path = os.path.join(sysroot, interp_real.lstrip("/")) 175 if os.path.exists(local_path): 176 if posixpath.basename(interp) == posixpath.basename(interp_real): 177 # Add the interpreter's directory to the search path. 178 return os.path.dirname(local_path) 179 else: 180 # If PT_INTERP is linker_asan[64], but the sysroot file is 181 # linker[64], then copy the local file to the name lldb expects. 182 result = make_temp_dir('lldbclient-linker-') 183 shutil.copy(local_path, os.path.join(result, posixpath.basename(interp))) 184 return result 185 186 # Pull the system linker. 187 result = make_temp_dir('lldbclient-linker-') 188 device.pull(interp, os.path.join(result, posixpath.basename(interp))) 189 return result 190 191 192def handle_switches(args, sysroot): 193 """Fetch the targeted binary and determine how to attach lldb. 194 195 Args: 196 args: Parsed arguments. 197 sysroot: Local sysroot path. 198 199 Returns: 200 (binary_file, attach_pid, run_cmd). 201 Precisely one of attach_pid or run_cmd will be None. 202 """ 203 204 device = args.device 205 binary_file = None 206 pid = None 207 run_cmd = None 208 209 args.su_cmd = ["su", args.user] if args.user else [] 210 211 if args.target_pid: 212 # Fetch the binary using the PID later. 213 pid = args.target_pid 214 elif args.target_name: 215 # Fetch the binary using the PID later. 216 pid = get_remote_pid(device, args.target_name) 217 elif args.run_cmd: 218 if not args.run_cmd[0]: 219 sys.exit("empty command passed to -r") 220 run_cmd = args.run_cmd 221 if not run_cmd[0].startswith("/"): 222 try: 223 run_cmd[0] = gdbrunner.find_executable_path(device, args.run_cmd[0], 224 run_as_cmd=args.su_cmd) 225 except RuntimeError: 226 sys.exit("Could not find executable '{}' passed to -r, " 227 "please provide an absolute path.".format(args.run_cmd[0])) 228 229 binary_file, local = gdbrunner.find_file(device, run_cmd[0], sysroot, 230 run_as_cmd=args.su_cmd) 231 if binary_file is None: 232 assert pid is not None 233 try: 234 binary_file, local = gdbrunner.find_binary(device, pid, sysroot, 235 run_as_cmd=args.su_cmd) 236 except adb.ShellError: 237 sys.exit("failed to pull binary for PID {}".format(pid)) 238 239 if not local: 240 logging.warning("Couldn't find local unstripped executable in {}," 241 " symbols may not be available.".format(sysroot)) 242 243 return (binary_file, pid, run_cmd) 244 245def generate_vscode_lldb_script(root, sysroot, binary_name, port, solib_search_path): 246 # TODO It would be nice if we didn't need to copy this or run the 247 # lldbclient.py program manually. Doing this would probably require 248 # writing a vscode extension or modifying an existing one. 249 # TODO: https://code.visualstudio.com/api/references/vscode-api#debug and 250 # https://code.visualstudio.com/api/extension-guides/debugger-extension and 251 # https://github.com/vadimcn/vscode-lldb/blob/6b775c439992b6615e92f4938ee4e211f1b060cf/extension/pickProcess.ts#L6 252 res = { 253 "name": "(lldbclient.py) Attach {} (port: {})".format(binary_name.split("/")[-1], port), 254 "type": "lldb", 255 "request": "custom", 256 "relativePathBase": root, 257 "sourceMap": { "/b/f/w" : root, '': root, '.': root }, 258 "initCommands": ['settings append target.exec-search-paths {}'.format(' '.join(solib_search_path))], 259 "targetCreateCommands": ["target create {}".format(binary_name), 260 "target modules search-paths add / {}/".format(sysroot)], 261 "processCreateCommands": ["gdb-remote {}".format(str(port))] 262 } 263 return json.dumps(res, indent=4) 264 265def generate_lldb_script(root, sysroot, binary_name, port, solib_search_path): 266 commands = [] 267 commands.append( 268 'settings append target.exec-search-paths {}'.format(' '.join(solib_search_path))) 269 270 commands.append('target create {}'.format(binary_name)) 271 # For RBE support. 272 commands.append("settings append target.source-map '/b/f/w' '{}'".format(root)) 273 commands.append("settings append target.source-map '' '{}'".format(root)) 274 commands.append('target modules search-paths add / {}/'.format(sysroot)) 275 commands.append('gdb-remote {}'.format(str(port))) 276 return '\n'.join(commands) 277 278 279def generate_setup_script(debugger_path, sysroot, linker_search_dir, binary_file, is64bit, port, debugger, connect_timeout=5): 280 # Generate a setup script. 281 root = os.environ["ANDROID_BUILD_TOP"] 282 symbols_dir = os.path.join(sysroot, "system", "lib64" if is64bit else "lib") 283 vendor_dir = os.path.join(sysroot, "vendor", "lib64" if is64bit else "lib") 284 285 solib_search_path = [] 286 symbols_paths = ["", "hw", "ssl/engines", "drm", "egl", "soundfx"] 287 vendor_paths = ["", "hw", "egl"] 288 solib_search_path += [os.path.join(symbols_dir, x) for x in symbols_paths] 289 solib_search_path += [os.path.join(vendor_dir, x) for x in vendor_paths] 290 if linker_search_dir is not None: 291 solib_search_path += [linker_search_dir] 292 293 if debugger == "vscode-lldb": 294 return generate_vscode_lldb_script( 295 root, sysroot, binary_file.name, port, solib_search_path) 296 elif debugger == 'lldb': 297 return generate_lldb_script( 298 root, sysroot, binary_file.name, port, solib_search_path) 299 else: 300 raise Exception("Unknown debugger type " + debugger) 301 302 303def do_main(): 304 required_env = ["ANDROID_BUILD_TOP", 305 "ANDROID_PRODUCT_OUT", "TARGET_PRODUCT"] 306 for env in required_env: 307 if env not in os.environ: 308 sys.exit( 309 "Environment variable '{}' not defined, have you run lunch?".format(env)) 310 311 args = parse_args() 312 device = args.device 313 314 if device is None: 315 sys.exit("ERROR: Failed to find device.") 316 317 root = os.environ["ANDROID_BUILD_TOP"] 318 sysroot = os.path.join(os.environ["ANDROID_PRODUCT_OUT"], "symbols") 319 320 # Make sure the environment matches the attached device. 321 # Skip when running in a chroot because the chroot lunch target may not 322 # match the device's lunch target. 323 if not args.chroot: 324 verify_device(root, device) 325 326 debug_socket = "/data/local/tmp/debug_socket" 327 pid = None 328 run_cmd = None 329 330 # Fetch binary for -p, -n. 331 binary_file, pid, run_cmd = handle_switches(args, sysroot) 332 333 with binary_file: 334 if sys.platform.startswith("linux"): 335 platform_name = "linux-x86" 336 elif sys.platform.startswith("darwin"): 337 platform_name = "darwin-x86" 338 else: 339 sys.exit("Unknown platform: {}".format(sys.platform)) 340 341 arch = gdbrunner.get_binary_arch(binary_file) 342 is64bit = arch.endswith("64") 343 344 # Make sure we have the linker 345 clang_base = 'prebuilts/clang/host' 346 clang_version = read_toolchain_config(root) 347 toolchain_path = os.path.join(root, clang_base, platform_name, 348 clang_version) 349 llvm_readobj_path = os.path.join(toolchain_path, "bin", "llvm-readobj") 350 interp = gdbrunner.get_binary_interp(binary_file.name, llvm_readobj_path) 351 linker_search_dir = ensure_linker(device, sysroot, interp) 352 353 tracer_pid = get_tracer_pid(device, pid) 354 if tracer_pid == 0: 355 cmd_prefix = args.su_cmd 356 if args.env: 357 cmd_prefix += ['env'] + [v[0] for v in args.env] 358 359 # Start lldb-server. 360 server_local_path = get_lldb_server_path(root, clang_base, clang_version, arch) 361 server_remote_path = "/data/local/tmp/{}-lldb-server".format(arch) 362 gdbrunner.start_gdbserver( 363 device, server_local_path, server_remote_path, 364 target_pid=pid, run_cmd=run_cmd, debug_socket=debug_socket, 365 port=args.port, run_as_cmd=cmd_prefix, lldb=True, chroot=args.chroot) 366 else: 367 print( 368 "Connecting to tracing pid {} using local port {}".format( 369 tracer_pid, args.port)) 370 gdbrunner.forward_gdbserver_port(device, local=args.port, 371 remote="tcp:{}".format(args.port)) 372 373 debugger_path = get_lldb_path(toolchain_path) 374 debugger = args.setup_forwarding or 'lldb' 375 376 # Generate the lldb script. 377 setup_commands = generate_setup_script(debugger_path=debugger_path, 378 sysroot=sysroot, 379 linker_search_dir=linker_search_dir, 380 binary_file=binary_file, 381 is64bit=is64bit, 382 port=args.port, 383 debugger=debugger) 384 385 if not args.setup_forwarding: 386 # Print a newline to separate our messages from the GDB session. 387 print("") 388 389 # Start lldb. 390 gdbrunner.start_gdb(debugger_path, setup_commands, lldb=True) 391 else: 392 print("") 393 print(setup_commands) 394 print("") 395 if args.setup_forwarding == "vscode-lldb": 396 print(textwrap.dedent(""" 397 Paste the above json into .vscode/launch.json and start the debugger as 398 normal. Press enter in this terminal once debugging is finished to shut 399 lldb-server down and close all the ports.""")) 400 else: 401 print(textwrap.dedent(""" 402 Paste the lldb commands above into the lldb frontend to set up the 403 lldb-server connection. Press enter in this terminal once debugging is 404 finished to shut lldb-server down and close all the ports.""")) 405 print("") 406 input("Press enter to shut down lldb-server") 407 408 409def main(): 410 try: 411 do_main() 412 finally: 413 global g_temp_dirs 414 for temp_dir in g_temp_dirs: 415 shutil.rmtree(temp_dir) 416 417 418if __name__ == "__main__": 419 main() 420