[david-on-spring]

What and why

Ocarina of Time (Switch 2, 0400486024DEC000, v131072; profile in #1299) runs out of GPU memory when Link leaves his house for Kokiri Forest. Command buffers fail with kIOGPUCommandBufferCallbackErrorOutOfMemory, with 16 GB of GPU memory allocated against Metal's recommended working set of 12.1 GB (16 GB Mac).

Cause: a pool table for handles traced to no slot (pool_gpu) resolves every registered texture ID, as a shader reading textures through handles may reach any of them. Ocarina of Time's texture pool has about 33,000 IDs. At a scene change the game finalizes the old scene's textures and leaves their IDs registered. mtl_tex_release drops their views, but the next table rebuild made a Metal texture for each of them again from its storage, and dropped it again at the end of the submission. At the house-to-forest change that was about 1,500 textures and 2.5 GB held only through retired IDs, plus as much again waiting in deferred release.

Fix: a new profile key, pool_skip_retired, off by default (DM_NVN_POOL_SKIP_RETIRED=1 / 0 overrides it). With the key on, a retired ID that holds no view gets the dummy texture in a pool table. Not affected:

• an ID bound to a slot;
• a retired ID that a draw in the same submission already resolved.

The table log line now counts the IDs it skipped.

It's a key rather than the default because on the console, a handle to a finalized texture still reads the texture's storage while that storage exists. A game that keeps sampling through such handles would read the dummy. If you'd rather make it the default, or drop retired IDs from the tables some other way, I'm happy to change it.

The profile line (pool_skip_retired on) can only go in #1299's game.tsv. I've put it in a comment there rather than stacking this PR on #1299. #1299 also splits this loop out into pool_entry, so the check moves there; the comment has those lines.

Reference entry: Finalized textures made again by pool tables. The symptom index is regenerated.

Checked

• Tests:
  • make -C dm/gfx/tests GAME=0400380020056000 check_t_pool_retired (new, 11 checks): one table with a live ID and a retired ID, with the key and without. With the skip line disabled, the "retired ID gets the dummy" check fails.
  • check_t_cpu_tex (56 checks, retired descriptors) and check_t_pool_chunks (75) pass.
  • test_game_profile.py, test_env_switches.py and test_docs.py pass.
  • lint_c.py tidy on nvn_mtl.m 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.
  • The rest of the Metal suite (make -C dm/gfx/tests run) was not 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 the other two fixes I'm sending), with the key on. 25 minutes in Kokiri Forest with no out-of-memory error, GPU memory peaking at about 12 GB, and frames down from 44 to 31 ms. This branch itself wasn't played, since main has no profile for the game.
• Devices and OS: Apple M4 (16 GB), macOS 27.0.1.
• regress.py: not run. The key is off by default, so no game on main changes behavior.

Docs

• The finding is in its docs/reference/nvn-objects.md entry, and python3 dm/tools/docs_symptoms.py was run (the symptom index)
• The key is in the keys table (dm/games/README.md), and the switch 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

[PucaVaz]

Testing this now on a second machine: Apple M4, 24 GB, macOS 27.2, Ocarina of Time v131072, docked. It's on lunks's fix/gmem-pool-table (574a38f) with this PR's check adapted and DM_NVN_POOL_SKIP_RETIRED=1, plus the 8 GB alias region from your #1299 comment. The route is the Link's house autosave → Kokiri Forest. Without the key, that same route on this Mac went from about 10 GB to a 14.6 GB footprint (13.2 GB GPU allocated) within seconds of stepping outside, so the before/after should be clear. I'll post the numbers here.

Drafted with Claude; reviewed by me.

[PucaVaz]

Second-machine confirmation: Apple M4, 24 GB, macOS 27.2.

Method: lunks's fix/gmem-pool-table (574a38f, #1299's profile) with this PR ported: pool_skip_retired() with DM_NVN_POOL_SKIP_RETIRED, and your line from #1299 in pool_entry. The table line also counts the skipped IDs. Only the host was rebuilt, and the chain stays 6406124273ec. Docked at 2560x1440, from the Link's house autosave, out the door into Kokiri Forest. Our run without the key had been stopped by our own 14 GB memory limit 132 s in.

Results:

• At the door: at frame 3900, just past the door, GPU allocated is 11.4 GB with the key against 13.2 GB without it (resident 12.2 against 14.2 GB). The house is the same in both (9.4 GB).
• In the forest: 18 minutes with the key, GPU allocated 10.1–11.9 GB, resident 11.0–13.1 GB, no out-of-memory, GPU error or abort. Swap did not grow.
• Tables: the 33,024-ID 2D table gives 12,000–17,000 retired IDs the dummy. With the key off, 29,767 of its 33,024 IDs had a texture.
• Images: no wrong or missing textures in the forest screenshots (cutscenes, dialogue, free roam, the pond).
• Frames: p50 is about 50 ms leaving the house either way. With the key, the forest settled to 34 ms p50 (p95 42) in the last minutes. I have no steady forest run without it, so I can't confirm the 44 → 31 ms.

Caveats:

• The run without the key was older, with the window in the background (DM_FOCUS_KEEP=1 in both).
• Table builds averaged 4.1 ms over the 18 minutes (8,000 builds), with nothing to compare in the forest.
• With [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's 8 GB alias region (DM_ALIAS_SIZE=0x200000000) footprint rose about 1.5 GB, and our 14 GB limit stopped that run after 3.5 minutes in the forest at 11.6 GB GPU allocated, without any error.

Drafted with Claude; reviewed by me.

[PaulEins]

Tested on a real device, and it fixes the stutter on entering Kokiri Village / Forest for me.

Setup: MacBook Pro, M4 Pro (14-core CPU / 20-core GPU), 48 GB, macOS 26.7.2, update-only NUP v131072, Mac app. Tree: stan69b's oot-clean + #1332, #1343, #1350, #1376, #1390, #1408, #1409, #1417, #1420, #1430 and current main. This PR didn't merge there (its pool walk is pool_entry now), so I ported the same check into pool_entry: a retired ID without a view gets the dummy, behind DM_NVN_POOL_SKIP_RETIRED.

Without it, entering Kokiri Village gave 3–5 s at roughly 10–17 fps. In that 300-frame window:

• packaged texture first uploads went from 26,594 to 198,561 (about 172,000, ~570 per frame)
• residency set: 514,901 additions / 157,668 MB, 1,228 commits taking 4,948 ms
• finalized textures still referenced 512 (small table, 188905 put in total)
• frame time p50 58.4 ms, of it submit+present 58.3 ms; GPU only 20.9 ms

A second, smaller burst came on the way into the forest (135,795 additions, 2,224 ms of commits). stan69b's B-6 fix was already in, so these were CPU-written (packaged) textures being made again on every walk, not new private ones.

With DM_NVN_POOL_SKIP_RETIRED=1: no such window over two runs (~15,000 frames). The worst 300-frame window is 36–38 fps, which is GPU-bound (24–27 ms). The dummy was handed out about 19 million times in one session, and I saw no missing or black textures in Kokiri Village, Kokiri Forest or Link's house, including after scene changes.

Drafted with Claude; reviewed by me.