[enjoyerofslop]

What and why

Symptom: in a game whose shaders read the texture pool (the pool for handles traced to no slot lines), the pool table's source line leads the residency report. Every 300 frames it shows thousands of residency-set additions and removals and hundreds of commits. Found on The Legend of Zelda: Ocarina of Time (Switch 2, 0400486024DEC000), where 4,823 of 42,854 shaders read the pool.

Cause: two things in pool_gpu (dm/gfx/nvn/nvn_mtl.m).

• A new buffer for every rebuild. Each rebuilt table went into a new buffer of 8 bytes per registered ID (264 KB at Ocarina of Time's 33,000). That meant an allocation, a residency-set addition and, behind the fence, a removal. A game that registers textures or changes their storage every frame rebuilds tables many times a frame.
• Lookups before the type check. A walk looked up every registered ID before checking its texture type. So a 2D-array table walked every 2D ID, and remade the views of retired registrations (which go at every submission end) only to turn them away.

Change:

• Spares. A replaced table becomes one of 64 spares (pool_buf_retire). A later rebuild writes it again once the submission that could still read it has completed (pool_buf, against g_done). Spares stay in the residency set. Argument blocks holding an old address are not reused past a rebuild (g_psnap_gen, unchanged).
• Type skip. A registration keeps the Metal type tex_by_id gave it (treg_t.tt, cleared when the ID is registered again), and a walk passes over an ID of another type without looking it up. The type is fixed by the descriptor (its target, the view's target and the layer count), so it outlives the cached view.
• Pool log line. It now counts table buffers made, reused and IDs of another type passed over.

Reference entry: Pool tables rebuilt into new buffers and walked over IDs of another type. The symptom index is regenerated. The entry also records what is still open: the table holds a Metal texture for every registered ID of its type, whether or not a shader reads it. In Ocarina of Time's Kokiri Forest that was about 4,200 textures (1.56 GB) that nothing read. Marking reads from the shaders to make them on demand cost about 22 % of GPU time, even with the marking switched off, because a fragment shader that can write memory runs its depth test after itself.

On #1299: that PR adds a copy-and-patch path to pool_gpu. With this change, its copy should come from pool_buf(p->buf.length) and the old table should go through pool_buf_retire(p->buf), and its pool_entry should get the same type check before tex_fast_rid. The Ocarina of Time numbers below are from main + #1299 + this change, merged that way.

Checked

• Tests:
  • make -C dm/gfx/tests GAME=01007EF00011E000 t_pool_table: 20 checks OK. It covers:
    • a spare not written again before its submission completes, and written again after;
    • a 3D ID in a 2D table passed over without its view being made again;
    • a new registration forgetting the type;
    • a timing check: a walk over 20,000 2D IDs with dropped views in a 2D-array table takes 0.08 ms instead of 3.2 ms (M5 Max, Metal validation on).
  • The same test, t_cpu_tex (62) and t_pool_chunks (81) also pass on the Ocarina of Time tree (main + [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 + this change).
  • make -k -C dm/gfx/tests GAME=01007EF00011E000 run: every test passes but t_nvn. It aborts in up_owner_check ("upload batches belong to the submit thread only: up_begin called on thread ''", from present_enqueue → tex_mtl → pkg_upload), and it aborts the same way on main (865cc35) without this change.
  • python3 -m unittest dm/tools/tests/test_docs.py: OK.
• Games run: The Legend of Zelda: Ocarina of Time, 0400486024DEC000, update v131072, 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.

  • Setup: Kokiri Forest from the same save, along the same scripted route (walking, camera turns, dialog). About 250 s per run, two runs per host, alternated. The game does not run under DM_DETCLOCK, so the runs are on the wall clock and their timings drift apart.

  • Results (per 300 frames of gameplay, medians):

    	before (2 runs)	after
    residency commits	664, 678	56
    residency additions	3,136, 2,500	276
    commit time	70 ms, 46 ms	11 ms
    table buffers made / reused (whole run)	all made	1,487 / 81,333
    lookups of IDs of another type	(all looked up)	74 million passed over, about 5,900 a frame

  • Spare count: with 8 spares instead of 64, 41,483 tables were made: the oldest spare was pushed out before it came free.

  • Frame times: p50 is vsync-bound at 16.4 ms in all runs. p95 and long frames (48 to 52 per 1,000 frames) moved within the runs' noise. Time per full pool build was 2.07 and 3.64 ms in the two runs before and 2.95 ms after, so the before runs alone differ by more than the change.

• regress.py: python3 scripts/regress.py check --baseline 865cc35f --candidate HEAD --games 01007EF00011E000,0100000000010000 (the full run), on the two NVN games this Mac has --platform mac builds of. regress.py impact lists Breath of the Wild among the games the change reaches, through the registration and lookup bookkeeping every NVN game has. Neither game has a shader that reads the texture pool, so the table code itself does not run in them.
  • Saves: the routes ran from this contributor's own saves, because the profiles' saves/outdoors and saves/look_around are not on this Mac.
    • Breath of the Wild waits at the load prompt: frame 2500 is not reached, in the baseline too.
    • Odyssey plays its opening from a new game.
  • The two flagged screenshots are run-to-run noise, not a change. The check's own baseline was a single run, so it reports a baseline noise of 0. Measured with regress.py's shot_hashes / shot_distance across five runs of 865cc35:
    • Breath of the Wild, 60 s (the title's artwork slideshow behind the load prompt): the baseline runs differ from each other by up to RGB 26.8 and 28 dHash bits. Each candidate run is within RGB 2.2 and 6.7, 2 bits, of a baseline run.
    • Odyssey, 95 s (the opening cutscene): baseline runs differ by up to RGB 14.9 and 9 bits. The candidate runs are within RGB 9.3 (8 bits) and 0.0 (one identical) of a baseline run.
  • Everything else is unchanged: shaders, frames reached, frame rate, p99, footprint and prebuild. validated.tsv was not recorded, as the routes did not run from the profiles' saves.

regress.py check (full): REGRESSION

Baseline 865cc35f 865cc35, candidate HEAD f537147; Apple M5 Max, macOS 27.0.1, Xcode 27.2; 918.6 s

game	status	shaders (base → cand)	newly failing	newly building	changed MSL	interface (new / known)	boot	fps p50	frame p99 ms	peak MB	prepare s	new RED
The Legend of Zelda Breath of the Wild 01007EF00011E000	REGRESSION	19420/19420 → 19420/19420	0	0	0	0 / 0	FAIL	29.5 → 29.8	91.83 → 67.72	3057 → 3075	1.49 → 1.55	0
Super Mario Odyssey 0100000000010000	CHANGED	27984/27984 → 27984/27984	0	0	0	0 / 0	ok	59.9 → 59.9	18.63 → 18.39	2359 → 2380	None → None	0

The Legend of Zelda Breath of the Wild 01007EF00011E000: REGRESSION

• REGRESSION: screenshot at 60 s differs (dHash 15 bits, RGB 23.3)
• known (baseline too): frame 2500 not reached by 60 s (max 3206)
  • screenshots (s: dHash bits / RGB diff / baseline noise): 60: 15/23.3/0, 80: 4/1.89/0
  • baseline: exit None, first frame 2.9 s, max frame 3189, reached False, prepare 1.49 s, prebuild 90.7 s (15631 built, 0 failed), fps 29.5, p50/p99 33.35/91.83 ms, peak 3057 MB
  • candidate: exit None, first frame 2.9 s, max frame 3206, reached False, prepare 1.55 s, prebuild 90.3 s (15631 built, 0 failed), fps 29.8, p50/p99 33.35/67.72 ms, peak 3075 MB
  • time: chain 11.1 s, smoke 402.4 s

Super Mario Odyssey 0100000000010000: CHANGED

• CHANGED: screenshot at 95 s moved (RGB 10.44)

  • screenshots (s: dHash bits / RGB diff / baseline noise): 70: 0/0.51/0, 95: 6/10.44/0
  • baseline: exit None, first frame 1.3 s, max frame 6520, reached True, prepare None s, prebuild 135.8 s (32864 built, 0 failed), fps 59.9, p50/p99 16.66/18.63 ms, peak 2359 MB
  • candidate: exit None, first frame 1.3 s, max frame 6505, reached True, prepare None s, prebuild 133.9 s (32864 built, 0 failed), fps 59.9, p50/p99 16.66/18.39 ms, peak 2380 MB
  • time: chain 13.7 s, smoke 491.1 s

• Devices and OS: M5 Max (Mac17,6), macOS 27.0.1.

Docs

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

🤖 Generated with Claude Code

[seedds]

Thank you. Both ideas, reusing replaced pool tables and passing over IDs of another type, are on main in 6121fd7 and credited in docs/reference/memory.md. Tables made fell to 11 in 11,700 frames here. Long frames didn't change from this alone, which matches your measurement. Final checks on the rebased tree (full shader build, walks, regression) are still running, so please report anything you see.

[jonpage0]

For the record, measured on an M3 Max (36 GB, macOS 27.0.1, Xcode 27.2) with Ocarina of Time v131072: this change adapted on top of #1430 and the 2026-11-05 main doubled the long frames in a 60 s window standing at the Kokiri balcony autosave (DM_CTL-driven, same save, no sampler): 466 against 235 [longframe] lines, 36 against 9 frames over 200 ms, submit-thread CPU p95 70.6 ms against 12.0 ms, 30.9 fps against 42.5. All native tests passed on it (t_pool_table, t_pool_retire, t_feedback, the gfx matrix with and without DM_NVN_ENC_THREAD=1), so it is the run-time cost, not a correctness problem, that showed. The walk that was actually hurting on this machine turned out to be alias_take_over's serial-table walk (#1439): with that change the same route went from 85 frames over 100 ms to 2.