[roandegraaf]

What and why

Symptom. In The Legend of Zelda: Ocarina of Time (0400486024DEC000, v131072) on the Mac, after several area changes with dungeon entries and exits the ground turns into crossing stripes ("plaid"), tile by tile, and stays that way until the game is restarted. Loading a save alone does not bring it. This is one of the wrong-terrain kinds reported in #1865 (refs #1865; it does not claim the others).

Cause. On the hardware a render pass, a texture clear or a copy into a texture writes the texture's storage, and a game may read it there. The host wrote that storage only for textures it uploads from their storage (Render passes into textures uploaded from their storage: Tears of the Kingdom's terrain normal maps, which a flush makes CPU-written).

Ocarina of Time has the same terrain defragmentation (SeqExecuteDefragmentationForTexture: memcpy to a new address in the pool, then the texture is re-created there) but never flushes its normal tiles (260x260 RG8, 9 levels, a CPU_CACHED | GPU_CACHED pool). They stay GPU textures, so their drawing lived in the host texture alone and the memcpy moved zeros. The texture made at the new address was then taken from those zeros: a zero normal.

How it was shown, not guessed: a 32-byte tag written into each drawn normal tile's storage was later found at a different address 172 times in one play session (the earliest 12 frames after the tile was drawn, half after about 1,290). In the frame that showed the stripes, 42 of the 57 registered normal tiles had been made from storage holding a copied tag and otherwise zeros, 16 of the 18 bound to the terrain draws among them.

Fix (every game, no profile key). What the GPU writes into a GPU texture whose storage could be its content is read back into that storage, through the existing mirror_readback path:

Part	What it does
tex_storage_gpu	Admits an uncompressed 2D texture that tex_storage_ok admits (no depth, display, video-decode, COMPRESSIBLE, IMAGE, LINEAR, multisample or buffer texture; a pool the CPU can access, not virtual)
gsb_mark	Render passes, texture clears and buffer/texture copies mark the level, slices and region they write, by storage range
gsb_flush	Reads the marks back once at the end of the submission, so a level written in several passes is read once
Cost bound	A level written within the two frames before waits until two frames pass without a write: a baked tile is read with no delay, a target drawn every frame costs two readbacks in all, not one a frame
mirror_rb_own	Lands only in storage that is still that texture's and the GPU's (its recorded span, not taken, no CPU write since); then stamps the span and the registered texture's entry again, so the host's own write is not taken for the CPU's and the texture stays a GPU texture

tex_storage_dst is unchanged, and the new kind never uses the CPU mirror of a copy, g_mrb or g_abs. One addition to the existing path: a texture clear of a texture uploaded from its storage is now read back as its render passes are. DM_NVN_GPU_STORAGE=0 turns the new readbacks off (to measure).

Reference entry with the open points: docs/reference/nvn-objects.md, "GPU textures in storage the CPU can read". Game note line under "Found on this game".

Checked

• Tests (on this branch, base 04811a63, M4 Pro): make -C dm/gfx/tests GAME=0400486024DEC000 run exits 0. New cases in t_cpu_storage (138 checks) and t_readback (gpu_storage, 175 / 176 cases); with DM_NVN_GPU_STORAGE=0, 10 and 5 of them fail. dm/tools/tests/test_docs.py and test_env_switches.py pass.

• Games run: Ocarina of Time 0400486024DEC000 v131072, Mac.

  • Before enabling, a count of what the rule would read on a route of one load and three reloads (8,500 frames): only the normal tiles, 1,099 level readbacks in 20 frames, 72 levels / 1.4 MB in the worst frame. No other texture of the game is reached.
  • With the fix, a windowed play session with dungeon entries and exits (7,800 frames): no stripes. 85 normal tiles were made from storage the game had copied, none with an empty level 0 (153 such copies held only zeros before); no landing was refused; frame times as before.

• Base of the gameplay runs, please read: they were made on a local tree at chain 3510ea767778 (an older main with PRs Ocarina of Time takes the launcher's Render scale: the 3D views at that fraction of the game's own size, the dynamic resolution held at its top level (Kokiri Forest docked at 0.75: GPU p50 15.77 → 14.31 ms, 60 fps held) #1903, Drag x Drive (Switch 2, 040041601D83A000, v196608, SDK 20.5.6) plays on the Mac with a pair of Joy-Con 2s at the game's own 30 fps: its profile, note and table row (it needs PR #1609 to boot, and PR #1921, the first commit of this branch) #1944, The game's compute dispatches with no game barrier between them run side by side (profile key dispatch_overlap, on for Ocarina of Time): Kokiri Forest GPU p50 15.63 → 14.76 ms #1901, A draw that writes depth and samples its own depth attachment reads a copy of it: Ocarina of Time's light-blue dashes over the rock at Death Mountain Trail's cave entrance are gone #1917, The controller applet's stand-in runs on the big host stack: Drag x Drive opened it from a game thread with too little stack for its log lines (SIGBUS in fprintf under focus_sync) #1943 and nn::hid::EnableUnintendedHomeButtonInputProtection is answered by the host and logged: Drag x Drive no longer crashes at sdk+0x63ce10 as player 1's Joy-Con 2 joins #1921 merged locally), with my own variant of the sliver fix that A GPU-written span's sliver inside a texture does not make it the GPU's: Ocarina of Time's terrain tiles no longer vanish or show another tile's surface (#1566) #1920 has since landed on main. For this PR the change was ported onto current main (chain 39eb2f781d07) and the landing guard adapted to main's gws_cpu_since. On this exact branch only the unit tests ran: I have no shader library for the new chain, so the game was not replayed on it.

• Devices and OS: MacBook Pro M4 Pro, macOS 27.2. No iPhone or iPad run.

• regress.py: impact names Breath of the Wild, Tears of the Kingdom and Pokémon Scarlet through the shared NVN entry points (render targets, clears, copies). check --games was not run: Ocarina of Time is the only game built on this Mac, and it has no smoke.tsv. What the change can reach elsewhere, from the notes:

  • any uncompressed colour target in a CPU-accessible pool without COMPRESSIBLE or IMAGE gets one readback at its first write and one when it stops being written. The Great Ace Attorney Chronicles (1920x1080 targets in a CPU_CACHED pool) is the one I would count first;
  • Tears of the Kingdom's terrain tiles and its four per-frame targets stay on the existing path;
  • Mario Kart World's terrain patches are CPU-filled and are reached only if the GPU also draws into them;
  • Xenoblade Chronicles 3's documented cases are 3D textures, which the rule leaves out.

  A run on those by someone who has them would be welcome; the switch above gives the before/after.

• Measurements: Ocarina frame times unchanged in the routes above (the readbacks happen only in the frames tiles are baked).

Docs

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

[akratch]

This is a strong lead for the persistent plaid terrain seen in our OOT playthrough. Our earlier terrain regression began with CPU-filled content; it did not establish the GPU-generated normal-map → backing storage → CPU relocation direction you traced here. Thank you for documenting that distinction and the exact-branch gameplay limit.

Two additional synthetic cases would help make this safe to take generally. These are source-review concerns, not claims of failures reproduced in our gameplay:

1. A valid CPU relocation immediately after the second completed submission. Write A, wait, advance one frame, write B, wait, then memcpy the backing storage and recreate/sample the texture at the new address. The current hot-level policy deliberately leaves A there until the quiet period; the repeated-frame test asserts that stale value. This is an explicit documented limitation, but it means submission completion alone does not provide storage visibility for a legitimate copy after a hot write.
2. A different GPU writer over the same storage while an old hot entry waits. Make A hot, then write that range through an IMAGE or CPU-uploaded texture B excluded from tex_storage_gpu. Check that A cannot later land over B after the quiet period. gsb_mark cancels overlaps only when the new writer itself passes tex_storage_gpu, while mirror_rb_own checks the exact range, taken, CPU stamps and liveness without requiring the writer generation/serial that scheduled the readback. Pool removal and address reuse deserve the same oracle. A GPU pixel result after recreation is preferable to checking only mark bookkeeping.

For our integration we are holding this change separately until those visibility/ownership cases are covered. We are not proposing a full-size stand-in, blanket texture flag change or lower rendering resolution as a substitute.

[seedds]

Landed reworked in 6c3aeb3, with you as co-author. Thank you: the tag in the storage made the cause certain, and the diagnosis, the tex_storage_gpu rule, the hook points in render passes, clears and copies, the tests and the docs are all yours and kept.

What changed is how the drawing reaches the storage. Instead of a CPU readback when the submission completes, the GPU writes it: after each render pass, texture clear or copy into such a texture, gsb_store copies the written region from the host texture into the frame arena and swizzles it into the pool's buffer with a new swz kernel (dm/gfx/msl/deswz.metal, the inverse of deswz). It is in the same command buffer, so it is in the storage before any fence after the write, as on the hardware. That removes:

• the GSB_QUIET wait and the race it brought (a copy within two frames of a repeated write got the older content): every write is now in the storage when its fence signals;
• the late landing and its guards (mirror_rb_own, the compare after writing, the restamp under the registered textures' lock): nothing lands after the game could have reused the storage. GPU writes are not seen by page protection, so the storage stays the GPU's without a restamp.

akratch's two cases are tests in t_cpu_storage now: a write the frame after another is in the storage at once and a memcpy right after it gets it; after the game reuses the storage, nothing of the older texture lands over it however many frames pass, and a texture made there holds the CPU's bytes. Also covered: a partial region, and every level of a 260x260 RG8 tile with 9 levels.

Checked on an M4 Pro: make -C dm/gfx/tests GAME=0400486024DEC000 run exits 0 (t_cpu_storage 136 checks, t_readback 204 cases; 9 and 5 fail with DM_NVN_GPU_STORAGE=0). Minecraft Dungeons II, title to first control, three on/off pairs: about 470 regions (116-125 MB) stored while loading, about 280 (47 MB) entering the level, none in play; 60 fps either way, the same picture. The power line now has [nvn] GPU texture storage up to frame … with the count.

Not run here: Ocarina of Time on this design (the build here has libraries of an older chain). A play session with dungeon entries and exits on current main, and a count of the GPU texture storage lines, would be very welcome from you; DM_NVN_GPU_STORAGE=0 gives the before.

Closing this PR, as the change is on main.