[MartinBouteruche]

Draft, for discussion. Raw global memory (shaders reading through an address they loaded from memory) read at Metal's own GPU address, with no pool table lookup. Opt-in per game with a new profile key, shader_raw_direct, set only for Ocarina of Time. Every other game's jobs, shaders and host behaviour stay as on main.

Why

On an M1 Pro, Ocarina of Time is GPU-bound and latency-bound: every limiter is low, and its raw-memory compute shaders run at 384 threads per threadgroup. The lookup (2 MiB hint plus a 13-step binary search) holds registers across every raw access. Measured offline on the game's 62 starved compute shaders (maxTotalThreadsPerThreadgroup):

variant	threads / threadgroup
lookup as on main	384
lookup out of line, looped search	384
2 MiB window table instead of the search	~490
address used as is (this PR)	~560

What it does

• Host (hle_nvn.c, nvn_mtl.m, when mtl_gva_on()):
  • NVN hands the game Metal's own GPU addresses: a pool's no-copy buffer gpuAddress plus the offset.
  • A large chunked pool gets one extra buffer over all of it that only provides the addresses. It is made resident once raw memory may reach the pool.
  • Every address the game passes back at an NVN entry point is mapped to the CPU through a table of GPU ranges sorted by address.
  • The pool table stays, with GPU ranges and a delta of 0, for residency and the write log.
• Translator (GlobalToStorage.TryGenerateRawDirectOp, through IGpuAccessor.QueryHostRawDirect and the job's raw_direct):
  • A raw access is a pointer built from the address's two words. A 64- or 128-bit load stays one vector load.
  • Loads have no check: the GPU reads 0 at an unmapped address, as a failed lookup returned, and any branch cost the registers back.
  • Stores and atomics outside macOS's GPU address range are dropped. They log their 2 MiB chunk, modulo the log's bits, in the write log.
• Diagnostics that established the safety, kept as switches:
  • DM_NVN_GPUVA_DIAG: what the pool table holds.
  • DM_NVN_GPUVA_SHIFT: hands out every GPU address moved into an unmapped range and counts CPU accesses through one.

Evidence

All measured on an M1 Pro (32 GB) during development on a branch with this change:

• Address width: Metal's pool buffer addresses stayed below 2^37 (0x15_0000_0000 to 0x18_cf50_a000 after 10 min).
• No address mixing: with DM_NVN_GPUVA_SHIFT, OoT made no CPU access through a GPU address and handed back no CPU address as a GPU one, over 9.8 M addresses handed out.
• Long run: 22.5 M Metal addresses handed out over 5 min, none of them a CPU address, no new [RED] line, picture correct.
• Speed: Kokiri Forest at 854x480, same spot, MetalFX upscaler, against the lookup build of that time: GPU 39.4 → 27.4 ms, frame 33.2 → 23.6 ms.

Not done yet (why it is a draft)

• No fresh A/B on current main: the numbers above come from my development branch (2026-11-07), not from a bench.py run of this exact commit against main.
• No 5-game regression run (regress.py check): the key is off for every other game, and test_dmsh_raw_last.py (main's lookup test) passes unchanged with this translator, so their translation should be byte-identical. regress.py chain on a couple of games would confirm it.
• Untested on sparse memory pools: games with sparse pools (Donkey Kong Bananza) have not run with the key. A sparse pool whose pages are not mapped at its GPU address would get its CPU address handed out (a [RED] line says so), and its raw accesses would read 0.

Tests

• test_dmsh_raw_direct.py (with DMSH_TEST_XLATE): helper shape, and GPU reads of three Metal buffers through their own addresses, scalar and 128-bit.
• test_dmsh_raw_last.py, test_dmsh_ampere_mem.py, test_dmsh_meshstage.py, test_nsp_chain.py and test_docs.py pass.
• test_env_switches.py fails as on main: DM_NVN_CUT_FIRST, DM_NVN_RT_RECLAIM, DM_NVN_VC_WAYS, DM_NVN_BC_ALIAS.
• Graphics tests (make -C dm/gfx/tests run): same results as main. t_pool_chunks, t_nvn, t_gmem_words and t_geometry now check both modes: with the key off (GAME=010015100B514000) they run main's checks unchanged; with it on (GAME=0400486024DEC000) they run the direct-address ones. Writing them turned up two host fixes, included here:
  • A large pool's address buffer is made with pool_buf, so one made over a write-protected page still takes the GPU's writes (issue GPU copies into a pool chunk get lost if its pages were write-protected (LEGO Star Wars text garbled) #1591). This is checked by a new case that fails without the fix.
  • gmem_commit_patch reads its lag statistics before the table rebuild, so lagging words are no longer counted as older.

Questions for reviewers

1. Is a per-profile opt-in acceptable as a first step, or should this wait until it can be on for every NVN game?
2. Does anyone have a game with sparse memory pools on hand to try shader_raw_direct 1?
3. Could someone with an M3 or later run OoT with and without the key? Those GPUs allocate registers dynamically, so the gain may be smaller there; I only have the M1 Pro.

Docs: a new reference entry in docs/reference/shaders.md ("Raw global memory read through Metal's own GPU addresses"), and the key's row in dm/games/README.md.

🤖 Generated with Claude Code

[lunks]

Data point from an M5 Pro (24 GB), Ocarina of Time v131072. We ported this PR onto our tree and read maxTotalThreadsPerThreadgroup from the compiled pipelines of the 731 compute shaders that read raw global memory: 584 compile on our tree (147 don't, with the key on and off alike). All 584 report 1024 with the pool table and 1024 with shader_raw_direct, so the register-pressure limit the PR describes (384 → ~560 on an M1 Pro) doesn't show on this GPU. The ALU cost of the lookup is not measured and nothing was booted with it.

Separately, in a compute and an object/mesh pipeline, reads at null, 0x100, an unmapped hole, a stray CPU address and an address above 0x70_0000_0000 returned 0 with no error, and stores there completed. One note on the store window: a fresh process's first Metal buffer got a GPU address of about 1.1 TB, outside 0x10_0000_0000..0x70_0000_0000; we have not looked at where the game's own pools land.

[dpadr]

Data point from a MacBook Air M2 (10-core GPU, 16 GB), macOS 27.0, Ocarina of Time v131072.

Build: this PR (shader_raw_direct 1) ported onto our OoT tree (base 7f50222, plus #1902 and #1897), chain cd098f1631bd, with a full shader rebuild. Handheld, 1440x810 main pass (dynamic resolution off), MetalFX upscaler, frame-rate hold off, target 60. Each run walks a route through Kokiri Forest.

Speed (paired A/B, interleaved runs, windows with the CPU clock below 2.9 GHz excluded; 5 runs on A, 7 on B). Caveat: A isn't exactly B minus this PR. B also carries:

• HFMA2 rounds once to half, as Ampere does (chain change) #1902 / HMMA with an f16 accumulator rounds once per 8 products, as Ampere does (chain change) #1897 (HFMA2 / HMMA rounding);
• AV1 on dav1d decodes frames in parallel, each picture with its packet's timestamp, outside the decoder lock #1377 / AV1 pictures by the movie's clock: a game slower than its movie skips late pictures instead of playing the movie slowly #1379 (movie decode and timing; no movie plays on the route);
• Ocarina of Time (Switch 2): GPU-written texture ranges fix the terrain holes; opt-in texture release saves ~2.3 GB; a page on playing it #1447 (texture release, switched off with DM_TEX_RELEASE=0);
• an archive-index port.

Of those, only #1902 / #1897 change gameplay shaders, and they are rounding fixes. Most of the difference should be this PR, but it isn't isolated.

	A (without)	B (with #1833)	Δ (95 % CI)
frame p50	32.72 ms	29.45 ms	−3.27 ms [−4.51, −2.63]
frame p95			−3.84 ms [−7.28, −2.35]
GPU span p50	30.20 ms	26.62 ms	−3.58 ms [−4.35, −2.49]
footprint			+0.04 GiB

[gpushift] NVN hands out Metal's GPU addresses (shader_raw_direct) was present in every run with the PR and absent in every run without it.

Reach: in a profiled gameplay frame, 0 of the 272 shaders (fragment, compute, task, mesh) still call the pool lookup. We matched on the lookup helper's signature. On the build without the PR, some of the same shaders did call it.

What unchecked reads do on the M2. One-thread probe through a 64-bit address; every command buffer completed with no error and no page fault:

• null, a CPU address, unmapped GPU ranges, just past a buffer's end, and a freed range not yet reused: all read 0;
• a freed range that a new buffer took (Metal reused it at once, for the next buffer of the same size) reads the new buffer's data, whether or not that buffer is resident in the pass.

So a stale pointer into a freed pool would read another pool's data rather than 0. That differs from the lookup only when Metal reuses a GPU range that the guest hasn't.

Stale-pointer check: two gameplay runs with DM_NVN_GPUVA_SHIFT=1 and the watchdog on: 0 hangs, 0 faults, 0 watchdog kills, 0 [RED] lines. A further gate run on the promoted build was also clean. These runs don't cover long sessions with heavy pool churn. Kokiri Forest's picture matched the build without the PR.

We now use it as our daily build for OoT on the Air.

[dpadr]

Follow-up to my comment above, on uncraftablexd's point about the fixed store window. On the M2 Air (macOS 27.0), every OoT pool buffer sat inside the first window: the [gpushift] GPU address table line ranged from 0x15_0006_8000 to 0x18_689d_0000 (4,537 buffers at the peak) across all our runs, within [0x10_0000_0000, 0x70_0000_0000). So no raw stores or atomics were dropped in our A/B, and the foliage drew normally; the picture matched the build without the PR. The −3.27 ms holds for the M2.

It agrees with the M4 Pro report, though: the window depends on the Mac, so taking its bounds from the host's address table instead of a literal would make the result portable.