[simonwjackson]

Linux users can lose much of their frame rate when device permissions prevent Hookshot from using /dev/udmabuf, without being told how to fix it. On my RX 7900 XT, a matched Kokiri Forest test measured 16.1–16.2 game fps with host-pointer imports versus 36.1 with DMA buffers.

What changed

• Warn once for EACCES or EPERM, with the error, slower-import consequence and group/udev access advice. Other open failures keep the existing logging.
• Preserve the original stderr when startup redirects its runtime log to hookshot_log.txt; writing another line to the redirected stderr alone would not reach the original caller. With unredirected stderr, the warning is logged only once.
• Document the existing owning-group option and device-scoped udev alternatives: active-local-session uaccess, or a dedicated group for service/SSH users. No world-writable device, root game process or automatic permission change.
• Add a game-free regression check. Linux-only descriptors remain outside Windows code.

Related: #1000; follows the DMA-import support merged in #448. This does not fix every Linux performance issue or close the tracking issue.

Evidence and tests

Base: upstream main 215ab3dd6536cb21fc67c2e89c31c10a18df555c.

Historical hardware evidence: RX 7900 XT / RADV NAVI31, Mesa 26.2.3, Linux 7.2.7, Ryzen 5 7600X. The permission-denied device was root:kvm 0660. With mesh draws disabled in both cases, the matched DMA run reached 36.1 game fps; reverting to HOS_GUEST_MEMFD=0 with the same access grant returned to 16.2. Queue-submit time was 29.10–30.15 ms without DMA and 0.49 ms with it. These are earlier diagnostic runs, not a benchmark of this warning patch or generated-display fps.

• Regression demonstrated before the change: no warning on stderr.

• python -I -B tests/run_all.py udmabuf_warning low_memory_notice: 2 passed. The new test checks EACCES/EPERM, ENOENT/EIO, success, repeated probes, and redirected/unredirected stderr.

• Compiled and ran the actual warning block plus the production logger against a real mode-000 file: one warning on original stderr and one in the redirected log. No game assets needed.

• C fixture: GCC, -std=c11 -Wall -Wextra -Werror; Ruff and git diff --check: passed.

• Full game-free suite: python -I -B tests/run_all.py --jobs 6 --timeout 1200 — 354 passed, 2 failed, 12 skipped, 520 s on Linux. tests/test_finish_output.py and tests/test_linux_update.py fail with NameError: name 'a' is not defined in the extracted nx2/make_game.py finish block; both failures reproduce on untouched upstream at the base SHA above. Skips cover game/GPU/Windows-only checks and unavailable dotnet, PIL and numpy. Earlier runs exposed an unrelated tests/test_make_game_ngx.py failure, reproduced on untouched upstream; upstream fixed it in test: main's source checks pass again after #2061 and #2046 #2068, and this branch was rebased onto that fix before the earlier passing full run.

• Whole-file host/hos_main.c Clang syntax/type check: passed, using the project's game-free runtime-header generators.

Not tested: the patched full game, Windows runtime/build, other GPUs, or applying either persistent udev policy. No new hardware benchmark was run, so no new tested-configurations row is claimed.

Screenshots

Before/after terminal captures of the game-free EACCES fixture, using the same warning code and real logger (not game screenshots):

Before: no output on stderr. After (once, also in hookshot_log.txt):

[hos host] WARNING: /dev/udmabuf permission denied; GPU imports may be slower, especially on AMD/RADV. Ask your administrator for access via its device group or a device-specific udev rule (see README, On Linux). Do not run the game as root. (Permission denied)

Both probes run twice; the new stderr warning appears once.

Note: tests/test_finish_output.py and tests/test_linux_update.py also fail on untouched current main (NameError: name 'a' is not defined); they are unrelated to this change.