WIP: perf(lift): a subtraction's V flag as N xor (a < b), so the game's signed compares are one host compare (A64_SUB_V) #1871

Draft
dyst wants to merge 4 commits from dyst/Longshot:perf/lift-sub-v into main
Member

Summary

The game's signed compares (CMP x1, x2 then B.LT, B.GE, B.GT, B.LE, or a CSEL/CSET on them: loop bounds, ranges, counters) cost seven to nine host instructions each in the lifted code, where an x86 CPU does them in two (cmp and jl). The translator writes a subtraction's V flag as overflow bits, ((a ^ b) & (a ^ r)) >> 63, and the signed conditions read it against N (N != V); clang folds neither at -O1 nor at -O2. In the lift of the game, subtractions set flags at about 168,000 places and signed conditions read N against V at about 170,000.

For a subtraction, N xor V is exactly "a < b" as signed integers of the operation's width (that is what Arm's LT means after a CMP). So this writes V as the result's sign bit xor that signed compare: the same bit for every a and b, and a reader's N != V becomes (N ^ N) ^ (a < b), which clang folds to one compare. CMP x1, w2, sxtw; B.LT goes from nine instructions to three, CMP w1, #29; CSEL from seven to three. Every flag keeps its value bit for bit; only V's C text changes, and only SetFlags' subtraction form (SUBS/CMP immediate, shifted and extended register, CCMP when its condition holds). ADDS/CMN (about 3,900 places) and ADCS/SBCS write V in other forms and are untouched.

The idea is from Rekarina, another recompiler of the game, which compares a SUBS's operands directly where only that kind of flag-setter reaches a reader (https://git.rekarina.dev/rekarina/rekarina, recomp/flags.py and runtime/cpu.h fc_sub). The identity here needs no reaching analysis and is exact for every reader. No code was copied.

Result: fewer host instructions for the same flags (longshot.exe's code 1.1 MB smaller), but no frame-rate gain this PC can show: over 15 interleaved runs a side the Market and Lake Hylia are within the spread (the game's time a frame 1-2 % lower). A first series of 5 showed +7 to +9 %; it did not reproduce.

Read first: nx2/cmpflags.py (the docstring has the proof), tests/test_cmpflags.py.

Testing

Tested: Windows 11 Pro (22631), RTX 3080 10 GB (NVIDIA 621.14), Ryzen 9 3900X: 10 hands-free runs (5 a side) through the Market from its entrance to the fountain and at Lake Hylia, child Link from the kokiri-start save; no crash and no FATAL in any log, the shots at the fountain and the lake as main's (the water's phase aside). docs/tested/2026-11-20-sub-v-dyst.md has the record. The lift log's patches all found their places, as on main (only the chunk numbers they land in moved: the text is shorter).

Checks: tests/test_cmpflags.py (new): the rewrite in Python; A64_SUB_V=0 leaves the translator as it was; 17 guest words (11 subtraction forms at 32 and 64 bits, CCMP register and immediate; ADDS, CMN, ADCS, SBCS, ANDS, CCMN must keep their text) translated both ways and run from the same context, the whole context compared after: every pair of 40 edge values under each of the 16 NZCV values, then 2,000,000 random states a word, at -O1 and -O2: 0 mismatches in 68.9 million checks. It has teeth: with the compare made unsigned it reports 403,641 mismatches. test_dead_flags, test_function_ends, test_doc_anchors pass; test_lift_cache fails only its "...and the others still by their code" check, as on main 89c3d21e (its checks that every module the lift loads is in the key pass with nx2/cmpflags.py). tests/run_all.py with the Builder's llvm-mingw: 704 passed, 55 failed, 123 skipped; the same 55 fail on main 89c3d21e, rerun beside it (none fails here only).

Still to test:

  • linux+amd, linux+nvidia: python -I -B tests/test_cmpflags.py, then the Market and Lake Hylia against main, expecting 0 mismatches and the same frame rate or better (@Beanstalk)
  • steamdeck: the Market standing against main, expecting the same frame rate or better (@Beanstalk)
  • windows+intel: an Intel CPU, the Market standing against main, expecting the same frame rate or better (@Beanstalk)

Measurements

Verdict: within the spread. Over 15 interleaved runs a side (four series on 2026-11-20), the Market walk 37.5 -> 38.3 FPS, at the fountain 43.9 -> 43.8, Lake Hylia 43.5 -> 44.9 (medians; every interquartile range overlaps), the game's time a frame 1-2 % lower. The first series (5 a side) showed +7.4 % at the fountain and +8.8 % at the lake; the two series after it in steadier conditions showed none, and the base itself ran 3-4 FPS faster in them. Not a measured gain.

Setup: Windows 11 Pro (22631), GeForce RTX 3080 10 GB (NVIDIA 621.14), Ryzen 9 3900X (12 cores, 24 threads), 64 GB. Default options (the game's 2560x1440 output, V-Sync and frame generation off), cap off (HOS_FPS_MAX=1000), a 1720x720 window. Child Link from the kokiri-start save, hands-free through the control bridge: the Debug teleport to the Market, a warm-up until no frame waits for a pipeline, 15 s with the left stick held forward (the entrance to the fountain), 30 s standing at the fountain; the teleport to Lake Hylia, the warm-up, 30 s standing. Each run a timing job of the PC's queue, interleaved (ABBAAB, BAAB, BAABBAABBA, ABBAABBAAB). FPS = 1000 / the mean frame time over the stretch, from the frame trace; the game's time a frame from its game_ms. The GPU waited 0.05 to 0.07 ms a frame: the processor sets the frame here.

Both sides are one shared base, main @ 3f2c9b3c, the change as a pack over it (measure/sub-v-3f2c @ 572bd93e on my fork: this PR's commit cherry-picked, without #1782's import line beside it): every object is the base's but the lifted game's.

Before: main @ 3f2c9b3c After: this PR (@ 572bd93e on 3f2c9b3c)
Market, walking to the fountain: FPS, median (interquartile range), 15 runs 37.5 (36.0-39.2) 38.3 (37.1-39.0)
Market, at the fountain 43.9 (41.9-44.5) 43.8 (42.5-44.4)
Lake Hylia 43.5 (42.5-44.9) 44.9 (44.2-45.2)
the game's time a frame, walk / fountain / lake (ms, median) 23.0 / 21.5 / 17.7 22.6 / 21.4 / 17.5
longshot.exe .text 503.5 MB 502.4 MB

Tried beside it and dropped: Z written as a == b as well (so HI, LS, GT and LE fold too) was slower, 5 runs a side: the walk 38.3 -> 35.1, the fountain 44.0 -> 39.6, the game's time a frame 21.7 -> 24.0 ms (likely the counter loops, subs x0, x0, #1; b.ne, where x86 takes Z from the subtraction itself and a == b needs a compare of its own).

Risks

What could break: nothing should, as every flag keeps its value; a mistake in the identity would show as a wrong branch in game logic anywhere, which tests/test_cmpflags.py checks on edge and random operands of every form at both widths. The rewrite matches the translator's exact text, so a change to SetFlags' text in the kit leaves the lift as main's (no rewrite) rather than wrong. Turning it off: A64_SUB_V=0 at lift time (the build translates the game again; the lift is then main's to the byte). After updating, the lift key changes, so the first build translates the game again and compiles all lifted code, as any translator change does; saves, longshot_options.ini and the shader caches are unchanged.

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.
  • mise run test passes (any failure that also fails on main is named). (tests/run_all.py: the 55 failures all fail on main 89c3d21e too.)
  • Measured against main, or Measurements says why there is nothing to measure. (Measured: within the spread on this PC; no gain shown.)
  • No game files, build output or hand-edited generated files; third_party/ untouched; nothing GPL-incompatible.

When it applies

  • A switch added or changed: it ships at the default the measurements chose, with its row in gpu/vk/switches.def. (A lift-time switch: on, as measured; its row is in docs/dev/reference/build.md beside A64_VECFP.)
  • 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 The game's signed compares (`CMP x1, x2` then `B.LT`, `B.GE`, `B.GT`, `B.LE`, or a `CSEL`/`CSET` on them: loop bounds, ranges, counters) cost seven to nine host instructions each in the lifted code, where an x86 CPU does them in two (`cmp` and `jl`). The translator writes a subtraction's V flag as overflow bits, `((a ^ b) & (a ^ r)) >> 63`, and the signed conditions read it against N (`N != V`); clang folds neither at `-O1` nor at `-O2`. In the lift of the game, subtractions set flags at about 168,000 places and signed conditions read N against V at about 170,000. For a subtraction, N xor V is exactly "a < b" as signed integers of the operation's width (that is what Arm's LT means after a CMP). So this writes V as the result's sign bit xor that signed compare: the same bit for every a and b, and a reader's `N != V` becomes `(N ^ N) ^ (a < b)`, which clang folds to one compare. `CMP x1, w2, sxtw; B.LT` goes from nine instructions to three, `CMP w1, #29; CSEL` from seven to three. Every flag keeps its value bit for bit; only V's C text changes, and only SetFlags' subtraction form (SUBS/CMP immediate, shifted and extended register, CCMP when its condition holds). ADDS/CMN (about 3,900 places) and ADCS/SBCS write V in other forms and are untouched. The idea is from Rekarina, another recompiler of the game, which compares a SUBS's operands directly where only that kind of flag-setter reaches a reader (https://git.rekarina.dev/rekarina/rekarina, `recomp/flags.py` and `runtime/cpu.h` `fc_sub`). The identity here needs no reaching analysis and is exact for every reader. No code was copied. Result: fewer host instructions for the same flags (`longshot.exe`'s code 1.1 MB smaller), but no frame-rate gain this PC can show: over 15 interleaved runs a side the Market and Lake Hylia are within the spread (the game's time a frame 1-2 % lower). A first series of 5 showed +7 to +9 %; it did not reproduce. Read first: `nx2/cmpflags.py` (the docstring has the proof), `tests/test_cmpflags.py`. ## Testing **Tested:** Windows 11 Pro (22631), RTX 3080 10 GB (NVIDIA 621.14), Ryzen 9 3900X: 10 hands-free runs (5 a side) through the Market from its entrance to the fountain and at Lake Hylia, child Link from the kokiri-start save; no crash and no FATAL in any log, the shots at the fountain and the lake as main's (the water's phase aside). `docs/tested/2026-11-20-sub-v-dyst.md` has the record. The lift log's patches all found their places, as on main (only the chunk numbers they land in moved: the text is shorter). Checks: `tests/test_cmpflags.py` (new): the rewrite in Python; `A64_SUB_V=0` leaves the translator as it was; 17 guest words (11 subtraction forms at 32 and 64 bits, CCMP register and immediate; ADDS, CMN, ADCS, SBCS, ANDS, CCMN must keep their text) translated both ways and run from the same context, the whole context compared after: every pair of 40 edge values under each of the 16 NZCV values, then 2,000,000 random states a word, at `-O1` and `-O2`: 0 mismatches in 68.9 million checks. It has teeth: with the compare made unsigned it reports 403,641 mismatches. `test_dead_flags`, `test_function_ends`, `test_doc_anchors` pass; `test_lift_cache` fails only its "...and the others still by their code" check, as on main 89c3d21e (its checks that every module the lift loads is in the key pass with `nx2/cmpflags.py`). `tests/run_all.py` with the Builder's llvm-mingw: 704 passed, 55 failed, 123 skipped; the same 55 fail on main 89c3d21e, rerun beside it (none fails here only). **Still to test:** - linux+amd, linux+nvidia: `python -I -B tests/test_cmpflags.py`, then the Market and Lake Hylia against main, expecting 0 mismatches and the same frame rate or better (@Beanstalk) - steamdeck: the Market standing against main, expecting the same frame rate or better (@Beanstalk) - windows+intel: an Intel CPU, the Market standing against main, expecting the same frame rate or better (@Beanstalk) ## Measurements **Verdict:** within the spread. Over 15 interleaved runs a side (four series on 2026-11-20), the Market walk 37.5 -> 38.3 FPS, at the fountain 43.9 -> 43.8, Lake Hylia 43.5 -> 44.9 (medians; every interquartile range overlaps), the game's time a frame 1-2 % lower. The first series (5 a side) showed +7.4 % at the fountain and +8.8 % at the lake; the two series after it in steadier conditions showed none, and the base itself ran 3-4 FPS faster in them. Not a measured gain. Setup: Windows 11 Pro (22631), GeForce RTX 3080 10 GB (NVIDIA 621.14), Ryzen 9 3900X (12 cores, 24 threads), 64 GB. Default options (the game's 2560x1440 output, V-Sync and frame generation off), cap off (`HOS_FPS_MAX=1000`), a 1720x720 window. Child Link from the kokiri-start save, hands-free through the control bridge: the Debug teleport to the Market, a warm-up until no frame waits for a pipeline, 15 s with the left stick held forward (the entrance to the fountain), 30 s standing at the fountain; the teleport to Lake Hylia, the warm-up, 30 s standing. Each run a timing job of the PC's queue, interleaved (ABBAAB, BAAB, BAABBAABBA, ABBAABBAAB). FPS = 1000 / the mean frame time over the stretch, from the frame trace; the game's time a frame from its `game_ms`. The GPU waited 0.05 to 0.07 ms a frame: the processor sets the frame here. Both sides are one shared base, main @ 3f2c9b3c, the change as a pack over it (`measure/sub-v-3f2c` @ 572bd93e on my fork: this PR's commit cherry-picked, without #1782's import line beside it): every object is the base's but the lifted game's. | | Before: main @ 3f2c9b3c | After: this PR (@ 572bd93e on 3f2c9b3c) | |---|---|---| | Market, walking to the fountain: FPS, median (interquartile range), 15 runs | 37.5 (36.0-39.2) | 38.3 (37.1-39.0) | | Market, at the fountain | 43.9 (41.9-44.5) | 43.8 (42.5-44.4) | | Lake Hylia | 43.5 (42.5-44.9) | 44.9 (44.2-45.2) | | the game's time a frame, walk / fountain / lake (ms, median) | 23.0 / 21.5 / 17.7 | 22.6 / 21.4 / 17.5 | | `longshot.exe` `.text` | 503.5 MB | 502.4 MB | Tried beside it and dropped: Z written as a == b as well (so HI, LS, GT and LE fold too) was slower, 5 runs a side: the walk 38.3 -> 35.1, the fountain 44.0 -> 39.6, the game's time a frame 21.7 -> 24.0 ms (likely the counter loops, `subs x0, x0, #1; b.ne`, where x86 takes Z from the subtraction itself and a == b needs a compare of its own). ## Risks What could break: nothing should, as every flag keeps its value; a mistake in the identity would show as a wrong branch in game logic anywhere, which `tests/test_cmpflags.py` checks on edge and random operands of every form at both widths. The rewrite matches the translator's exact text, so a change to SetFlags' text in the kit leaves the lift as main's (no rewrite) rather than wrong. Turning it off: `A64_SUB_V=0` at lift time (the build translates the game again; the lift is then main's to the byte). After updating, the lift key changes, so the first build translates the game again and compiles all lifted code, as any translator change does; saves, `longshot_options.ini` and the shader caches are unchanged. ## Checklist ### Ready for review - [x] One topic, on current `main`; the title is a Conventional Commit. - [x] Tested on my own PC, in the game for a change the game runs, as Testing says. - [x] `mise run test` passes (any failure that also fails on `main` is named). (`tests/run_all.py`: the 55 failures all fail on main 89c3d21e too.) - [ ] Measured against `main`, or Measurements says why there is nothing to measure. (Measured: within the spread on this PC; no gain shown.) - [x] No game files, build output or hand-edited generated files; `third_party/` untouched; nothing GPL-incompatible. ### When it applies - [x] A switch added or changed: it ships at the default the measurements chose, with its row in `gpu/vk/switches.def`. (A lift-time switch: on, as measured; its row is in `docs/dev/reference/build.md` beside `A64_VECFP`.) - [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)
suyu's translator writes a SUBS/CMP/CCMP's V as the overflow bits ((a ^ b) & (a ^ r)) >> 63, and the
signed conditions read it against N. clang does not fold that: CMP + B.LT became seven instructions
where the CPU has cmp and jl, at -O1 and -O2. For a subtraction N xor V is exactly a < b (signed), so
V is now written as the result's sign bit xor that compare; a reader's N != V folds to the compare.
Every flag keeps its value; A64_SUB_V=0 lifts as before. Idea from Rekarina's recomp/flags.py.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Co-Authored-By: Claude Opus 5.5 <[email protected]>
docs(tested): A64_SUB_V in the Market and at Lake Hylia, Windows 11, RTX 3080, Ryzen 9 3900X
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 12s
CI / Workflow lint (actionlint) (pull_request) Successful in 13s
Website / Website on Cloudflare (pull_request_target) Has been skipped
Third-party parts / As their notes say (pull_request) Successful in 14s
CI / Website build and checks (pull_request) Has been cancelled
623636a07e
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Author
Member

Tested in game: Windows 11 Pro 22631, RTX 3080 (NVIDIA 621.14), Ryzen 9 3900X: 5 hands-free runs against 5 of main through the Market (entrance to the fountain, then standing) and at Lake Hylia, child Link; no crash or FATAL, pictures as main's; fountain +7.4 %, Lake Hylia +8.8 %, walk within the spread.

Tested in game: Windows 11 Pro 22631, RTX 3080 (NVIDIA 621.14), Ryzen 9 3900X: 5 hands-free runs against 5 of main through the Market (entrance to the fountain, then standing) and at Lake Hylia, child Link; no crash or FATAL, pictures as main's; fountain +7.4 %, Lake Hylia +8.8 %, walk within the spread.
docs(tested): A64_SUB_V over 15 runs a side: within the spread
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 20s
PR description / Description follows the template (pull_request_target) Successful in 31s
Guide screenshots / Guide images and local UI source review (pull_request) Failing after 31s
CI / Workflow lint (actionlint) (pull_request) Successful in 37s
Third-party parts / As their notes say (pull_request) Successful in 41s
beanstalk/approval needs a second approval (sensitive paths)
Website / Website on Cloudflare (pull_request_target) Has been skipped
CI / Website build and checks (pull_request) Failing after 3m5s
af09e83426
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Author
Member

Correction to the numbers this opened with: the +7.4 % (fountain) and +8.8 % (Lake Hylia) came from the first series of 5 runs a side, and three more interleaved series on the same PC and base did not reproduce them. Over 15 runs a side the Market walk, the fountain and Lake Hylia are all within the spread (the game's time a frame 1-2 % lower; the description has the table). The base itself ran 3-4 FPS faster in the later series, which points at the PC's state during the first, not at this change. Also tried and dropped: Z written as a == b as well, which was clearly slower (fountain 44.0 -> 39.6 FPS), likely because the subs/b.ne counter loops lose x86's free ZF. This stays WIP: the instruction count is lower for the same flags, but no frame-rate gain is shown here; a weaker CPU (the Steam Deck) may show one, or it can be closed.

Correction to the numbers this opened with: the +7.4 % (fountain) and +8.8 % (Lake Hylia) came from the first series of 5 runs a side, and three more interleaved series on the same PC and base did not reproduce them. Over 15 runs a side the Market walk, the fountain and Lake Hylia are all within the spread (the game's time a frame 1-2 % lower; the description has the table). The base itself ran 3-4 FPS faster in the later series, which points at the PC's state during the first, not at this change. Also tried and dropped: Z written as a == b as well, which was clearly slower (fountain 44.0 -> 39.6 FPS), likely because the subs/b.ne counter loops lose x86's free ZF. This stays WIP: the instruction count is lower for the same flags, but no frame-rate gain is shown here; a weaker CPU (the Steam Deck) may show one, or it can be closed.
Owner

@Beanstalk

@Beanstalk
Member

@HumanBean approval of af09e83 recorded. This diff touches sensitive paths, so a second member of BigBeans must approve it too.

@HumanBean approval of `af09e83` recorded. This diff touches sensitive paths, so a second member of `BigBeans` must approve it too.
Member

Beanstalk test farm

Commit af09e83 · approved by HumanBean (untrusted) · dashboard

This diff touches sensitive paths, so it needs two members of BigBeans: nx2/cmpflags.py, nx2/lift.py

A member of BigBeans can review this commit and comment @Beanstalk to test it.

<!-- beanstalk:sticky --> ### Beanstalk test farm Commit `af09e83` · approved by HumanBean (untrusted) · [dashboard](https://beanstalk.magicbean.dev/prs/1871) This diff touches sensitive paths, so it needs two members of `BigBeans`: `nx2/cmpflags.py`, `nx2/lift.py` A member of `BigBeans` can review this commit and comment `@Beanstalk` to test it.
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 20s
PR description / Description follows the template (pull_request_target) Successful in 31s
Guide screenshots / Guide images and local UI source review (pull_request) Failing after 31s
CI / Workflow lint (actionlint) (pull_request) Successful in 37s
Third-party parts / As their notes say (pull_request) Successful in 41s
beanstalk/approval needs a second approval (sensitive paths)
Website / Website on Cloudflare (pull_request_target) Has been skipped
CI / Website build and checks (pull_request) Failing after 3m5s
This pull request is marked as a work in progress.
This branch is out-of-date with the base branch
View command line instructions

Checkout

From your project repository, check out a new branch and test the changes.
git fetch -u 'perf/lift-sub-v:dyst-perf/lift-sub-v'
git switch 'dyst-perf/lift-sub-v'
Sign in to join this conversation.
No reviewers
No milestone
No project
No assignees
3 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!1871
No description provided.