WIP: perf(lift): RX_POLL_PRESERVE=1, the interrupt poll's call keeps the caller's registers (compile only, off) #1985
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
4 participants
Notifications
Due date
No due date set.
Dependencies
No dependencies set
Reference
MagicBeanDev/Longshot!1985
Loading…
Reference in a new issue
No description provided.
Delete branch "siantm/Longshot:perf/lift-poll-preserve"
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?
Summary
A lifted loop's back-edge poll calls
a64_poll_cur()only when the interrupt flag is set, but under the C conventionevery polled loop moves its live values to callee-saved registers or spills them for that rare call. With
RX_POLL_PRESERVE=1the generateda64.hdeclares the poll with clang'spreserve_most(x86-64): the call keeps everygeneral-purpose integer register but R11 for its caller. The lifted code and the host's files include that header, and
host/mkw_glue.c's definition takes the convention from the declaration, so caller and callee cannot disagree. Thenative build only (the emulator-hosted DLL polls through
a64_poll(c)). Unset or off,a64.his main's byte forbyte, so no lifted object's key changes. Compile only; the build's log names the mode, and
dev.py packbuilds thegame when it is on. From 2a831341 on a local performance branch, reworked in review.
Read first:
rt_headerandhost_flagsinnx2/build.py,POLL_PRESERVEinnx2/rtgen.py,docs/dev/reference/poll-convention.md,tests/test_poll_preserve.py.Testing
Tested: Windows 11, i7-9700, RTX 4060, llvm-mingw clang 23.1.5, Python 3.14.7 (the Builder's); game-free checks
only. This change has not run in the game on this PC yet, with the switch on or off (Still to test). Each check ran in
a hidden console of its own, through the PC's job queue (job fb2-1985-final), at
8e9d1c21onmain@f1f2dc5b, thetest run with no arguments (its compiler found through
LONGSHOT_MINGW, astests/run_all.pygives it):python -I -B tests/test_poll_preserve.py: exit 0, "all passed": the header main's for every off value and differentin the poll's declaration alone for every on value; seeds 1 to 3, O1 and O2, bitmap off and on, the same digest, polls
and marks with the switch off and on (e.g. "seed 3, O2, bitmap on: off 3b699ce7951861dc 7657 3701, on 3b699ce7951861dc
7657 3701"); "a definition without preserve_most under callers with it: caught in 12 of 12 programs".
python -I -B tests/test_vk_pgo.py(pack routes),tests/test_split_giants.pyandtests/test_light_passes.py(both import
nx2/build.pyand write the guest model): exit 0 each.Earlier, at 7de00eaf (the first form,
-DA64_POLL_PRESERVEon both sides),python -I -B tests/run_all.py --strict --changed origin/mainonmain@2e1f6c32: 102 passed, 22 failed, 7 skipped; the 21 failures that fail onmaintooand the one
tests/test_prepare_stall.pyfailure that did not repeat are named in the comment of that run. That runwas not repeated on this head. Two of those 21,
test_pipeline_states.pyandtest_recorder_sync.py, had found no Vulkan headers in that run (RX_CPMunset) and compiled nothing on either side; run again with the headers at8e9d1c21and onmain@f1f2dc5b,test_pipeline_states.pypasses on both andtest_recorder_sync.pyfails onmaintoo with the same lines.Still to test:
with
RX_POLL_PRESERVE=1(LONGSHOT_KEEP_BUILD_FILES=1, one translation), the same scene interleaved, warmed:average fps, 1% lows, median and p99 frame times, expecting the switch's build the same or better (by hand)
python3 -I -B tests/test_poll_preserve.py, expecting it to pass (by hand)Measurements
Verdict:
RX_POLL_PRESERVEships off: an experiment, not measured in play on this PC yet; only its game-free testhas run. A synthetic lift probe on the branch it came from (another PC, another base) is in the docs, labelled as such;
counts over the game's lifted functions were taken locally and are not published.
Setup: Windows 11, i7-9700, llvm-mingw clang 23.1.5;
tests/test_poll_preserve.pythrough the PC's job queue51f5f9da(the first form's test file copied in)8e9d1c21tests/test_poll_preserve.pypoll_cc_flags)Risks
Caller and callee must agree on the convention: both take it from the one generated
a64.h, and the test shows adefinition built without it going wrong under callers built with it. Off by default: unset, the build and its header are
main's. Turning it off is unsetting it and building again: an executable keeps what it was built with. Changing it
compiles the lifted code and the host's files again, and translates the game again where the translated C is gone (a
player's build folder; a development checkout and
LONGSHOT_KEEP_BUILD_FILES=1keep it). Nothing a player keeps(saves,
longshot_options.ini) changes.Checklist
Ready for review
main; the title is a Conventional Commit.mise run testpasses (any failure that also fails onmainis named).main, or Measurements says why there is nothing to measure.third_party/untouched; nothing GPL-incompatible.When it applies
tests/that reads changed source is updated, not weakened.Assisted-by:/Co-Authored-By:trailers.Ready to merge
main, measured again or a comment says why the numbers still hold.Possibly related, for context:
Recommendation: Request changes. The generated header invalidates every cached lifted object on the first update even with the switch off. The ABI test can also pass with mismatched production flags, and the in-game gain remains unproven.
An opt-in Clang calling convention lets lifted loops keep more integer registers live across an interrupt poll. It may reduce spills in those loops, at the cost of extra register saves when a poll is taken and a new ABI contract between separately compiled objects.
@fixwill do (10)nx2/rtgen.py:28: The generated a64.h changes even with the switch unset. (more on the line)nx2/build.py:1755: The enabled define enters the emulator DLL's object keys even though A64_POLL_CTX calls a64_poll(c) with the C convention. The define also reaches every host source. Scope the variant to the native callers and the host translation unit that defines the poll so an A/B rebuild can reuse unaffected objects.docs/dev/reference/poll-convention.md:26: The committed benchmark section includes output sampled from the game and static counts from lifted game functions. (more on the line)docs/dev/reference/poll-convention.md:11: The note attributes register preservation to a fiber switch inside the poll. (more on the line)tests/test_poll_preserve.py:190: Both fixture files use build.flags and the driver supplies its own poll definition. (more on the line)tests/test_poll_preserve.py:149: The fixture modifies c->poll through cur_ while the running loop accesses the same member through its restrict-qualified context pointer. (more on the line)tests/test_poll_preserve.py:35: The suite always passes --cc clang, bypassing CC and the configured Builder toolchain. (more on the line)tests/test_poll_preserve.py:32: The test imports build before isolating its configuration. (more on the line)For the author (1) (a run, a measurement or a decision)
Checks: Still running:
CI / Conventional Commit title (pull_request),CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request),CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request),CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request),CI / Workflow lint (actionlint) (pull_request),CI / Website build and checks (pull_request),Guide screenshots / Guide images and local UI source review (pull_request),Third-party parts / As their notes say (pull_request),Third-party parts / The same as upstream (pull_request),Website / Website on Cloudflare (pull_request).More: does it help, other systems, switches, what was read
Does it help: Unproven. The reported Windows fixture on 7de00eaf matched digests and poll counts for three seeds at O1 and O2. The older branch reports 2.2% fewer weighted static instructions and 0.5–1.2% fewer dynamic instructions in a scratch probe. There are no matched gameplay or build measurements for
81db088dagainst6e1521a7.Other systems: Windows and Linux use the changed lifted caller and host wrapper. Hot, cold and split lifted code inherit the flag, so the Steam Deck and other Tier 1 systems need coverage. The wrapper reaches virtual-core scheduling, where latency can affect pacing regardless of GPU vendor. The emulator DLL still uses its context-taking poll but inherits a needless cache-key change when the switch is set. The diff does not change the renderer interface, shader cache inputs, save format, audio or input code.
Switches: RX_POLL_PRESERVE is a build-only A/B switch, off when unset. A64_POLL_PRESERVE is its internal compiler define. The build reference is the correct table for build-only switches. The developer-only scope is appropriate, but measurements have yet to establish a shipping default. Where the translated C was discarded, turning the switch off requires translating and building again.
Reviewed:
81db088d5fagainst6e1521a70a: Read all eight diffs, both changed reference pages, the new test and nx2/rtgen.py in full, and the repository rules, standards and PR template. Read the relevant surrounding functions in the larger changed files and traced the scheduler, emulator shim, compiler selection, test runner, object keys and retained translation. Reviewed the reported runs and CI status. Unrelated portions of the larger modules and unrelated historical run records were outside the review. No review-checklist.md or adjacent Tooling checkout was present.; nothing run (a code review).Checked and fine:
Testing: Read-only review. No project code or tests were run. The author reports the Windows fixture passed on an earlier equivalent patch. The broad run reported 102 passes, 22 failures and 7 skips. Twenty-one failures reproduced on the base, and the remaining watchdog failure did not reproduce in isolated repeats. The supplied head CI is still pending.
Overlaps and merge order: No overlap confirmed from the checkout or supplied discussion. The four other experiments appear in the test report without diffs or a demonstrated merge dependency.
Automated code review by BeanBot (gpt-6.2-sol), on the pull request's opening. Nothing was run; a maintainer decides.
@ -0,0 +8,4 @@`RX_POLL_PRESERVE=1` (a build switch, compile only: not in the lift key; off by default) declares `a64_poll_cur` withclang's `preserve_most` (`A64_POLL_CC`, `nx2/rtgen.py`): the callee keeps every general register but R11.- `host/mkw_glue.c`'s definition takes the convention from the declaration and saves the registers itself on its coldL5 (minor): The note attributes register preservation to a fiber switch inside the poll. The checkpoint can yield and reacquire a virtual core on the same host stack. The attributed wrapper is responsible for preserving integer registers. Correct this note and the corresponding comment in mkw_glue.c, and limit the register claim to the convention's integer registers.
@ -0,0 +23,4 @@and other lift changes (flag fusion, loops' stores sunk to their exits) were in both sides; they are not measurementsof main with the switch.A profile of the game (Kokiri Forest and Hyrule Field, 3 runs each) put the lifted code at 122 / 106 % of a core; itsL4: The committed benchmark section includes output sampled from the game and static counts from lifted game functions. The repository rule covers those derived outputs. Remove the game-derived figures and keep measurements from an authored synthetic fixture plus the PR's permitted gameplay results.
@ -26,3 +26,3 @@emulator-hosted DLL (nx2/rt/eden_shim.c), whose host's poll takes the context. */void a64_poll(Ctx *A64_NOESC c);void a64_poll_cur(void);/* (nx2/rtgen.py) A64_POLL_CC under A64_POLL_PRESERVE (nx2/build.py poll_cc_flags): the call keeps every general registerL1: The generated a64.h changes even with the switch unset. build.py hashes its full contents into every lifted object's key, so a player updating from the base gets KEPT_STALE and a full relift and lifted-code compile. Preserve the existing generated header bytes in the default mode and generate the alternate poll declaration only for enabled native builds, with both modes keyed separately.
@ -0,0 +29,4 @@sys.path.insert(0, os.path.join(ROOT, "nx2"))sys.path.insert(0, HERE)import kit # noqa: E402,F401 (a64-kit on the path)import build # noqa: E402L9: The test imports build before isolating its configuration. An inherited RX_MARK_BITMAP=0 silently removes bitmap coverage. RX_MARCH can select instructions the local CPU lacks, and RX_TARGET=windows with LONGSHOT_MINGW on Linux produces an executable the test cannot run locally. Isolate the build import and fixture flags with an explicit native target, baseline CPU and mark mode. If cross-target IR coverage is wanted, keep execution native.
@ -0,0 +32,4 @@import build # noqa: E402import rtgen # noqa: E402RUN_ALL_ARGS = ["--cc", "clang"]L8: The suite always passes --cc clang, bypassing CC and the configured Builder toolchain. A supported Windows setup with LLVM-MinGW available only through LONGSHOT_MINGW fails or skips before find_cc runs. Let the suite discover Clang through the same resolver as the standalone check, honor a Clang supplied via CC, and use target flags that match the resolved compiler.
@ -0,0 +146,4 @@A64_POLL_CC void a64_poll_cur(void) {polls_++;(void)rand(); /* (a C library call: the caller-saved registers change) */if (++npoll_ %% 3) __atomic_store_n(&cur_->poll, 1, __ATOMIC_RELAXED);L7: The fixture modifies c->poll through cur_ while the running loop accesses the same member through its restrict-qualified context pointer. The atomic store still violates the C restrict contract. An optimized build is free to miss the rearm, and both binaries can agree with just one poll per round. Rearm from the loop through c in the fixture and check the expected poll count.
@ -0,0 +187,4 @@with switch(value):fl = build.flags(d, rt, opt, True)fl += ["-DA64_HOST_BASE=((uintptr_t)guest_mem)", "-include", os.path.join(d, "pre.h")]r = subprocess.run([cc] + fl + cflags + [os.path.join(d, "loop.c"), os.path.join(d, "driver.c"), "-o", exe],L6: Both fixture files use build.flags and the driver supplies its own poll definition. A host job that drops the define after host_fl is constructed would still pass the source check, IR check and digest comparison. Compile the real wrapper, or extract it using the existing source-cut helper, as a separate object with the flags from the production host job. Stub the checkpoint with a normal-ABI function that deliberately clobbers volatile integer registers. Check that removing the define from just the host flags fails the test.
Recommendation: Request changes. The development pack can silently run the base executable when you ask for the
RX_POLL_PRESERVE=1variant. That can make an on/off comparison measure the same calling convention twice.Blocking
scripts/devtools/build.py:51excludes the flag from the lift-key diagnostic. Pack selection still depends on source changes and the existing profile switches inscripts/devtools/packs.py:440. With a clean checkout matching a shared base built with the switch unset,RX_POLL_PRESERVE=1plusdev.py packmakes an empty pack, anddev.py rttakes the base executable. A renderer-only diff also leaves the game executable at the base revision. Route the enabled flag to a game build, using the same on/off parsing asnx2/build.py, and cover both pack routes. Record the effective poll mode for the resulting build so the comparison can verify which ABI each arm used.Does it help? Gameplay benefit remains unmeasured. In the normal native build, the lifted calls and host definition share the same flag and compiler target, and the object keys distinguish the two modes. The generated runtime header still changes with the flag unset, which invalidates retained object reuse on update. The current fixture exercises a stand-in poll. Extend it to exercise the production host and lifted flags, as the existing review describes. BeanBot’s review of this head
Testing. Reviewed
81db088d5f7cagainst6e1521a70a32with revision-matched source maps and direct source inspection. The author reports a passing Windows fixture on the earlier equivalent patch and two isolated watchdog passes each on the current head and base. Required head CI is pending. Before leaving WIP, use builds whose poll mode is verified to compare gameplay and frame times, clean build time and size, and off-mode update cost. The enabled Windows and Linux paths need a controlled compile-time comparison. Stock Test Farm variants cannot setRX_POLL_PRESERVEfor compilation.@ -49,1 +49,3 @@COMPILE_ONLY_ENV = ("RX_HOT_OPT", "RX_PGO", "RX_VK_PGO", "RX_VK_PGO_FILE", "RX_A64_RT_O2", "RX_GAME_ONLY") # (make_game.py's: left out of the lift key)# (make_game.py's: left out of the lift key)COMPILE_ONLY_ENV = ("RX_HOT_OPT", "RX_PGO", "RX_VK_PGO", "RX_VK_PGO_FILE", "RX_A64_RT_O2", "RX_GAME_ONLY","RX_POLL_PRESERVE")This classifies the switch for the lift-key diagnostic. With a clean checkout and a matching shared base built with the switch unset, RX_POLL_PRESERVE=1 still leaves pack_route at None, so dev.py pack creates an empty pack and dev.py rt runs the base executable. A renderer-only diff also leaves the game at base. Have packs.py route the enabled flag to a game build using the same boolean parsing, and test both routes.
81db088d5f8e9d1c219dPushed
8e9d1c21(one commit, onmain@f1f2dc5b; it replaces81db088d, squashed so that no pushed doc keeps the counts over the game's lifted functions, which are removed as asked). What changed: with the switch unseta64.his main's byte for byte (thepreserve_mostdeclaration is emitted only with the switch on, native build only); the-DA64_POLL_PRESERVEflag is gone,host/mkw_glue.ctakes the convention from the one declaration;dev.py packbuilds the game when the switch is on; the build's log names the mode; the test links the reala64_poll_curcompiled with the host's flags over a register-clobbering checkpoint, and catches a mismatched definition in 12 of 12 programs. Tested on the new head:tests/test_poll_preserve.py(no arguments),test_vk_pgo.py,test_split_giants.py,test_light_passes.py, all exit 0, through the PC's job queue. Still to test: the in-game A/B and Linux.https://git.magicbean.dev/MagicBeanDev/Longshot/pulls/1985#issuecomment-62884: fixed in
8e9d1c21.scripts/devtools/packs.pypack_routenow builds the game whenRX_POLL_PRESERVEis on (nx2/kit.pyenv_on's rule, asnx2/build.pyreads it), for an unchanged tree and for a renderer-only change alike;tests/test_poll_preserve.pychecks both routes and that0/offleave the route as it was. The build's log also printsbuild: RX_POLL_PRESERVE=1: ...when the executable has the convention.https://git.magicbean.dev/MagicBeanDev/Longshot/pulls/1985#issuecomment-62885: addressed in
8e9d1c21(rebased onmain@f1f2dc5b). The pack route is fixed as in the inline reply (62884), and the build's log records the poll mode. With the switch unset the generateda64.his now main's byte for byte (the convention is emitted only with the switch on, native build only), so retained objects keep their keys; and the fixture now links the reala64_poll_curcut out ofhost/mkw_glue.c, compiled withbuild.host_flags, over a checkpoint stand-in that overwrites every caller-saved integer register: off and on agree, and a definition built without the switch under callers built with it is caught in 12 of 12 programs. The in-game A/B (merge base, off, on) is pending with the opener.https://git.magicbean.dev/MagicBeanDev/Longshot/pulls/1985#issuecomment-62613 (L1): fixed in
8e9d1c21.rtgen.writeemits thepreserve_mostdeclaration only withpoll_preserve=True(nx2/build.pyrt_header, switch on, native build); otherwisea64.his main's byte for byte.tests/test_poll_preserve.pycompares the header withrtgen.write's default for every off value and checks that the on header differs in that declaration alone.(L2 in https://git.magicbean.dev/MagicBeanDev/Longshot/pulls/1985#issuecomment-62620): partly fixed in
8e9d1c21. The emulator-hosted DLL now gets main's header (rt_header(out, dll)), so its keys no longer change; the test checks it. The host's files still rebuild when the switch flips: the convention is on the one declaration every caller and the definition include, which is what keeps them from disagreeing (the define on the command line is gone), and the host is a few files beside the lifted chunks.(L3 in https://git.magicbean.dev/MagicBeanDev/Longshot/pulls/1985#issuecomment-62620): fixed in
8e9d1c21. The commit message,docs/dev/reference/poll-convention.md, the build reference row and Risks now say a change of the switch translates the game again where the translated C is gone (a player's build folder), and that an A/B build usesLONGSHOT_KEEP_BUILD_FILES=1or a development checkout, with the game folder copied between the two builds.https://git.magicbean.dev/MagicBeanDev/Longshot/pulls/1985#issuecomment-62614 (L4): removed in
8e9d1c21as asked. The profile-weighted and static counts over the game's lifted functions are gone from the docs, the commit message and the description; the page says the per-function counts were taken locally and are not published, and keeps only the synthetic probe's result, labelled with its branch and PC. The squashed commit replaces the earlier one so no pushed doc still carries them.https://git.magicbean.dev/MagicBeanDev/Longshot/pulls/1985#issuecomment-62615 (L5): fixed in
8e9d1c21. The doc and the comment inhost/mkw_glue.cnow say the attributed wrapper saves the registers the convention keeps before it calls the checkpoint and restores them after, the checkpoint running on the same stack whether or not it yields; the register claim is limited to the general-purpose integer registers (vector and FP registers stay the caller's to save).https://git.magicbean.dev/MagicBeanDev/Longshot/pulls/1985#issuecomment-62616 (L6): fixed in
8e9d1c21. The fixture cuts the reala64_poll_curout ofhost/mkw_glue.cwithtests/srccut.py, compiles it alone withbuild.host_flagsand the generated header, and links it under a normal-ABIhos_vcore_checkpointstand-in that overwrites rax, rcx, rdx, rsi, rdi and r8 to r11. Building that definition with main's header while the loops use the switch's goes wrong in 12 of 12 programs, and the test fails if none does.https://git.magicbean.dev/MagicBeanDev/Longshot/pulls/1985#issuecomment-62617 (L7): fixed in
8e9d1c21. The poll stand-in no longer touches the context; the copy loop raises the request itself throughcevery eighth iteration, and the driver checks the exact number of polls taken ((n-1)/8 per call) and the exact marks left after the last poll, with the switch off and on.https://git.magicbean.dev/MagicBeanDev/Longshot/pulls/1985#issuecomment-62618 (L8): fixed in
8e9d1c21.RUN_ALL_ARGSis gone, so the test resolves the compiler itself:--cc, thenCC, clang on PATH, thenLONGSHOT_MINGW's clang; it uses that compiler's own target (build.target()is dropped from the flags), and a--targetin--cflagsruns the IR checks only. The final run took the Builder's clang throughLONGSHOT_MINGWwith no arguments.https://git.magicbean.dev/MagicBeanDev/Longshot/pulls/1985#issuecomment-62619 (L9): fixed in
8e9d1c21.nx2/build.pyis imported with the build's own variables (RX_*,LONGSHOT_*,OOT_*) cleared,RX_MARCH=x86-64(a baseline every x86-64 CPU runs) and no process allowed to start while it loads; the native target comes from the compiler, and every program is built with the bitmap off and on explicitly.(L10 in https://git.magicbean.dev/MagicBeanDev/Longshot/pulls/1985#issuecomment-62620): the edit part is fixed in
8e9d1c21: default object keys stay main's (L1) and the mode is scoped to the native build (L2). Doing the no-kick check inside the attributed wrapper to skip the C call for stale requests depends on taken polls showing a cost, which needs the in-game run; it is pending with the opener, as is the A/B with taken-poll frequency.@Beanstalk This adds a compile switch, RX_POLL_PRESERVE, off by default: set, the lifted code's interrupt poll keeps the caller's registers (nx2/build.py, nx2/rtgen.py, host/mkw_glue.c). The farm cannot build with it set, so only the default build is to test: with the switch unset, the lift and its C must be main's. Please time the lift against main's and check the lifted C is the same, on a Windows PC and on a Linux PC. No game scenario is needed: unset, the game's code is main's.
@siantm only members of
BigBeanscan start the farm. One of them can approve this request by reacting 👍 to it or to this comment.Tested corrected: an earlier run on this PC had no Vulkan headers for the renderer checks (
RX_CPMunset), so the ones it listed as also failing onmainhad compiled nothing on either side. They ran again with the headers at8e9d1c21and onmain(queue job fb2-vk-1); the description now gives those results. No check fails at this head alone; nothing in the branch changed.View command line instructions
Checkout
From your project repository, check out a new branch and test the changes.