feat(runtime): HOS_DEV_DLL_SWAP, a renderer built alone taken at the next start, checked against the game first #183
No reviewers
Labels
No labels
area/accessibility
area/audio
area/input
area/install
area/menu
area/renderer
area/saves
area/tooling
area/upscaling
beanstalk: approved
beanstalk: failed
beanstalk: needs approval
beanstalk: running
beanstalk: tested
ci: approved
good first issue
gpu/amd
gpu/igpu
gpu/intel
gpu/nvidia
help wanted
kind
bug
kind
chore
kind
docs
kind
feature
kind
performance
kind
question
needs measurements
platform/linux
platform/macos
platform/steam-deck
platform/windows
preview
priority
critical
priority
high
priority
low
regression
risk
high
risk
low
risk
medium
status
blocked
status
confirmed
status
duplicate
status
invalid
status
needs-info
status
wontfix
ci: approved
No milestone
No project
No assignees
2 participants
Notifications
Due date
No due date set.
Dependencies
No dependencies set
Reference
MagicBeanDev/Longshot!183
Loading…
Reference in a new issue
No description provided.
Delete branch "dyst/Longshot:feat/renderer-swap"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Type: feat · Risk: low · Tested on: Windows 11, RTX 3080 (NVIDIA 621.14), in the game; Linux (Docker), game-free · Needs: Linux, any GPU, in the game
Why
Trying a change to the renderer means quitting the game, building the whole game folder again and starting it, or copying the DLL in by hand with nothing to say whether it pairs with the executable. On Linux the renderer reaches the host through weak
hos_*symbols, so one from another tree fails atdlopen, or calls through NULL. This builds the renderer alone while the game keeps running, checks it against the game, and has the game take it at its next start.This is the dev-loop proposal's B1, its second part (https://github.com/NotRexed/Hookshot/pull/2636). There is no Longshot issue for it. The loop restarts the game with
longshot_ctl.py relaunch, which #97 added and which is on main now.What changed
With
HOS_DEV_DLL_SWAP=1, the game renames a staged<renderer>.newover its renderer at the start, before loading it, when the staged file is built for the game's vk interface, and keeps the old renderer as<renderer>.oldso a bad one can be undone.scripts/stage_renderer.pystages a renderer there only when it is built for the executable's vk interface (both export theirMKWVK_API_VERSION, read from the files) and every symbol it needs from the executable is one the executable exports. Off, nothing is looked for. The loop: build the renderer alone, stage it,longshot_ctl.py relaunch(the game started again with the same environment, the switch included).Main also has
scripts/dev_packs.py(#147), which builds a renderer-only change as a pack over a base and runs it from a fresh runtime copied from that base, so the game and the renderer always come from one base's build; it suits comparing a change against a base.HOS_DEV_DLL_SWAPinstead swaps the renderer in place, in the game folder you are already running, after checking it against that folder's executable; the two don't depend on each other.dev_dll_swapinhost/rx_backend.c, called byload_vulkanbeforeLoadLibraryA. WithHOS_DEV_DLL_SWAP=1, a<renderer>.newbeside the game (longshot_vk.dll.new,longshot_vk.so.newon Linux, the nameLoadLibraryA's shim opens) is renamed over the renderer first, logged either way. The old process has ended by then (a restart waits for it:HOS_RESTART_OF), so nothing holds the old file. Off, nothing is looked for: a release never swaps.const unsigned mkwvk_api_version(gpu/vk/vk_main.cpp) and the executablemkwvk_host_api_version(host/rx_backend.c; on Linux throughnx2/build.py's--export-dynamic-symbol, besidehos_posix_*in the linkrun_linkruns), theMKWVK_API_VERSIONeach was built with. They are new exports, not members ofMkwVkHostorMkwVkRenderer, soMKWVK_API_VERSIONstays as it is (vk_api.hsays so besidemkwvk_init; its only change is that comment).exported_u32inhost/rx_backend.cand inscripts/stage_renderer.pyreads such a constant from a file without loading it: a PE file's export table (a DLL or an EXE) or an ELF64 file's dynamic symbols.dev_dll_swapreads the staged file'smkwvk_api_versionbefore anything moves. Another version, or none (a renderer from before the export), is left where it is, and the old renderer loads, logged with the version found. Otherwise the old renderer is moved to<renderer>.oldfirst, then the staged one over it; if that move fails, the old one is put back.stage_renderer.py --undo GAME_DIRmoves.oldback over the renderer.scripts/stage_renderer.py GAME_DIR [RENDERER](new, standard library) copies the renderer (default: the work folder'ssa/build/one) whole to<name>.newbeside the executable (bin/when the game has one), only when it pairs. On both platforms it refuses a renderer whosemkwvk_api_versiondiffers from the executable'smkwvk_host_api_version, or either missing (version_problem), before it looks at the symbols. Linux: every name it leaves for the loader (nm -D --undefined-only), weak ones too, unless versioned (the C and C++ runtime's) or the start files' own (__gmon_start__,_ITM_*...), is one the executable exports. Windows: every function it imports from the executable is one the executable exports (llvm-objdump -p); today the renderer imports none (the host hands it a table), so on Windows the version is the check that matters. One that doesn't pair isn't staged, and the names are said.build.py'scheck_vk_symbolschecks the renderer alone at build time; this pairs it with the executable it will run under.docs/development.md: the switch's row in Running a test, and Trying a renderer change in place after Testing a change against a base: the steps (the renderer built alone, staged, the game started once with the switch, thenlongshot_ctl.py relauncheach time after), what the pairing check refuses, what the log says when the move fails,--undo, and when a pack is the better tool.tests/test_stage_renderer.py(new): the readers onnmandllvm-objdumpoutput, the staging, the versions read from a real DLL and EXE (Windows) or shared object and executable (Linux), the refusals,--undo, anddev_dll_swapcut out ofhost/rx_backend.cand run with the switch on and off, a renderer staged and not, of the same version, another and none: on Windows with the real Win32 calls, on Linux overhost/posix/win32_posix.c, where it swaps the.so.Measurements
Verdict: faster: a renderer edit to in play again in 51.6 s against 73.2 s on main (median of 3), about 22 s a loop, with the building itself about the same (16.2 s against 16.9 s); no errors in the PR runs' logs. Measured at the PR's first head (2a333461, on main
f41db065), before the version check and.oldand before the rebases; the timed runs below on this head are coming.Timed runs on this head (
6575b590, on main @d9486a08), main vs this PR: to come.Hardware: RTX 3080 (NVIDIA 621.14), Ryzen 9 3900X, 64 GB, Windows 11
Scene: Kokiri Forest from a save (the title's Continue), headless, muted; both builds from one work folder
Method: from a comment added to
gpu/vk/vk_menu.cppwhile the game is in play to being in play again on the new renderer, by the script's clock, rounds interleaved (main, PR, main, PR...). main: quit,make_game.py(the game folder built again; the lift skipped), launch, Continue. This PR:RX_VK_ONLY=1 nx2/build.py --standalone(the renderer alone) while the game plays on,scripts/stage_renderer.py,longshot_ctl.py relaunch(the game started withHOS_DEV_DLL_SWAP=1), Continue. The PR side was the PR's first commit on #97's branch @ 0fa72f49 (the same patch), sincerelaunchwas not on main then.How to reproduce: as the method, with a save copied into each game folder.
f41db065The medians are of rounds 2 to 4. Round 1 is left out on both sides: main's build ran the lift again, because the PR's first build from the other checkout had changed the shared work folder's lift key, and the PR's was its first
RX_VK_ONLYbuild there, which compiles every renderer file once. In a warm work folder building the renderer alone is no faster than the game folder's build (everything else is cached); the ~22 s a loop saved is the game left running through the build and relaunched over the bridge, against quit, launch and wait.Why the numbers should still hold on this head: since 2a333461 the swap reads a few hundred bytes of the staged file's headers before it moves anything (the version check), and keeps the old renderer as
.old(one more rename); both are at the start, well under the timer's resolution. Main's build has moved on both sides sincef41db065(one object store, #371; a lift reused across work folders, #372; a renderer header edit compiling only the files that read it, #37; a link skipped when nothing it reads changed, #30; an update copying no unchanged exe, #631), which can lower main's game-folder build and the PR's renderer build alike; the part this PR saves, the game kept running through the build and started again over the bridge, doesn't depend on them. The timed runs above will say.Flags and settings
One developer switch,
HOS_DEV_DLL_SWAP, off by default, documented in docs/development.md (its row in Running a test, and Trying a renderer change in place).HOS_DEV_DLL_SWAP<renderer>.newbeside the game, built for the game's vk interface, takes the renderer's place before it is loaded; the old one is kept as.old1, the next start renames the staged renderer over the old one and loads it, logged either way; off, no file is looked forTesting
Tested:
6575b590, on main @d9486a08), Windows with the Builder's llvm-mingw, 8 at once: the 130 checks that read this diff (everytests/andnx2/test_*.pycheck whose text names a changed file, the PR's own test among them), not the whole suite: 111 passed, 6 skipped (tools this PC lacks: the Vulkan and SPIR-V headers, spirv-val), 13 failed, each also failing on main @d9486a08the same way (run there on a clean checkout):nx2/test_dll,test_appimage_player_build,test_auto_handheld,test_crash_dialog,test_driver_cache_folder,test_driver_env_choose,test_fpx_sticky,test_linux_preflight,test_pads_after_menu,test_pipeline_tour,test_vk_occlusion_queries,test_vk_pgo,test_walk_key.tests/test_stage_renderer.pypassed.tests/test_stage_renderer.pyon Linux too, on this head (Dockerpython:3.12, gcc 14.2 and binutils: a real shared object and executable with the exports,dev_dll_swapover the POSIX shim, swapping the.so): passed.host/rx_backend.ccompiled to an object with the Builder's llvm-mingw clang (x86_64-w64-mingw32,-Wall -Wextra: no warning in the new code; the object carries-export:mkwvk_host_api_version,data) and with gcc 14.2 on Linux (host/posixon the include path;mkwvk_host_api_versiondefined in it). The lift's two runtime headers taken from a local work folder. It covers this file, not a whole game build or link.45fa6e42, on main @bbe6fdf2):gpu/vk/vk_main.cppcompiled with llvm-mingw clang++ and, on Linux, clang++ 19; the Python reader read a reallongshot_vk.dllandlongshot.exefrom before the change (mkwvk_close_askedfound, nomkwvk_api_version, as expected). The rebase changed neither file's new code;nx2/build.py's one conflict was main'srun_link(#30) in the Linux executable's link, which now carries the extra--export-dynamic-symbol.The 130 checks run
The checks under
tests/andnx2/test_*.pywhose text namesdevelopment.md,vk_api.h,vk_main.cpp,rx_backend.c,build.py,stage_renderer.pyortest_stage_renderer, picked withgrep -land run withtests/run_all.py --exact.Not tested: the swap in the game on Linux (its code ran there over the shim, not in a game build); a game folder with a launcher (
bin/), where the script stages besidebin/longshot; the loop in the game on this head, and the exports in a whole game build (a DLL and EXE linked by build.py).Must be tested:
HOS_DEV_DLL_SWAP=1, a renderer staged withscripts/stage_renderer.py, thenlongshot_ctl.py relaunch, expecting "HOS_DEV_DLL_SWAP: ... took the old renderer's place" in the log and the game playing (by hand: that log line, and play continuing)scripts/stage_renderer.py <game>with a renderer from main (expecting it refused:exports no mkwvk_api_version) and with this PR's (staged), the game started withHOS_DEV_DLL_SWAP=1(expecting "took the old renderer's place (kept as ...old)" in the log, and play), thenstage_renderer.py --undo <game>(expecting the old renderer back) (by hand: the script's lines and the log)Risks
What could break: with the switch set and a stale or wrong
.newbeside the game, that renderer loads in place of the old one if it is built for the same vk interface: the game itself refuses one of another version (or none) before anything moves, and the script refuses one that doesn't pair; a bad one of the same version is undone with--undo(the old one is kept as.old). Each swap replaces the last.old, so only one step back is kept. Without the switch nothing changes: no file is looked for.Turning it off: unset
HOS_DEV_DLL_SWAP(or delete the.new); to go back after a swap,python -I scripts/stage_renderer.py --undo <game folder>; reverting the commits removes it.Compatibility: Nothing changes for a player: the switch is off and nothing is staged; saves,
longshot_options.iniand the caches are untouched. The vk ABI (MKWVK_API_VERSION,MkwVkHost,MkwVkRenderer) is unchanged: the two new exports sit besidemkwvk_init, and a renderer and an executable from before them still load each other as before (only the swap and the script need the exports).Checklist
Everyone
type(scope): description) of the status line's type.main.python -I -B tests/run_all.pypasses (any failure that also fails onmainis named).third_party/untouched (a new folder with aPROVENANCE.mdinstead).When it applies
Assisted-by:/Co-Authored-By:trailers.tests/that reads changed source updated in this PR, not weakened.🤖 Generated with Claude Code
Test request T-PZ2F opened for the Linux run (it needs the 'testing wanted' label to be claimed).
WIP: feat(runtime): HOS_DEV_DLL_SWAP, a renderer built alone taken at the next start, checked against the game firstto feat(runtime): HOS_DEV_DLL_SWAP, a renderer built alone taken at the next start, checked against the game first91c52733557480ea3f14Rebased onto main
6c9edffewith no conflicts (head now7480ea3f), and the description moved to the new template (#571).tests/run_all.py, the whole suite, again on this branch and on main @6c9edffe(Windows, the Builder's llvm-mingw): no failure main doesn't have; the details are under Testing. The measurements are kept under the commits they were taken at, with a line on what main changed since.What changed now says how this relates to scripts/dev_packs.py (#147): a renderer pack runs from a fresh runtime copied from its base, where HOS_DEV_DLL_SWAP swaps the renderer into the folder you are running, after checking it against that folder's game. The measured loop still uses #97's relaunch, which needs a rebase of its own.
Pushed
8aa2bf43: HOS_DEV_DLL_SWAP is documented in docs/development.md, its row in Running a test and a short section, Trying a renderer change in place (the three steps, what stage_renderer.py's check refuses, what the log says when the move fails, and when a dev_packs pack is the better tool). The checks that read docs/development.md pass here, apart from four that fail on main too (test_crash_dialog, test_oot_state_tap, test_vk_pgo, test_walk_key).8aa2bf43c90fde8ca222Rebased onto
main@bbe6fdf2: one conflict, indocs/development.md: main dropped theRX_BACKENDrow from the switch table; kept that removal and this PR'sHOS_DEV_DLL_SWAProw. No tests were run here; the test boxes stay yours.Tested HumanBean's rebase onto main
bbe6fdf2(head0fde8ca2), unchanged: the 31 checks that read this diff, not the whole suite (the agreed process now): 25 passed, 6 failed, each failing on main too (test_crash_dialog, test_oot_state_tap, test_vk_pgo, test_walk_key at1310ecc6; test_pipeline_tour, test_vk_occlusion_queries at7bacf846), test_stage_renderer passing. The description now says this needs #97 (longshot_ctl.py relaunch) and merges after it.Code-only review of
0fde8ca2(nothing run). The branch stands alone: four files, none of #97's commits. The only tie to it is that the comments and docs namelongshot_ctl.py relaunch, so merge after it.What is right: the switch is off unless set (
env_on), nothing is looked for when off, and the only thing taken is<renderer>.newbeside the executable's own renderer, never a path from the environment.stage_renderer.pycopies whole and replaces atomically; a failed move is logged and the old renderer loads.Points, none blocking on their own:
MKWVK_API_VERSION. The docs say the trees "must have the same MKWVK_API_VERSION", butstage_renderer.pyonly pairs symbols. The runtime does refuse a renderer whoseversiondiffers (load_vulkan), but only after the swap has already replaced the old file, and then it draws nothing, with no way back. On Windows the check is also vacuous: the renderer imports nothing from the executable, somissing()returns the empty set and anything is staged. That is the platform the PR was measured on. A renderer from a tree with another vk ABI is exactly what the PR text promises to refuse, and on Windows it won't be. Suggest reading the version out of the staged file (themkwvk_initresult is the only place it lives, so either export amkwvk_api_versionconstant or compare against a string the build bakes in) or saying plainly in the docs and in the description that the pairing check is Linux-only and the ABI version is checked at load.dev_dll_swapdeletes the old renderer byMoveFileEx(..., REPLACE_EXISTING), so a bad.newleaves no renderer to fall back to. Keeping the old one as.oldwould make the "turning it off" line true.Verdict: comment. Safe by default; the version-check gap in (1) is worth a decision from the author before merge.
Thanks for the review. Pushed
45fa6e42(one commit on your0fde8ca2; it still merges cleanly with main). Your points, in order:No
MKWVK_API_VERSIONcheck, and vacuous on Windows. The version is exported now.const unsigned mkwvk_api_version(gpu/vk/vk_main.cpp) and the executablemkwvk_host_api_version(host/rx_backend.c; on Linux throughnx2/build.py's--export-dynamic-symbol), each theMKWVK_API_VERSIONit was built with. These are new exports, not changes toMkwVkHostorMkwVkRenderer, so the version itself doesn't move;vk_api.hsays so besidemkwvk_init.stage_renderer.pyreads both from the files without loading them: a PE export table, or an ELF file's dynamic symbols. It refuses, on Windows too, a renderer of another version, or either file without the export, before it looks at symbols.dev_dll_swapreads the staged file's version the same way before anything moves. One of another version, or with none, is left where it is, and the old renderer loads, with the version found in the log.The old renderer was deleted. It's kept as
<renderer>.oldnow: the old one is moved aside first, then the staged one over it, and if that second move fails the old one is put back.stage_renderer.py --undo <game folder>moves.oldback by hand.docs/development.md(Trying a renderer change in place, the switch's row) and the Risks section's "Turning it off" line say how.Testing.
tests/test_stage_renderer.pybuilds real binaries with the exports: a DLL and EXE on Windows, a shared object and executable on Linux. It checks:--undo;dev_dll_swapwith a staged renderer of the same version (taken, old one kept as.old), another version and none (both left where they are).It passes on Windows (real Win32 calls) and Linux (Docker, over the POSIX shim). The reader also finds
mkwvk_close_askedin the local work folder's reallongshot_vk.dll, and no version in it, as expected for a build from before.host/rx_backend.candgpu/vk/vk_main.cppcompile on this head and on main for Windows (llvm-mingw) and Linux (gcc, clang 19). The checks that read the diff: 104 passed, 5 skipped, 10 failed, each failing on main too. T-PZ2F (Linux, in the game) is still open, and I've added a Windows check of a whole build under Must be tested.This still merges after #97.
45fa6e422f6575b59043Rebased onto main
d9486a08and pushed (head now6575b590). One conflict, innx2/build.py: main's #30 moved the Linux executable's link torun_link; kept that and this PR's extra--export-dynamic-symbol=mkwvk_host_api_versionin it. The four earlier commits now carry the dyst identity as author too. Nothing else in them changed.One new commit,
6575b590(docs): #97 has merged, solongshot_ctl.py relaunchis on main. Trying a renderer change in place now gives it as the step after the first start: the game is started once withHOS_DEV_DLL_SWAP=1, thenrelaunchstarts it again with the same environment. The description no longer says this PR waits for #97.Thanks again for the review, HumanBean. Where your points stand on this head:
MKWVK_API_VERSIONcheck, and the Windows gap. Done in45fa6e42and unchanged by the rebase. The renderer exportsmkwvk_api_versionand the executablemkwvk_host_api_version.stage_renderer.pyrefuses a mismatch, or a missing export, on both platforms.dev_dll_swapchecks the staged file's version before anything moves.45fa6e42. It's kept as<renderer>.old, it goes back if the second move fails, andstage_renderer.py --undorestores it.Checks on this head: the 130 checks that read this diff, not the whole suite. 111 passed, 6 were skipped for missing tools, and 13 failed. All 13 fail the same way on a clean checkout of main
d9486a08; the names are under Testing.tests/test_stage_renderer.pypassed on Windows and on Linux (Docker, gcc 14.2).host/rx_backend.ccompiles clean on both. The Measurements are still from the PR's first head. Timed runs of main against this head are coming and will go in the description.6575b59043d1aef96699View 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.