WIP: feat(build): one shader that crashes or hangs the GPU driver costs the preparation that shader, not the whole run #1386

Closed
HumanBean wants to merge 4 commits from HumanBean/Longshot:feat/prepare-supervisor into main
Owner

Type: feat · Risk: medium · Tested on: Linux, RTX 3090 · Needs: Windows (the Builder there, and a real driver fault); Intel

Why

After a build the Builder runs longshot --prepare-shaders, which has the GPU driver compile every shader and pipeline before the first start. It is all or nothing: one shader that crashes or hangs the driver's compiler loses the whole run, and the work falls to the game's own first start, where the same shader meets the same driver inside the game. The in-process guards catch such a fault but leave the driver's state behind it. Track E of the renderer rework plan, step 1. Stacked on #1309: review the last commit only.

How much it helps, honestly: of 55 crash reports grouped for the plan, about 5 are in the shader phase or inside a driver. Most device-lost reports are during play, which this does not touch.

What changed

  • A journal (gpu/vk/prepare_journal.h): in a preparation run started with --prepare-journal <file>, each call into the driver's compiler writes a begin line before it and an end line after, flushed to the OS first, so the entry that was open survives the process dying. An entry is named exactly as longshot_driver_faults.txt names a program. Play pays one test of a flag.
  • A per-entry limit (--prepare-entry-limit, 240 s from the Builder): an entry open longer ends the run with exit status 6 and a line naming it. The whole-run watchdog and exit codes 3 and 4 are as they were.
  • A supervisor (nx2/prepare_supervisor.py, used by nx2/make_game.py and scripts/dev_packs.py): when the run dies, hangs or exits 6, it reads the journal, names the program that was inside the driver, appends it to longshot_driver_faults.txt for that driver version, and starts again past it. With several programs open it starts again building those one at a time, so a neighbour is never blamed. Bounds: 8 programs, 20 starts; past them it gives up as today. It writes cache/longshot_prepare_results.txt.
  • The game needs no change to honour it: it already leaves out programs listed in that file, with a log line, until the driver's version changes.
  • RX_VK_TEST_PREPARE_FAULT (diagnostic) crashes or hangs a chosen program in a journalled preparation, to test all of this. Five rows in gpu/vk/switches.def; docs/development/shader-preparation.md (new).

No file of the shader translation's stamp is edited: nobody's shaders translate again.

Measurements

Nothing to measure in play. The preparation itself: a clean run journalled 259,795 entries and ended prepared; its duration with and without the journal was not compared.

Testing

Tested: Linux, RTX 3090 (NVIDIA 620.70), a dev runtime:

  • A clean supervised preparation: 259,795 entries built, 0 left out.
  • Forced crashes (RX_VK_TEST_PREPARE_FAULT=crash:5000, five programs): 11 runs, each culprit named (with nine programs open at once, the suspects were rebuilt one at a time and the right one found), five lines in longshot_driver_faults.txt, and the preparation ended prepared.
  • A forced hang with a 20 s limit: vk: preparation: STOPPED: entry 153032 (program 1f2e258ec71b4c98) has been inside the GPU driver for 20 s, exit 6, the program left out, the second run prepared.
  • The game after it: vk: 5 programs the driver faulted on in earlier runs are not asked of it, then Kokiri Forest and Hyrule Field at main's frame rates (67.1 and 92.8 fps), no error line.
shader preparation: the game ended with 9 programs inside the GPU driver; started again with those built one at a time, to find which it was
shader preparation: the GPU driver ended the game compiling a shader module of program 1f2e258ec71b4c98: that program is left out on this driver
shader preparation: 5 programs left out on this GPU driver (.../cache/longshot_prepare_results.txt; a driver update tries them again)

Known wrong: the result file's totals said crashed 0 and timed-out 0 while its rows for the programs left out were right.

Not tested:

  • tests/run_all.py, and the two new checks.
  • Windows: not compiled, not run. The exit status of a crash under the host's crash filter there is not known, and one that came out as 3 or 4 would be read as "no Vulkan" or "stalled".
  • A real driver fault. The forced ones are a null write and a sleep inside the entry.
  • The Builder itself (nx2/make_game.py): the supervisor was run directly and through dev_build.py rt.

Must be tested:

  • Windows, through the Builder: a build with RX_VK_TEST_PREPARE_FAULT=crash:5000 set, expecting the same supervisor lines and a game that starts; then the same with hang:5000.
  • An Intel GPU: a normal build. The 240 s limit may be too short there: one optimized compute compile on a UHD was measured at 389 s, and it would now be left out on that driver, where before the whole preparation was skipped and the game compiled it in play.

Risks

What could break: a slow but finite compile is left out (missing draws for that program until the driver updates); a program is blamed wrongly if the journal names the wrong one for a pipeline; the preparation takes longer when it restarts.

Turning it off: LONGSHOT_PREPARE_ENTRY_S=0 in the Builder's environment turns the per-entry limit off. Deleting cache/longshot_driver_faults.txt tries every program again.

Compatibility: none: no cache is rebuilt, MKWVK_API_VERSION stays. The preparation's exit code 6 is new.

Issues

See #1300

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). Not run on this PC; left to the forge's checks.
  • 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.
  • 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. Built on Linux only here.
  • Docs updated.

🤖 Generated with Claude Code

https://claude.ai/code/session_017vw8dzCsAL3UdW7ft8ptL9

**Type:** feat · **Risk:** medium · **Tested on:** Linux, RTX 3090 · **Needs:** Windows (the Builder there, and a real driver fault); Intel ## Why After a build the Builder runs `longshot --prepare-shaders`, which has the GPU driver compile every shader and pipeline before the first start. It is all or nothing: one shader that crashes or hangs the driver's compiler loses the whole run, and the work falls to the game's own first start, where the same shader meets the same driver inside the game. The in-process guards catch such a fault but leave the driver's state behind it. Track E of the [renderer rework plan](https://git.magicbean.dev/MagicBeanDev/Longshot/wiki/Renderer-rework-plan), step 1. Stacked on #1309: review the last commit only. How much it helps, honestly: of 55 crash reports grouped for the plan, about 5 are in the shader phase or inside a driver. Most device-lost reports are during play, which this does not touch. ## What changed - **A journal** (`gpu/vk/prepare_journal.h`): in a preparation run started with `--prepare-journal <file>`, each call into the driver's compiler writes a begin line before it and an end line after, flushed to the OS first, so the entry that was open survives the process dying. An entry is named exactly as `longshot_driver_faults.txt` names a program. Play pays one test of a flag. - **A per-entry limit** (`--prepare-entry-limit`, 240 s from the Builder): an entry open longer ends the run with exit status 6 and a line naming it. The whole-run watchdog and exit codes 3 and 4 are as they were. - **A supervisor** (`nx2/prepare_supervisor.py`, used by `nx2/make_game.py` and `scripts/dev_packs.py`): when the run dies, hangs or exits 6, it reads the journal, names the program that was inside the driver, appends it to `longshot_driver_faults.txt` for that driver version, and starts again past it. With several programs open it starts again building those one at a time, so a neighbour is never blamed. Bounds: 8 programs, 20 starts; past them it gives up as today. It writes `cache/longshot_prepare_results.txt`. - **The game needs no change to honour it:** it already leaves out programs listed in that file, with a log line, until the driver's version changes. - `RX_VK_TEST_PREPARE_FAULT` (diagnostic) crashes or hangs a chosen program in a journalled preparation, to test all of this. Five rows in `gpu/vk/switches.def`; `docs/development/shader-preparation.md` (new). No file of the shader translation's stamp is edited: nobody's shaders translate again. ## Measurements Nothing to measure in play. The preparation itself: a clean run journalled 259,795 entries and ended `prepared`; its duration with and without the journal was not compared. ## Testing **Tested:** Linux, RTX 3090 (NVIDIA 620.70), a dev runtime: - A clean supervised preparation: 259,795 entries built, 0 left out. - **Forced crashes** (`RX_VK_TEST_PREPARE_FAULT=crash:5000`, five programs): 11 runs, each culprit named (with nine programs open at once, the suspects were rebuilt one at a time and the right one found), five lines in `longshot_driver_faults.txt`, and the preparation ended `prepared`. - **A forced hang** with a 20 s limit: `vk: preparation: STOPPED: entry 153032 (program 1f2e258ec71b4c98) has been inside the GPU driver for 20 s`, exit 6, the program left out, the second run `prepared`. - **The game after it:** `vk: 5 programs the driver faulted on in earlier runs are not asked of it`, then Kokiri Forest and Hyrule Field at main's frame rates (67.1 and 92.8 fps), no error line. ``` shader preparation: the game ended with 9 programs inside the GPU driver; started again with those built one at a time, to find which it was shader preparation: the GPU driver ended the game compiling a shader module of program 1f2e258ec71b4c98: that program is left out on this driver shader preparation: 5 programs left out on this GPU driver (.../cache/longshot_prepare_results.txt; a driver update tries them again) ``` **Known wrong:** the result file's totals said `crashed 0` and `timed-out 0` while its rows for the programs left out were right. **Not tested:** - `tests/run_all.py`, and the two new checks. - Windows: not compiled, not run. The exit status of a crash under the host's crash filter there is not known, and one that came out as 3 or 4 would be read as "no Vulkan" or "stalled". - A real driver fault. The forced ones are a null write and a sleep inside the entry. - The Builder itself (`nx2/make_game.py`): the supervisor was run directly and through `dev_build.py rt`. **Must be tested:** - Windows, through the Builder: a build with `RX_VK_TEST_PREPARE_FAULT=crash:5000` set, expecting the same supervisor lines and a game that starts; then the same with `hang:5000`. - An Intel GPU: a normal build. **The 240 s limit may be too short there**: one optimized compute compile on a UHD was measured at 389 s, and it would now be left out on that driver, where before the whole preparation was skipped and the game compiled it in play. ## Risks **What could break:** a slow but finite compile is left out (missing draws for that program until the driver updates); a program is blamed wrongly if the journal names the wrong one for a pipeline; the preparation takes longer when it restarts. **Turning it off:** `LONGSHOT_PREPARE_ENTRY_S=0` in the Builder's environment turns the per-entry limit off. Deleting `cache/longshot_driver_faults.txt` tries every program again. **Compatibility:** none: no cache is rebuilt, `MKWVK_API_VERSION` stays. The preparation's exit code 6 is new. ## Issues See #1300 ## 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`. - [ ] `python -I -B tests/run_all.py` passes (any failure that also fails on `main` is named). Not run on this PC; left to the forge's checks. - [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] 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. Built on Linux only here. - [x] Docs updated. 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_017vw8dzCsAL3UdW7ft8ptL9
refactor(vk): 93 kill switches and the older paths they kept are deleted from the four large renderer files
All checks were successful
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
Guide screenshots / Guide images and local UI source review (pull_request) Successful in 11s
Third-party parts / As their notes say (pull_request) Successful in 14s
CI / Workflow lint (actionlint) (pull_request) Successful in 19s
PR description / Description follows the template (pull_request_target) Successful in 5s
Website / Website on Cloudflare (pull_request_target) Has been skipped
b9805ef295
The renderer rework plan's track F. A kill switch turned off, or back to an older way, something that is on for
every PC; nobody ships with one set, and each kept an old path alive. vk_draw.cpp 32, vk_texture.cpp 21,
vk_replay.cpp 20, vk_memory.cpp 20: the read and the path are gone, the default is the only behaviour, and each name
is a GONE row of gpu/vk/switches.def, so a run that still sets one is told. 26 are kept, each for a reason (a value
set by a tool or named in the README, a default that follows the PC, a young fix's way out).

Co-Authored-By: Claude Fable 5.2 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8dzCsAL3UdW7ft8ptL9
refactor(vk): 18 more kill switches and their older paths are deleted from the smaller renderer files
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
PR description / Description follows the template (pull_request_target) Successful in 13s
Guide screenshots / Guide images and local UI source review (pull_request) Failing after 14s
CI / Workflow lint (actionlint) (pull_request) Successful in 20s
Website / Website on Cloudflare (pull_request_target) Has been skipped
Third-party parts / As their notes say (pull_request) Successful in 23s
5742f65ca1
The renderer rework plan's track F, after the four large files (#1309). vk_vma.cpp, vk_main.cpp, vk_temporal.cpp,
vk_xfer.cpp, vk_dlss.cpp, vk_fsr4.cpp, vk_jobs.cpp, vk_reflex.cpp, vk_framegen.cpp, vk_programs.cpp and vk_progcache.cpp
lose the read and the path; each name is a GONE row of gpu/vk/switches.def. 18 are kept: the README or a script
names them, the shader cache's stamp holds them, or they are a way out that measurement runs or a driver still need.

Co-Authored-By: Claude Fable 5.2 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8dzCsAL3UdW7ft8ptL9
feat(host): the host's switches join the table: every HOS_ and LONGSHOT_ name the game reads has a row
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 13s
Guide screenshots / Guide images and local UI source review (pull_request) Failing after 15s
CI / Workflow lint (actionlint) (pull_request) Successful in 17s
Third-party parts / As their notes say (pull_request) Successful in 17s
Website / Website on Cloudflare (pull_request_target) Has been skipped
PR description / Description follows the template (pull_request_target) Successful in 5s
2e0743237d
The renderer rework plan's track F. gpu/vk/switches.def gains the host's 216 switches (89 diagnostics, 50 that turn
something off, 23 player settings, 24 numbers, 20 that turn on something nobody ships, 8 that follow the PC), read
once each from the code. The start's report names them when set and says a HOS_ name that is none; a LONGSHOT_ name
that is none is passed over (the launcher and the Builder have their own). The host's three removed HOS_ names become
GONE rows.

Co-Authored-By: Claude Fable 5.2 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8dzCsAL3UdW7ft8ptL9
feat(build): one shader that crashes or hangs the GPU driver costs the preparation that shader, not the whole 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 7s
PR description / Description follows the template (pull_request_target) Successful in 10s
Guide screenshots / Guide images and local UI source review (pull_request) Failing after 10s
CI / Workflow lint (actionlint) (pull_request) Successful in 12s
Third-party parts / As their notes say (pull_request) Successful in 15s
Website / Website on Cloudflare (pull_request_target) Has been skipped
973ff04b6c
The renderer rework plan's track E, step 1. The preparation the Builder runs after a build (longshot
--prepare-shaders) keeps a journal of each call into the driver's compiler; nx2/prepare_supervisor.py reads it when
the run dies, hangs or passes an entry's limit, names the program that was inside the driver (building suspects one
at a time when several were), appends it to longshot_driver_faults.txt for that driver version, and starts again
past it. The game already leaves such a program out. docs/development/shader-preparation.md has the journal, the
arguments, the exit codes and the bounds; RX_VK_TEST_PREPARE_FAULT crashes or hangs a chosen program to test it.

Co-Authored-By: Claude Fable 5.2 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8dzCsAL3UdW7ft8ptL9
Author
Owner

Tested in game: Linux, RTX 3090, NVIDIA 620.70: a clean supervised preparation (259,795 entries), forced crashes of five programs and a forced hang each isolated and quarantined, then a game start that logged the 5 programs left out and played Kokiri Forest and Hyrule Field at main's frame rates.

Tested in game: Linux, RTX 3090, NVIDIA 620.70: a clean supervised preparation (259,795 entries), forced crashes of five programs and a forced hang each isolated and quarantined, then a game start that logged the 5 programs left out and played Kokiri Forest and Hyrule Field at main's frame rates.
Collaborator

Possibly related, for context:

  • issue #462 Game: shader preparation hard-freezes the whole PC (no TDR, no watchdog) — RX 9070 XT, Windows — Requests per-shader quarantine after preparation hang
  • issue #407 Game: up-front shader preparation does not finish on Intel Arc (Windows) with compiles one at a time — Intel shader preparation stalls; limit may affect it
  • issue #1356 Install: Linux Arc B580 shader preparation stalls at 38,808 of 38,809 programs — Intel Arc preparation stalls during install
  • PR #517 WIP: fix(vk): free a stalled shader preparation's pipeline notes — Overlapping stalled-preparation worker teardown changes
  • PR #1174 WIP: fix(builder): a preparation the GPU driver stalled is not promised for the first start — Builder handling of driver-stalled preparations
Possibly related, for context: - issue #462 Game: shader preparation hard-freezes the whole PC (no TDR, no watchdog) — RX 9070 XT, Windows — Requests per-shader quarantine after preparation hang - issue #407 Game: up-front shader preparation does not finish on Intel Arc (Windows) with compiles one at a time — Intel shader preparation stalls; limit may affect it - issue #1356 Install: Linux Arc B580 shader preparation stalls at 38,808 of 38,809 programs — Intel Arc preparation stalls during install - PR #517 WIP: fix(vk): free a stalled shader preparation's pipeline notes — Overlapping stalled-preparation worker teardown changes - PR #1174 WIP: fix(builder): a preparation the GPU driver stalled is not promised for the first start — Builder handling of driver-stalled preparations
Author
Owner

Folded into #1334, which is now the one pull request for tooling (trace replay and shader preparation). The commits are unchanged apart from being rebased into one stack and carrying the fixes the check suite asked for; nothing was dropped.

Folded into #1334, which is now the one pull request for tooling (trace replay and shader preparation). The commits are unchanged apart from being rebased into one stack and carrying the fixes the check suite asked for; nothing was dropped.
HumanBean closed this pull request 2026-11-17 15:48:27 +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 7s
PR description / Description follows the template (pull_request_target) Successful in 10s
Guide screenshots / Guide images and local UI source review (pull_request) Failing after 10s
CI / Workflow lint (actionlint) (pull_request) Successful in 12s
Third-party parts / As their notes say (pull_request) Successful in 15s
Website / Website on Cloudflare (pull_request_target) Has been skipped

Pull request closed

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!1386
No description provided.