WIP: feat(vk): the renderer's switches in the switch store: nine draw, submit, pipeline-wait and memory switches change during a run #2209

Draft
dyst wants to merge 4 commits from dyst/Longshot:feat/switch-store-renderer into main
Member

Summary

#2185 made 16 of the host's switches change during a run, set and applied through the control bridge (switch_set, switch_apply) and alternated by HOS_AB. This PR gives the renderer the same store and lists its first nine switches. They can then be tried at another value with no restart, and A/B'd in one run:

  • Draw and submit:
    • RX_VK_INDEX_REBASE, each draw's index bind. bind_index compares the buffer, offset and type, so rebased and plain binds mix in one command buffer;
    • RX_VK_PUSH_ALL, each descriptor push.
  • Submit batching: RX_VK_BATCH_MAX (each held submit), RX_VK_BATCH_POLL_US (each progress poll).
  • Waiting for pipelines: RX_VK_QUICK_MS, RX_VK_PIPE_WAIT_MS and RX_VK_TRANSLATE_WAIT_MS, the budgets each frame is refilled from. Each is logged when it changes.
  • Memory:
    • RX_VK_TARGET_POOL_MB: pool_trim asks it at every present. The rule's size is still worked out once, by what the driver allows at the first look;
    • RX_VK_COMPACT_PCT: each compaction pass.

How it reads the store:

  • The interface: the host-renderer interface, version 45, adds sw_env (a switch's text as the game reads it now) and sw_gen (the store's generation).
  • The readers: gpu/vk/vk_live.h gives the renderer the host's reader pattern (vk_sw_env, vk_sw_on, vk_sw_int, vk_sw_due, vk_sw_seen). Each reader keeps its value with its own rule, default and clamps, and works it out again when the generation has moved: two loads a use, no lock.
  • When a change lands: at each reader's next use, wherever in a frame that is. So a frame may draw with both values, and only switches whose every use stands alone are listed.
  • Old hosts: with a host older than 45, a switch's text is the environment's and is read once, as before.

Stacked on #2185: this PR carries #2185's commits until it merges. The new commit is the last one.

Left out on purpose:

  • RX_VK_VRAM_MB: on an integrated GPU, texture_frame works the texture budget out again every pass from its own last value (driver_budget = own; own = integrated_texture_budget(driver_budget, …)). That wants untangling, and a look at whether it is meant, before the budget can change.
  • The switches that must change only at a frame's boundary. That needs an apply at the render thread's frame start, a change of its own.

Read first: gpu/vk/vk_live.h, the MkwVkHost addition in gpu/vk/vk_api.h and host/rx_backend.c, then one converted reader, batch_max in gpu/vk/vk_replay.cpp.

Testing

Tested: nothing yet. Not compiled, not run in the game and no checks run, by the request of the person I work for: opened untested.

  • Checks adapted, none run yet:
    • The checks that cut a converted function take stand-ins for vk_live.h: test_quick_pipelines, test_draw_side_effects, sampler_admission_test. The last answers RX_VK_PUSH_ALL through its own getenv; vk_live.h calls an unqualified getenv for that reason.
    • test_target_image_pool, test_vram_compact and test_quick_pipelines read the store's call in the source.
    • test_hos_ab's table of the host's functions gains hos_sw_env.
    • test_switch_store holds the nine reads to the store.

Still to test:

  • Windows, any GPU: build this PR, start the game with HOS_CONTROL set, switch_set RX_VK_BATCH_MAX 4 with apply true, then RX_VK_TARGET_POOL_MB 0 the same way. Expecting changed: 1 each time, the log's switches: applied lines, and the game playing on (by hand)
  • Windows, any GPU: HOS_AB=RX_VK_INDEX_REBASE=0,3,20 for a minute of play, expecting the A/B's end line with both sides' frames and no visual change (by hand)
  • Windows, any GPU: tests/run_all.py --changed, expecting no check failing that passes on main (by hand)
  • Linux, any GPU: build this PR and start it to the title (@Beanstalk)

Measurements

Not measured yet. Nothing has run. What it costs with nothing set, an extra load at each read of these nine switches, wants a dev.py ab against main before it leaves WIP.

Risks

  • Nothing set, nothing changes: the readers' rules, defaults and clamps are as before, and the text is the environment's.
  • A changed value can land mid-frame: the nine are those whose each use stands alone, so a frame drawn with both values is one that ran with both.
  • The interface moves to version 45: whichever of this and another PR that takes 45 lands second renumbers.
  • Turning it off: don't send switch_set; reverting is enough.

Checklist

Ready for review

  • One topic, on current main; the title is a Conventional Commit.
  • Tested on my own PC, in the game for a change the game runs, as Testing says. Not yet: opened untested.
  • mise run test passes (any failure that also fails on main is named). Not run yet.
  • Measured against main, or Measurements says why there is nothing to measure. Not yet.
  • No game files, build output or hand-edited generated files; third_party/ untouched; nothing GPL-incompatible.

When it applies

  • A check under tests/ that reads changed source is updated, not weakened.
  • MKWVK_API_VERSION bumped (MkwVkHost or MkwVkRenderer in gpu/vk/vk_api.h changed).
  • Host code builds on Windows (llvm-mingw) and Linux, with UTF-8 paths. Not built yet.
  • Docs updated.
  • AI assistance recorded with Assisted-by: / Co-Authored-By: trailers.

Ready to merge

  • Everything in Still to test has run, its results in Tested.
  • Tier 1 hardware it can affect is tested (docs/dev/standards.md, "Hardware tiers").
  • Approved in review, every comment answered.
  • CI passes on the head; on current main, measured again or a comment says why the numbers still hold.

🤖 Generated with Claude Code

## Summary #2185 made 16 of the host's switches change during a run, set and applied through the control bridge (`switch_set`, `switch_apply`) and alternated by `HOS_AB`. This PR gives the renderer the same store and lists its first nine switches. They can then be tried at another value with no restart, and A/B'd in one run: - **Draw and submit:** - `RX_VK_INDEX_REBASE`, each draw's index bind. `bind_index` compares the buffer, offset and type, so rebased and plain binds mix in one command buffer; - `RX_VK_PUSH_ALL`, each descriptor push. - **Submit batching:** `RX_VK_BATCH_MAX` (each held submit), `RX_VK_BATCH_POLL_US` (each progress poll). - **Waiting for pipelines:** `RX_VK_QUICK_MS`, `RX_VK_PIPE_WAIT_MS` and `RX_VK_TRANSLATE_WAIT_MS`, the budgets each frame is refilled from. Each is logged when it changes. - **Memory:** - `RX_VK_TARGET_POOL_MB`: `pool_trim` asks it at every present. The rule's size is still worked out once, by what the driver allows at the first look; - `RX_VK_COMPACT_PCT`: each compaction pass. **How it reads the store:** - **The interface:** the host-renderer interface, version 45, adds `sw_env` (a switch's text as the game reads it now) and `sw_gen` (the store's generation). - **The readers:** `gpu/vk/vk_live.h` gives the renderer the host's reader pattern (`vk_sw_env`, `vk_sw_on`, `vk_sw_int`, `vk_sw_due`, `vk_sw_seen`). Each reader keeps its value with its own rule, default and clamps, and works it out again when the generation has moved: two loads a use, no lock. - **When a change lands:** at each reader's next use, wherever in a frame that is. So a frame may draw with both values, and only switches whose every use stands alone are listed. - **Old hosts:** with a host older than 45, a switch's text is the environment's and is read once, as before. **Stacked on #2185:** this PR carries #2185's commits until it merges. The new commit is the last one. **Left out on purpose:** - `RX_VK_VRAM_MB`: on an integrated GPU, `texture_frame` works the texture budget out again every pass from its own last value (`driver_budget = own; own = integrated_texture_budget(driver_budget, …)`). That wants untangling, and a look at whether it is meant, before the budget can change. - The switches that must change only at a frame's boundary. That needs an apply at the render thread's frame start, a change of its own. Read first: `gpu/vk/vk_live.h`, the `MkwVkHost` addition in `gpu/vk/vk_api.h` and `host/rx_backend.c`, then one converted reader, `batch_max` in `gpu/vk/vk_replay.cpp`. ## Testing **Tested:** nothing yet. Not compiled, not run in the game and no checks run, by the request of the person I work for: opened untested. - **Checks adapted, none run yet:** - The checks that cut a converted function take stand-ins for `vk_live.h`: `test_quick_pipelines`, `test_draw_side_effects`, `sampler_admission_test`. The last answers `RX_VK_PUSH_ALL` through its own `getenv`; `vk_live.h` calls an unqualified `getenv` for that reason. - `test_target_image_pool`, `test_vram_compact` and `test_quick_pipelines` read the store's call in the source. - `test_hos_ab`'s table of the host's functions gains `hos_sw_env`. - `test_switch_store` holds the nine reads to the store. **Still to test:** - Windows, any GPU: build this PR, start the game with `HOS_CONTROL` set, `switch_set RX_VK_BATCH_MAX 4` with `apply` true, then `RX_VK_TARGET_POOL_MB 0` the same way. Expecting `changed: 1` each time, the log's `switches: applied` lines, and the game playing on (by hand) - Windows, any GPU: `HOS_AB=RX_VK_INDEX_REBASE=0,3,20` for a minute of play, expecting the A/B's end line with both sides' frames and no visual change (by hand) - Windows, any GPU: `tests/run_all.py --changed`, expecting no check failing that passes on main (by hand) - Linux, any GPU: build this PR and start it to the title (@Beanstalk) ## Measurements Not measured yet. Nothing has run. What it costs with nothing set, an extra load at each read of these nine switches, wants a `dev.py ab` against main before it leaves WIP. ## Risks - **Nothing set, nothing changes:** the readers' rules, defaults and clamps are as before, and the text is the environment's. - **A changed value can land mid-frame:** the nine are those whose each use stands alone, so a frame drawn with both values is one that ran with both. - **The interface moves to version 45:** whichever of this and another PR that takes 45 lands second renumbers. - **Turning it off:** don't send `switch_set`; reverting is enough. ## Checklist ### Ready for review - [x] One topic, on current `main`; the title is a Conventional Commit. - [ ] Tested on my own PC, in the game for a change the game runs, as Testing says. Not yet: opened untested. - [ ] `mise run test` passes (any failure that also fails on `main` is named). Not run yet. - [ ] Measured against `main`, or Measurements says why there is nothing to measure. Not yet. - [x] No game files, build output or hand-edited generated files; `third_party/` untouched; nothing GPL-incompatible. ### When it applies - [x] A check under `tests/` that reads changed source is updated, not weakened. - [x] `MKWVK_API_VERSION` bumped (`MkwVkHost` or `MkwVkRenderer` in `gpu/vk/vk_api.h` changed). - [ ] Host code builds on Windows (llvm-mingw) and Linux, with UTF-8 paths. Not built yet. - [x] Docs updated. - [x] AI assistance recorded with `Assisted-by:` / `Co-Authored-By:` trailers. ### Ready to merge - [ ] Everything in Still to test has run, its results in Tested. - [ ] Tier 1 hardware it can affect is tested (docs/dev/standards.md, "Hardware tiers"). - [ ] Approved in review, every comment answered. - [ ] CI passes on the head; on current `main`, measured again or a comment says why the numbers still hold. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
A switch was read once, as the game starts, so trying another value meant a restart. Sixteen of the host's switches now
change during a run (gpu/vk/switches_live.def): the spin and short-sleep timings (HOS_SPIN_US, HOS_SPIN_OTHER_US,
HOS_SHORT_SLEEP_TIMER, HOS_SHORT_SLEEP_POLLERS, HOS_POLL_SLEEP_NS), the virtual cores' four timings (HOS_VCORE_SLICE_US,
_STARVE_US, _ESCAPE_US, _ESCAPE_EQ_US), and the present and pacing ones (HOS_PRESENT_NOWAIT, HOS_PRESENT_POLL,
HOS_NVN_SYNC_BLOCK, HOS_NO_PACING, HOS_VI_DOUBLE, HOS_GAME_INTERVAL, HOS_VSYNC_YIELD). Each is decided again at every use,
so a change between two uses leaves nothing the old value built.

host/switch_store.c holds their text: the environment's (and longshot_env.txt's), taken before the game's threads start,
until an apply gives one another. Each reader keeps its value, with its own rule, default and clamps, as before, and works
it out again when the store's generation has moved (hos_sw_due, hos_sw_seen): a use costs two loads, and no read takes a
lock. The control bridge's switch_set gives one a value for the next apply, switch_apply applies (switch_set with "apply"
does both), switch_list and switch_get say what each switch reads now and has pending. A switch read once at the start is
refused (at_start), as is a name that is no switch or a value its type does not take. HOS_AB alternates a store switch by
setting and applying its value at each change of side, so any of them can be A/B'd in one run.

tests/test_switch_store.py holds every read of a listed switch to the store and compiles the store with a fixture (set,
apply, refusals, four threads reading through 2000 applies, broken variants caught); test_control and test_hos_ab cover
the bridge's commands and the A/B's sets. The checks that cut a converted reader from the source take the store's header
and a stand-in that reads the environment (tests/switch_store_stub.h).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
scripts/longshot_bridge.py sends no argument whose value is None, so a script could not unset a switch with
"value": null: the bridge took it as no value and refused. "unset": true does the same as a null value, and is refused
with a value beside it.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
fix(test): the two virtual-core checks take the switch store's stand-in
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 10s
Guide screenshots / Guide images and local UI source review (pull_request) Failing after 13s
CI / Workflow lint (actionlint) (pull_request) Successful in 14s
Third-party parts / As their notes say (pull_request) Successful in 16s
PR description / Description follows the template (pull_request_target) Successful in 5s
CI / Website build and checks (pull_request) Failing after 19s
ed6ce62dfe
test_vcore_escape and test_vcore_mask0 cut host/hos_thread.c's virtual-core block, where vc_acquire's four timings now
come from the switch store (vc_sw_ns, hos_sw_due): like the other checks that cut a converted reader, their fixtures
take tests/switch_store_stub.h, the store's header and a stand-in that reads the environment.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
feat(vk): the renderer's switches in the switch store: nine draw, submit, pipeline-wait and memory switches change during a run
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 9s
Website / Website on Cloudflare (pull_request_target) Has been skipped
Guide screenshots / Guide images and local UI source review (pull_request) Failing after 16s
CI / Workflow lint (actionlint) (pull_request) Successful in 16s
Third-party parts / As their notes say (pull_request) Successful in 17s
PR description / Description follows the template (pull_request_target) Successful in 40s
CI / Website build and checks (pull_request) Failing after 50s
1d6be3bb07
The renderer reads the host's switch store (host/switch_store.c) through MkwVkHost, version 45 (sw_env, sw_gen), with the
host's reader pattern (gpu/vk/vk_live.h: vk_sw_env, vk_sw_on, vk_sw_int, vk_sw_due, vk_sw_seen): each reader keeps its
value with its own rule, default and clamps, and works it out again when the store's generation has moved. Nine switches
join gpu/vk/switches_live.def, each one whose every use stands alone:

- RX_VK_INDEX_REBASE (each draw's index bind: bind_index compares buffer, offset and type, so rebased and plain binds mix),
  RX_VK_PUSH_ALL (each descriptor push);
- RX_VK_BATCH_MAX (each held submit), RX_VK_BATCH_POLL_US (each progress poll);
- RX_VK_QUICK_MS, RX_VK_PIPE_WAIT_MS, RX_VK_TRANSLATE_WAIT_MS (the budgets each frame is refilled from; logged when they
  change);
- RX_VK_TARGET_POOL_MB (pool_trim at every present; the rule's size still worked out once, at the first look),
  RX_VK_COMPACT_PCT (each compaction pass).

A changed value reaches each reader at its next use, wherever in a frame that is. With a host older than 45 the text is
the environment's and the generation never moves. RX_VK_VRAM_MB stays read once: on an integrated GPU its budget is
worked out again every pass from its own last value, which wants untangling first.

The checks that cut a converted function take stand-ins for vk_live.h (test_quick_pipelines, test_draw_side_effects,
sampler_admission_test); test_target_image_pool, test_vram_compact and test_quick_pipelines read the store's call;
test_hos_ab's table gains hos_sw_env.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
dazemc left a comment

A live change can land inside a frame-wide budget or a memory pass, so five of the nine do not meet the "each use stands alone" rule. Read from the source, not run here.

RX_VK_QUICK_MS, RX_VK_PIPE_WAIT_MS and RX_VK_TRANSLATE_WAIT_MS are per-frame budgets, not per-draw values: quick_budget_ms(), pipe_wait_budget_ms() and the translate reader return the new total at each draw while quick_pipe::FrameBudget / the wait budget is keyed by the frame, so one frame can run with two budgets. RX_VK_TARGET_POOL_MB is asked by pool_trim at every present and RX_VK_COMPACT_PCT by each compaction pass; both can free or compact images within a frame, not only between draws. That may be safe, but it is not a frame boundary, and "nothing rebuilt" is not the same as "nothing changed". The docs already say "a frame may draw with both values"; for these five the unit of use is a frame or a pass, so the criterion in the description ("every use stands alone") is weaker than it reads. Either move these five to a frame-start apply (the PR's own "left out on purpose" bucket) or state per switch why a mid-frame change is safe; do not list a frame budget as a per-use value.

The test gap is the same shape. tests/test_switch_store.py fails on main because host/switch_store.c and switches_live.def do not exist (so it is more than a switch-table parse): it compiles and runs the store, covers set/apply/refusals, hos_sw_each, the path redaction, and four readers against 2000 applies. But it exercises HOS_SPIN_US only. test_quick_pipelines, test_draw_side_effects and sampler_admission_test stub vk_sw_due() to return 1 once, so a second generation never reaches a renderer reader. No check changes any of the nine renderer switches live or asserts the effect (a rebased bind, a batch cap flush, a quick/pipe budget, a pool cap or compaction percentage). Add one live change per reader kind (bool, int, float, string), or at least one per section, and assert the effect rather than only that the name is read through the store.

Q1: all nine keep their switches.def rows; none is player, so there is no longshot_options.ini key to lose and no settings break. The new switches.md section covers the list (only QUICK_MS and TRANSLATE_WAIT_MS have individual rows, which is the page's stated scope). Q3: the writer is the control thread under switch_store.c's lock; readers are lock-free with atomic pointers and generation, and the texts are kept for the run (old texts are not freed, deliberately, so a reader may hold one; that is a slow leak, not a race). Q5: no overlap with #2215/#2216 or the menu keys/ini table; the shared surface is switches.def's sort/test. MKWVK_API_VERSION 45 is a collision point for any other interface PR. vk_replay.cpp overlaps #2211/#2212 only by file (rebase), so a measurement must pin RX_VK_ASYNC_PARTS and RX_VK_ASYNC_FENCES on both arms; the #1988 drain shares vk_texture.cpp but not these hunks.

No fix claim; the PR is WIP and nothing has run yet.

**A live change can land inside a frame-wide budget or a memory pass, so five of the nine do not meet the "each use stands alone" rule.** Read from the source, not run here. `RX_VK_QUICK_MS`, `RX_VK_PIPE_WAIT_MS` and `RX_VK_TRANSLATE_WAIT_MS` are per-frame budgets, not per-draw values: `quick_budget_ms()`, `pipe_wait_budget_ms()` and the translate reader return the new total at each draw while `quick_pipe::FrameBudget` / the wait budget is keyed by the frame, so one frame can run with two budgets. `RX_VK_TARGET_POOL_MB` is asked by `pool_trim` at every present and `RX_VK_COMPACT_PCT` by each compaction pass; both can free or compact images within a frame, not only between draws. That may be safe, but it is not a frame boundary, and "nothing rebuilt" is not the same as "nothing changed". The docs already say "a frame may draw with both values"; for these five the unit of use is a frame or a pass, so the criterion in the description ("every use stands alone") is weaker than it reads. Either move these five to a frame-start apply (the PR's own "left out on purpose" bucket) or state per switch why a mid-frame change is safe; do not list a frame budget as a per-use value. **The test gap is the same shape.** `tests/test_switch_store.py` fails on main because `host/switch_store.c` and `switches_live.def` do not exist (so it is more than a switch-table parse): it compiles and runs the store, covers set/apply/refusals, `hos_sw_each`, the path redaction, and four readers against 2000 applies. But it exercises `HOS_SPIN_US` only. `test_quick_pipelines`, `test_draw_side_effects` and `sampler_admission_test` stub `vk_sw_due()` to return 1 once, so a second generation never reaches a renderer reader. No check changes any of the nine renderer switches live or asserts the effect (a rebased bind, a batch cap flush, a quick/pipe budget, a pool cap or compaction percentage). Add one live change per reader kind (bool, int, float, string), or at least one per section, and assert the effect rather than only that the name is read through the store. **Q1:** all nine keep their `switches.def` rows; none is `player`, so there is no `longshot_options.ini` key to lose and no settings break. The new `switches.md` section covers the list (only QUICK_MS and TRANSLATE_WAIT_MS have individual rows, which is the page's stated scope). **Q3:** the writer is the control thread under `switch_store.c`'s lock; readers are lock-free with atomic pointers and generation, and the texts are kept for the run (old texts are not freed, deliberately, so a reader may hold one; that is a slow leak, not a race). **Q5:** no overlap with #2215/#2216 or the menu keys/ini table; the shared surface is `switches.def`'s sort/test. `MKWVK_API_VERSION` 45 is a collision point for any other interface PR. `vk_replay.cpp` overlaps #2211/#2212 only by file (rebase), so a measurement must pin `RX_VK_ASYNC_PARTS` and `RX_VK_ASYNC_FENCES` on both arms; the #1988 drain shares `vk_texture.cpp` but not these hunks. No fix claim; the PR is WIP and nothing has run yet.
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 9s
Website / Website on Cloudflare (pull_request_target) Has been skipped
Guide screenshots / Guide images and local UI source review (pull_request) Failing after 16s
CI / Workflow lint (actionlint) (pull_request) Successful in 16s
Third-party parts / As their notes say (pull_request) Successful in 17s
PR description / Description follows the template (pull_request_target) Successful in 40s
CI / Website build and checks (pull_request) Failing after 50s
This pull request is marked as a work in progress.
View command line instructions

Checkout

From your project repository, check out a new branch and test the changes.
git fetch -u 'feat/switch-store-renderer:dyst-feat/switch-store-renderer'
git switch 'dyst-feat/switch-store-renderer'
Sign in to join this conversation.
No reviewers
No milestone
No project
No assignees
2 participants
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!2209
No description provided.