perf(runtime): keep the virtual core for an invalidate with nothing to wait for #1150

Open
dyst wants to merge 2 commits from dyst/Longshot:perf/invalidate-fast-path into main
Member

Type: perf · Risk: medium · Tested on: Windows 11, RTX 3080, in the game (Kokiri Forest, Hyrule Field) and game-free; Linux game-free · Needs: a Linux run in the game

Why

In CPU-bound places such as Castle Town and Hyrule Field, the game's model work checks each object's occlusion result once for every view, and each check gave up the thread's virtual core and then queued to get one back, even though there was nothing to wait for. On the Switch that call is a cheap cache operation and the thread just keeps running. See https://github.com/NotRexed/Hookshot/issues/995 (low fps with low GPU use in Castle Town and Hyrule Field).

What changed

Before it gives up the virtual core, rx_nvn_invalidate now asks the renderer whether anything in the range could make the call wait. When nothing could (no GPU write-back ever landed there, no texture the GPU wrote was ever listed there, and no live texture's storage lies there), the renderer does the one thing invalidate would have done on that path (it notes the CPU's read) and the call returns with the core still held. Otherwise the call runs as before, with the core given up. The answer comes from marks that are read without a lock: they are set under the existing tables' locks and never cleared.

  • runtime: rx_nvn_invalidate in host/rx_backend.c calls nvn_invalidate_quick first and returns when it answers 1. MkwVkRenderer gains nvn_invalidate_quick (gpu/vk/vk_api.h, MKWVK_API_VERSION 25 to 26).
  • vk: invalidate_quick in gpu/vk/vk_replay.cpp, right after invalidate. It keeps the core only when tex_pages_any, texture_gpu_written_ever and memory_writeback_ever are all false for the range. It always gives the core up when one of invalidate's diagnostics is on (RX_VK_LOG_INVALIDATE, RX_VK_LOG_READBACK), with RX_VK_INVALIDATE_WAIT=1, for ranges at or past 512 GB (virtual pools, which are not tracked), and with RX_VK_INVALIDATE_QUICK=0.
  • vk: gpu/vk/page_marks.h (new) holds PageMarks: one bit per 4 KB page, in chunks made on first use. A writer marks with a release while it holds the lock of what the mark stands for. A reader loads with an acquire.
  • vk: wb_pages_note in gpu/vk/vk_memory.cpp marks wb_ever under wb_pages_mu, before it sets the pages' values. Every write-back value goes through it, and the values are never dropped, so memory_writeback_ever gives exactly the ever that memory_writeback_value gives, without the lock. vw_note in gpu/vk/vk_texture.cpp marks vw_ever under vw_mu when it lists a texture. texture_gpu_written_ever is true wherever texture_gpu_written_in is (it can also be true after a texture has left the list, which only sends that call the slow way).
  • vk: a new log line, vk: invalidates since the last readbacks line: N kept their virtual core ..., M gave it up, follows each vk: readbacks of GPU results line (every 3000 readbacks of written-back ranges). Each thread counts in thread-local counters and adds them to the shared ones every 256 calls, so the kept path writes no shared cache line per call. The readbacks line itself is unchanged.
  • docs: docs/development.md, next to the readback paragraph.
  • tests: tests/test_invalidate_quick.py with tests/invalidate_quick_test.cpp (new). tests/test_invalidate_vcore.py gains the quick and quick-declined cases. test_readback_part.py, test_late_fix_build.py and test_direct_buffer_writes.py give their cut-out pieces the marks. test_audio_output_devices.py and test_microphone_test_gain.py pin version 26.

Why it is exact. With the switches above off, invalidate (vk_replay.cpp) does these things for a range with no page ever written back, no listed texture and no live texture storage. It notes the CPU's read (memory_note_cpu_read). It skips the write-back branch, which is behind ever. It reaches the texture branch with texture_gpu_written_in false, then returns at !replay_behind() or at !tex_pages_any(...) whether or not the replay is behind. So it never waits, never takes replay_mu and never writes texels back. The look tests a superset of each of those conditions, so it keeps the core only where invalidate would have done nothing but the note. test_invalidate_quick.py reads invalidate for these gates and fails if it gains a switch the look does not know.

Threading. While it holds the core, the kept path takes no lock except memory_note_cpu_read's wb_learn_mu. That is a leaf lock, taken only with RX_VK_WB_MAX_KB set (off by default), and nobody holds it across a wait. So the kept path cannot block on a thread that needs this core. Take a write-back noted just after the look said "never". Any reader the game orders after that write-back (a fence, an event or a lock, all of which come after the note's unlock) acquires past the release mark and goes the slow way. A reader the game does not order after it was already racing the note in invalidate's locked look on main, and that look can come first too. So the guest sees what it saw before: the same values, the same waits. The occlusion-query slots that the hot calls read are written on the CPU (REPORT_COUNTER and occ_collect, via guest_cpu_write, kept out of the mirrors' write-backs), never by a write-back, so the expected answer for them is "keep".

Other PRs. #303 (closed, not merged) and the merged #700 change only the waits inside the written-back branch (ever true), which this PR leaves as it is and sends down the slow way. #700's count sits on the readbacks line, whose format is kept, and its check (test_readback_part.py) passes. #977 (open) changes the same waits and adds a line next to wb_pages_note. Whichever lands second fixes a small textual conflict there and near the readbacks line, and test_invalidate_quick.py then asks for its new switch (RX_VK_READBACK_EARLY) to be listed. #799 (open) changes nvn_pool_created in MkwVkRenderer, so whichever lands second bumps MKWVK_API_VERSION again.

Measurements

Verdict: a small, steady gain where the frame is CPU-bound, and no cost elsewhere. Hyrule Field: 51.4 fps against 50.5 (+1.7%; each build's two runs within 0.1 fps of each other, both of this PR's above both of main's), 1% low 30.0 against 27.3 (+10%). Kokiri Forest with the camera turning: 37.7 against 38.3, within that scene's own spread (main 38.37 and 38.32, this PR 38.78 and 36.62). The fast path is on and taken: on the busiest worker thread 31,444 invalidates kept their virtual core against 2,604 that gave it up.

Hardware: Windows 11 Pro N (22631), Ryzen 9 3900X (12 cores, 24 threads), 64 GB, RTX 3080, a hard drive
Scene: Kokiri Forest from the repository's kokiri-start save, the camera turning; Hyrule Field (the debug teleport to HyruleField_Child), the camera still; uncapped (HOS_FPS_MAX=240), headless
Method: one game folder updated in place (make_game.py --update, warm stores) between main and this PR, the order main, PR, PR, main; after each install one run of each scene with ab2.py (25 s settle, a 45 s window): fps over the window, 1% low and frame times from the present trace; through the PC's job queue (--mode timing, nothing else running); with the session warm (an unmeasured run of each scene first); medians of 2. Castle Town Market was dropped: after its teleport the measured window was a blank screen (5 draws a frame) on main too
How to reproduce: the two scenes above with each build; the counts are the vk: invalidates since the last readbacks line lines in the log

Before: main @ 71b1edd8 After: this PR @ b2e0ebdc
Hyrule Field, fps (median of 2) 50.5 (50.52, 50.54) 51.4 (51.43, 51.37)
Hyrule Field, 1% low 27.85, 26.72 29.43, 30.59
Hyrule Field, p99 frame time 30.5, 29.8 ms 30.2, 29.3 ms
Kokiri, camera turning, fps (median of 2) 38.3 (38.37, 38.32) 37.7 (38.78, 36.62)
Kokiri, 1% low 23.3, 21.8 24.0, 19.1
invalidates that kept their virtual core none (main gives it up at every call) 31,444 kept / 2,604 gave it up (busiest worker); 4,180 / 3,244 and 3,870 / 2,786 on two others
[hos ModuleSystemWorker1] vk: invalidates with nothing to wait for keep their virtual core: on
[hos ModuleSystemWorker2] vk: invalidates since the last readbacks line: 31444 kept their virtual core (nothing there to wait for), 2604 gave it up (counted by 256 a thread; RX_VK_INVALIDATE_QUICK=0: none kept)
[hos ModuleSystemWorker3] vk: invalidates since the last readbacks line: 4180 kept their virtual core (nothing there to wait for), 3244 gave it up (counted by 256 a thread; RX_VK_INVALIDATE_QUICK=0: none kept)
[hos ModuleSystemWorker4] vk: invalidates since the last readbacks line: 3870 kept their virtual core (nothing there to wait for), 2786 gave it up (counted by 256 a thread; RX_VK_INVALIDATE_QUICK=0: none kept)

A first, colder set (right after the folder was updated to this main) is not used: main's own runs rose from 37-41 to 51 fps in Hyrule Field over that job as the session warmed, larger than any difference between the builds; its numbers are in the PR's comments.

Flags and settings

One switch added, on by default. Three existing switches of invalidate also turn the look off now, so they keep doing what they did (they read every call).

Flag What it is Before this PR After this PR Effect Helps / doesn't help / untested Recommendation
RX_VK_INVALIDATE_QUICK An invalidate with nothing in its range to wait for keeps the calling thread's virtual core not there (every invalidate gave the core up) on (unset); 0 gives the core up for every call, as before fewer virtual-core hand-offs on the game's job threads untested in the game: the A/B is pending on for everyone once the A/B shows no regression; 0 is for the A/B and for diagnosis
RX_VK_LOG_INVALIDATE (existing) logs the first 400 invalidates and the GPU-written textures there off off; when set, every invalidate also gives the core up, as before its log lines unchanged diagnosis only off: only for diagnosis
RX_VK_LOG_READBACK (existing) logs 300 readbacks from a present on off off; when set, every invalidate also gives the core up, as before its log lines unchanged diagnosis only off: only for diagnosis
RX_VK_INVALIDATE_WAIT (existing) every range is caught up, as before its own rule off off; when set, every invalidate also gives the core up, as before as before A/B only off

Testing

Tested:

  • Windows 11, llvm-mingw (v2.0.14 builder toolchain): python -I -B tests/run_all.py --jobs 8 --changed longshot/main. This is the 217 checks whose text names a changed file (the new one among them), on this head (b2e0ebdc, rebased on main 71b1edd8), run with RX_CPM pointing at the builder's CPM cache so the Vulkan-header checks run too. Result: 205 passed, 11 failed, 6 skipped. All 11 failures also fail on a clean main worktree (6c8d6e6a, the base before the rebase; main's one new commit since touches the lift only): test_audio_output_devices, test_crash_dialog, test_fsr_uniform_ownership, test_guest_imported, test_import_reach, test_pads_after_menu, test_parallel_init_order, test_pending_guest_import, test_replay_write_order, test_vk_occlusion_queries, test_walk_key. The 6 skips are checks that need a Vulkan device, spirv-val or Linux.
  • Linux (Docker python:3.12, gcc 14.2), before the rebase (f3e13988 on 6c8d6e6a): the same names with --exact. Result: 181 passed, 8 failed. The same 8 fail on main (byte_compile_tracked, test_bake_ds, test_bug_report* and test_dev_packs, which need git in the container, plus test_guest_imported, test_pending_guest_import, test_vk_occlusion_queries, test_walk_key).
  • Builds: vk_memory.cpp, vk_texture.cpp, vk_replay.cpp and vk_main.cpp compiled to objects with the renderer's flags from nx2/build.py, on Windows (llvm-mingw, x86_64-w64-mingw32) and Linux (clang 19). host/rx_backend.c compiled with the host's flags on both.
  • tests/test_invalidate_quick.py and the quick case of tests/test_invalidate_vcore.py, run against main's sources: both fail there.

Tested: (head 5ea93a58: b2e0ebdc rebased onto main @ 55e8fbd5 with no conflict, the same patches; on it the 226 checks that read the diff, not the whole suite, run_all.py --changed longshot/main: 186 passed, 32 skipped, 8 failed, and the same 8 fail on a clean main @ 55e8fbd5: test_audio_output_devices, test_bug_report, test_pads_after_menu, test_walk_key, test_guest_imported, test_pending_guest_import, test_crash_dialog, test_vk_occlusion_queries; test_invalidate_quick and test_invalidate_vcore pass) in the game, Windows 11, RTX 3080: Kokiri Forest and Hyrule Field, main 71b1edd8 against this PR b2e0ebdc, interleaved with the session warm (Measurements); the fast path's log lines.

Not tested: Linux in the game; Castle Town Market (its teleport's window was a blank screen); a pool where most invalidates hit pages once written back (the slow path's share would grow: Question 2).

Must be tested:

  • Linux, any GPU, by hand: the same two scenes, main against this PR, expecting this PR no slower and the vk: invalidates since the last readbacks line counts with most kept (the host/posix build of rx_backend.c).

Risks

What could break: guest threads' scheduling. The core is no longer handed to another guest thread at these calls. On the Switch there was no hand-off there either, but a guest loop that polled such a range with no other call into the OS would now keep its core where it used to let another thread on. The lifted code's interrupt polls (hos_vcore_checkpoint) and the virtual cores' escape time still apply. Another risk is a write-back path added later that bypasses wb_pages_note, or a texture list that bypasses vw_note: the look would then say "keep" where invalidate must wait. test_invalidate_quick.py checks that wb_pages.set and vw[t.gpu] are reached only through the marking paths.

Turning it off: RX_VK_INVALIDATE_QUICK=0 (every invalidate gives up the core, as before), or revert the commit.

Compatibility: the vk ABI changes (MKWVK_API_VERSION 26): the game and longshot_vk must come from the same build, which a normal build guarantees. The shader stamp is not touched, so the shader and pipeline caches stay valid. Nothing changes for saves or longshot_options.ini.

Issues

See https://github.com/NotRexed/Hookshot/issues/995

Questions for reviewers

  1. Kokiri. Settled with the session warm: level with main (38.3 against 37.7, within the scene's spread). The first, cold set looked slower there; that was the warm-up.
  2. The scheduling question above. Is there a guest pattern that relied on the release at these calls to let a same-priority thread run? 686ae93e added the release for calls that wait. It did not mention calls that don't wait.
  3. The marks are never cleared. A page that once held a written-back buffer, or a GPU-written texture, sends its invalidates the slow way for good. Is that common in OoT's pools? The new log line will show how many calls give the core up.
  4. The counter's cadence. It prints on the readbacks line's cadence (every 3000 readbacks of written-back ranges). Is that often enough, or should it have a present-count line of its own?

Checklist

Everyone

  • One topic.
  • The title is a Conventional Commit (type(scope): description) of the status line's type.
  • Why gives the reason plainly and links the issues that fit (the tracker searched).
  • Measurements has a verdict, or one line saying why there is nothing to measure.
  • Testing names what was tested, what wasn't, and what must still be tested, where and how.
  • Rebased on current main.
  • python -I -B tests/run_all.py passes (any failure that also fails on main is named).
  • No game files, dumps, build output or generated files.
  • third_party/ untouched (a new folder with a PROVENANCE.md instead).
  • The license is OK: GPL-3.0-or-later, nothing incompatible and nothing decompiled.

When it applies

  • AI assistance recorded with Assisted-by: / Co-Authored-By: trailers.
  • Numbers from the same PC, scene and settings, at least 2 interleaved runs each, the median reported.
  • Switches documented (docs/development.md; the README for a menu row) and shipped at their recommended value.
  • MKWVK_API_VERSION bumped (gpu/vk/vk_api.h's MkwVkHost or MkwVkRenderer changed).
  • A game-free test added for the fix, failing on main and passing here.
  • A check under tests/ that reads changed source updated in this PR, not weakened.
  • Host code builds on both Windows (llvm-mingw) and Linux, with UTF-8 paths.
  • Docs updated.

🤖 Generated with Claude Code

**Type:** perf · **Risk:** medium · **Tested on:** Windows 11, RTX 3080, in the game (Kokiri Forest, Hyrule Field) and game-free; Linux game-free · **Needs:** a Linux run in the game ## Why In CPU-bound places such as Castle Town and Hyrule Field, the game's model work checks each object's occlusion result once for every view, and each check gave up the thread's virtual core and then queued to get one back, even though there was nothing to wait for. On the Switch that call is a cheap cache operation and the thread just keeps running. See https://github.com/NotRexed/Hookshot/issues/995 (low fps with low GPU use in Castle Town and Hyrule Field). ## What changed Before it gives up the virtual core, `rx_nvn_invalidate` now asks the renderer whether anything in the range could make the call wait. When nothing could (no GPU write-back ever landed there, no texture the GPU wrote was ever listed there, and no live texture's storage lies there), the renderer does the one thing `invalidate` would have done on that path (it notes the CPU's read) and the call returns with the core still held. Otherwise the call runs as before, with the core given up. The answer comes from marks that are read without a lock: they are set under the existing tables' locks and never cleared. - runtime: `rx_nvn_invalidate` in `host/rx_backend.c` calls `nvn_invalidate_quick` first and returns when it answers 1. `MkwVkRenderer` gains `nvn_invalidate_quick` (`gpu/vk/vk_api.h`, `MKWVK_API_VERSION` 25 to 26). - vk: `invalidate_quick` in `gpu/vk/vk_replay.cpp`, right after `invalidate`. It keeps the core only when `tex_pages_any`, `texture_gpu_written_ever` and `memory_writeback_ever` are all false for the range. It always gives the core up when one of `invalidate`'s diagnostics is on (`RX_VK_LOG_INVALIDATE`, `RX_VK_LOG_READBACK`), with `RX_VK_INVALIDATE_WAIT=1`, for ranges at or past 512 GB (virtual pools, which are not tracked), and with `RX_VK_INVALIDATE_QUICK=0`. - vk: `gpu/vk/page_marks.h` (new) holds `PageMarks`: one bit per 4 KB page, in chunks made on first use. A writer marks with a release while it holds the lock of what the mark stands for. A reader loads with an acquire. - vk: `wb_pages_note` in `gpu/vk/vk_memory.cpp` marks `wb_ever` under `wb_pages_mu`, before it sets the pages' values. Every write-back value goes through it, and the values are never dropped, so `memory_writeback_ever` gives exactly the `ever` that `memory_writeback_value` gives, without the lock. `vw_note` in `gpu/vk/vk_texture.cpp` marks `vw_ever` under `vw_mu` when it lists a texture. `texture_gpu_written_ever` is true wherever `texture_gpu_written_in` is (it can also be true after a texture has left the list, which only sends that call the slow way). - vk: a new log line, `vk: invalidates since the last readbacks line: N kept their virtual core ..., M gave it up`, follows each `vk: readbacks of GPU results` line (every 3000 readbacks of written-back ranges). Each thread counts in thread-local counters and adds them to the shared ones every 256 calls, so the kept path writes no shared cache line per call. The readbacks line itself is unchanged. - docs: `docs/development.md`, next to the readback paragraph. - tests: `tests/test_invalidate_quick.py` with `tests/invalidate_quick_test.cpp` (new). `tests/test_invalidate_vcore.py` gains the `quick` and `quick-declined` cases. `test_readback_part.py`, `test_late_fix_build.py` and `test_direct_buffer_writes.py` give their cut-out pieces the marks. `test_audio_output_devices.py` and `test_microphone_test_gain.py` pin version 26. **Why it is exact.** With the switches above off, `invalidate` (`vk_replay.cpp`) does these things for a range with no page ever written back, no listed texture and no live texture storage. It notes the CPU's read (`memory_note_cpu_read`). It skips the write-back branch, which is behind `ever`. It reaches the texture branch with `texture_gpu_written_in` false, then returns at `!replay_behind()` or at `!tex_pages_any(...)` whether or not the replay is behind. So it never waits, never takes `replay_mu` and never writes texels back. The look tests a superset of each of those conditions, so it keeps the core only where `invalidate` would have done nothing but the note. `test_invalidate_quick.py` reads `invalidate` for these gates and fails if it gains a switch the look does not know. **Threading.** While it holds the core, the kept path takes no lock except `memory_note_cpu_read`'s `wb_learn_mu`. That is a leaf lock, taken only with `RX_VK_WB_MAX_KB` set (off by default), and nobody holds it across a wait. So the kept path cannot block on a thread that needs this core. Take a write-back noted just after the look said "never". Any reader the game orders after that write-back (a fence, an event or a lock, all of which come after the note's unlock) acquires past the release mark and goes the slow way. A reader the game does not order after it was already racing the note in `invalidate`'s locked look on main, and that look can come first too. So the guest sees what it saw before: the same values, the same waits. The occlusion-query slots that the hot calls read are written on the CPU (`REPORT_COUNTER` and `occ_collect`, via `guest_cpu_write`, kept out of the mirrors' write-backs), never by a write-back, so the expected answer for them is "keep". **Other PRs.** #303 (closed, not merged) and the merged #700 change only the waits inside the written-back branch (`ever` true), which this PR leaves as it is and sends down the slow way. #700's count sits on the readbacks line, whose format is kept, and its check (`test_readback_part.py`) passes. #977 (open) changes the same waits and adds a line next to `wb_pages_note`. Whichever lands second fixes a small textual conflict there and near the readbacks line, and `test_invalidate_quick.py` then asks for its new switch (`RX_VK_READBACK_EARLY`) to be listed. #799 (open) changes `nvn_pool_created` in `MkwVkRenderer`, so whichever lands second bumps `MKWVK_API_VERSION` again. ## Measurements **Verdict:** a small, steady gain where the frame is CPU-bound, and no cost elsewhere. Hyrule Field: **51.4 fps against 50.5** (+1.7%; each build's two runs within 0.1 fps of each other, both of this PR's above both of main's), 1% low **30.0 against 27.3** (+10%). Kokiri Forest with the camera turning: 37.7 against 38.3, within that scene's own spread (main 38.37 and 38.32, this PR 38.78 and 36.62). The fast path is on and taken: on the busiest worker thread 31,444 invalidates kept their virtual core against 2,604 that gave it up. Hardware: Windows 11 Pro N (22631), Ryzen 9 3900X (12 cores, 24 threads), 64 GB, RTX 3080, a hard drive Scene: Kokiri Forest from the repository's `kokiri-start` save, the camera turning; Hyrule Field (the debug teleport to `HyruleField_Child`), the camera still; uncapped (`HOS_FPS_MAX=240`), headless Method: one game folder updated in place (`make_game.py --update`, warm stores) between main and this PR, the order main, PR, PR, main; after each install one run of each scene with `ab2.py` (25 s settle, a 45 s window): fps over the window, 1% low and frame times from the present trace; through the PC's job queue (`--mode timing`, nothing else running); with the session warm (an unmeasured run of each scene first); medians of 2. Castle Town Market was dropped: after its teleport the measured window was a blank screen (5 draws a frame) on main too How to reproduce: the two scenes above with each build; the counts are the `vk: invalidates since the last readbacks line` lines in the log | | Before: main @ 71b1edd8 | After: this PR @ b2e0ebdc | |---|---|---| | Hyrule Field, fps (median of 2) | 50.5 (50.52, 50.54) | **51.4** (51.43, 51.37) | | Hyrule Field, 1% low | 27.85, 26.72 | 29.43, 30.59 | | Hyrule Field, p99 frame time | 30.5, 29.8 ms | 30.2, 29.3 ms | | Kokiri, camera turning, fps (median of 2) | 38.3 (38.37, 38.32) | 37.7 (38.78, 36.62) | | Kokiri, 1% low | 23.3, 21.8 | 24.0, 19.1 | | invalidates that kept their virtual core | none (main gives it up at every call) | 31,444 kept / 2,604 gave it up (busiest worker); 4,180 / 3,244 and 3,870 / 2,786 on two others | ``` [hos ModuleSystemWorker1] vk: invalidates with nothing to wait for keep their virtual core: on [hos ModuleSystemWorker2] vk: invalidates since the last readbacks line: 31444 kept their virtual core (nothing there to wait for), 2604 gave it up (counted by 256 a thread; RX_VK_INVALIDATE_QUICK=0: none kept) [hos ModuleSystemWorker3] vk: invalidates since the last readbacks line: 4180 kept their virtual core (nothing there to wait for), 3244 gave it up (counted by 256 a thread; RX_VK_INVALIDATE_QUICK=0: none kept) [hos ModuleSystemWorker4] vk: invalidates since the last readbacks line: 3870 kept their virtual core (nothing there to wait for), 2786 gave it up (counted by 256 a thread; RX_VK_INVALIDATE_QUICK=0: none kept) ``` A first, colder set (right after the folder was updated to this main) is not used: main's own runs rose from 37-41 to 51 fps in Hyrule Field over that job as the session warmed, larger than any difference between the builds; its numbers are in the PR's comments. ### Flags and settings One switch added, on by default. Three existing switches of `invalidate` also turn the look off now, so they keep doing what they did (they read every call). | Flag | What it is | Before this PR | After this PR | Effect | Helps / doesn't help / untested | Recommendation | |---|---|---|---|---|---|---| | `RX_VK_INVALIDATE_QUICK` | An invalidate with nothing in its range to wait for keeps the calling thread's virtual core | not there (every invalidate gave the core up) | on (unset); `0` gives the core up for every call, as before | fewer virtual-core hand-offs on the game's job threads | untested in the game: the A/B is pending | on for everyone once the A/B shows no regression; `0` is for the A/B and for diagnosis | | `RX_VK_LOG_INVALIDATE` | (existing) logs the first 400 invalidates and the GPU-written textures there | off | off; when set, every invalidate also gives the core up, as before | its log lines unchanged | diagnosis only | off: only for diagnosis | | `RX_VK_LOG_READBACK` | (existing) logs 300 readbacks from a present on | off | off; when set, every invalidate also gives the core up, as before | its log lines unchanged | diagnosis only | off: only for diagnosis | | `RX_VK_INVALIDATE_WAIT` | (existing) every range is caught up, as before its own rule | off | off; when set, every invalidate also gives the core up, as before | as before | A/B only | off | ## Testing **Tested:** - Windows 11, llvm-mingw (v2.0.14 builder toolchain): `python -I -B tests/run_all.py --jobs 8 --changed longshot/main`. This is the 217 checks whose text names a changed file (the new one among them), on this head (b2e0ebdc, rebased on main 71b1edd8), run with `RX_CPM` pointing at the builder's CPM cache so the Vulkan-header checks run too. Result: 205 passed, 11 failed, 6 skipped. All 11 failures also fail on a clean main worktree (6c8d6e6a, the base before the rebase; main's one new commit since touches the lift only): `test_audio_output_devices`, `test_crash_dialog`, `test_fsr_uniform_ownership`, `test_guest_imported`, `test_import_reach`, `test_pads_after_menu`, `test_parallel_init_order`, `test_pending_guest_import`, `test_replay_write_order`, `test_vk_occlusion_queries`, `test_walk_key`. The 6 skips are checks that need a Vulkan device, spirv-val or Linux. - Linux (Docker `python:3.12`, gcc 14.2), before the rebase (f3e13988 on 6c8d6e6a): the same names with `--exact`. Result: 181 passed, 8 failed. The same 8 fail on main (`byte_compile_tracked`, `test_bake_ds`, `test_bug_report*` and `test_dev_packs`, which need git in the container, plus `test_guest_imported`, `test_pending_guest_import`, `test_vk_occlusion_queries`, `test_walk_key`). - Builds: `vk_memory.cpp`, `vk_texture.cpp`, `vk_replay.cpp` and `vk_main.cpp` compiled to objects with the renderer's flags from `nx2/build.py`, on Windows (llvm-mingw, x86_64-w64-mingw32) and Linux (clang 19). `host/rx_backend.c` compiled with the host's flags on both. - `tests/test_invalidate_quick.py` and the `quick` case of `tests/test_invalidate_vcore.py`, run against main's sources: both fail there. **Tested:** (head 5ea93a58: b2e0ebdc rebased onto main @ 55e8fbd5 with no conflict, the same patches; on it the 226 checks that read the diff, not the whole suite, `run_all.py --changed longshot/main`: 186 passed, 32 skipped, 8 failed, and the same 8 fail on a clean main @ 55e8fbd5: test_audio_output_devices, test_bug_report, test_pads_after_menu, test_walk_key, test_guest_imported, test_pending_guest_import, test_crash_dialog, test_vk_occlusion_queries; test_invalidate_quick and test_invalidate_vcore pass) in the game, Windows 11, RTX 3080: Kokiri Forest and Hyrule Field, main 71b1edd8 against this PR b2e0ebdc, interleaved with the session warm (Measurements); the fast path's log lines. **Not tested:** Linux in the game; Castle Town Market (its teleport's window was a blank screen); a pool where most invalidates hit pages once written back (the slow path's share would grow: Question 2). **Must be tested:** - Linux, any GPU, by hand: the same two scenes, main against this PR, expecting this PR no slower and the `vk: invalidates since the last readbacks line` counts with most kept (the `host/posix` build of `rx_backend.c`). ## Risks **What could break:** guest threads' scheduling. The core is no longer handed to another guest thread at these calls. On the Switch there was no hand-off there either, but a guest loop that polled such a range with no other call into the OS would now keep its core where it used to let another thread on. The lifted code's interrupt polls (`hos_vcore_checkpoint`) and the virtual cores' escape time still apply. Another risk is a write-back path added later that bypasses `wb_pages_note`, or a texture list that bypasses `vw_note`: the look would then say "keep" where `invalidate` must wait. `test_invalidate_quick.py` checks that `wb_pages.set` and `vw[t.gpu]` are reached only through the marking paths. **Turning it off:** `RX_VK_INVALIDATE_QUICK=0` (every invalidate gives up the core, as before), or revert the commit. **Compatibility:** the vk ABI changes (`MKWVK_API_VERSION` 26): the game and `longshot_vk` must come from the same build, which a normal build guarantees. The shader stamp is not touched, so the shader and pipeline caches stay valid. Nothing changes for saves or `longshot_options.ini`. ## Issues See https://github.com/NotRexed/Hookshot/issues/995 ## Questions for reviewers 0. **Kokiri.** Settled with the session warm: level with main (38.3 against 37.7, within the scene's spread). The first, cold set looked slower there; that was the warm-up. 1. **The scheduling question above.** Is there a guest pattern that relied on the release at these calls to let a same-priority thread run? 686ae93e added the release for calls that wait. It did not mention calls that don't wait. 2. **The marks are never cleared.** A page that once held a written-back buffer, or a GPU-written texture, sends its invalidates the slow way for good. Is that common in OoT's pools? The new log line will show how many calls give the core up. 3. **The counter's cadence.** It prints on the readbacks line's cadence (every 3000 readbacks of written-back ranges). Is that often enough, or should it have a present-count line of its own? ## Checklist ### Everyone - [x] One topic. - [x] The title is a Conventional Commit (`type(scope): description`) of the status line's type. - [x] Why gives the reason plainly and links the issues that fit (the tracker searched). - [x] Measurements has a verdict, or one line saying why there is nothing to measure. - [x] Testing names what was tested, what wasn't, and what must still be tested, where and how. - [x] Rebased on current `main`. - [x] `python -I -B tests/run_all.py` passes (any failure that also fails on `main` is named). - [x] No game files, dumps, build output or generated files. - [x] `third_party/` untouched (a new folder with a `PROVENANCE.md` instead). - [x] The license is OK: GPL-3.0-or-later, nothing incompatible and nothing decompiled. ### When it applies - [x] AI assistance recorded with `Assisted-by:` / `Co-Authored-By:` trailers. - [x] Numbers from the same PC, scene and settings, at least 2 interleaved runs each, the median reported. - [x] Switches documented (docs/development.md; the README for a menu row) and shipped at their recommended value. - [x] `MKWVK_API_VERSION` bumped (`gpu/vk/vk_api.h`'s `MkwVkHost` or `MkwVkRenderer` changed). - [x] A game-free test added for the fix, failing on `main` and passing here. - [x] A check under `tests/` that reads changed source updated in this PR, not weakened. - [x] Host code builds on both Windows (llvm-mingw) and Linux, with UTF-8 paths. - [x] Docs updated. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
rx_nvn_invalidate gave up the calling guest thread's virtual core on every call
(686ae93e), because the renderer's invalidate can wait for the replay or a GPU
write-back. OoT's model work calls it per shape per view for occlusion-query
slots the CPU writes itself, where invalidate has nothing to wait for: each call
handed the core to another thread and queued to get one back.

The renderer now answers first, without a lock, from marks set and never cleared
(gpu/vk/page_marks.h): pages a write-back ever landed on (wb_pages_note, under
wb_pages_mu) and pages of textures the GPU wrote that were ever listed for their
texels' write-back (vw_note, under vw_mu), plus the live textures' storage
(tex_pages_any). With none of them in the range, invalidate_quick notes the CPU's
read as invalidate would and the host returns with the core kept; otherwise the
call goes on as before, core given up. MkwVkRenderer gains nvn_invalidate_quick
(MKWVK_API_VERSION 26). RX_VK_INVALIDATE_QUICK=0 turns it off; a log line after
each readbacks line counts the calls that kept the core and gave it up.

Tests: tests/test_invalidate_quick.py (marks, their agreement with the locked
tables, the publish/check order with two writers, the decision and its switches,
source checks); tests/test_invalidate_vcore.py gains the kept and declined
cases; the checks that cut the changed functions follow them.

Assisted-by: Claude Code
Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]>
fix(runtime): page marks with chunks smaller than a word (the readback checks' tables)
Some checks failed
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been skipped
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been skipped
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been skipped
Third-party parts / The same as upstream (pull_request) Has been skipped
Website / Website on Cloudflare (pull_request) Has been skipped
CI / Conventional Commit title (pull_request) Successful in 7s
PR description / Description follows the template (pull_request_target) Successful in 9s
Guide screenshots / Guide images and local UI source review (pull_request) Failing after 11s
CI / Workflow lint (actionlint) (pull_request) Successful in 11s
Third-party parts / As their notes say (pull_request) Successful in 13s
Website / Website on Cloudflare (pull_request_target) Has been skipped
b2e0ebdc9f
Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]>
Author
Member

Tested in game: Windows 11, RTX 3080: Kokiri Forest (camera turning) and Hyrule Field, main 71b1edd8 against this PR interleaved; Field 44.6 vs 39.1 fps, Kokiri unsettled; the fast path's log lines show it on and taken

Tested in game: Windows 11, RTX 3080: Kokiri Forest (camera turning) and Hyrule Field, main 71b1edd8 against this PR interleaved; Field 44.6 vs 39.1 fps, Kokiri unsettled; the fast path's log lines show it on and taken
Author
Member

Correction to the numbers in the description, before anyone reads too much into them: main's own runs in the same job kept getting faster as the session warmed up (Hyrule Field 40.85, 37.38, then 43.66 and 51.12 fps in the next PR's set; Kokiri 31.25 to 38.48), so this PR's Field gain (44.6 against 39.1) is within that drift and not shown yet. I'm re-running main against this PR with the game warm (the same order, main, PR, PR, main, both scenes) and will replace the Measurements with those; it stays WIP until then.

Correction to the numbers in the description, before anyone reads too much into them: main's own runs in the same job kept getting faster as the session warmed up (Hyrule Field 40.85, 37.38, then 43.66 and 51.12 fps in the next PR's set; Kokiri 31.25 to 38.48), so this PR's Field gain (44.6 against 39.1) is within that drift and not shown yet. I'm re-running main against this PR with the game warm (the same order, main, PR, PR, main, both scenes) and will replace the Measurements with those; it stays WIP until then.
dyst force-pushed perf/invalidate-fast-path from b2e0ebdc9f
Some checks failed
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been skipped
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been skipped
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been skipped
Third-party parts / The same as upstream (pull_request) Has been skipped
Website / Website on Cloudflare (pull_request) Has been skipped
CI / Conventional Commit title (pull_request) Successful in 7s
PR description / Description follows the template (pull_request_target) Successful in 9s
Guide screenshots / Guide images and local UI source review (pull_request) Failing after 11s
CI / Workflow lint (actionlint) (pull_request) Successful in 11s
Third-party parts / As their notes say (pull_request) Successful in 13s
Website / Website on Cloudflare (pull_request_target) Has been skipped
to 5ea93a5849
Some checks failed
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been skipped
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been skipped
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been skipped
Third-party parts / The same as upstream (pull_request) Has been skipped
Website / Website on Cloudflare (pull_request) Has been skipped
CI / Conventional Commit title (pull_request) Successful in 8s
Guide screenshots / Guide images and local UI source review (pull_request) Failing after 14s
CI / Workflow lint (actionlint) (pull_request) Successful in 16s
Third-party parts / As their notes say (pull_request) Successful in 18s
PR description / Description follows the template (pull_request_target) Successful in 6s
2026-11-16 17:11:53 +00:00
Compare
Author
Member

The warm re-run is in, and it replaces the Measurements (the first set was taken while the session was still warming up, as the correction above said).

With the session warm, main @ 71b1edd8 against this PR @ b2e0ebdc, main, PR, PR, main, Windows 11, RTX 3080:

  • Hyrule Field: 51.4 fps against 50.5 (+1.7%), each build's two runs within 0.1 fps, both of this PR's above both of main's; 1% low 30.0 against 27.3 (+10%).
  • Kokiri, camera turning: level (37.7 against 38.3, inside the scene's own 2 fps spread). The cold set's Kokiri "loss" was the warm-up.
  • The fast path is taken: 31,444 kept / 2,604 gave up on the busiest worker.

Also rebased onto main @ 55e8fbd5 (head 5ea93a58, no conflict, the same patches; MKWVK_API_VERSION still 25 -> 26 there). The checks that read the diff run again on it next, then this leaves WIP.

The warm re-run is in, and it replaces the Measurements (the first set was taken while the session was still warming up, as the correction above said). With the session warm, main @ 71b1edd8 against this PR @ b2e0ebdc, main, PR, PR, main, Windows 11, RTX 3080: - **Hyrule Field: 51.4 fps against 50.5** (+1.7%), each build's two runs within 0.1 fps, both of this PR's above both of main's; **1% low 30.0 against 27.3** (+10%). - **Kokiri, camera turning: level** (37.7 against 38.3, inside the scene's own 2 fps spread). The cold set's Kokiri "loss" was the warm-up. - The fast path is taken: 31,444 kept / 2,604 gave up on the busiest worker. Also rebased onto main @ 55e8fbd5 (head 5ea93a58, no conflict, the same patches; `MKWVK_API_VERSION` still 25 -> 26 there). The checks that read the diff run again on it next, then this leaves WIP.
Author
Member

The checks that read the diff, on the rebased head 5ea93a58: 186 passed, 32 skipped, 8 failed, each of the 8 failing on a clean main @ 55e8fbd5 too (named in Testing). Out of WIP.

The checks that read the diff, on the rebased head 5ea93a58: 186 passed, 32 skipped, 8 failed, each of the 8 failing on a clean main @ 55e8fbd5 too (named in Testing). Out of WIP.
dyst changed title from WIP: perf(runtime): keep the virtual core for an invalidate with nothing to wait for to perf(runtime): keep the virtual core for an invalidate with nothing to wait for 2026-11-16 17:40:08 +00:00
Some checks failed
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been skipped
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been skipped
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been skipped
Third-party parts / The same as upstream (pull_request) Has been skipped
Website / Website on Cloudflare (pull_request) Has been skipped
CI / Conventional Commit title (pull_request) Successful in 8s
Guide screenshots / Guide images and local UI source review (pull_request) Failing after 14s
CI / Workflow lint (actionlint) (pull_request) Successful in 16s
Third-party parts / As their notes say (pull_request) Successful in 18s
PR description / Description follows the template (pull_request_target) Successful in 6s
This pull request has changes conflicting with the target branch.
  • gpu/vk/vk_memory.cpp
  • gpu/vk/vk_replay.cpp
  • tests/test_late_fix_build.py
View command line instructions

Manual merge helper

Use this merge commit message when completing the merge manually.

Checkout

From your project repository, check out a new branch and test the changes.
git fetch -u 'perf/invalidate-fast-path:dyst-perf/invalidate-fast-path'
git switch 'dyst-perf/invalidate-fast-path'
Sign in to join this conversation.
No reviewers
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
MagicBeanDev/Longshot!1150
No description provided.