[ycarogabriel-lgtm]

What and why

Three switches we used, or will use, while chasing Ocarina of Time (0400486024DEC000) problems on an M1, 16 GB. All are off by default and cost one getenv when off.

1. TEXDUMP over a range, with depth targets.

   • DM_NVN_TEXDUMP=<first>-<last>:<path> dumps every frame of the range. Each file name gets _F<frame> before its extension, because a serial that lives across frames would otherwise be overwritten.
   • DM_NVN_TEXDUMP_DEPTH=1 (or =WxH) also saves the depth attachments of the dumped frames: the raw depth with a text header, and an 8-bit PGM stretched over the depths below 1.
   • Why: OoT's per-actor shadow maps are 76x76 depth-only passes whose textures are made anew each frame. DM_NVN_TEXRAW, which takes a known serial, cannot reach them, and TEXDUMP saved only one frame's colour targets.
   • The single-frame, size= and layers= forms behave as before.
   • DM_CTL paths that start with ~/ are under $HOME (an iOS app's data container), and DM_NVN_TEXDUMP_MINW keeps a texdump to the wide targets #1483 adds DM_NVN_TEXDUMP_MINW. The two do not overlap in code, but they touch the same function.

2. DM_NVN_A5288_C3=1.

   • In the passes that hang on Apple silicon (Ocarina of Time (0400486024DEC000 v131072, Mac): GPU hang about 10 minutes into play takes WindowServer down #1326, Ocarina of Time on an M1 (16 GB): GPU hang (kIOGPUCommandBufferCallbackErrorHang) under memory pressure, about 24 fps at 720p / 30 fps #1605), the only loop is the Hi-Z scan of task a5288d0a6c4971fd, bounded by c3[193].xy. Those are the occlusion tile grid's width and height, at byte 3088 of Maxwell constant buffer 3 (NVN uniform binding 0). The tiles are floats of the same block from byte 3120.
   • For every a5288 draw the switch keeps those values, the block's address and size, whether an inline update of the block is deferred in the pass, and the fence. It then:
     • logs each change, and logs in red a W×H whose tiles do not fit the block (with the values read as floats too);
     • at each submission's completion, reads the values again and counts the draws whose values changed since encode, i.e. a block rewritten while the GPU could read it;
     • on kIOGPUCommandBufferCallbackErrorHang, lists the hung command buffer's draws against the 64 command buffers before it.
   • This is meant to test the suspects from Ocarina of Time (0400486024DEC000 v131072, Mac): GPU hang about 10 minutes into play takes WindowServer down #1326: the block rewritten while the GPU reads it, a stale binding, or a lost write.

3. DM_NVN_MESH_GRID_LOG was dropped from this PR after merging main: 09dcb62 launches a mesh shader with no task in blocks of 1024, so a log of draws past the 1,024 mesh grid no longer applies.

Evidence

• TEXDUMP range and depth were used on the M1 to follow OoT's shadow chain over 9 consecutive frames while the camera turned (our test log EXP-meshM1-71). Every input of the shadow projection came from the same frame, so we found no stale data in that chain; the visual glitch we still see is under investigation elsewhere.
• DM_NVN_A5288_C3 builds and is documented, but has not been run in a game yet. The first run is planned with DM_NVN_ISOLATE_TASK=0 against =1 on the M1. No result is claimed here.

Risks and caveats

• Off by default.
• The range dump synchronizes with the GPU every frame, like the single-frame dump. It changes timing and hides timing-dependent problems.
• DM_NVN_A5288_C3 reads guest memory on the completion handler thread, for a5288 draws only.

Checked

• Host builds; no new compiler warnings.
• With MTL_DEBUG_LAYER=1: t_pso_archive 135 checks, 0 failed; t_clear_tex 51 checks, 0 failed.
• test_env_switches: the new rows are accepted. The test still fails on DM_NVN_BC_ALIAS and DM_YIELD_CLOCK, which also fail on main 7f50222.

🤖 Generated with Claude Code

[ycarogabriel-lgtm]

A note on the red clang-tidy (ratchet) check: it is not from this diff. The same job on main 7f50222 (run 42513044169) fails with the same counts in dm/gfx/nvn/nvn_mtl.m: clang-analyzer-core.BitwiseShift 1 (baseline 0), CallAndMessage 1 (baseline 0), NullDereference 10 (baseline 9). The findings the report lists for this PR are at the same places as in main's report (e.g. lines 5902, 9229 and the di/src/dst dereferences), none in the code this PR adds. So the baseline probably needs a refresh on main; I did not add any NOLINT here so as not to hide it.

[ycarogabriel-lgtm]

Update on the red clang-tidy (ratchet) mentioned above. The failure I described then (counts in nvn_mtl.m that main 7f50222 also had) no longer applies: main's baseline has been refreshed and its lint-c run at 09dcb62 passes.

The failure on head bf62ae0 is a different one and it is from this PR: dm/gfx/nvn/nvn_mtl.m has 16 clang-analyzer-nullability.NullablePassedToNonnull findings against 15 in the baseline (run 42547297527; the job reports 224 findings, baseline 223, one file/check pair above it). The extra one is in td_dump_depth, added here: it passed the result of newBufferWithLength: (nullable) as the toBuffer: of a blit copy.

Pushed 0ae9505: a failed allocation now logs a [texdump] line and skips that texture. Host build, test_docs, test_lint_c and test_env_switches pass locally; I cannot run clang-tidy 23.1.4 here, so whether the count is back to 15 is for the job to show once it re-runs.

[ycarogabriel-lgtm]

The Sanitizers job failed on head 0ae9505 (run 42558669890) in the step ThreadSanitizer, the host tests that start threads, not in ASan/UBSan. The log ends with Assertion failed: (signaled(device_stopped, 3)), function blocked_start, file t_audio_device.c, line 191 (the audio device test waiting on a semaphore, built with -fsanitize=thread).

This PR changes only dm/gfx/nvn/nvn_mtl.m, docs/env_switches.tsv and the Ocarina of Time note, and does not touch the audio code or that test. The same job passed on the previous head bf62ae0 of this branch, and tsan-threads passed locally on that head. That points to a timing-dependent test on a loaded runner, not to this diff, but I have not reproduced the failure or shown it is flaky. I cannot re-run it (the API asks for admin rights); a re-run of the failed job would settle it.

[ycarogabriel-lgtm]

The Unsigned iOS app job failed on head 0ae9505 (run 42558669890) at the link step of the iOS project build: ld: framework 'IOBluetooth' not found.

It is not from this diff (nvn_mtl.m, docs/env_switches.tsv, the Ocarina of Time note; none mentions IOBluetooth or a framework). IOBluetooth is imported by dm/host/pad_switch2_apple.m, added on main by a342d64 (Switch 2 controllers over Bluetooth LE on the Mac), which this branch does not contain; the job builds the pull request merged onto current main. The same error, framework 'IOBluetooth' not found, fails the same job on #1928 (run 42578128891, head c890f78a). The iOS job passed on this PR's earlier heads, before that commit was on main. I have not tried to fix it here, since it is main's.

[ycarogabriel-lgtm]

The clang-tidy (ratchet) job failed on head dfed038 (run 42632137357), and this time it is not from this PR: dm/gfx/tests/t_pso_archive.m has 3 clang-analyzer-nullability.NullablePassedToNonnull findings against 2 in the baseline (224 findings in total, baseline 223, one file/check pair above it). The 0ae9505 fix for nvn_mtl.m held: that file is not in the list any more.

This PR does not touch t_pso_archive.m. The file changed on main in 70b9a68 (the pipeline archive index), and the baseline on main still lists 2 for it. Main's own lint-c run 42634192860 (head 1d37720, which contains 70b9a68) fails with the same line: the same file, 3 against 2, 224 findings against 223. So the baseline needs a refresh on main; I have not added a NOLINT here.

[ycarogabriel-lgtm]

The Tool tests failure on head dfed038 (test_no_new_abi_literals: dm/gfx/nvn/nvn_mtl.m '?' went from 2 to 3) is not from this PR. I ran python3 -m unittest dm.tools.tests.test_dmsh_abi on main 04811a6 alone, on this branch's head dfed038, and it fails the same way on both: {'dm/gfx/nvn/nvn_mtl.m': {"'?'": '2 -> 3'}}. The diff of this PR against main adds no '?' literal to nvn_mtl.m. #1981 (open) changes that ratchet so it no longer counts "?"; I have not changed anything here for it.