[nafields]

Stacked on #1482, which is stacked on #1391. Only the last commit (cddc1c0) is new. Happy for it to be folded into either one instead.

What and why

Symptom. On a 16 GB M2 Pro, Ocarina of Time with every pool resident (DM_NVN_GMEM_ALL=1) kernel-panicked the Mac at 10,463 MB wired, with 48 MB free and 3 GB compressed. That was under #1391's 95% stop (11,517 MB of a 12,124 MB working set), so the guard never tripped.

Cause. GPU memory is wired out of the same RAM as everything else. On a 16 GB Mac the system can run out before the residency set reaches Metal's working set, and the working-set side can't see that, whether it counts currentAllocatedSize (#1391) or the set's own size (#1482).

Change.

• guard_sys_tick, on A GPU memory guard before each residency commit stops the game instead of freezing the Mac #1391's 100 ms timer, reads kern.memorystatus_level (available memory, free plus reclaimable).
• It raises the guard's level below a margin (stop) or below twice the margin (evict).
• The margin starts at DM_NVN_SYS_MARGIN_MB (default 1024; 0 turns this side off) and grows by 512 MB, up to 4 GB, at each memory-pressure warning.
• The stop line says which side tripped.
• The working-set side is The GPU memory guard reads the residency set's size, not currentAllocatedSize (on #1391) #1482's, unchanged. Our first version also switched it to the set's size; that was the same as The GPU memory guard reads the residency set's size, not currentAllocatedSize (on #1391) #1482 and is left out.

The guard's reference entry in docs/reference/memory.md has a paragraph on this, and env_switches.tsv lists the switch.

Checked

• Tests: check_t_guard_sys (new, 8 checks, 0 failed); make -C dm/host GAME=0400486024DEC000; test_docs.py; env_switches.py --check.
• Host tests on this branch stop at t_nro, which doesn't link (_mtl_present_screen). That comes from The GPU memory guard reads the residency set's size, not currentAllocatedSize (on #1391) #1482's base, not from this commit, which touches only nvn_mtl.m, the graphics test Makefile and its new test.
• Game: Ocarina of Time (0400486024DEC000, v131072), runs to f7,500 on an M2 Pro 16 GB with The GPU memory guard reads the residency set's size, not currentAllocatedSize (on #1391) #1482:
  • the guard no longer stopped at the Kokiri load;
  • the system side evicted once, at 12% available (1,966 MB left);
  • the runs stayed at 18% or more available, wired at most 8.8 GB.
• After the panic above, game runs on 16 GB Macs used this side as their safety net. It hasn't been tried on 8 GB or 24 GB+ Macs, or on iOS, where the system's own footprint limit comes first.
• regress.py check wasn't run: only Ocarina of Time is available here.

Docs

• Reference entry updated (docs/reference/memory.md), docs_symptoms.py run
• No chain tool changed
• No game files, keys or data extracted from a game in the change or the attachments

[nafields]

Rebase status: this PR's own commit (the system-memory side, cddc1c0) is unchanged. It conflicts with main only through its base: #1391's guard commit conflicts with main's new GPU-lost alert (5636e7a, #1332), since both reshape the same front-end alert in front_mac.m / front.h, and in one spot of nvn_mtl.m. That merge is #1391's to make. Once #1391 (and #1482 on it) is rebased onto main, this commit goes on top again without conflicts of its own.

[AmateurWizrd]

Five faults in the guard as it stands at cddc1c0f (this PR with #1391 and #1482 under it). They came out of a review of a port of it and I checked each against this head. All five have a fix and a test in one commit on a fork: AmateurWizrd/nxnative@78764a9d (t_res_guard, 26 checks; t_guard_sys, 9).

1. The stop decides before its own eviction lands (guard_act, from A GPU memory guard before each residency commit stops the game instead of freezing the Mac #1391). It evicts, waits for the current submission's fence, commits and reads the set. What guard_evict lets go is released behind the next submission's fence, so a set a little over 95 % is stopped with the memory that would have brought it under still held. Fix: evict, return, and decide when the submit thread comes back after the next submission.
2. The system side stops on one 100 ms sample (guard_sys_tick, guard_level, guard_act; this PR). The timer waits GUARD_TICKS ticks before it stops, but guard_level folds g_sys_lv in, so the submit thread's guard_act reads the same sample again right after its eviction and calls guard_stop. Letting GPU memory go cannot move kern.memorystatus_level that fast. The margin also only grows (512 MB per pressure warning, up to 4 GB) and never comes back. Fix: for the system side the submit thread only evicts, the timer alone stops, and the margin returns to its start when the system reports normal pressure.
3. The set's allocatedSize counts overlapping no-copy buffers in full (guard_used, from The GPU memory guard reads the residency set's size, not currentAllocatedSize (on #1391) #1482). The comment there says only currentAllocatedSize does. A 20-line probe on an M3 Pro, macOS 27.3: four no-copy buffers over one 64 MB region, added to a residency set, read 256 MB from both. A large pool's chunks overlap, so the guard counts too much and stops early. Fix: from the eviction level on, take the overlap off with the page accounting res_top already has.
4. The timer's copy of the size is from before the commit. res_commit stores g_guard_set before it commits, so a commit that takes transient buffers out leaves the timer the size with them in.
5. The wall does not see the commit's own additions. The GUARD_WALL test uses the set's size from before this commit, so one commit can take the set past the working set. Fix for 4 and 5: count the set as the commit leaves it (its size, plus the additions, less the removals).

Not checked: a run where the guard really evicts or stops. On an 18 GB M3 Pro with Ocarina of Time (0400486024DEC000) the residency set stayed under 6.9 GB against an 8,192 MB test limit, so those paths ran only in the tests.