[oliverames]

Opt-in, off by default. Read on one device so far (below); the Mac test and one iPhone run are the only checks.

What and why

Mario Kart World 1.8.0 (#1383's build) on a physical iPhone goes from about 9 to 30 ms of GPU time a frame, a tight plateau, 30 to 50 s into a race: seen in six runs with HDR on and off, with the game's present interval and with DM_PRESENT_INTERVAL=display, with and without a scheduler declaration change, while the CPU stayed at a full clock and 55 to 63% on performance cores (and the ProcessInfo thermal state did not track it). cheemu21/plumber-racer-2 reports the same plateau on a cold phone. The game's GPU time moves with its scene and with the GPU clock, so it cannot say which of the two stepped.

DM_GPU_CANARY=1 submits a fixed compute dispatch (about 1 G dependent FMAs, no memory traffic) on the app's own queue once a second, after five seconds, and logs its GPU time: gpu canary #n at s s: GPU x ms, submit to done y ms. It does not move with the scene, so a step in it at the moment the game's GPU time steps says the GPU clock fell, and a flat canary says the scene got heavier. It shares the GPU with the game, so read the smallest of a few samples. It costs a few milliseconds of GPU a second. Without the variable nothing is created or submitted. Switch row in docs/env_switches.tsv; reading guide in docs/development.md.

Checked

• Tests: new t_gpu_canary runs the real Metal path (mtl_init with the variable set): the start line is logged, three samples arrive in 8 s, GPU time positive and bounded (7.6 ms on an M-series Mac), built with make -C dm/gfx/tests GAME=0400C3F00006E000 t_gpu_canary. It caught a real bug while writing it (the timer source was a local and was released at once, so nothing ever fired); fixed. nvn_mtl.m also syntax-checks for the iPhoneOS SDK. dm/tools/tests/test_docs.py passes; the new switch is in docs/env_switches.tsv with its meaning (at the time env_switches.py --check reported DM_NVN_BC_ALIAS, which was missing from the table on main too; main's d8b2b64a1 has since added that row).
• Games run, with title ID and version: Mario Kart World (0400C3F00006E000) 1.8.0, built from WIP: Mario Kart World 1.8.0 on iOS - rendering, memory and presentation #1383's tree with the same function, one run of 62 s with the canary on, handheld, HDR off.
• Devices and OS: Apple-silicon Mac, macOS 27.3, for the test; iPhone 19,4 (iOS 27.3) for the run.
• Measurements: the canary took 4.3 to 4.8 ms from 11 to 28 s, ramped over 4 s, then 13.8 to 17.9 ms (3.1 to 3.3 times) from 34 s to the end; the game's own GPU p50 went 7.5 to 8.9 ms, then 29 to 31 ms (3.3 to 3.5 times) at the same moment; the ProcessInfo thermal state stayed 1 and the CPU stayed at a full clock. So the GPU clock fell to about a third and the scene was not the cause.
• scripts/regress.py check --games: not run: off by default, so every game runs as before without the variable.
• Not checked: whether the canary's cost changes the game's frame time (about 4 ms of GPU a second on the phone, small next to a 16.7 ms frame; unmeasured); a second run; a run on another game or device.

Front ends

None: no front end has to act on this.

Docs

• The reading guide is in docs/development.md and the switch in docs/env_switches.tsv; no game finding, so no symptom entry
• A chain tool changed: dmsh_chain.py --header was run and dm/gfx/nvn/dmsh_chain.h is part of the change. Not applicable: no chain tool changed.
• No game files, keys or data extracted from a game in the change or the attachments

[oliverames]

Device read of the canary (iPhone 18 Pro class, 2P+4E cores, MKW 1.8.0, HDR off, thermal state 1 throughout), not fully tested:

• Across two device runs the canary shows the GPU running 3.1 to 3.3x slower about 30 s into sustained MKW load, while ProcessInfo.thermalState stays at 1 and the CPU keeps its clock. So the slowdown is not visible to the thermal API.
• In a third run (DM_PRESENT_HZ=30) the canary read 4.4 to 7 ms from 13 to 25 s, then 14 to 16 ms from 29 s on, the same step.
• HDR on or off, game or display present interval, and DM_RT60 made no difference.

Conclusion: the canary separates a GPU clock drop from the game's own pacing, which is what it was added for. It does not explain the drop, so this PR is a diagnostic only.