[david-on-spring]

What and why

Ocarina of Time (Switch 2, 0400486024DEC000, v131072; profile in #1299) runs at 60–65 ms a frame in Link's house on a 16 GB Mac. The residency set is at 11.7 GB, against Metal's 12.1 GB working set. Romen-Adama-Dev's report on #1299 shows the same thing on an 18 GB M3 Pro: memory pools 4553, all resident for the raw global memory table.

Cause: a shader with raw global memory can reach any address it loads from memory. So its pool table (gmem_map_gpu) listed every memory pool and made each one resident. A zero-copy buffer in the residency set is wired whole. The game makes over 4,500 pools, and most of them hold only textures. There was a second path to the same result: the pool walk's storage check (tex_storage_live) went through mtl_addr, which also puts the pool it finds into the residency set, for every registered texture.

Fix: general, in nvn_mtl.m. A shader can only reach an address the game wrote into memory, and the game only gets a GPU address from three calls:

• nvnMemoryPoolGetBufferAddress
• nvnBufferInitialize (then nvnBufferGetAddress)
• nvnTextureGetTextureAddress

Each of these now marks the pool's range (mtl_pool_buffer_addr). The table lists, and makes resident, only the pools that meet a mark, and takes a large pool whole only then (big_full). A pool without a mark still comes into the residency set when a binding addresses it.

Supporting changes:

• Storage check: tex_storage_live only asks whether a pool maps the storage (mtl_addr_mapped).
• Uploads: a texture upload from an unlisted pool reads it through a buffer of its own, which the upload batch retires (up_big_src), as large pools already do.
• Marks:
  • Kept by address, so a virtual pool's runs, registered again on each mapping, keep theirs.
  • A mark left by a finalized pool only lists a later pool at that address, which is the safe side.
  • A full mark table (24,576 ranges) lists every pool, with a red line.
  • A new mark moves the pool generation under g_mu, so a table built while a mark arrives is rebuilt.
• Replays: nvn_replay marks every captured pool, since a capture doesn't record the marks.
• Escape hatch: DM_NVN_GMEM_ALL=1 lists every pool, as before.

Relation to #1360, which rewrites the same table to grow with the pools: this PR only filters which pools go in. It doesn't change the table's size or layout. It merges with #1360 without conflicts (git merge-tree). After the merge, #1360's new 5,000-pool cases in t_pool_chunks and t_gmem_raw add pools without marking them, so 3 and 4 of their checks fail. Adding mtl_pool_buffer_addr beside their mtl_pool_add calls (3 lines) makes both pass: 89 and 61 checks, 0 failed. Whichever of the two lands second should carry those lines, and I can add them here once #1360 is in.

#1360's entry says every pool has to stay in the table, because a zero read through a missing pool can become a hang. That still holds for every pool the game could hold an address in. This PR only leaves out pools the game never got an address from.

Reference entry: Pools the game took no buffer address in, out of the raw pool table. The symptom index is regenerated.

Checked

• Tests:
  • make -C dm/gfx/tests GAME=0400380020056000 check_t_gmem_marks (new, 28 checks) covers:
    • marked pools are listed and resident, and an unmarked one is neither;
    • the unmarked pool stays out of the residency set through the storage check and a texture upload, and the texture holds the pool's bytes;
    • a pool marked later is listed;
    • DM_NVN_GMEM_ALL lists every pool.
  • Each of the three host changes, undone alone, fails 1, 2 or 5 of its checks.
  • check_t_pool_chunks (79 checks; it now marks its large pool before the table takes it whole).
  • check_t_nvn (234), check_t_cpu_tex (56), check_t_readback (154 cases) and check_t_capture_live (the replay matches the live frame) pass.
  • Host tests (make -C dm/host/tests GAME=0400380020056000): 143 checks passed.
  • test_env_switches.py and test_docs.py pass.
  • lint_c.py tidy on nvn_mtl.m, hle_nvn.c and the new test: no finding above the baseline. My clang-tidy is LLVM 21, and the baseline was made with 23.
  • make -C dm/host GAME=0400380020056000 dmhost builds.
  • Not run: the rest of the Metal suite (make -C dm/gfx/tests run).
• Game run: Ocarina of Time v131072, on our stack ([WIP] The Legend of Zelda: Ocarina of Time (Switch 2, 0400486024DEC000, v0, SDK 22.2.8) runs on the Mac through the title movie into Kokiri Forest #1299 with other open PRs and a fixed 8,191-entry table in place of Raw global memory's pool table grows with the pools: pools past 4,095 were left out and hung the GPU in Ocarina of Time #1360). In Link's house, frames went from 60–65 ms to about 26 ms, and the residency set from 11.7 to 9.5 GB. This branch itself wasn't played: main has no profile for the game.
• Devices and OS: Apple M4 (16 GB), macOS 27.0.1.
• regress.py: not run. Not checked: the other games with raw global memory, which are Donkey Kong Bananza (gsys's indirect draw records), Tears of the Kingdom and Super Mario Bros. Wonder (vertex shader 588e242a52f5f7aa). Their record pools come from nvnMemoryPoolGetBufferAddress / nvnBufferInitialize, so they should still be listed. Donkey Kong Bananza's tunnel is the run that would show a miss: walls and floor missing.

Docs

• The finding is in its docs/reference/nvn-objects.md entry (with a link from the raw global memory entry in shaders.md), and python3 dm/tools/docs_symptoms.py was run (the symptom index)
• DM_NVN_GMEM_ALL is in docs/env_switches.tsv
• No game files, keys or data extracted from a game in the change or the attachments

Drafted with Claude; reviewed by me.

🤖 Generated with Claude Code