[aksmith-git]

What and why

keys_hash (hle_nvn.c) checks that a shader's code lies in a memory pool before it hashes the code into the shader's key. It asked mtl_addr, which also makes the pool resident (pool_res). The GPU never reads that code, since the shaders run translated. So every pool a program's code lies in stayed in the residency set: in Ocarina of Time, 222 pools and 334 MB, read from the residency line's additions by source line, where mtl_addr had added them as the game set its programs. On an iPad, Metal's working set is 8,192 MB, and this game goes past it (#1436).

mtl_pool_holds is the same lookup as mtl_addr (pool_find), without the residency. Keys are unchanged: a shader is keyed exactly when it was before. A pool the GPU does read, through a binding or an address, is still made resident on that path.

Reference entry: docs/reference/memory.md, "Pools that hold shader code made resident to key the shaders", with its line in the symptom index and Ocarina of Time's note.

Checked

• Tests: check_t_pool_holds (new, 8 checks: the lookup, a range past the end, no pool made resident, mtl_addr still making it resident, a removed pool), t_nvn (236 checks), test_docs.py.
• make -C dm/host GAME=0400486024DEC000 dmhost builds on main 0f510fd.
• Games run: the change ran in our Ocarina of Time (0400486024DEC000 v131072) builds on the Mac (M4 Pro) and an iPad Pro (M5, iOS 27). It was on a stack of other changes there, so there is no separate before/after run of this one. The 334 MB figure comes from that stack's residency line.
• regress.py not run: we have no --platform mac builds of other games on this machine. Keys are unchanged, and the only behaviour change is that a pool is not made resident at program set time.

Docs

• The finding is in docs/reference/memory.md, and python3 dm/tools/docs_symptoms.py was run
• No game files, keys or data extracted from a game in the change

[nafields]

Data from Ocarina of Time (Switch 2, 0400486024DEC000, v131072), M2 Pro 16 GB, with this PR ported onto a tree with #1417, #1391/#1482, the render-target reclaim (#1588) and #1607:

• Estimated saving, read off the residency log (not an A/B of footprint): 222 pools holding shader code stay out of the residency set, about 334 MB.
• Stability: runs to f7,750 with it have no crash or regression we could attribute to it.
• Ruled out as the cause of a deterministic GPU page fault near f780 (the Kokiri load spike). A run with the pre-PR mtl_addr (shader code pools made resident again) still faults there, so that fault has another cause.

[seedds]

Thanks, landed as f25fa95 with you as co-author. The diagnosis, the test and the reference entry are kept.

What changed:

• keys_hash now asks mtl_addr_known, the side-effect-free pool lookup texture uploads already used on main, made public, instead of a new mtl_pool_holds. mtl_pool_holds went through pool_find, and for a pool in chunks (512 MB or more) that makes the chunk holding the code, so it still had a side effect there. mtl_addr_known answers from the pool's range, and now checks that the whole range lies in it.
• The test is now t_addr_known, with a large-pool case (no chunk made, nothing resident).

Measured on main, with hosts built with and without the change:

• The Great Ace Attorney Chronicles (DM_CTL restop): shared buffers in the residency set 19 / 241 MB -> 16 / 236 MB at 30 s, 22 / 353 MB -> 19 / 348 MB at 60 s (three chunks of its 1,000 MB pool).
• Ocarina of Time: no change, 4,276 resident pools before and 4,277 after on the village walk, 2,324 on both at the title. Its shaders read raw global memory, and on main the raw pool table (gmem_map) makes every pool the game took an address in resident, shader code pools included. The 222 pools / 334 MB came from your build with other changes. The reference entry says so.