diff --git a/docs/agent-control.md b/docs/agent-control.md index f0eec78010..e6484c0bbc 100644 --- a/docs/agent-control.md +++ b/docs/agent-control.md @@ -25,8 +25,8 @@ and reports every run. ## Access Player controls and observations work over authorized ADB on any build: `state`, `start`, `stop`, -`resume`, `wait`, `launch`, `quit`, `focus`, `input`, `ui`, `logs`, `screenshot`, `record`, `displays`, -`wake`, and `access`. +`resume`, `wait`, `launch`, `quit`, `focus`, `input`, `ui`, `logs`, `screenshot`, `record`, `pacing`, +`displays`, `wake`, and `access`. **Setup > Diagnostics > Debugging tools** is off by default in every build, including debug builds. It enables `run`, `guest`, `cdp`, all `env` operations, `override`, and `prefs`. The toggle switches @@ -118,12 +118,19 @@ tools/droiddeckctl prefs set session some_key true --type bool tools/droiddeckctl logs latest ./session-artifacts tools/droiddeckctl screenshot ./screen.png --display 4 tools/droiddeckctl record ./clip.mp4 --seconds 8 --display 0 +tools/droiddeckctl pacing --seconds 30 tools/droiddeckctl displays tools/droiddeckctl wake ``` A sleeping device suspends the session and hides the app's windows from `ui dump`; `wake` first. +`pacing` reads SurfaceFlinger's timestats for the game's layer (the session's SurfaceView when the +compositor has no layer of its own) and reports the frames that reached the panel, `fpsOnScreen`, +the present-to-present histogram and the share of intervals off the usual cadence. A game's own fps +counter counts frames handed over, not frames shown, so it can read 60 while one frame in four +stays on screen for two refreshes. + `input` needs a session that has drawn its first frame. Pad input goes through the session screen's virtual pad, the same one the on-screen controls drive, so games that ignore touch still respond. `launch`, `quit` and `cdp` need a Steam session; `focus` and `wait focused` need gamescope (every diff --git a/tools/droiddeckctl b/tools/droiddeckctl index 10f2cb6822..d88327a59d 100755 --- a/tools/droiddeckctl +++ b/tools/droiddeckctl @@ -285,6 +285,64 @@ def record(adb: str, serial: str, path: str, seconds: float, display: int | None return {"ok": True, "command": "record", "path": str(destination), "seconds": seconds, "display": display} +def pacing_summary(text: str, package: str = PACKAGE) -> dict: + """What reached the panel, from a `dumpsys SurfaceFlinger --timestats -dump`. + + The game is on the compositor's own layer (droiddeck_wayland_game) when it has one, otherwise on + the session's SurfaceView. SurfaceFlinger keeps one record per layer AND refresh rate, so a panel + that switches between 60 and 120 Hz mid-capture splits the same layer into several records: they + are summed. A game's own fps counter does not show any of this - it counts frames handed over, not + frames shown, and 60 handed over can be 48 on screen with one in four held for two refreshes. + """ + records = {"game": [], "surface": []} + for part in re.split(r"^layerName = ", text, flags=re.M)[1:]: + name, _, body = part.partition("\n") + kind = ("game" if "droiddeck_wayland_game" in name + else "surface" if f"SurfaceView[{package}/" in name else None) + frames = re.search(r"^totalFrames = (\d+)", body, re.M) + hist = re.search(r"^present2present histogram is as below:\n(.*)", body, re.M) + if kind and frames and hist: + records[kind].append((re.sub(r"#\d+$", "", name.strip()), int(frames.group(1)), hist.group(1))) + chosen = records["game"] or records["surface"] + histogram: dict[int, int] = {} + for _, _, hist in chosen: + for ms, count in re.findall(r"(\d+)ms=(\d+)", hist): + if int(count): + histogram[int(ms)] = histogram.get(int(ms), 0) + int(count) + intervals = sum(histogram.values()) + cadence = max(histogram, key=histogram.get) if histogram else None + off = intervals - histogram.get(cadence, 0) if histogram else 0 + return { + "layers": sorted({name for name, _, _ in chosen}), + "frames": sum(frames for _, frames, _ in chosen), + "refreshRates": sorted({int(r) for r in re.findall(r"^displayRefreshRate = (\d+)", text, re.M)}), + "presentToPresentMs": {str(ms): histogram[ms] for ms in sorted(histogram)}, + "cadenceMs": cadence, + "offCadence": off, + "offCadencePercent": round(100.0 * off / intervals, 1) if intervals else None, + } + + +def pacing(adb: str, serial: str, seconds: float) -> dict: + """Frames on screen and their intervals over `seconds`, from SurfaceFlinger's timestats.""" + seconds = max(1.0, min(600.0, seconds)) + timestats = ("shell", "dumpsys", "SurfaceFlinger", "--timestats") + if run_adb(adb, serial, *timestats, "-clear", "-enable").returncode != 0: + raise ControlError("could not enable SurfaceFlinger timestats", "PACING_FAILED") + started = time.monotonic() + time.sleep(seconds) + dump = run_adb(adb, serial, *timestats, "-dump", timeout=60) + elapsed = time.monotonic() - started + run_adb(adb, serial, *timestats, "-disable") + if dump.returncode != 0: + raise ControlError(dump.stderr.decode(errors="replace").strip() or "timestats dump failed", "PACING_FAILED") + summary = pacing_summary(dump.stdout.decode(errors="replace")) + if not summary["layers"]: + raise ControlError("No DroidDeck layer drew during the capture: is a session on screen?", "NO_FRAMES") + summary["fpsOnScreen"] = round(summary["frames"] / elapsed, 1) + return {"ok": True, "command": "pacing", "seconds": round(elapsed, 1), **summary} + + def start_session(adb: str, serial: str, request: dict) -> dict: if request.get("mode") == "run": @@ -504,6 +562,9 @@ def execute(args: argparse.Namespace, adb: str, serial: str) -> dict: if command == "record": return add_serial(record(adb, serial, args.path, args.seconds, args.display), serial) + if command == "pacing": + return add_serial(pacing(adb, serial, args.seconds), serial) + if command == "wake": run_adb(adb, serial, "shell", "input", "keyevent", "KEYCODE_WAKEUP") run_adb(adb, serial, "shell", "wm", "dismiss-keyguard") @@ -661,6 +722,9 @@ def build_parser() -> argparse.ArgumentParser: rec.add_argument("--seconds", type=float, default=10) rec.add_argument("--display", type=int) + pace = commands.add_parser("pacing", help="frames that reached the screen and their intervals (SurfaceFlinger)") + pace.add_argument("--seconds", type=float, default=30) + commands.add_parser("displays", help="the device's displays and their capture ids") commands.add_parser("wake", help="wake the device and dismiss the keyguard") return parser @@ -670,10 +734,11 @@ EXIT_ADB = {"ADB_NOT_FOUND", "ADB_FAILED", "INVALID_PROVIDER_RESPONSE"} EXIT_SESSION = { "SESSION_ACTIVE", "NO_ACTIVE_SESSION", "SESSION_NOT_SUSPENDED", "SESSION_FAILED", "GUEST_EXIT", "GUEST_START_FAILED", "RUNTIME_INSTALL_FAILED", "DESKTOP_INSTALL_FAILED", "ACTIVITY_START_FAILED", - "NO_STEAM_SESSION", "SESSION_NOT_READY", "AGENT_UNAVAILABLE", "LAUNCH_REJECTED", "NO_PAD", + "NO_STEAM_SESSION", "SESSION_NOT_READY", "AGENT_UNAVAILABLE", "LAUNCH_REJECTED", "NO_PAD", "NO_FRAMES", } EXIT_TIMEOUT = {"TIMEOUT", "ARTIFACT_TIMEOUT"} -EXIT_FILE = {"NO_SESSION_LOGS", "LOG_PULL_FAILED", "SCREENSHOT_FAILED", "FILE_IO", "RECORD_FAILED", "PUSH_FAILED"} +EXIT_FILE = {"NO_SESSION_LOGS", "LOG_PULL_FAILED", "SCREENSHOT_FAILED", "FILE_IO", "RECORD_FAILED", "PUSH_FAILED", + "PACING_FAILED"} EXIT_DENIED = {"AGENT_COMMANDS_DISABLED", "PROTECTED_PREFS", "PROTECTED_CONTROL"} diff --git a/tools/tests/test_droiddeckctl.py b/tools/tests/test_droiddeckctl.py index eda0c43dc4..afb5cc2182 100644 --- a/tools/tests/test_droiddeckctl.py +++ b/tools/tests/test_droiddeckctl.py @@ -57,6 +57,8 @@ FAKE_ADB = textwrap.dedent('''\ print(config.get("dumpsys_display", "")) elif args[:3] == ["shell", "dumpsys", "power"]: print(" mWakefulness=Awake") + elif args[:3] == ["shell", "dumpsys", "SurfaceFlinger"] and "-dump" in args: + print(config.get("timestats", "")) elif args[:2] == ["exec-out", "screencap"]: sys.stdout.buffer.write(b"\\x89PNG fake") with open(config["log"], "a") as log: @@ -79,6 +81,32 @@ DUMPSYS_DISPLAY = textwrap.dedent('''\ ''') +def timestats_record(name, frames, histogram, hz): + bins = " ".join(f"{ms}ms={histogram.get(ms, 0)}" for ms in (8, 16, 17, 25, 33, 50)) + return (f"displayRefreshRate = {hz} fps\nrenderRate = {hz} fps\nuid = 10479\nlayerName = {name}\n" + f"packageName = \ntotalFrames = {frames}\ndroppedFrames = 0\n" + f"present2present histogram is as below:\n{bins}\nlatch2present histogram is as below:\n8ms={frames}\n") + + +# A capture where the panel went from 60 to 120 Hz: the game layer is split in two records. The +# activity's own window and an unrelated app draw too, and must not count. +TIMESTATS_SPLIT = "SurfaceFlinger TimeStats:\ntotalFrames = 2000\n" + "".join([ + timestats_record("droiddeck_wayland_game#6110", 900, {16: 700, 33: 199}, 60), + timestats_record("droiddeck_wayland_game#6110", 900, {16: 850, 25: 49}, 120), + timestats_record("com.droiddeck.launcher/com.droiddeck.launcher.SessionActivity#6097", 8, {16: 7}, 60), + timestats_record("f291fb6 SurfaceView[com.droiddeck.launcher/com.droiddeck.launcher.SessionActivity]#6101", + 30, {33: 29}, 60), + timestats_record("StatusBar#106", 1, {}, 60), +]) + +# A build that presents the game on the session's SurfaceView instead of a layer of its own. +TIMESTATS_SURFACEVIEW = "SurfaceFlinger TimeStats:\n" + "".join([ + timestats_record("a1b2c3 SurfaceView[com.droiddeck.launcher/com.droiddeck.launcher.SessionActivity]#77", + 1800, {16: 1796, 33: 3}, 120), + timestats_record("a1b2c3 SurfaceView[com.other.app/com.other.app.Main]#12", 500, {8: 499}, 120), +]) + + def state(phase="READY", focused=None, focusable=()): focus = None if focused is None else {"focusedApp": focused, "focusableApps": list(focusable), "baselayerAppIds": [], "seq": 1, "t": 0} @@ -243,6 +271,40 @@ class DroiddeckctlTest(FakeAdbTest): self.assertEqual(2, code) self.assertEqual("NO_SUCH_DISPLAY", out["error"]["code"]) + def test_pacing_sums_split_records_of_the_game_layer_only(self): + summary = ctl.pacing_summary(TIMESTATS_SPLIT, "com.droiddeck.launcher") + self.assertEqual(["droiddeck_wayland_game"], summary["layers"]) + self.assertEqual(1800, summary["frames"]) + self.assertEqual([60, 120], summary["refreshRates"]) + self.assertEqual({"16": 1550, "25": 49, "33": 199}, summary["presentToPresentMs"]) + self.assertEqual(16, summary["cadenceMs"]) + self.assertEqual(248, summary["offCadence"]) + self.assertEqual(13.8, summary["offCadencePercent"]) + + def test_pacing_falls_back_to_the_sessions_surfaceview(self): + summary = ctl.pacing_summary(TIMESTATS_SURFACEVIEW, "com.droiddeck.launcher") + self.assertEqual(1, len(summary["layers"])) + self.assertIn("SurfaceView[com.droiddeck.launcher/", summary["layers"][0]) + self.assertEqual(1800, summary["frames"]) + self.assertEqual(3, summary["offCadence"]) + + def test_pacing_captures_then_turns_timestats_off(self): + self.configure({}, timestats=TIMESTATS_SURFACEVIEW) + with unittest.mock.patch.object(ctl.time, "sleep"): + code, out = self.run_ctl("pacing", "--seconds", "1") + self.assertEqual(0, code) + self.assertEqual("pacing", out["command"]) + self.assertIn("fpsOnScreen", out) + sf = [c["args"][3:] for c in self.calls() if c["args"][:3] == ["shell", "dumpsys", "SurfaceFlinger"]] + self.assertEqual([["--timestats", "-clear", "-enable"], ["--timestats", "-dump"], ["--timestats", "-disable"]], sf) + + def test_pacing_without_a_session_on_screen_exits_4(self): + self.configure({}, timestats="SurfaceFlinger TimeStats:\n" + timestats_record("StatusBar#1", 3, {16: 2}, 60)) + with unittest.mock.patch.object(ctl.time, "sleep"): + code, out = self.run_ctl("pacing", "--seconds", "1") + self.assertEqual(4, code) + self.assertEqual("NO_FRAMES", out["error"]["code"]) + def test_input_requests(self): self.configure({"input": {"ok": True, "command": "input"}}) self.run_ctl("input", "tap", "0.5", "0.25", "--space", "fraction")