[oliverames]

What and why

The GPU tests under dm/gfx/tests only run on a Mac, so a depth/stencil fault that shows on an iPhone's GPU alone has no test to run there. This adds dm/ios/tools/test_gfx_on_iphone.py, which builds a small signed app around t_clear_ds.m, compiled unchanged, and with --run installs it on a connected iPhone, starts it and reads the result back. --generate-only stops after the Xcode project and --build-only after the signed app. It reads no game files or keys.

It came from testing Donkey Kong Bananza on an iPhone 17 Pro Max. The fixture covers the shared depth/stencil clear behaviour, so it can help check renderer changes other titles use. It doesn't change how any game renders.

I've cut this PR down to that one change. Earlier versions also carried a window_copy fixture, a push_capture fixture and a --measurement metal_conversion mode. Those are gone from this branch: window_copy came from #1140, which was closed, push_capture only exists in #1160, and the measurement probe belongs to separate HDR work. The old head (92b6d73) is kept on my fork as archive/iphone-gfx-runner-extras-20261110 in case any of it is wanted later.

The branch is now one commit on main fd8188c9 (head 2dba6cd1). clear_ds is the only fixture offered.

While trimming I moved what the tool decides into four small functions so it can be tested without a phone:

• results.json is accepted only when it's a JSON object with this build's run ID and complete set. The same bundle ID keeps its Documents folder across installs, so an earlier run's report is still there until the new app writes its own. A copy that doesn't parse is polled again instead of ending the run.
• A pass needs a zero exit code, at least one check, no failed check and the app's own passed field. Before, the tool trusted passed alone.

Checked

• Tests: python3 dm/ios/tests/test_gfx_phone_runner.py (11 tests, new: which report is accepted, what counts as a pass, the names of what it builds, and that the support source list still matches the tests' Makefile). CI's tool tests job picks it up with the other dm/ios/tests files. python3 dm/tools/tests/test_docs.py (6 tests). The Python lint ratchet against main: 323 findings, all in the baseline, none new.
• Build: --generate-only on main fd8188c9, then an unsigned xcodebuild of the generated project for generic/platform=iOS (Xcode 27.3, profile 040074A01BF12000). It compiled and linked.
• Games run: none. The tool uses a profile for compile-time constants only.
• Devices and OS: I haven't run this head on a phone. Nothing was signed, installed or launched, so --build-only's signing steps and all of --run are untested at this commit. The only phone run was on 2026-11-04 with the first version of the tool, on an iPhone 17 Pro Max (A19 Pro GPU, iOS 27.2): all 11 cases and 59 checks passed with Metal API Validation Enabled in the collected log, and the full --run path built, signed, installed, launched and pulled the matching report (Debug app, upstream renderer at 1d4b8e82). The report handling has changed since then and only has the unit test behind it.
• No regress.py report: the change adds a tool and a test and doesn't touch the host, the shader chain or any game.

Front ends

None: nothing here is for a front end to act on.

Docs

• docs/development.md (Continuous integration) says how to run the tool, what a pass means and what the test covers. There's no game finding or reference entry in this change, so docs_symptoms.py wasn't needed.
• A chain tool changed: not applicable.
• No game files, keys or data extracted from a game in the change or the attachments

[oliverames]

Commit 54e15b37 adds --fixture window_copy and --fixture push_capture, with documentation linking the fixture sources in #1140 and #1160. clear_ds remains the default. Use --tree to select the checkout containing the requested fixture; a missing source fails before output creation or any device operation.

Both new choices passed project/header generation using the iPhoneOS SDK. Ruff and pyright report zero findings for the runner, all 11 documentation tests pass, and the missing-source check passes. The initial sandboxed generation failed on access to Xcode's compiler cache; generation succeeded with cache access.

The local runner previously exercised these choices on iPhone 17 Pro Max: 31 window-copy checks and 28 push-capture checks passed. Those results apply to their recorded fixture hashes, not the newer 32-check window-copy completion case. No new phone run occurred for this commit. The PR remains draft, and neither fixture establishes sustained gameplay, visible-screen output or a fur-shimmer improvement.

[oliverames]

@seedds, new head edd9817d adds a separate raw-measurement mode for the Switch 2 games running on iPhone investigation. It uses #1168's standalone conversion probe, embeds the same 95 exact inputs, and records raw output without treating rounding as a regression pass. The iOS 26 app builds and signs, source/input hashes are checked, report-contract tests and Python/docs checks pass, and independent review found no actionable issues. It has not been installed or measured on iPhone 17 Pro Max. Existing fixture behavior remains separate; this stays draft pending physical measurement and hosted CI.

[oliverames]

@seedds Flagging from my open-PR index of my 32 open PRs here: this one stays draft pending hosted CI and the remaining device verification. The description above is still the full picture, nothing new from me. Happy to rebase, split or retitle whenever review suits.

[oliverames]

@seedds Marking this ready for review now, so it stops waiting in draft on me. The remaining item from the description is still open: hosted CI and the remaining device verification. It can carry on alongside a review instead of ahead of it. The description stays the source of truth; happy to rebase, split or retitle whenever review suits.

[oliverames]

Closing this. It only runs on a physical iPhone, and the checks it would add are better made on the Mac, where you work. Thanks!