[fmilioni]

What

In Ocarina of Time (0400486024DEC000), the ground opens in holes after walking a distance: loading a save in a cave, walking out and on, the terrain starts missing (black holes, water and sky showing through), and walking back into the cave shows it broken too. Saving and loading makes everything right again, until the next areas stream in.

Cause

tex_cpu_content takes an uncompressed 2D texture from its storage at first use only in a pool the GPU has not written (pool_t.gpu_written): once anything in a pool had been a render target, a clear's or a copy's destination, or a shader image, no uncompressed 2D texture of that pool was taken from its storage again.

Ocarina of Time keeps its terrain tiles' height maps (260x260 R32F) and blend / hole maps (260x260 RGBA8, one and two layers) in the same CPU_CACHED | GPU_CACHED pool (flags 0x24) as the tiles' normal maps (260x260 RG8), which the GPU draws. The CPU fills the height and blend maps before nvnTextureInitialize, with no flush, so neither tex_dirty_upload (it stamps at registration) nor the flushed-range fill sees the write. After the first normal map was drawn, every tile streamed in became a GPU texture of zeros. A reload hid it because the area's tiles were read again before the first normal map of the session was drawn.

A diagnostic line at GPU texture creation (storage holding data, made as a GPU texture) showed exactly those textures: 260x260 format 0xa and 260x260x1/x2 format 0x25, pool flags 0x24, gpu_written 1, not flushed, about 25 seconds into the walk.

Fix

The decision is made per address range instead of per pool (nvn_mtl.m):

• The host keeps the ranges a render target, a clear, a copy into a texture or a shader image is recorded over (mtl_tex_gpu_written, gws_span), dropped with their pool. It replaces mtl_pool_gpu_written at the same seven sites, and pool_t.gpu_written goes.
• tex_cpu_content refuses an uncompressed 2D texture only when the GPU wrote its own storage.
• Storage reused for a texture the CPU fills is told from storage the GPU still owns by page protection: each range keeps the dirty-page generation of its last GPU write and has its whole pages protected, so a CPU write there afterwards makes the storage the content again. A texture taken that way becomes a GPU texture at the next GPU write there (cpu_unc_drop, now triggered by those ranges instead of a pool's first write). Only whole pages count, since a range's first and last pages are shared with whatever lies beside it.
• Reference entry Uncompressed storage beside storage the GPU writes, the previous entry's fix updated, the game note and the symptom index.

Related pull requests

• The Legend of Zelda: Ocarina of Time (0400486024DEC000): renderer, shader and pipeline archive fixes through the Forest Temple #1590 fixes the same symptom with a size rule: it takes 260x260 and 68x68 textures from their storage even in a pool the GPU writes. This change covers that case for any texture size and any game, so that part of The Legend of Zelda: Ocarina of Time (0400486024DEC000): renderer, shader and pipeline archive fixes through the Forest Temple #1590 is no longer needed if both land.
• A registered texture the CPU rewrites after its first use is kept as the GPU's only once the GPU has written it (Ocarina of Time's flat blue terrain holes) #1558 is a different, complementary case: textures the CPU rewrites after their first use, which nvn_ft_poll dropped because mtl_tex_gpu_owned took render-target usage for GPU ownership. Here the CPU writes before the first use, a path A registered texture the CPU rewrites after its first use is kept as the GPU's only once the GPU has written it (Ocarina of Time's flat blue terrain holes) #1558 does not reach. The two do not overlap.

Tests

• In game on the Mac (M5 Max): the same route (cave save, walk out and far, back into the cave). Before, the ground opened within the walk; with the fix the ground stays whole, confirmed by eye, and the log shows the 260x260 R32F height maps taken from their storage. Frame time unchanged (p50 about 20 ms), no new red line.
• t_cpu_storage: 40 checks, 0 failed. New cases: a texture beside a GPU-written texture in the same pool is taken from its storage; one over storage the GPU wrote and the CPU then rewrote is taken, and becomes a GPU texture at the next GPU write there.
• dm/gfx/tests: every test of the run list passes except t_nvn and t_gfx_suspend (they do not link on main, fixed by The graphics run list passes on main again: t_nvn and t_gfx_suspend link, t_fuse_check checks its kept target by serial #1578) and t_fuse_check (2 of 10 checks fail on main as well).
• lint_c.py tidy (LLVM 23.1.4) on nvn_mtl.m, hle_nvn.c, t_cpu_storage.m: no new finding; the 3 file/check pairs above the baseline in nvn_mtl.m are the same on main.
• test_docs.py: pass.

regress.py

Games: Super Mario Bros. Wonder, the only local build with a route that runs the NVN texture paths. Breath of the Wild has a route but its local build is on another chain. Ocarina of Time has no route; it was checked by hand above. Wonder never reaches the changed path (neither run logs a texture taken from storage), so its run shows no collateral change, not the fix. Unchecked: Mario Kart World, the game the previous per-pool rule was found on (its terrain patches lie in a pool the GPU does not write, which the range rule treats the same way), and the other profiles with tex_dirty_upload.

regress.py check (full): PASS

Baseline 88c7e03 88c7e03, candidate 731096b 731096b3615a; Apple M5 Max, macOS 27.0.1, Xcode 27.2; 743.7 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
Super Mario Bros Wonder 010015100B514000	PASS	16268/16268 → 16268/16268	0	0	0	0 / 0	ok	59.7 → 59.7	20.24 → 21.82	2503 → 2528	None → None	0

Super Mario Bros Wonder 010015100B514000: PASS

• screenshots (s: dHash bits / RGB diff / baseline noise): 50: 2/0.68/0, 58: 3/0.69/0
• baseline: exit None, first frame 0.8 s, max frame 3832, reached True, prepare None s, prebuild 82.3 s (18300 built, 0 failed), fps 59.7, p50/p99 19.96/20.24 ms, peak 2503 MB
• candidate: exit None, first frame 0.8 s, max frame 3846, reached True, prepare None s, prebuild 91.7 s (18300 built, 0 failed), fps 59.7, p50/p99 19.98/21.82 ms, peak 2528 MB
• time: chain 170.9 s, smoke 572.6 s

[lunks]

Thanks for this, and for the careful route test. #1390 (open, from our fork) fixes the same symptom the same way: GPU-written storage kept as address ranges instead of per pool, so a pool holding both kinds no longer leaves the CPU-written textures at zero. Worth a look before both land, since they touch the same code (mtl_tex_gpu_written, tex_cpu_content, cpu_unc_drop) and will conflict.

One idea in yours that #1390 lacks: protecting the pages of a range, so a later CPU write to reused storage makes the storage the content again. #1390 decides that case with gpu_holds and by dropping the range. The two are worth comparing on the reuse case.

[fmilioni]

Thanks for pointing to #1390. I missed it when I searched for related PRs before opening this one, and it has the same core idea, earlier.

I measured the reuse case on Ocarina of Time. A diagnostic counter counted every uncompressed texture taken from its storage over storage the GPU had written, where the CPU then wrote again: that is, every texture a range rule without a CPU-rewrite check would refuse. Same route as before: load the cave save, walk out a long way, walk back in. About 9,900 frames.

• 150 textures taken from their storage, 20 of them (13%) over storage the GPU had written.
• 10 of those 20 are terrain maps: 3 height maps (260x260 R32F) and 7 blend / hole maps (260x260 RGBA8, 1 and 2 layers). With ranges that are never cleared until the pool goes, each would come out as zeros, a hole in the ground.
• The other 10 are the tiles' RG8 normal maps, which the GPU draws right after. They become GPU textures at that draw either way.
• The reuses come throughout the walk, not only at load, so the count grows with the distance walked.

So tile storage does move between GPU-drawn and CPU-filled textures in this game. A range has to stop counting once the CPU writes it again, which is what the page protection in this PR does.

Happy to rebase this onto #1390 if that is easier to review: its range table, with this PR's page-protection and re-stamp on top. Or the other way round. Your call with the maintainers.

[lunks]

Thank you for the numbers: 10 terrain maps in 20 reuses over a walk is exactly the case to get right. Yes please, rebasing your page protection and re-stamp onto #1390's range table would be welcome; one range table is easier to review than two. I'll check the reuse case against #1390 on our side too.

[seedds]

Landed as e2b76d4, with you as co-author. Thank you for the diagnosis, the route test and the reuse-case numbers: the page protection that lets storage go back to the CPU is what made this the right fix.

Changed on top of your branch:

• Ranges do not merge. A GPU write over part of a range re-stamped the whole merged range (in gws_add, and in gws_rewritten for a write inside a range), so a CPU rewrite elsewhere in it was forgotten and a texture made there later came out as zeros again. A GPU write now cuts the ranges it overlaps (gws_set), and the parts outside keep their own stamps.
• Storage the CPU cannot write gets no range (a CPU_NO_ACCESS or virtual pool). tex_cpu_content takes no texture there, and most render targets live there, so they are no longer protected or looked at.
• A range keeps its dirty-page handle (nvn_dirty_since_cached), so the check at each render target, clear and copy no longer scans every registered pool. In tex_cpu_content, the locked range check now runs after the cheap flag checks.
• Two more t_cpu_storage cases (44 checks), and an open limit in the reference entry: GPU writes are stamped when recorded, so a command buffer submitted again does not stamp them again.

Checked on an M4 Pro:

• Ocarina of Time, Kokiri autosave and a walk: the 260x260x2 blend maps and a 260x260 R32F height map are taken from their storage, none on main. 433 CPU-written textures alive against 270, with the same frame and GPU time.
• Minecraft Dungeons II, menu to first control: the same picture and frame time. mprotect takes 44.7 ms over the run against 5.4 ms, about 11 µs a frame.