[aksmith-git]

What and why

Ocarina of Time (Switch 2, 0400486024DEC000, profile in #1299) runs on an iPad (iPad17,3, M5, 12 GB) at about 22 ms a frame until the first area load after a save, then runs out of GPU memory: GPU out of memory: the residency set holds 9124 objects, 8259 MB against Metal's 8,192 MB working set, with kIOGPUCommandBufferCallbackErrorOutOfMemory, pink or broken frames and 120-300 ms of GPU a frame. Handheld mode fails later, 27 MB over. #1369 hit the same wall on an iPhone. This PR does not fix it: it adds two diagnostics and records what fills the working set, so the next attempt starts from numbers.

• DM_CTL poolstat: the resident memory pools, the texture storage inside them, the largest pools.
• DM_CTL texstat: host textures by kind; those made from guest memory by frames since their last use (NvPkg gets a last-use frame); render targets by shape with distinct guest storage addresses, their span, and live serials. Each host texture is counted once.
• docs/reference/memory.md: the measurements and three experiments that did not help (symptom index regenerated), with a line in Ocarina of Time's note; docs/env_switches.tsv lists the two lines under DM_CTL.

Measurements (M4 Pro, handheld, 7 minutes from a save; guest memory in files)

These were taken before main's raw pool table and pool read bitmap changes, which address the pool row below (the 2,432 MB pool now stays out of the table). The doc entry says so and links them; the render-target row is still open. The iPad has not been measured on a host with both changes.

working set	12.1-12.5 GB (iPad: 8 GB)
memory pools (raw table keeps all resident)	5.9 GB; 2,625 of 5,370 MB is texture storage, so resident twice
textures from guest memory	2.36 GB, 5,527, every one resolved in the last second
render targets	2.4 GB, 860; transient ones duplicated at shifting offsets (103 x 720x405 RGBA16F over a 9.4 MB span, 36 + 36 x 1440x810 over 46.6 MB)

The raw table is needed: 783 of the 8,319 shaders a play used do raw loads.

Not kept (details in the doc entry): leaving texture-only pool memory out of the raw table (one GPU hang before the first frame), a large pool through its chunks only (no saving), reclaiming taken-over shared textures by alias-lookup idleness (active targets looked idle).

Checked

• Rebased on main 0f510fd (the docs conflicted with the two memory entries above; resolved by keeping both and pointing this entry at them). make -C dm/host GAME=0400486024DEC000 dmhost builds; check_t_pso_pending, check_t_pool_chunks, check_t_cpu_tex, docs_symptoms.py, test_docs.py, test_env_switches.py pass. lint_c.py tidy not run here (this machine's LLVM does not start). The earlier clang-tidy failure was main's t_int_float_view.m, not this change.
• The diagnostics were run on our Ocarina of Time stack (main 056e41f + [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 + Ampere F2IP and a task shader's own payload read: Ocarina of Time's untranslated shaders translate, all but one that is data #1300); main itself has no profile for it.

[williamstonef]

Same device class here: iPad Pro 11-inch (M5), 12 GB, iPadOS 27.2, same game (v131072), NX2Apple 1.2.3 engine pin 88c7e03f51e3, shader chain adec7d81d970. Handheld + MetalFX upscaler, Encode thread off, Frame buffering on.

It runs at about 54 fps (frame p50 18.5 ms, p95 29 ms over the last windows), but memory climbs the whole time (host memory up to frame lines):

frame	resident	GPU allocated
300	2.2 GB	2.4 GB
10,500	6.8 GB	9.5 GB
21,900	9.4 GB	15.3 GB
41,700	10.6 GB	16.4 GB

At 20:00 of play (frame 41,806) the host log just stops, with no CRASH line and no GPU out of memory line. iOS wrote a JetsamEvent for the same minute: the system hit vm-pageshortage and ended 118 processes (background daemons and suspended apps), with DmShell frontmost at 9.83 GB resident, lifetime max 11.06 GB. So on this iPad the jetsam kill came before Metal's own out-of-memory failure.

If it helps, I can run any of the DM_CTL poolstat/texstat captures on this iPad.

Drafted with Claude; reviewed by me.

[aksmith-git]

Thanks, that matches what pushed us to the guest-file path. On an iPad Pro 13-inch (M5) with the same game (v131072) and guest memory in files (DM_GUEST_FILE=1, plus the hole punching from #1492 and the idle upload staging release from #1491), a 15-minute handheld run stayed at 3.5 GB resident (GPU allocated 10.7 GB) from start to end, no jetsam: 49,800 frames, no out-of-memory line. With guest memory in RAM the climb you see is mostly the guest's own pages, which iOS counts against the footprint; in files they're clean file-backed pages the system can evict. If you can, a run with DM_GUEST_FILE=1 in env.txt and the memory up to frame / [mem] guest file lines would show whether it holds there too.

[aksmith-git]

Rebased on main eed7c42 (the conflicts were the note's entry list and the DM_CTL row of env_switches.tsv). Builds with the Ocarina of Time profile; t_hid 169 checks, 0 failed; docs_symptoms --check current; test_docs OK. test_env_switches fails on main itself (DM_NVN_CUT_FIRST, DM_NVN_RT_RECLAIM, DM_NVN_VC_WAYS, DM_NVN_BC_ALIAS), nothing from this change.