pymobiledevice3 5.0.4__py3-none-any.whl → 7.0.6__py3-none-any.whl

pymobiledevice3/cli/developer/dvt/core_profile_session.py

@@ -0,0 +1,295 @@
+import importlib.resources
+import json
+import logging
+from itertools import islice
+from pathlib import Path
+from typing import Annotated, Optional
+
+import typer
+from pykdebugparser.pykdebugparser import PyKdebugParser
+from typer_injector import InjectingTyper
+
+import pymobiledevice3.resources
+from pymobiledevice3.cli.cli_common import (
+    BASED_INT,
+    ServiceProviderDep,
+    default_json_encoder,
+    print_json,
+    user_requested_colored_output,
+)
+from pymobiledevice3.exceptions import ExtractingStackshotError
+from pymobiledevice3.services.dvt.dvt_secure_socket_proxy import DvtSecureSocketProxyService
+from pymobiledevice3.services.dvt.instruments.core_profile_session_tap import CoreProfileSessionTap
+from pymobiledevice3.services.dvt.instruments.device_info import DeviceInfo
+
+logger = logging.getLogger(__name__)
+
+BSC_SUBCLASS = 0x40C
+BSC_CLASS = 0x4
+VFS_AND_TRACES_SET = {0x03010000, 0x07FF0000}
+
+
+cli = InjectingTyper(
+    name="core-profile-session",
+    help="Access tailspin features",
+    no_args_is_help=True,
+)
+
+
+BSCFilter = Annotated[
+    bool,
+    typer.Option(help="Whether to print BSC events or not."),
+]
+ClassFilter = Annotated[
+    list[int],
+    typer.Option(
+        "--class-filters",
+        "-cf",
+        click_type=BASED_INT,
+        default_factory=list,
+        show_default=False,
+        help="Events class filter. Omit for all. Can be specified multiple times.",
+    ),
+]
+SubclassFilter = Annotated[
+    list[int],
+    typer.Option(
+        "--subclass-filters",
+        "-sf",
+        click_type=BASED_INT,
+        default_factory=list,
+        show_default=False,
+        help="Events subclass filter. Omit for all. Can be specified multiple times.",
+    ),
+]
+Count = Annotated[
+    Optional[int],
+    typer.Option(
+        "--count",
+        "-c",
+        help="Number of events to print. Omit to endless sniff.",
+    ),
+]
+ThreadID = Annotated[
+    Optional[int],
+    typer.Option(help="Thread ID to filter. Omit for all."),
+]
+ShowThreadID = Annotated[
+    bool,
+    typer.Option(help="Whether to print thread ID or not."),
+]
+
+
+def parse_filters(subclasses: list[int], classes: list[int]) -> Optional[set[int]]:
+    if not subclasses and not classes:
+        return None
+    parsed: set[int] = set()
+    for subclass in subclasses:
+        if subclass == BSC_SUBCLASS:
+            parsed |= VFS_AND_TRACES_SET
+        parsed.add(subclass << 16)
+    for class_ in classes:
+        if class_ == BSC_CLASS:
+            parsed |= VFS_AND_TRACES_SET
+        parsed.add((class_ << 24) | 0x00FF0000)
+    return parsed
+
+
+@cli.command("live")
+def live_profile_session(
+    service_provider: ServiceProviderDep,
+    *,
+    count: Count = -1,
+    bsc: BSCFilter = False,
+    class_filters: ClassFilter,
+    subclass_filters: SubclassFilter,
+    tid: ThreadID = None,
+    timestamp: Annotated[
+        bool,
+        typer.Option(help="Whether to print timestamp or not."),
+    ] = True,
+    event_name: Annotated[
+        bool,
+        typer.Option(help="Whether to print event name or not."),
+    ] = True,
+    func_qual: Annotated[
+        bool,
+        typer.Option(help="Whether to print function qualifier or not."),
+    ] = True,
+    show_tid: ShowThreadID = True,
+    process_name: Annotated[
+        bool,
+        typer.Option(help="Whether to print process name or not."),
+    ] = True,
+    args: Annotated[
+        bool,
+        typer.Option(help="Whether to print event arguments or not."),
+    ] = True,
+) -> None:
+    """Print kevents received from the device in real time."""
+    parser = PyKdebugParser()
+    class_filters = class_filters
+    subclass_filters = subclass_filters
+    parser.filter_class = class_filters
+    if bsc:
+        subclass_filters.append(BSC_SUBCLASS)
+    parser.filter_subclass = subclass_filters
+    filters = parse_filters(subclass_filters, class_filters)
+    parser.filter_tid = tid
+    parser.show_timestamp = timestamp
+    parser.show_name = event_name
+    parser.show_func_qual = func_qual
+    parser.show_tid = show_tid
+    parser.show_process = process_name
+    parser.show_args = args
+    with DvtSecureSocketProxyService(lockdown=service_provider) as dvt:
+        trace_codes_map = DeviceInfo(dvt).trace_codes()
+        time_config = CoreProfileSessionTap.get_time_config(dvt)
+        parser.numer = time_config["numer"]
+        parser.denom = time_config["denom"]
+        parser.mach_absolute_time = time_config["mach_absolute_time"]
+        parser.usecs_since_epoch = time_config["usecs_since_epoch"]
+        parser.timezone = time_config["timezone"]
+        with CoreProfileSessionTap(dvt, time_config, filters) as tap:
+            for i, event in enumerate(parser.formatted_kevents(tap.get_kdbuf_stream(), trace_codes_map)):
+                print(event)
+                if i == count:
+                    break
+
+
+@cli.command("save")
+def save_profile_session(
+    service_provider: ServiceProviderDep,
+    out: Path,
+    *,
+    bsc: BSCFilter = False,
+    class_filters: ClassFilter,
+    subclass_filters: SubclassFilter,
+) -> None:
+    """Dump core profiling information."""
+    if bsc:
+        subclass_filters.append(BSC_SUBCLASS)
+    filters = parse_filters(subclass_filters, class_filters)
+    with (
+        DvtSecureSocketProxyService(lockdown=service_provider) as dvt,
+        CoreProfileSessionTap(dvt, {}, filters) as tap,
+        out.open("wb") as out_file,
+    ):
+        tap.dump(out_file)
+
+
+@cli.command("stackshot")
+def stackshot(
+    service_provider: ServiceProviderDep,
+    out: Annotated[Optional[Path], typer.Option()] = None,
+) -> None:
+    """Dump stackshot information."""
+    with DvtSecureSocketProxyService(lockdown=service_provider) as dvt, CoreProfileSessionTap(dvt, {}) as tap:
+        try:
+            data = tap.get_stackshot()
+        except ExtractingStackshotError:
+            logger.exception("Extracting stackshot failed")
+            return
+
+        if out is not None:
+            out.write_text(json.dumps(data, indent=4, default=default_json_encoder))
+        else:
+            print_json(data)
+
+
+@cli.command("parse-live")
+def parse_live_profile_session(
+    service_provider: ServiceProviderDep,
+    *,
+    count: Count = None,
+    bsc: BSCFilter = False,
+    class_filters: ClassFilter,
+    subclass_filters: SubclassFilter,
+    tid: ThreadID = None,
+    show_tid: ShowThreadID = False,
+    process: Annotated[
+        Optional[str],
+        typer.Option(help="Process ID / name to filter. Omit for all."),
+    ] = None,
+) -> None:
+    """Print traces (syscalls, thread events, etc.) received from the device in real time."""
+    with DvtSecureSocketProxyService(lockdown=service_provider) as dvt:
+        print("Receiving time information")
+        time_config = CoreProfileSessionTap.get_time_config(dvt)
+        parser = PyKdebugParser()
+        parser.filter_class = list(class_filters)
+        if bsc:
+            subclass_filters.append(BSC_SUBCLASS)
+        parser.filter_subclass = subclass_filters
+        filters = parse_filters(subclass_filters, class_filters)
+        parser.numer = time_config["numer"]
+        parser.denom = time_config["denom"]
+        parser.mach_absolute_time = time_config["mach_absolute_time"]
+        parser.usecs_since_epoch = time_config["usecs_since_epoch"]
+        parser.timezone = time_config["timezone"]
+        parser.filter_tid = tid
+        parser.filter_process = process
+        parser.show_tid = show_tid
+        parser.color = user_requested_colored_output()
+
+        with CoreProfileSessionTap(dvt, time_config, filters) as tap:
+            if show_tid:
+                print("{:^32}|{:^11}|{:^33}|   Event".format("Time", "Thread", "Process"))
+            else:
+                print("{:^32}|{:^33}|   Event".format("Time", "Process"))
+
+            for trace in islice(parser.formatted_traces(tap.get_kdbuf_stream()), count):
+                print(trace, flush=True)
+
+
+def get_image_name(dsc_uuid_map, image_uuid, current_dsc_map):
+    if not current_dsc_map:
+        for dsc_mapping in dsc_uuid_map.values():
+            if image_uuid in dsc_mapping:
+                current_dsc_map.update(dsc_mapping)
+
+    return current_dsc_map.get(image_uuid, image_uuid)
+
+
+def format_callstack(callstack: str, dsc_uuid_map, current_dsc_map) -> str:
+    lines = callstack.splitlines()
+    for i, line in enumerate(lines[1:]):
+        if ":" in line:
+            uuid = line.split(":")[0].strip()
+            lines[i + 1] = line.replace(uuid, get_image_name(dsc_uuid_map, uuid, current_dsc_map))
+    return "\n".join(lines)
+
+
+@cli.command("callstacks-live")
+def callstacks_live_profile_session(
+    service_provider: ServiceProviderDep,
+    count: Count = -1,
+    process: Annotated[
+        Optional[str],
+        typer.Option(help="Process ID / name to filter. Omit for all."),
+    ] = None,
+    tid: ThreadID = None,
+    show_tid: ShowThreadID = False,
+) -> None:
+    """Print callstacks received from the device in real time."""
+    with DvtSecureSocketProxyService(lockdown=service_provider) as dvt:
+        print("Receiving time information")
+        time_config = CoreProfileSessionTap.get_time_config(dvt)
+        parser = PyKdebugParser()
+        parser.numer = time_config["numer"]
+        parser.denom = time_config["denom"]
+        parser.mach_absolute_time = time_config["mach_absolute_time"]
+        parser.usecs_since_epoch = time_config["usecs_since_epoch"]
+        parser.timezone = time_config["timezone"]
+        parser.filter_tid = tid
+        parser.filter_process = process
+        parser.color = user_requested_colored_output()
+        parser.show_tid = show_tid
+
+        with importlib.resources.open_text(pymobiledevice3.resources, "dsc_uuid_map.json") as fd:
+            dsc_uuid_map = json.load(fd)
+
+        current_dsc_map = {}
+        with CoreProfileSessionTap(dvt, time_config) as tap:
+            for callstack in islice(parser.formatted_callstacks(tap.get_kdbuf_stream()), count):
+                print(format_callstack(callstack, dsc_uuid_map, current_dsc_map))

pymobiledevice3/cli/developer/dvt/simulate_location.py

@@ -0,0 +1,56 @@
+from pathlib import Path
+from typing import Annotated
+
+import typer
+from typer_injector import InjectingTyper
+
+from pymobiledevice3.cli.cli_common import OSUTILS, ServiceProviderDep
+from pymobiledevice3.services.dvt.dvt_secure_socket_proxy import DvtSecureSocketProxyService
+from pymobiledevice3.services.dvt.instruments.location_simulation import LocationSimulation
+
+cli = InjectingTyper(
+    name="simulate-location",
+    help="Simulate device location by given input",
+    no_args_is_help=True,
+)
+
+
+@cli.command("clear")
+def dvt_simulate_location_clear(service_provider: ServiceProviderDep) -> None:
+    """Clear currently simulated location"""
+    with DvtSecureSocketProxyService(service_provider) as dvt:
+        LocationSimulation(dvt).clear()
+
+
+@cli.command("set")
+def dvt_simulate_location_set(service_provider: ServiceProviderDep, latitude: float, longitude: float) -> None:
+    """
+    Set a simulated location.
+
+    \b
+    For example:
+    \b    ... set -- 40.690008 -74.045843 for liberty island
+    """
+    with DvtSecureSocketProxyService(service_provider) as dvt:
+        LocationSimulation(dvt).set(latitude, longitude)
+        OSUTILS.wait_return()
+
+
+@cli.command("play")
+def dvt_simulate_location_play(
+    service_provider: ServiceProviderDep,
+    filename: Annotated[
+        Path,
+        typer.Argument(exists=True, file_okay=True, dir_okay=False),
+    ],
+    timing_randomness_range: int = 0,
+    disable_sleep: Annotated[bool, typer.Option()] = False,
+) -> None:
+    """Simulate inputs from a given .gpx file"""
+    with DvtSecureSocketProxyService(service_provider) as dvt:
+        LocationSimulation(dvt).play_gpx_file(
+            str(filename),
+            disable_sleep=disable_sleep,
+            timing_randomness_range=timing_randomness_range,
+        )
+        OSUTILS.wait_return()

pymobiledevice3/cli/developer/dvt/sysmon/__init__.py

@@ -0,0 +1,69 @@
+import logging
+from dataclasses import asdict
+from typing import Annotated, Optional
+
+import typer
+from typer_injector import InjectingTyper
+
+from pymobiledevice3.cli.cli_common import ServiceProviderDep
+from pymobiledevice3.cli.developer.dvt.sysmon import process
+from pymobiledevice3.services.dvt.dvt_secure_socket_proxy import DvtSecureSocketProxyService
+from pymobiledevice3.services.dvt.instruments.sysmontap import Sysmontap
+
+logger = logging.getLogger(__name__)
+
+
+cli = InjectingTyper(
+    name="sysmon",
+    help="System monitor options.",
+    no_args_is_help=True,
+)
+cli.add_typer(process.cli)
+
+
+@cli.command("system")
+def sysmon_system(
+    service_provider: ServiceProviderDep,
+    fields: Annotated[
+        Optional[str],
+        typer.Option(
+            "--fields",
+            "-f",
+            help='field names separated by ",".',
+        ),
+    ] = None,
+) -> None:
+    """show current system stats."""
+
+    split_fields = fields.split(",") if fields is not None else None
+
+    with DvtSecureSocketProxyService(lockdown=service_provider) as dvt:
+        sysmontap = Sysmontap(dvt)
+        with sysmontap as sysmon:
+            system = None
+            system_usage = None
+            system_usage_seen = False  # Tracks if the first occurrence of SystemCPUUsage
+
+            for row in sysmon:
+                if "System" in row and system is None:
+                    system = sysmon.system_attributes_cls(*row["System"])
+
+                if "SystemCPUUsage" in row:
+                    if system_usage_seen:
+                        system_usage = {
+                            **row["SystemCPUUsage"],
+                            "CPUCount": row["CPUCount"],
+                            "EnabledCPUs": row["EnabledCPUs"],
+                        }
+                    else:  # Ignore the first occurrence because first occurrence always gives a incorrect value - 100 or 0
+                        system_usage_seen = True
+
+                if system and system_usage:
+                    break
+
+    assert system is not None and system_usage is not None  # for type checker
+
+    attrs_dict = {**asdict(system), **system_usage}
+    for name, value in attrs_dict.items():
+        if (split_fields is None) or (name in fields):
+            print(f"{name}: {value}")

pymobiledevice3/cli/developer/dvt/sysmon/process.py

@@ -0,0 +1,188 @@
+import contextlib
+import json
+import logging
+import time
+from collections import namedtuple
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Annotated, Optional
+
+import typer
+from typer_injector import InjectingTyper
+
+from pymobiledevice3.cli.cli_common import ServiceProviderDep, default_json_encoder, print_json
+from pymobiledevice3.services.dvt.dvt_secure_socket_proxy import DvtSecureSocketProxyService
+from pymobiledevice3.services.dvt.instruments.device_info import DeviceInfo
+from pymobiledevice3.services.dvt.instruments.sysmontap import Sysmontap
+
+logger = logging.getLogger(__name__)
+
+
+cli = InjectingTyper(
+    name="process",
+    help="Process monitor options.",
+    no_args_is_help=True,
+)
+
+
+@cli.command("monitor")
+def sysmon_process_monitor(service_provider: ServiceProviderDep, threshold: float) -> None:
+    """monitor all most consuming processes by given cpuUsage threshold."""
+
+    Process = namedtuple("process", "pid name cpuUsage physFootprint")
+
+    with DvtSecureSocketProxyService(lockdown=service_provider) as dvt, Sysmontap(dvt) as sysmon:
+        for process_snapshot in sysmon.iter_processes():
+            entries = []
+            for process in process_snapshot:
+                if (process["cpuUsage"] is not None) and (process["cpuUsage"] >= threshold):
+                    entries.append(
+                        Process(
+                            pid=process["pid"],
+                            name=process["name"],
+                            cpuUsage=process["cpuUsage"],
+                            physFootprint=process["physFootprint"],
+                        )
+                    )
+
+            logger.info(entries)
+
+
+@cli.command("single")
+def sysmon_process_single(
+    service_provider: ServiceProviderDep,
+    attributes: Annotated[
+        Optional[list[str]],
+        typer.Option(
+            "--attributes",
+            "-a",
+            help="filter processes by given attribute value given as key=value. Can be specified multiple times.",
+        ),
+    ] = None,
+) -> None:
+    """show a single snapshot of currently running processes."""
+
+    count = 0
+
+    result = []
+    with DvtSecureSocketProxyService(lockdown=service_provider) as dvt:
+        device_info = DeviceInfo(dvt)
+
+        with Sysmontap(dvt) as sysmon:
+            for process_snapshot in sysmon.iter_processes():
+                count += 1
+
+                if count < 2:
+                    # first sample doesn't contain an initialized value for cpuUsage
+                    continue
+
+                for process in process_snapshot:
+                    skip = False
+                    if attributes is not None:
+                        for filter_attr in attributes:
+                            filter_attr, filter_value = filter_attr.split("=", 1)
+                            if str(process[filter_attr]) != filter_value:
+                                skip = True
+                                break
+
+                    if skip:
+                        continue
+
+                    # adding "artificially" the execName field
+                    process["execName"] = device_info.execname_for_pid(process["pid"])
+                    result.append(process)
+
+                # exit after single snapshot
+                break
+
+    print_json(result)
+
+
+@cli.command("monitor-single")
+def sysmon_process_monitor_single(
+    service_provider: ServiceProviderDep,
+    attributes: Annotated[
+        Optional[list[str]],
+        typer.Option(
+            "--attributes",
+            "-a",
+            help="filter processes by attribute (key=value). Multiple filters on same attribute use OR logic, different attributes use AND.",
+        ),
+    ] = None,
+    output: Annotated[
+        Optional[Path],
+        typer.Option(
+            "--output",
+            "-o",
+            help="output file path for JSONL format (optional, defaults to stdout)",
+        ),
+    ] = None,
+    interval: Annotated[
+        Optional[int],
+        typer.Option(
+            "--interval",
+            "-i",
+            help="minimum interval in milliseconds between outputs (optional)",
+        ),
+    ] = None,
+    duration: Annotated[
+        Optional[int],
+        typer.Option(
+            "--duration",
+            "-d",
+            help="maximum duration in milliseconds to run monitoring (optional)",
+        ),
+    ] = None,
+) -> None:
+    """Continuously monitor a single process with comprehensive metrics."""
+    count = 0
+    start_time = None
+
+    # Parse attributes into grouped filters: same attribute uses OR, different attributes use AND
+    parsed_filters: dict[str, list[str]] = {}
+    if attributes:
+        for raw in attributes:
+            key, value = raw.split("=", 1)
+            parsed_filters.setdefault(key, []).append(value)
+
+    def matches_filters(proc: dict) -> bool:
+        """Check if process matches all filter criteria."""
+        if not parsed_filters:
+            return True
+        return all(str(proc.get(key)) in values for key, values in parsed_filters.items())
+
+    with contextlib.ExitStack() as stack:
+        output_file = stack.enter_context(open(output, "w")) if output else None
+
+        dvt = stack.enter_context(DvtSecureSocketProxyService(lockdown=service_provider))
+        sysmon = stack.enter_context(Sysmontap(dvt))
+
+        for process_snapshot in sysmon.iter_processes():
+            count += 1
+
+            if count < 2:
+                continue
+
+            if start_time is None:
+                start_time = time.time()
+
+            if duration is not None:
+                elapsed_ms = (time.time() - start_time) * 1000
+                if elapsed_ms >= duration:
+                    break
+
+            for process in process_snapshot:
+                if not matches_filters(process):
+                    continue
+
+                process["timestamp"] = datetime.now(timezone.utc).isoformat()
+
+                if output_file:
+                    json_output = json.dumps(process, default=default_json_encoder)
+                    output_file.write(json_output + "\n")
+                    output_file.flush()
+                else:
+                    print_json(process)
+
+            if interval:
+                time.sleep(interval / 1000.0)