Skip to content

Ocarina of Time's residency set on the iPhone: the physical pool behind GPU-only targets, large targets' heap slack, the zero buffer and idle uploaded textures leave it (depends on #2270) - #2566

Open
stan69b wants to merge 76 commits into
seedds:mainfrom
stan69b:pr/oot-fps-d-memory

Conversation

@stan69b

@stan69b stan69b commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

Depends on #2270 (built on its head b8cb0bd, which adds the census and the small-device rules this changes). Merge #2270 first; this PR's own commits are the last eight.

On the iPhone 17 (8 GB), walking Hyrule Field into Kakariko Village, Ocarina of Time's residency set reached 3.9 GB, wired memory 5.7 GB of 7.67, 147 MB free, and the village load warned. This PR finds what the set holds, by holder, and cuts what a general rule can cut.

What changed

  1. D-1, the census says who holds what (nvn_mtl.m res_top). DM_CTL restop lists the set's largest textures one by one with their holders, and a pool of 32 MB or more says what made it resident: a lookup's caller in the host image, or the raw pool table. In Kakariko this showed a 305 MB CPU_NO_ACCESS pool (flags 0x18c) with nothing but virtual mappings and texture addresses in it.
  2. D-2, texture addresses and virtual mappings in storage the CPU cannot reach stay out of the raw pool table (hle_nvn.c, mtl_pool_addressed_by, kind 5). The game keeps its render targets in GPU-only virtual pools over that physical pool. A block-linear texture there keeps its content in a Metal texture of its own, so no shader reading the table can need the pool's bytes. A buffer, a linear texture, the pool's own address and CPU-visible storage still put the pool in.
  3. D-2, pools of 256 MB and more are wired in chunks (BIG_MIN 512 → 256 MB). Once the table let go, one compute shader (f8965bffbdf51d78_b) still bound a 200 KB storage buffer inside the 305 MB pool every frame, and the lookup wired all of it. Now only the 31 MB the lookups reach are wired.
  4. D-2, a new recycled render-target heap carries at most 4 MB of slack, not an eighth (rh_heap, RH_SLACK). The 12288x12288 Depth16 shadow target (296 MB, sampled in Kakariko, so it stays) sat in a 333 MB heap; it is now in a 300 MB one. Targets up to 32 MB keep their eighth.
  5. D-3, colour textures and scissored clears are zeroed in pieces of rows (tex_zero_fill, clear_rect_zero). The shared zero buffer stays at 4 MB; it had grown to 64 MB and stayed resident.
  6. D-3, small devices free idle uploaded textures every 10 s (pkg_sweep; small_working_set, a Metal working set under 6 GB). The rules are those of the memory-pressure trim (30 s unused; pinned, GPU-written, placed and sparse ones kept). Until now each area's textures stayed until the next pressure warn. DM_NVN_TEX_EVICT_IDLE=0 / 1 forces it off or on. Macs keep waiting for pressure.

No profile key, no per-game threshold. Docs: four entries in docs/reference/memory.md and the chunk entry in nvn-objects.md; the symptom index is regenerated; the game note carries the Kakariko holders.

Measurements

Mac (16 GB, the iPhone's memory settings: guest in files, window spans, smaller textures, dynamic resolution, MetalFX, encode thread, 30 fps cap), from the owner's phone save, the same route each time (Kakariko, out to Hyrule Field, back). Residency set in MB; the Mac's set carries about 560 MB of c1 banks the phone does not have.

Point Before All but the chunk threshold (sweep forced on) All
Kakariko, a minute after the load 4,526 4,381 4,171
Hyrule Field, then +60 s 5,070 4,777 → 4,696 4,550 → 4,486
Kakariko again, then +2 min 4,894 4,562 → 4,384 4,311 → 4,133
  • The 0x18c pool: 305 MB before, 31 MB after (two chunks).
  • Uploaded textures on the second Kakariko visit: 762 MB before, 522 then 346 MB with the sweep.
  • A sweep pass takes 0.1 to 3.5 ms.
  • Frame time p50 is 33.33 ms in all three runs, with no GPU errors. The screenshots at each point are whole.

iPhone 17 (build oot-build-vis, before): set 3,190 to 3,398 MB in Hyrule Field, 3,704 to 3,939 MB in Kakariko; wired 5.43 to 5.69 GB, 127 to 173 MB free; one memory-pressure warn at the village load (trim 290 MB). Holders in Kakariko (3,729 MB):

Holder MB
memory pools (the 305 MB 0x18c pool among them) 1,608
recycled render-target heaps 779
uploaded textures 561
span heaps 288
arenas 92
upscaler 84
nn::ndve 84
zero buffer 64

iPhone 17, after, run unattended and back to back on 2026-11-13: iphone_drive_batch.sh picks Continue into Kakariko, then turns the camera for 7 minutes. Baseline oot-build-vis against oot-build-vis plus this PR's commits.

Kakariko, after the load Baseline This PR
Residency set 3,524–3,555 MB 3,075–3,153 MB
Wired (of 7,672) 5,255–5,360 MB 4,826–4,964 MB
Free 93–165 MB 77–221 MB
Memory-pressure warns / trims 0 / 0 0 / 0
Frame p50 (300-frame windows) 33.39–35.15 ms 33.19–35.89 ms
  • The set is about 450 MB smaller: target 3.0 GB, reached 3.08 to 3.15 GB.
  • Neither run warned, because this route loads Kakariko straight from the save, without Hyrule Field before it. The warn seen at the village load came after walking in from the field, which needs the owner.
  • Both runs survived with the same RED lines, and env.txt was restored after each.
  • Open: a sweep pass took 0.3 to 2.3 ms, but 11 ms once right after the area load (136 textures in one pass). It runs at a submission's start; a cap per pass is the likely next step.

regress.py check

scripts/regress.py check --baseline b8cb0bd6 --candidate 125d2a78 --games 0400486024DEC000, Apple M4, macOS 27.2. Only Ocarina of Time, the game the batch is about. The sweep runs only on small devices, so no Mac run takes it. Kind 5, the row-piece zero fill, the heap slack and the chunk threshold reach every NVN game. A check on the other local NVN games (Echoes of Wisdom, Super Mario 3D All-Stars) is still pending: the Mac is shared with three other sessions of this batch tonight.

game status shaders changed MSL boot fps p50 frame p99 ms peak MB new RED
Ocarina of Time REGRESSION (see below) 42848/42848 → 42848/42848 0 ok 59.6 → 59.6 17.8 → 17.78 2896 → 2861 0

The two flagged screenshots (350 s and 385 s) are the title screen in both runs, whole, with its rotating backdrop on different scenes: forest at night against the desert, the ranch by day against Lake Hylia. Nothing else differs.

Tests

make -C dm/gfx/tests GAME=0400486024DEC000, all passing:

Target Checks
t_gpu_only_addr (new) 12
t_zero_colour (new) 30
t_rt_recycle 30
t_pkg_evict 53
t_pool_chunks 151
t_image_alias 337
t_window_alias 25
t_addr_known 20
t_zero_depth 55
t_clear_ds 59
t_clear_tex 51
t_file_wire 10
t_upload_src 41

python3 -m unittest dm/tools/tests/test_docs.py passes.

@stan69b

stan69b commented Nov 13, 2026

Copy link
Copy Markdown
Contributor Author

OoT-fps combined phone build, against the baseline (session A, A-2)

iPhone 17, Ocarina of Time, Kakariko Village by day, unattended drive script, 7 minutes each, back to back (2026-11-13, 22:20 and 22:36). Medians over the gameplay windows (more than 1,000 draws a frame).

baseline (512 ring) combined change
fps 28.6 29.4 +0.8
frame time p50 / p95 34.3 / 40.6 ms 33.6 / 37.1 ms p95 −3.5 ms
NVN submit+present p50 14.13 ms 12.25 ms −13 %
GPU p50 31.2 ms 30.4 ms −3 %
submit thread CPU a frame 13.47 ms at 2.05 GHz 12.00 ms at 1.82 GHz −11 % at a lower clock
instructions per draw 26,790 24,614 −8.1 %
draws per frame 2,680 2,770
share of CPU time on performance cores 49 % 51 %
CPU energy 0.99 W 0.84 W −15 %
residency set 3,499-3,561 MB 3,014-3,174 MB −0.4 GB
system wired 5,230-5,397 MB 4,808-4,950 MB −0.4 GB
memory-pressure warns 1 0
thermal state (max) 1 2
  • Both runs show the same screenshots and the same RED line: the stale pipeline archive message, which both builds print.
  • After each run, env.txt was put back byte for byte, and the save was not touched.
  • The game's real-time threads in the combined run were never demoted: 0 of 300 frames on the acquire, queue replay and encode threads.

Against A-1's targets:

  • Submit ≤ 15 ms: reached.
  • A steady 30 fps: nearly; 29.4 median, p95 37 ms.
  • Performance-core share ≥ 60 %: not reached (51 %).

An earlier pair that cannot be compared: the first pair (21:04-21:19) gave 11.4 fps for the baseline and 29.2 fps for the combined build. That gap is the time of day, not the change: the baseline's save loaded Kakariko at night (GPU p50 60 ms) and the combined build's by day, as B found (#2582). Every run's end.png was checked for time of day, and only day runs are compared above.

The combined build is the one installed on the phone.

@stan69b

stan69b commented Nov 16, 2026

Copy link
Copy Markdown
Contributor Author

Rebased onto main, stacked on the rebased #2270.

Adapted to main:

  • BIG_MIN is 256 MB on main's pool-reach design (main no longer has BIG_UNKNOWN);
  • the kind-5 texture address keeps main's vpool_taken;
  • the row-by-row zero fill now runs inside main's clear bookkeeping.

Added two commits:

  • t_gpu_only_addr's case for an address given out before the first mapping now checks that address. Main makes such a pool sparse (vmode 2), so the pool's own range stays in the table.
  • a row for DM_NVN_TEX_EVICT_IDLE in docs/env_switches.tsv.

…k before the commit, so the commit no longer pages the guest's files in from the GPU driver's path, where the M1 iPad froze for good

With the guest's memory in files (the iOS app's default when the game's pool is larger
than its memory), Ocarina of Time on an M1 iPad (8 GB) froze with sound and no picture,
once in Link's house and once at the title movie. A sysdiagnose spindump during the
freeze: the encode thread in res_commit <- gmem_map, IOGPUFamily -> the VM -> apfs
pagein, blocked by an APFS rwlock owned by a launchd background-I/O thread that stopped
4 ms after it and never ran again. Ordinary page-ins of the same files (700,000 in a run)
never hung.

file_wire (nvn_mtl.m): a shared buffer whose pages are file-backed (vm_region_recurse_64:
external pager) is mlocked before it joins the set, and the mlocks are given back right
after the commit, which holds the pages for the GPU from then on. Anonymous memory and
Metal's own buffers are untouched, so nothing changes with the guest anonymous (every Mac
run unless DM_GUEST_FILE=1). Counted in the 300-frame residency line. t_file_wire checks
it (failed before the fix, passes after).

iPad, the same route that froze twice: alive past frame 12,900, 20 fps in the house (GPU
34-42 ms), headroom 5.3 GB, commits under 2 ms per 300 frames. Mac (M4 Air 16 GB, idle)
with DM_GUEST_FILE=1, a route that stalled at 7-37 s a frame before: played through,
frame time p50 16.7 ms, 3.9 GB wired at most.

memory.md "The residency commit froze over the guest's files"; Ocarina of Time's note.

Rebased onto main 0c07813, whose residency changes are queued and applied by the commit outside g_res_mu (0c07813): res_add_at wires a buffer's file pages before it queues the change, and res_commit takes the wired ranges together with the queue, so each commit gives back after itself exactly the ranges of the buffers it made resident; a range wired for a change queued after it waits for that change's own commit.

(cherry picked from commit 2261a38)
…share bytes in a placement heap per 32 MB span, as on NVN: Ocarina of Time no longer runs out of GPU memory going outdoors on an M1 iPad

With the render targets' recycled heaps (rh_texture, 7f50222) every live description in a
GPU-only pool is a Metal texture of its own. On the M1 iPad (8 GB, recommended working set
5,461 MB) that reached 5,184 MB resident at the outdoor save load (544 heaps of 1,384 MB
over 1,455 MB of textures), and every command buffer then failed with
kIOGPUCommandBufferCallbackErrorOutOfMemory.

window_texture (nvn_mtl.m): a texture whose storage lies in a CPU_NO_ACCESS pool (not
sparse, not linear, one sample) is placed in a heap standing for a 32 MB span of guest
addresses, at its NVN offset scaled by 9/8 and rounded to Metal's alignment, if its Metal
size ends within its scaled NVN range, so textures overlap here where they overlap on NVN.
A span's heap is made only once it saves memory; a texture across a span's end tries the
half-offset spans; covered bytes are inherited, new ones zero-filled. Placed textures have
no GPU-optimized contents: with lossless compression, another format's writes over the
same bytes hung the iPad's GPU (kIOGPUCommandBufferCallbackErrorHang by Link's house).
Anything that does not fit takes the usual path (image_texture, then rh_texture).

On only where recommendedMaxWorkingSetSize is under 8 GB (window_wants): sharing a target
pool's bytes corrupted the picture on the Mac in PR seedds#1453 (the game keeps live targets in
the part of the full-size scene target its current resolution leaves unused, which only
NVN's layout makes safe), so larger devices keep each target's own layout. 8 GB devices
have 5.3-5.5 GB of working set, a 16 GB M4 Mac 12,124 MB; the separate heaps needed
5.2 GB at the outdoor save load, sharing 4.3 GB. DM_NVN_WINDOW_ALIAS=0/1 forces it, and a
log line says which way it went. The gfx test Makefile runs every test with it off unless
the test turns it on, so an 8 GB Mac runs them as a 16 GB one does.

Also for reading the set (res_top: the first GPU out-of-memory error, DM_CTL restop, and
once when the set passes three quarters of the working set): the set by the source line
that added each object, the resident pools by raw table / binding, by who gave an address
in them (hle_nvn.c passes the kind: mtl_pool_addressed_by) and by pool flags
(mtl_pool_tag), the GPU-made textures by pool, and the spans' counts.

Tests: t_window_alias (new; 25 checks with the spans on, direct and deferred encoding,
Metal validation; 8 fail with them off, the separate allocations), including the 8 GB rule.
t_image_alias, t_rt_recycle, t_alias_takeover, t_upgrade_alias, t_copy_alias,
t_rt_lifetime, t_pool_chunks, t_addr_known, t_file_wire pass.

memory.md "Textures in GPU-only memory took an allocation per description"; rendering.md's
recycled-heap entry links it; env_switches.tsv.

Rebased onto main's pool and render-target structure: the virtual pool's runs are tagged after
main's one-step mtl_pool_replace (vrun_set); the new pools' tag is set after pool_new_put; the
storage range for res_top is kept on the texture before own_alias_publish (nvn_owner.m); a span's
heap is an NvImageHeap with window set, which main's family-heap search (own_alias_at_locked)
skips and which is freed with its last texture rather than waiting in rh_wait's free list.
rendering.md keeps main's Fix and Check wording and adds the window heap.

Rebased onto main 0c07813: res_add_at records the adding line in g_res_line beside main's queued change (res_q_put), and sets no g_res_dirty, which the queue replaced.

(cherry picked from commit bfa1214)
…edicted sleeps, the waits a sleep ended too late for, how late the sleeps woke and the period: Ocarina of Time makes none, so its slow motion on the M1 iPad is GPU time

Before, the power line counted clock waits only for its two top yielders, so a clock wait on any
other thread was invisible. On an M1 iPad, Ocarina of Time ran at game speed 0.62 in one run
and 0.99 in another with DM_YIELD_CLOCK=0, which pointed at 8bdfcb7's predicted sleep.

dm_clock_top (hle_thread.c), printed by the power report every 300 frames (hle_nvn.c) as
"clock waits up to frame <n>": the two threads with most clock-wait yields since the last
report, their predicted sleeps, how many of those waits had already ended by the first poll
after the sleep (slept through), how late the sleeps woke (mean / max) and the learned period.
No clock wait, no line. No behaviour changes: counters only.

On the M1 iPad, 12 minutes from the title through the Deku Tree (upstream main + this
branch, no switches but the device's own): no line at all, so no thread of the game makes a
clock wait and the predicted sleep never runs. Its slow motion there is the GPU: views that
take 54-67 ms of GPU a frame cannot fit the frame step's longest hold, 3 vsyncs (game speed
0.61, then 0.53), where lighter views hold 20 fps at 34-36 ms.

t_clockwait checks the clause (the thread, 40 predicted sleeps, the waits slept through, a
16.68 ms period, and nothing once no clock wait came); t_pollwait, t_preempt, t_condvar,
t_condvar_old, t_sync_wait, t_system_event and t_notify_sched pass. threads.md "Clock waits
sleep to their predicted end".

(cherry picked from commit 3db7eb5)
…ee's entrance with the guest in files and a 3.2 GB residency set; heavier views are GPU-bound

"For an iPhone or iPad build" under Memory: the device (iPad Pro 11-inch 3rd generation, M1,
8 GB, iPadOS 27.0.1), the memory limit and headroom (7.97 GB of room against the 9 GB pool,
so the guest in files; footprint 2.2-2.3 GB, headroom 5.87 GB at its lowest; working set
5,461 MB, residency set 3.2 GB with the GPU-only spans on), fps and GPU time (20.0 fps in
every window of two 32-minute runs at the Deku Tree's entrance, GPU 34-35 ms, game speed
0.97-1.00; heavier views 54-67 ms of GPU, 11-12 fps and game speed 0.53-0.61; the title and
game over screens 61 and 66-74 ms), no clock waits, no switch needed, and what is open: the
heavy views' GPU time, a GPU hang on an earlier build in the draws of PR seedds#1842's M1 hangs,
one kernel data abort, and PR seedds#1906 for an iOS build on 7ffa63c.

Found on: "Textures in GPU-only memory took an allocation per description"; memory.md's two
entries link the new section. The Open list's "no iOS run" line points at it.

(cherry picked from commit aa82d4c)
…height matches the shape the host asked for gives the picture that shape instead of 16:9

A game that renders a wider or taller picture into larger window textures and crops the window to it (Ocarina of Time: a 2536x1152 crop of 2560x1440 textures at
2.2:1) was presented as a 16:9 picture. present_shape / present_fit (nvn_mtl.m) now take the crop's own ratio when it matches the screen shape mtl_present_screen set
(screen_aspect any), and keep 16:9 for a crop of any other shape. t_present_crop checks a wider crop, a taller crop, a crop of another shape and a 5:4 crop filling a 5:4
canvas on the classic and Metal 4 presents: 120 / 120.

(cherry picked from commit e0209b5)
…e while the game runs, from 0.25 to 6, portrait included

game.py: screen_aspect off / on / any (DM_GAME_SCREEN_ASPECT 0 / 1 / 2); on (Breath of the Wild, Animal Crossing: taller than 16:9, set at the start) is unchanged.
loader.c (screen_any_apply / screen_any_write / dm_screen_view_changed): for an any profile, DM_SCREEN_ASPECT unset or auto follows the front end's view, 1.777 or 0
is 16:9, a number fixes the shape. It writes the state page: +0xa0 the ratio (0 = 16:9), +0xa4 / +0xa8 the width and height factors, +0xac a change count, +0xc4 /
+0xc8 the camera's x / y multipliers (wider than 16:9 keeps the vertical angle, between 1:1 and 16:9 the horizontal one; upright takes the scale of the same screen
turned landscape), tells the present the shape, and on a change pushes the display-change notifications (hle_oe.c dm_display_changed) so the game lays out again.
front_mac.m reports the window's shape 300 ms after a resize settles; front_ios.m the app window's in landscape (upright stays 16:9 for now). settings.tsv: the
Picture shape setting for any profiles (Match window / Match screen, or 16:9), auto by default.

Front-ends: new: front_view_aspect() (front.h) answers the game view's width / height and dm_screen_view_changed(aspect) reports a settled resize; a profile with screen_aspect any (Ocarina of Time) follows them under DM_SCREEN_ASPECT auto, and renders 16:9 until a front end provides them (the loader's weak front_view_aspect returns 0).
(cherry picked from commit cf623ee)
… for matrices and float pairs in guest memory, and a write watch armed from a probe's register

DM_PROBE_FP prints s0-s7 on probe hits. DM_PROBE_FINDMAT=<s>[,<n>] scans the guest heap for perspective matrices and arms the write watch on the n-th at 16:9;
DM_PROBE_FINDF=<s>,<a>,<b>[,<gap>[,<n>]] scans the heap and the alias region's mapped parts for two floats and arms it on one. DM_PROBE_WATCH=@xn+<offset>[+<length>]
arms the watch on that register plus the offset at the first printed probe hit, for objects whose addresses move between runs (Ocarina of Time's layouts in the alias
region); DM_PROBE_XREG=N lets DM_PROBE_X2 dump xN's memory. The watch carries out CAS and single-lane ST1 itself. Found Ocarina of Time's camera copy and HUD
screen size.

(cherry picked from commit 021300a)
… its output size, window textures and camera projection follow the shape, with no bars and no stretch

screen_aspect any, and four stubs as function-matched others of the frame-step rule (patches.py, found on v131072 main):
- output size (main+0x1087f40, the display settings' size setter): the requested size times the shape's factors, capped at 1.5 times the pixels, each side a multiple
  of 8; the crop, the scene's targets and the dynamic-resolution sizes follow. It copies the camera multipliers the size was made with to state +0xb8 / +0xbc.
- window crop (main+0xe9a860, setCrop): a crop beyond the 2560x1440 window textures grows them; the next acquire re-creates them.
- camera copy (main+0x33a8c0 +0x2ec): the camera named "Main" hands its cached sead::PerspectiveProjection matrix here each frame; rows x / y times the multipliers,
  the aspect beside it, in memory and in the registers the frustum code reads after. set(), tanf and the 16/9 literals do not run in play: found with DM_PROBE_FINDMAT
  and the write watch.
- display update (main+0x6502e0 +0x18): flag bit 17 set when the loader's change count moved, so the game recomputes its size and a resized window takes effect.
Wider than 16:9 keeps the vertical angle, between 1:1 and 16:9 the horizontal one, upright the scale of the same screen turned landscape. test_oot_aspect.py runs the
stubs with unicorn (12 tests). Checked on the Mac at six window shapes resized live (iPhone and iPad upright and landscape, 1700x478, 16:9). The HUD is the next commit.

(cherry picked from commit d97bed7)
…instead of a 16:9 layout stretched over the picture

Every eui layout file holds a screen size of 3840x2160 (LayoutResData +0x200, file offset 0x2f8). A screen's init (main+0x773b90) builds its orthographic projection
from it once and keeps it in the screen's uniform block, which the draw copies to the frame's ring each frame (main+0x2d2ba0). Two stubs, function-matched others of the
frame-step rule:
- hud upload (main+0x2d2ba0 +0x4c, after the memcpy): the copy's x / y rows times the HUD's multipliers and the size divided by them, each frame, so a resize takes
  effect at the next one; a capture's block (its own size beside the screen's) is left as it is.
- layout size (main+0x583fd0, the getter): the size the HUD draws with for the game's conversions between the layout space and the screen; the screen's init still
  gets the file's.
The HUD's multipliers are the camera's divided by the largest of them and 1: in landscape the HUD keeps the size it has at 16:9 of the same height or width; upright the
whole 16:9 space fits the width, smaller, nothing cut off. test_oot_aspect.py: 6 more tests (18). Checked on the Mac at six shapes resized live, the pause menu, the
"A Open" prompt and the Kokiri Forest cutscene with its location card.

Left open (game note, Screen shape): eui places panes about the screen's centre and does not anchor them to its edges, so the HUD keeps its 16:9 arrangement in the
middle (in wide shapes the hearts sit at the 16:9 band's edge, upright the HUD sits around mid-height), and full-screen panes (fades, the menu backdrop, 3840x2160)
cover the 16:9 middle only. Moving the edge groups (60x80 nulls at the space's edges) and stretching those panes needs eui's per-frame pane transform, not found yet.

(cherry picked from commit a8fe89b)
…e screen_aspect key, DM_SCREEN_ASPECT for any profiles, the probe switches, and a reference entry for a camera that caches its projection

- Game note: a Screen shape section (the six stubs, the rule for wider, taller and upright, the HUD, what is open: the HUD's edge groups and full-screen panes,
  upright on iOS, the vertical angle upright) and its line under Found on this game.
- docs/reference/rendering.md: a screen-shape stub on the projection setter changes nothing, the camera caches its matrix (find the per-frame reader with
  DM_PROBE_FINDMAT, DM_PROBE_FINDF and the watch armed from a register); the symptom index regenerated.
- dm/games/README.md: the screen_aspect key (off / on / any). docs/env_switches.tsv: DM_SCREEN_ASPECT's any range and auto, DM_PROBE_FINDMAT, DM_PROBE_FINDF,
  DM_PROBE_XREG and DM_PROBE_WATCH's heap+ and @xn forms. docs/settings.md: Picture shape for any profiles.
- docs/agents/game-patches.md regenerated: Ocarina of Time's screen-shape and HUD stubs are function-matched (BINDING rows in its patches.py), and Animal Crossing's
  row names them as the model. docs_patches.py's dry run puts a rule's other functions 4 MB apart instead of 16 MB: with 16 MB the ninth (Ocarina's layout size)
  landed out of a branch's reach of the patch area.

(cherry picked from commit 2f2c543)
…load reads' budget, the census by allocation, and the iPhone 17's death entering Hyrule Field

(cherry picked from commit d07be66)
…ule Field to the castle town, which thrashes under 10 fps

(cherry picked from commit e3193df)
…e 17 thrashed at under 1 fps with 6.19 GB wired: the death is not fixed

(cherry picked from commit 23d12a5)
…rashing 11 minutes in, back on the field after the castle town

(cherry picked from commit 93ff62f)
…re event and once past three quarters of the working set after any commit, and its line gives what each source line holds

The iPhone 17 is ended for proc-thrashing, with no GPU error, so no log of it had a residency
breakdown: the one-time res_top at three quarters of Metal's working set (4,096 MB) was checked
only at the 300-frame line, which read 4,059 MB at most while the set passed 4.4 GB between lines.

- res_commit checks the three-quarters line after each commit.
- A memory pressure warn or critical runs res_top and mem_census, each level at most once a
  minute. Both reports run on a utility queue (res_report): res_commit is called with g_mu held
  on some paths, and the census takes it.
- The residency line adds what is in the set now by the line that added it (adds less removals,
  the eight largest) and each one's change since the last line, so a load's leftovers show.
- The 300-frame line's buffer for it grows from 400 to 1,400 bytes: the upload reads' figure was
  cut off on the phone.

Mac reproduction (16 GB M4, guest in files, DM_NVN_WINDOW_ALIAS=1 DM_NVN_TEX_DROP_MIP=1, the
field save, then four tunnel / Kokiri Forest round trips): the set was 3.46 GB on the field,
4.23 GB after the first load into the forest (the 12288x12288 Depth16 target's own 296 MB heap,
+149 MB of textures uploaded from pools, other targets outside the spans), then 4.26-4.28 GB in
the forest and 4.37-4.39 GB in the tunnel, 5-15 MB more per round trip. The set grows on each
new area's first load and does not grow with going back and forth.

Rebased onto main 0c07813: res_add_at and res_remove count each source line's bytes (rs_live_add) beside main's queued changes and set no g_res_dirty; res_commit takes the set's size after its commit under g_res_commit_mu and checks the three-quarters line after releasing it (res_report takes no lock).

(cherry picked from commit cb57493)
…ency set and whether its pool lives, and textures over a buffer count nothing in the set's breakdowns

- res_bytes: a texture made over a buffer (tex_linear's linear textures over their pool's
  buffer) is that buffer's memory. MTLResidencySet counts it once (measured: an 8 MB buffer and
  31 textures over it read 8 MB in allocatedSize), but res_top, the additions by line and the
  set by line summed each texture's allocatedSize, the whole buffer. Ocarina of Time keeps 31-64
  linear targets over one 8 MB pool (flags 0xa2): the iPhone 17's "line 4926: 64, 512 MB" back on
  the field was memory the set did not hold. The set's own total was always right.
- mem_census adds the set's textures by the line that added them, by holder (live serial,
  finalized serial, pin, sharing table, live or retired descriptor) and by whether the memory
  pool of their storage still exists. Uploaded textures now keep their storage range for it
  (g_tex_up_key, apart from res_top's GPU-made textures).

What accumulates on the Mac reproduction (field, Kokiri Forest, back in the tunnel): textures
uploaded from guest memory (the upload's res_add), 1,176 / 1,713 / 1,935 of them, 467 / 634 /
829 MB, all named by live descriptors of texture objects the game has not finalized, in pools
that still exist. They are the game's own live textures; on NVN they cost nothing beyond their
pools, here each is a Metal copy. Nothing in the host holds one after the game lets it go: 17-23
textures (10-12 MB) are named by nothing. Freeing the copies would be an eviction of host
copies of live textures (serial table, packaged entry, sharing table and pool tables at once),
which is not done here.

Rebased onto main's resource owner (nvn_owner.m): the census asks it who holds a texture
(own_ghost_holds_locked, own_shared_locked) instead of reading its tables.

Rebased onto main 0c07813: res_add_at and res_remove count res_bytes beside main's queued changes, without g_res_dirty.

(cherry picked from commit 29b351d)
…e Mac, the breakdowns' count of textures over a buffer, and the reports at memory pressure

The set grows on each area's first load (3.46 GB on the field, 4.23 GB in Kokiri Forest) and not with going back and forth (5-15 MB per round trip over four). What grows is Metal copies of textures the game keeps live in live pools (467 / 634 / 829 MB); freeing them would be an eviction of host copies, not done. The raw-table-only pools (710-778 MB) stay: no safe rule leaves them out.

(cherry picked from commit 28083ec)
…d through the castle town and Lon Lon Ranch at 6.27 GB wired; guest pools hold 2.1 GB of its set

(cherry picked from commit 0832d01)
…thin 3 s, or any spare at memory pressure, leaves the residency set

The uploaded textures the census found held by nothing (line 3664 [ P]; on the iPhone 17 up to 168, 123 MB) were not left over from a texture ID registered again: an ID's views never own residency (defer_obj_unref), and every base texture is owned by the serial table, directly or through its NvPkg. The census looked up the NvPkg, not its textures. With letters for them (k / K a live / only a finalized serial's packaged texture, e a spare), the Mac route shows every uploaded texture as [kv P] and no re-uploads on pool content change; on the phone the unheld ones went from 40 (6 MB) to 168 (123 MB) as those re-uploads went from 0 to 129. Each re-upload keeps the texture it replaced as the package's spare, resident until the texture object is finalized, which pays only when the CPU rewrites the texture again soon (a movie frame).

spare_trim: at a submission's start (at most every 250 ms) a spare older than 3 s is retired through defer_obj_release, as a spare a re-upload cannot take always was: after the submissions that used it, and only once no serial entry holds it. mem_trim retires every spare and logs them. The report gives the spares held and retired. t_pkg_spare: an idle spare and one at a critical trim leave the set while the current texture stays and resolves, the next re-upload makes a new texture, and a re-upload within the limit still reuses the spare.

Rebased onto main: the spare's note sits beside main's own_note (nvn_owner.m), and the census
finds the packages' textures and spares with own_each_locked.

(cherry picked from commit 1df6607)
…der reaches: 831 of Ocarina of Time's 851 such shaders take an address through a loaded pointer or a loop, and every frame runs about 185 of their draws

Measured, nothing changed in code: the pools the raw pool table lists stay resident. The address of each raw access in the 851 translated shaders that take the table was traced back through their MSL (598 read it through a raw pointer, 233 more through a loop or branch variable, 20 only from buffer words at fixed places); the Mac's field route binds the table about 185 times a frame in every window (raw pool table words at commit).

(cherry picked from commit c680394)
…tures nothing used for 30 s are freed and made again at their next read

On NVN a texture costs nothing beyond its pool; here each uploaded one is a Metal copy, and the game keeps the texture objects of areas it has left (0.6-1.0 GB of the iPhone 17's residency set). mem_trim now frees the packages (NvPkg) no texture ID naming their serials was used by for 30 s, that nothing resolved either, that are not sparse, placed or bound as a view, whose storage the GPU never wrote (gws_owned) and that no pin, sharing entry or takeover holds. Everything naming the copy lets go together: the serials' entries, live and finalized, the storage's sharing entry, the IDs' views, the view cache, and the pool tables, which take the IDs again as a copy at their next use; the texture goes through deferred release after the submissions that used it.

Use: a bind's lookup (tex_fast_rid, not a pool walk's) and a shader's read through a pool, whose bitmap's folded-in bits are now cleared every 10 s so a read sets its bit again (g_tid_used). An evicted ID has its read bit cleared, and a pool walk leaves it the dummy until a shader reads it; a bind makes it again at once. The trim's log says what it freed and why the rest stayed. DM_CTL memtrim asks for a trim on the Mac.

Mac (16 GB M4, the field route, guest in files): two trims on the field freed 481 textures (119 MB) and then 577 (215 MB), the set 3,487 → 3,163 MB; 24 packages were made again between them, and the screenshots after each show the owl's scene whole. t_pkg_evict: the idle copy leaves the set, its entry reads the dummy, the walk does not make it again, a read does; a texture used lately, one the GPU wrote and a pinned one stay; nothing goes without pressure. With the walk's gate off it fails.

On this branch: a freed texture's pool table entry holds its stand-in when it has one
(pool_stand), else the dummy, and a package whose storage took GPU stores (stored)
stays, as a GPU-written one does.

Rebased onto main's resource owner (nvn_owner.m, 96259d4): the packages are found with
own_each_locked, and their serials' entries, live and finalized, go through a new
own_drop_where_locked, which drops each as serial_del does and frees a finalized serial's ring slot
(the walk over g_by_serial and g_ghost it replaces left the slot behind). A pin, the sharing table
(own_shared_locked) or a serial holding the texture (entry_holds) keeps a package as before.

(cherry picked from commit d634521)
…reed at memory pressure, and what stays of the raw pool table's pools

(cherry picked from commit 7374881)
…s before each, and two of the owner's runs ended at the castle

One driven process ran 60 rounds of the castle town and the field with a
memory pressure trim before each load (2.4 hours, 152,019 idle uploaded
textures freed and made again), at most 6.29 GB wired and the set at
4.43 GB. The owner's first run stopped drawing at the castle entrance's
load with the sound on, the residency commit freeze's signs; the second
ended at the castle gate with no report. Both are open in the game note.

(cherry picked from commit c7ebf30)
…r rows in docs/env_switches.tsv

(cherry picked from commit 408e1b4)
…pipelines through the Metal 4 path with the pipeline archive made offline and the hybrid pipelines

Through the MTLDevice, each render pipeline first drawn in a scene state the phone had never
drawn compiled on the submit thread: on an iPhone 17 in Kokiri Forest after the first boss,
about 17 pipelines of about 400 ms each made 8 frames of 0.17-1.26 s (6.0 s in all), every wait
"hybrid off". The archive for applegpu_g18p holds every pair's pulling base (30,690) and a
pipeline per compute shader (4,125): 3,501 MB, 28.5 min of metal-tt on the Mac.

From the experiment commit 7e5d12c6 (the game.tsv lines), on main's key: main has the launcher's
setting (DM_PSO_MTL4) and the fix for pipeline bases missing from the archive (2f131ed, the
experiment's 3af843f3), not this profile's default. The game note's "For an iPhone or iPad build"
says so, and dm/games/README.md's pso_mtl4 row names the game. No shader input changes (pso_mtl4
is no shader_* / nvn_* key).

(cherry picked from commit 36e013e)
RED_ONCE(160) is main's. The warning that a texture which left out its largest level could not be made whole
again now has key 179, past main's highest (174). Frame generation (seedds#2241, seedds#2582) takes 175-178.
…M_NVN_TF_CPU, which the rebase onto main dropped

Two conflicts in docs/env_switches.tsv (iPhone memory 1's DM_NVN_TEX_DROP_MIP row, and the rows of
DM_NVN_MEM_PRESSURE and DM_NVN_UPLOAD_SRC_MB) were resolved by taking this branch's side, which left
out the rows main added beside them. dm/tools/env_switches.py --check now reports what it reports on
main, nothing more.
…ole too, and tex_mtl_replay_ref keeps its name

Main now looks textures up for the replay through borrowed references (tex_mtl_replay, from seedds#1473), and many of
the non-sampling uses this PR makes whole (render targets, image slots, copies, upgrades, MetalFX inputs) moved
to it. tex_mtl_replay goes through tex_mtl_replay_at, which applies tex_undrop like tex_mtl_at. The whole texture
is held by its package (pk->tex), so the borrow stays valid until the fence, as main requires. main's
t_upgrade_alias calls tex_mtl_replay_ref by name, which is kept as a wrapper (line 0).

Tests: t_tex_drop_mip 184, t_upgrade_alias 29, t_pkg_evict 43, t_pkg_spare 59, t_upload_slots 307,
t_upload_src 61, t_copy_alias 126, t_rt_lifetime 9, t_window_alias 25, t_res_absent, t_rt_recycle.
…et one by one with their holders, and a pool of 32 MB or more says what made it resident

(cherry picked from commit 42fc4b3)
…U cannot reach stay out of the raw pool table, so the physical pool behind GPU-only render targets is not wired for the table's sake

(cherry picked from commit 6b5ea9c)
…s of rows, so the zero buffer stays at 4 MB instead of growing to the largest texture zeroed and staying resident

(cherry picked from commit 1829861)
… than its texture, not an eighth, so a large target's heap carries no memory nothing uses

rh_heap made each new heap an eighth larger than the texture it was made for, so that the next steps of a
dynamic resolution can reuse it. On a large target that eighth is resident memory nothing uses: Ocarina of
Time's 12288x12288 Depth16 shadow target (296 MB, alive in every area) sat in a 333 MB heap, and its 4096x4096
targets (64 MB) in 72 MB heaps. The extra is now an eighth up to 4 MB (RH_SLACK): every target up to 32 MB
keeps its eighth, the shadow target's heap is 300 MB.

t_rt_recycle checks a 48 MB target's new heap is at most RH_SLACK larger (30 checks, 0 failed);
t_image_alias and t_window_alias pass.

(cherry picked from commit 5c80ed0)
… are freed every 10 s, not only at memory pressure, so an area's textures leave once the game has left it

A game keeps the texture objects of an area it has left. On NVN they cost nothing beyond their pool; here
each is a Metal copy, and pkg_evict_idle freed the idle ones only at a memory-pressure trim. So each area load
added its textures to the last one's, and on a small device they came back only once the system was short:
Ocarina of Time on the iPhone 17, walking Hyrule Field into Kakariko Village, warned of memory pressure at the
village load with the field's copies resident (the trim then freed 206 MB of them); on the Mac, the second
Kakariko visit held 762 MB of uploaded textures against 435 MB on the first, with pools back at 1,474 MB.

Where Metal's working set is under 6 GB (small_working_set, the rule for smaller textures and for staging
released after each batch), pkg_sweep runs pkg_evict_idle every 10 s at a submission's start, with the same
rules as at pressure (idle 30 s, never written by the GPU, not placed, sparse, a view, pinned or held). What it
frees is made again at its next use, from its stand-in for the frame of a pool read, at once for a bind.
DM_NVN_TEX_EVICT_IDLE=0 / 1 forces it. The system memory line counts what the sweeps freed.

t_pkg_evict checks a sweep frees the idle texture without pressure, leaves the used, GPU-written and pinned
ones, a read makes it again, and the next sweep waits 10 s (53 checks, 0 failed).

(cherry picked from commit 1cfe4ca)
…ookups reach, not whole, so a small buffer bound in a large GPU-only pool no longer wires all of it

Pools of BIG_MIN or more have no buffer of their own: a lookup gets a zero-copy chunk over the 16 MB stride
that holds what it asked, and only what lookups reach is wired (raw global memory still takes a pool whole).
BIG_MIN was 512 MB, set for Mario Kart World's 2.4 GB graphics pool. Ocarina of Time keeps its render targets
in virtual pools over one 305 MB physical pool (flags 0x18c): with the raw pool table no longer naming it
(kind 5, the commit before), one compute shader (f8965bffbdf51d78_b) still binds a 200 KB read-write storage
buffer at an address in it every frame, and that lookup (encode_args_, NVN_RB_SBUFP) made all 305 MB
resident: on the Mac run the pool showed as "not in it, looked up 4, 306 MB". From 256 MB that pool is in
chunks too, and the binding wires about 32 MB of it.

t_pool_chunks (151 checks), t_addr_known, t_upload_src, t_gpu_only_addr and t_file_wire pass.

(cherry picked from commit 125d2a7)
…e first mapping stays in the raw pool table

OoT-fps D-2's case expected the physical pool's range in the table once a virtual pool whose own address
was given out is mapped whole. Main makes such a pool sparse instead (nvnMemoryPoolMapVirtual, vmode 2:
the physical pages are remapped into the pool's reserved range, so the address the game holds stays
valid), and that range is what the table names. The case now checks the address given out.
t_gpu_only_addr: 12 checks, 0 failed.
…rgets, the large targets' heap slack, the zero buffer and the small devices' sweep of idle uploaded textures; the chunk threshold in nvn-objects.md; Ocarina of Time's Kakariko holders

(cherry picked from commit 848bb3e)
…oot-build-vis: residency set 3.5 → 3.1 GB, wired 5.3 → 4.9 GB, same frame time; the sweep's 11 ms pass after an area load is open

(cherry picked from commit 28b3e60)
OoT-fps D-3 added the switch without a row in docs/env_switches.tsv, so env_switches.py --check listed
it among the switches without a meaning.
@stan69b

stan69b commented Nov 18, 2026

Copy link
Copy Markdown
Contributor Author

Rebased onto main 31b537f, stacked on the rebased #2270. All ten of this PR's own commits applied with no conflict.

Checked on the rebased tree: the Mac host builds for Ocarina of Time. Passing: t_gpu_only_addr 12, t_pkg_evict 53, t_zero_colour 30, t_rt_recycle, t_tex_drop_mip 184, t_sparse_tiles 4278, test_docs and test_env_switches; the symptom index is current. Not run: a game, and regress.py (no Ocarina of Time libraries for main's chain 63853cc4c4e3 on this Mac).

@stan69b
stan69b force-pushed the pr/oot-fps-d-memory branch from d9a5b1f to 91b6d10 Compare November 18, 2026 10:57
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

docs Documentation game: 01006F8002326000 Animal Crossing: New Horizons game: 0400486024DEC000 A game host The Horizon host: SVCs, services, threads, memory (dm/host) ios The iPhone and iPad app (dm/ios) mac The Mac front end and app (dm/mac, front_mac.m) nvn NVN on Metal and its tests (dm/gfx/nvn, dm/gfx/tests) rewriter The NSO rewriter and per-build patches tools Tools and scripts (dm/tools, scripts)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants