blob: c37b66e26667fd39076ece677396b41f32c7a764 [file]
# Copyright 2026 The Fuchsia Authors. All rights reserved.
# Use of this source code is governed by a BSD-style license that can be
# found in the LICENSE file.
import argparse
import sys
from typing import Any
from cli.commands.base import BaseCommand
from shared.protocol.attach import COMMAND_NAME
class Command(BaseCommand):
"""CLI command definition for `attach`."""
COMMAND_NAME = COMMAND_NAME
@staticmethod
def register_cli(subparsers: Any) -> None:
"""Registers the `attach` subparser and arguments."""
attach_parser = subparsers.add_parser(
Command.COMMAND_NAME,
help="Attach to a process or driver_host",
)
attach_parser.add_argument(
"filter",
nargs="?",
default=None,
help="Process name or ID to attach to",
)
attach_parser.add_argument(
"-d",
"--driver",
default=None,
help=(
"Driver component/module name or URL substring (e.g. 'xhci' or"
" 'xhci.cm')"
),
)
attach_parser.add_argument(
"-n",
"--node",
default=None,
help="Device topology node moniker (e.g. 'dev.sys.platform.xhci')",
)
attach_parser.add_argument(
"--weak",
action="store_true",
default=False,
help=(
"Attach weakly (defer symbol loading until an exception occurs;"
" note that running `modules` transitions a weak attach to a"
" strong attach)"
),
)
attach_parser.add_argument(
"--exact",
action="store_true",
default=False,
help=(
"Match filter string against exact process name instead of"
" substring (cannot be used with --driver or --node)"
),
)
attach_parser.add_argument(
"-r",
"--recursive",
action="store_true",
default=False,
help=(
"Also match child jobs when installing a filter"
" (with --driver/--node, applies only to --wait filter)"
),
)
attach_parser.add_argument(
"--job-only",
action="store_true",
default=False,
help=(
"Only attach to matching job filters (with --driver/--node,"
" applies only to --wait filter)"
),
)
attach_parser.add_argument(
"--wait",
action="store_true",
default=False,
help=(
"When using --driver or --node, install a deferred"
" 'driver_host' process filter if no matching host is currently"
" running"
),
)
@staticmethod
async def execute(args: argparse.Namespace) -> int | None:
"""Validates that exactly one target selector argument is provided."""
provided = [
getattr(args, field, None) is not None
for field in ("filter", "driver", "node")
]
if sum(provided) != 1:
print(
"Error: Must specify exactly one of positional <filter>,"
" --driver, or --node.",
file=sys.stderr,
)
return 1
if args.exact and (args.driver is not None or args.node is not None):
print(
"Error: --exact cannot be used with --driver or --node.",
file=sys.stderr,
)
return 1
return None