perf(build): lifted chunks with small functions compile without -O1's module passes (LONGSHOT_LIGHT_PASSES, on by default) #1002

Merged
HumanBean merged 4 commits from madebyjordan/Longshot:perf/light-passes into main 2026-11-16 11:19:49 +00:00
Member

Type: perf · Risk: low · Tested on: Windows 11, RX 6700 XT (Ryzen 5 5600, 6 cores) · Needs: a 4-core PC or a Steam Deck (game-thread CPU, main against this PR)

Why

A player's first build spends most of its time compiling the game's code, which the lift turned into C. Most of that
code is ordinary functions, and clang's -O1 runs a group of whole-file passes over them (the inliner, constant
propagation across functions, function attributes ...) that do little for this code. Without them those files compile
about a fifth faster. This PR turns that on by default for the ordinary files and keeps every pass for the rest.
See #362 (a first build in under 10 minutes).

What changed

Lifted chunks whose functions are all under 1 MB compile at -O1 without its module passes (-mllvm -opt-disable=...).
The size test is on the lifted functions, so where LONGSHOT_SPLIT_GIANTS cuts some of them into pieces, the pieces
compile light too. The giant functions (1 MB or more), the hot pieces and every non-lifted file keep their flags. The
lifter's header helpers are all always_inline now, so the inliner's absence leaves none of them as a call.

  • build: nx2/build.py:
    • LIGHT_FLAGS, and light_passes_kb(), the size bar: the largest lifted function must be under
      LONGSHOT_LIGHT_PASSES_KB, 1024 KB by default.
    • lifted_flags, and source_flags: the per-source choice main() made inline (hot pieces, lifted chunks, the rest),
      moved into a function.
    • largest_function: the function-size scan mem_need already had, now shared.
    • lifted_largest keeps each lifted file's largest function in the hash record (hash_cache.json, load_hashes), so
      a build that already knows a file doesn't read it again.
    • The light flags are part of each object's key (object_key, flag_text), so the object cache and the object store
      never mix a light object with a full one.
    • light_flags_work: one tiny compile asks the compiler first. -opt-disable is LLVM 22's, and a Linux build from
      source may use the system's older clang (the README says it builds), which stopped every light chunk with "Unknown
      command line argument". With such a compiler the build prints a line saying so and every lifted chunk keeps main's
      flags.
  • lift: third_party/a64-kit/lift/a64_lift.py:
    • VFPX_HEADER's 7 SSE helpers (a64_v_ult, abs, big, zero, nonfin, subn, ovf) are now always_inline,
      and so are VSET_HEADER's and FPX_FZ_HEADER's non-SSE fallbacks. All are marked (longshot).
    • Without the module inliner, the 7 a64_v_* became real calls in 46 of 56 chunks (+4.6% game CPU in the first
      round below).
    • At full -O1 the objects keep their sizes and .text (a few dozen bytes differ: the COFF timestamp and a few
      offsets), and the exe's sections are the same sizes.
    • A deliberate a64-kit change: listed in its PROVENANCE.md note, with the tree-sha256 updated in the same commit
      (check_third_party.py --update a64-kit).
  • fast float regions: nx2/fastfp.py's FASTFP_HEADER, appended to the same a64_fpx.h, had two plain static helpers. a64_ff_enabled_ is called by A64_FF_ON at every fast float region; a64_ff_check is A64_FASTFP=check only. Both are always_inline now, like the rest of that header. KIT_TREE moves on with a64-kit's new tree-sha256 (its copy of emit_function is unchanged: test_fastfp_override.py compares them), and test_fastfp_regions.py's hook follows the enable line.
  • docs: docs/development.md: the switch's row.
  • tests: tests/test_light_passes.py (new, game-free). It fails on main. It checks:
    • which sources get the light flags: by default (including a chunk with a 300 KB function the splitter cuts), with
      LONGSHOT_SPLIT_GIANTS=0, with LONGSHOT_LIGHT_PASSES=0 (main's flags for every source), with a lower KB bar,
      and for kept files;
    • that the flags are in the object key, and that the largest function survives the hash record;
    • that a compiler which refuses the flags (or doesn't start) gets no light passes, that main() asks it, and that a
      real clang takes them exactly when it is LLVM 22 or newer;
    • that every static inline helper of a64_fpx.h is always_inline, and every static helper of fastfp's header too (apart from its one noinline cold printer).

Measurements

Verdict: faster to build, at a small game CPU cost.

  • Build: the 56 chunks this covers compile 21% faster (3,437 → 2,705 compiler-s in the clean pair). That's about
    15% of a first build's compile: roughly 3 minutes of its 22 at 4 jobs on this PC.
  • Code: identical in shape (the same symbols in every object, no helper left out of line), 3.2% larger in those
    chunks.
  • In the game, same build of this exact branch, 11 + 11 interleaved runs: game-thread CPU +0.75% (95% CI +0.12 to
    +1.38%, adjusted for the PC's other load). fps and frame times didn't change: 58.73 → 58.64 fps, frame time median
    16.97 → 16.96 ms.

Why the numbers still hold on main 8a4aa282: they were measured on main aa95d35f. main's build.py changes since (#30, #35, #37, #356, #540, #577, #660, #857, #673, #1001) don't change a lifted chunk's flags or which chunks compile, and #22's lift key still holds the lifter and fastfp.py (lift_sources), so this PR's header change lifts again once, as Compatibility says. The one change in what the light chunks hold is the fast float regions (#38), whose helpers this PR also makes always_inline (see Not tested).

Hardware: Windows 11 Home, Ryzen 5 5600 (6 cores / 12 threads), 16 GB (RAM at Auto, DOCP off), RX 6700 XT (AMD 26.10.1), Crucial P3 NVMe

Build time.
Scene: the build (no game): nx2/build.py --standalone --jobs 4 with RX_RELEASE=1 A64_HOT_CHUNK=1, RX_MARCH default (native: znver3)
Method: one lift (main 514591a3's, the same lifter as aa95d35f). The copy had two edits: a64_fpx.h as this PR's lifter writes it, and the 6 lines #573 removed from the lifter taken out of code_014.c. Main (aa95d35f) and this PR (6f53b75e: this head's three commits before the rebase onto cefce0d1, without the fastfp lines below) built it in one hold of the PC's job lock, toolchain nightly-130 (clang 23.1.5).

  • A1: main, everything.
  • B1: the light chunks, light.
  • A2: the light chunks' objects evicted, main again.
  • B2: evicted, light again.

Compiler seconds per file are from build.py's @@file lines. Symbols are from llvm-nm, .text from llvm-size, both on the cached objects.
How to reproduce: %LOCALAPPDATA%\LongshotMerge\bold\lightpasses\lp.py A1,B1,A2,B2,L,OFF, then lpcheck.py (local scripts: the lift is the game's)

Before: main @ aa95d35f After: this PR @ 6f53b75e Δ
light chunks 0 56 of 75 (1,248.5 MB of 1,381 MB of C; 50 of them have functions split into pieces, 7,790 pieces)
their compile, A2 / B2 (both after an eviction, back to back: the clean pair) 3,437.2 compiler-s, 890.7 s wall 2,704.7 compiler-s, 712.1 s wall -21.3% / -20.0%
their compile, A1 / B1 (A1 a whole build, B1 right after it) 3,321.4 compiler-s 2,930.7 compiler-s -11.8%
whole build, compiler-s (A1) 4,734 (lifted 4,135), 1,312 s wall ~4,000-4,350 (est.: A1 less 390-733 s) -8..-15%
.text of the 56 objects 327,184,740 337,623,823 +3.19%
longshot.exe .text / bytes 421,259,494 / 460,744,704 431,738,534 / 471,107,584 +2.49% / +2.25%
defined function symbols, 56 objects the same set the same set none differ
header helpers defined out of line a64_vfpx_mul32_lanes (cold, by design) a64_vfpx_mul32_lanes none new
LONGSHOT_LIGHT_PASSES=0 all 75 lifted object keys equal main's
A1 aa95d35f  compiled 523  4734.0 compiler-s (lifted 4135.3)  wall 1311.5 s  .text 421259494
A2 aa95d35f  compiled 56   3437.2 compiler-s  wall 890.7 s
B1 build: 56 lifted chunks without -O1's module passes (LONGSHOT_LIGHT_PASSES, functions under 1024 KB): code_000_1.c ... code_055.c
B1 compiled 56  2930.7 compiler-s  wall 777.2 s
B2 compiled 56  2704.7 compiler-s  wall 712.1 s  .text 431738534
OFF          LONGSHOT_LIGHT_PASSES=0: 0 compiled, every lifted object key = A1's
all light: a2 3437.2 s, b2 2704.7 s (0.787); text 327184740 -> 337623823 (+3.19%); symbol sets differ in 0 of 56; out of line: a64_vfpx_mul32_lanes in A and B

Game speed.
Scene: Hyrule Field from a pinned save, Link standing still, headless, muted, uncapped (HOS_FPS_MAX=1000, the log says "frame rate uncapped"), 1280x720, RX_VK_PRECOMPILE=0
Method: A and B built from one lift copy in one job-lock hold (nightly-189 toolchain, --jobs 4). A is this branch with LONGSHOT_LIGHT_PASSES=0: its 75 lifted object keys, exe size and .text equal main aa95d35f's build. B is the branch as is: exactly the 56 light chunks differ (50 as split pieces). Two warm-ups, then 11 + 11 interleaved ABBA runs of 240 s, measured over 120-230 s; one renderer DLL for all runs, only bin\longshot.exe swapped. Every run had its pipelines warm, no translation, no shader or pipeline wait in the window, VRAM 5.7-5.85 GB of 11.47 GB allowed, and no other game, compiler or VM running (watched every 5 s). Medians:
How to reproduce: %LOCALAPPDATA%\LongshotMerge\bold\lightpasses\gab\tools\gab_build.py A,B, then gab_runs.py and gab_sum.py (local scripts: the lift is the game's)

A: main's flags B: light (pieces light too) B/A
game-thread CPU (cores) 3.507 (3.464-3.554) 3.541 (3.509-3.575) 1.0097
game-thread CPU ms a frame 59.95 60.39 1.0073
whole process (cores) 6.242 6.266 1.0038
fps 58.73 (58.35-58.92) 58.64 (58.11-58.85) 0.9985
frame time median / p99 16.97 / 20.51 ms 16.96 / 20.59 ms 0.999 / 1.004
other load on the PC (cores) 0.416 0.428

Game-thread CPU, three ways:

  • Load-adjusted fit over all 22 runs: +0.75% (95% CI +0.12 to +1.38%).
  • Adjacent ABBA pairs: median +0.71%, with B higher in 9 of 11.
  • Rank test: p = 0.035.

The PC was quiet (0.42 cores of other load), so this small cost shows up as real. It fits the ~2.5% larger code. On
this 6-core PC it is off the frame's critical path: fps and frame times didn't move.

Earlier rounds (same flags, the same 56 chunks whole, on main 5e072fc8 before the giants were split; a busier PC):

  • Second round, with this PR's header: +1.0% median game-thread CPU; load-adjusted +1.2% (±1.1); pairs +0.27%.
  • First round, without the always_inline header: +4.6%, with 10 of 11 light runs above every main run. The header
    fix removed that.

The alternative considered: keep the inliner and turn off only the other module passes (no third_party change).
Compile was only -18% / -6% on code_051 / code_014_1, against -34% / -26% for this (two compiles of each, one at a
time). Rejected.

Flags and settings

One switch added, on by default.

Flag What it is Before this PR After this PR Effect Helps / doesn't help / untested Recommendation
LONGSHOT_LIGHT_PASSES Lifted chunks whose functions are all under the bar compile at -O1 without its module passes; 0 turns it off (none) on (unset); 0, off, false or no turns it off -21% compile on those chunks (56 of 75, their split pieces included); ~3% more code there; +0.75% game-thread CPU, fps the same (6 cores) Helps: first builds and every rebuild of those chunks. Costs: under 1% game CPU on 6 cores; untested on 4 cores and the Steam Deck On for everyone
LONGSHOT_LIGHT_PASSES_KB The bar: the largest lifted function, in KB of C, a light chunk may hold (none) 1024 A lower bar keeps more chunks at full -O1 Only for testing Leave unset

Testing

Tested:

  • The game-free checks, on Windows 11 with nightly-189's toolchain (python, llvm-mingw): python -I -B tests/run_all.py --jobs 4.
    • main @ 8a4aa282: 560 passed, 19 failed, 94 skipped. This PR @ d7bba514 (rebased on it): 561 passed, the same 19 failed,
      94 skipped (the extra pass is the new test).
    • The 19 fail on main on this PC too, and none reads build.py's flags or the lifter: test_audio_output_devices,
      test_auto_handheld, test_bug_report_defaults, test_crash_dialog, test_crt_options, test_failed_compile_keeps_objects,
      test_guest_imported, test_job_queue, test_linux_preflight, test_make_game_cache, test_missing_nup,
      test_pads_after_menu, test_pending_guest_import, test_portable_builder_home, test_portable_builder_startup,
      test_run_all_changed, test_tested_configurations, test_vk_occlusion_queries, test_walk_key.
    • test_fastfp_override.py, test_fastfp_regions.py and test_fastfp_fma.py pass with clang (the fast float regions' C compiled at x86-64-v2 and v3).
    • The new tests/test_light_passes.py passes here and fails on main (FAIL: nx2/build.py has no light passes).
    • python -I scripts/check_third_party.py: 13 parts as their notes say.
    • The compiler check, with nightly-189's clang 23.1.5: it takes the light flags (a light chunk's static inline helper
      stays a call, an always_inline one is inlined, nothing printed), and with an unknown -mllvm option added the check
      refuses, so the build would fall back to main's flags.
  • Real builds of the game's lift by main and by this PR, and with LONGSHOT_LIGHT_PASSES=0 (Build time).
  • In the game on this PC (Game speed): 22 runs, no crash, no shader or pipeline difference between A and B.

Not tested:

  • A real clang older than LLVM 22 (none on this PC). The check relies on LLVM's "Unknown command line argument" error,
    which LLVM gives for any option it doesn't know (checked above with a made-up one).
  • The fast float regions (#38) in the game with this PR. They merged after the game runs above (the lift there is from before them). Their header's two plain helpers, a64_ff_enabled_ (called at every region) and a64_ff_check (A64_FASTFP=check only), are always_inline here like the rest of it, and tests/test_light_passes.py checks it, so no helper stays a call; the game wasn't timed with fast float regions in it.
  • Linux. The rule is the same Python; the AppImage's clang is LLVM 23, and an older system clang falls back to main's flags (the compiler check).
  • A make_game.py build through the launcher. The switch is read by build.py alone.

Must be tested:

  • steamdeck, or a 4-core CPU (Windows or Linux): build main and this PR, run Hyrule Field headless and uncapped for a
    few minutes on each, interleaved, at least 3 runs each. Compare the game threads' CPU and the fps, expecting them
    within about 1-2% of each other (Test Farm: @Beanstalk steamdeck or a 4-core CPU: compare the game threads' CPU and fps
    of main and this PR in Hyrule Field, uncapped)

Risks

What could break: game speed on CPUs with few cores, if the ~3% larger code of the light chunks costs more there
than the +0.75% game CPU measured here. Correctness: none expected (-opt-disable skips only passes LLVM marks
optional, the same code compiled less; the game-free checks and 22 + 22 game runs found nothing).

Turning it off: LONGSHOT_LIGHT_PASSES=0 (those chunks compile again with main's flags), or revert the commit.

Compatibility: the lifter's header changes, so the first build after updating translates the game again (once), and
the light chunks compile again (their flags are in their keys). Saves, longshot_options.ini, the shader and pipeline
caches, the vk ABI and the builder's tools: nothing changes.

Issues

See #362

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).
  • No game files, dumps, build output or generated files.
  • third_party/ untouched (a new folder with a PROVENANCE.md instead). A deliberate change to a64-kit's lifter header, listed in its PROVENANCE.md note with the tree-sha256 updated in the same commit, as CONTRIBUTING allows.
  • 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 game-free test added for the fix, failing on main and passing here.
  • A check under tests/ that reads changed source updated in this PR, not weakened. (tests/test_light_passes.py is new; no existing check changed.)
  • Docs updated.

🤖 Generated with Claude Code

**Type:** perf · **Risk:** low · **Tested on:** Windows 11, RX 6700 XT (Ryzen 5 5600, 6 cores) · **Needs:** a 4-core PC or a Steam Deck (game-thread CPU, main against this PR) ## Why A player's first build spends most of its time compiling the game's code, which the lift turned into C. Most of that code is ordinary functions, and clang's `-O1` runs a group of whole-file passes over them (the inliner, constant propagation across functions, function attributes ...) that do little for this code. Without them those files compile about a fifth faster. This PR turns that on by default for the ordinary files and keeps every pass for the rest. See #362 (a first build in under 10 minutes). ## What changed Lifted chunks whose functions are all under 1 MB compile at `-O1` without its module passes (`-mllvm -opt-disable=...`). The size test is on the lifted functions, so where `LONGSHOT_SPLIT_GIANTS` cuts some of them into pieces, the pieces compile light too. The giant functions (1 MB or more), the hot pieces and every non-lifted file keep their flags. The lifter's header helpers are all `always_inline` now, so the inliner's absence leaves none of them as a call. - build: `nx2/build.py`: - `LIGHT_FLAGS`, and `light_passes_kb()`, the size bar: the largest lifted function must be under `LONGSHOT_LIGHT_PASSES_KB`, 1024 KB by default. - `lifted_flags`, and `source_flags`: the per-source choice `main()` made inline (hot pieces, lifted chunks, the rest), moved into a function. - `largest_function`: the function-size scan `mem_need` already had, now shared. - `lifted_largest` keeps each lifted file's largest function in the hash record (`hash_cache.json`, `load_hashes`), so a build that already knows a file doesn't read it again. - The light flags are part of each object's key (`object_key`, `flag_text`), so the object cache and the object store never mix a light object with a full one. - `light_flags_work`: one tiny compile asks the compiler first. `-opt-disable` is LLVM 22's, and a Linux build from source may use the system's older clang (the README says it builds), which stopped every light chunk with "Unknown command line argument". With such a compiler the build prints a line saying so and every lifted chunk keeps main's flags. - lift: `third_party/a64-kit/lift/a64_lift.py`: - VFPX_HEADER's 7 SSE helpers (`a64_v_ult`, `abs`, `big`, `zero`, `nonfin`, `subn`, `ovf`) are now `always_inline`, and so are VSET_HEADER's and FPX_FZ_HEADER's non-SSE fallbacks. All are marked `(longshot)`. - Without the module inliner, the 7 `a64_v_*` became real calls in 46 of 56 chunks (+4.6% game CPU in the first round below). - At full `-O1` the objects keep their sizes and `.text` (a few dozen bytes differ: the COFF timestamp and a few offsets), and the exe's sections are the same sizes. - A deliberate a64-kit change: listed in its `PROVENANCE.md` note, with the tree-sha256 updated in the same commit (`check_third_party.py --update a64-kit`). - fast float regions: `nx2/fastfp.py`'s FASTFP_HEADER, appended to the same `a64_fpx.h`, had two plain `static` helpers. `a64_ff_enabled_` is called by `A64_FF_ON` at every fast float region; `a64_ff_check` is `A64_FASTFP=check` only. Both are `always_inline` now, like the rest of that header. `KIT_TREE` moves on with a64-kit's new tree-sha256 (its copy of `emit_function` is unchanged: `test_fastfp_override.py` compares them), and `test_fastfp_regions.py`'s hook follows the enable line. - docs: `docs/development.md`: the switch's row. - tests: `tests/test_light_passes.py` (new, game-free). It fails on main. It checks: - which sources get the light flags: by default (including a chunk with a 300 KB function the splitter cuts), with `LONGSHOT_SPLIT_GIANTS=0`, with `LONGSHOT_LIGHT_PASSES=0` (main's flags for every source), with a lower KB bar, and for kept files; - that the flags are in the object key, and that the largest function survives the hash record; - that a compiler which refuses the flags (or doesn't start) gets no light passes, that `main()` asks it, and that a real clang takes them exactly when it is LLVM 22 or newer; - that every `static inline` helper of `a64_fpx.h` is `always_inline`, and every static helper of fastfp's header too (apart from its one `noinline` cold printer). ## Measurements **Verdict:** faster to build, at a small game CPU cost. - **Build:** the 56 chunks this covers compile 21% faster (3,437 → 2,705 compiler-s in the clean pair). That's about 15% of a first build's compile: roughly 3 minutes of its 22 at 4 jobs on this PC. - **Code:** identical in shape (the same symbols in every object, no helper left out of line), 3.2% larger in those chunks. - **In the game,** same build of this exact branch, 11 + 11 interleaved runs: game-thread CPU +0.75% (95% CI +0.12 to +1.38%, adjusted for the PC's other load). fps and frame times didn't change: 58.73 → 58.64 fps, frame time median 16.97 → 16.96 ms. **Why the numbers still hold on main 8a4aa282:** they were measured on main aa95d35f. main's build.py changes since (#30, #35, #37, #356, #540, #577, #660, #857, #673, #1001) don't change a lifted chunk's flags or which chunks compile, and #22's lift key still holds the lifter and fastfp.py (lift_sources), so this PR's header change lifts again once, as Compatibility says. The one change in what the light chunks hold is the fast float regions (#38), whose helpers this PR also makes `always_inline` (see Not tested). Hardware: Windows 11 Home, Ryzen 5 5600 (6 cores / 12 threads), 16 GB (RAM at Auto, DOCP off), RX 6700 XT (AMD 26.10.1), Crucial P3 NVMe **Build time.** Scene: the build (no game): `nx2/build.py --standalone --jobs 4` with `RX_RELEASE=1 A64_HOT_CHUNK=1`, `RX_MARCH` default (`native`: znver3) Method: one lift (main 514591a3's, the same lifter as aa95d35f). The copy had two edits: `a64_fpx.h` as this PR's lifter writes it, and the 6 lines #573 removed from the lifter taken out of `code_014.c`. Main (aa95d35f) and this PR (6f53b75e: this head's three commits before the rebase onto cefce0d1, without the fastfp lines below) built it in one hold of the PC's job lock, toolchain nightly-130 (clang 23.1.5). - A1: main, everything. - B1: the light chunks, light. - A2: the light chunks' objects evicted, main again. - B2: evicted, light again. Compiler seconds per file are from build.py's `@@file` lines. Symbols are from llvm-nm, `.text` from llvm-size, both on the cached objects. How to reproduce: `%LOCALAPPDATA%\LongshotMerge\bold\lightpasses\lp.py A1,B1,A2,B2,L,OFF`, then `lpcheck.py` (local scripts: the lift is the game's) | | Before: main @ aa95d35f | After: this PR @ 6f53b75e | Δ | |---|---|---|---| | light chunks | 0 | 56 of 75 (1,248.5 MB of 1,381 MB of C; 50 of them have functions split into pieces, 7,790 pieces) | | | their compile, A2 / B2 (both after an eviction, back to back: the clean pair) | 3,437.2 compiler-s, 890.7 s wall | 2,704.7 compiler-s, 712.1 s wall | -21.3% / -20.0% | | their compile, A1 / B1 (A1 a whole build, B1 right after it) | 3,321.4 compiler-s | 2,930.7 compiler-s | -11.8% | | whole build, compiler-s (A1) | 4,734 (lifted 4,135), 1,312 s wall | ~4,000-4,350 (est.: A1 less 390-733 s) | -8..-15% | | `.text` of the 56 objects | 327,184,740 | 337,623,823 | +3.19% | | `longshot.exe` `.text` / bytes | 421,259,494 / 460,744,704 | 431,738,534 / 471,107,584 | +2.49% / +2.25% | | defined function symbols, 56 objects | the same set | the same set | none differ | | header helpers defined out of line | `a64_vfpx_mul32_lanes` (cold, by design) | `a64_vfpx_mul32_lanes` | none new | | `LONGSHOT_LIGHT_PASSES=0` | | all 75 lifted object keys equal main's | | ``` A1 aa95d35f compiled 523 4734.0 compiler-s (lifted 4135.3) wall 1311.5 s .text 421259494 A2 aa95d35f compiled 56 3437.2 compiler-s wall 890.7 s B1 build: 56 lifted chunks without -O1's module passes (LONGSHOT_LIGHT_PASSES, functions under 1024 KB): code_000_1.c ... code_055.c B1 compiled 56 2930.7 compiler-s wall 777.2 s B2 compiled 56 2704.7 compiler-s wall 712.1 s .text 431738534 OFF LONGSHOT_LIGHT_PASSES=0: 0 compiled, every lifted object key = A1's all light: a2 3437.2 s, b2 2704.7 s (0.787); text 327184740 -> 337623823 (+3.19%); symbol sets differ in 0 of 56; out of line: a64_vfpx_mul32_lanes in A and B ``` **Game speed.** Scene: Hyrule Field from a pinned save, Link standing still, headless, muted, uncapped (`HOS_FPS_MAX=1000`, the log says "frame rate uncapped"), 1280x720, `RX_VK_PRECOMPILE=0` Method: A and B built from one lift copy in one job-lock hold (nightly-189 toolchain, `--jobs 4`). A is this branch with `LONGSHOT_LIGHT_PASSES=0`: its 75 lifted object keys, exe size and `.text` equal main aa95d35f's build. B is the branch as is: exactly the 56 light chunks differ (50 as split pieces). Two warm-ups, then 11 + 11 interleaved ABBA runs of 240 s, measured over 120-230 s; one renderer DLL for all runs, only `bin\longshot.exe` swapped. Every run had its pipelines warm, no translation, no shader or pipeline wait in the window, VRAM 5.7-5.85 GB of 11.47 GB allowed, and no other game, compiler or VM running (watched every 5 s). Medians: How to reproduce: `%LOCALAPPDATA%\LongshotMerge\bold\lightpasses\gab\tools\gab_build.py A,B`, then `gab_runs.py` and `gab_sum.py` (local scripts: the lift is the game's) | | A: main's flags | B: light (pieces light too) | B/A | |---|---|---|---| | game-thread CPU (cores) | 3.507 (3.464-3.554) | 3.541 (3.509-3.575) | 1.0097 | | game-thread CPU ms a frame | 59.95 | 60.39 | 1.0073 | | whole process (cores) | 6.242 | 6.266 | 1.0038 | | fps | 58.73 (58.35-58.92) | 58.64 (58.11-58.85) | 0.9985 | | frame time median / p99 | 16.97 / 20.51 ms | 16.96 / 20.59 ms | 0.999 / 1.004 | | other load on the PC (cores) | 0.416 | 0.428 | | Game-thread CPU, three ways: - Load-adjusted fit over all 22 runs: +0.75% (95% CI +0.12 to +1.38%). - Adjacent ABBA pairs: median +0.71%, with B higher in 9 of 11. - Rank test: p = 0.035. The PC was quiet (0.42 cores of other load), so this small cost shows up as real. It fits the ~2.5% larger code. On this 6-core PC it is off the frame's critical path: fps and frame times didn't move. **Earlier rounds** (same flags, the same 56 chunks whole, on main 5e072fc8 before the giants were split; a busier PC): - Second round, with this PR's header: +1.0% median game-thread CPU; load-adjusted +1.2% (±1.1); pairs +0.27%. - First round, without the `always_inline` header: +4.6%, with 10 of 11 light runs above every main run. The header fix removed that. **The alternative considered:** keep the inliner and turn off only the other module passes (no third_party change). Compile was only -18% / -6% on code_051 / code_014_1, against -34% / -26% for this (two compiles of each, one at a time). Rejected. ### Flags and settings One switch added, on by default. | Flag | What it is | Before this PR | After this PR | Effect | Helps / doesn't help / untested | Recommendation | |---|---|---|---|---|---|---| | `LONGSHOT_LIGHT_PASSES` | Lifted chunks whose functions are all under the bar compile at `-O1` without its module passes; `0` turns it off | (none) | on (unset); `0`, `off`, `false` or `no` turns it off | -21% compile on those chunks (56 of 75, their split pieces included); ~3% more code there; +0.75% game-thread CPU, fps the same (6 cores) | Helps: first builds and every rebuild of those chunks. Costs: under 1% game CPU on 6 cores; untested on 4 cores and the Steam Deck | On for everyone | | `LONGSHOT_LIGHT_PASSES_KB` | The bar: the largest lifted function, in KB of C, a light chunk may hold | (none) | 1024 | A lower bar keeps more chunks at full `-O1` | Only for testing | Leave unset | ## Testing **Tested:** - **The game-free checks,** on Windows 11 with nightly-189's toolchain (python, llvm-mingw): `python -I -B tests/run_all.py --jobs 4`. - main @ 8a4aa282: 560 passed, 19 failed, 94 skipped. This PR @ d7bba514 (rebased on it): 561 passed, the same 19 failed, 94 skipped (the extra pass is the new test). - The 19 fail on main on this PC too, and none reads build.py's flags or the lifter: test_audio_output_devices, test_auto_handheld, test_bug_report_defaults, test_crash_dialog, test_crt_options, test_failed_compile_keeps_objects, test_guest_imported, test_job_queue, test_linux_preflight, test_make_game_cache, test_missing_nup, test_pads_after_menu, test_pending_guest_import, test_portable_builder_home, test_portable_builder_startup, test_run_all_changed, test_tested_configurations, test_vk_occlusion_queries, test_walk_key. - test_fastfp_override.py, test_fastfp_regions.py and test_fastfp_fma.py pass with clang (the fast float regions' C compiled at x86-64-v2 and v3). - The new `tests/test_light_passes.py` passes here and fails on main (`FAIL: nx2/build.py has no light passes`). - `python -I scripts/check_third_party.py`: 13 parts as their notes say. - The compiler check, with nightly-189's clang 23.1.5: it takes the light flags (a light chunk's `static inline` helper stays a call, an `always_inline` one is inlined, nothing printed), and with an unknown `-mllvm` option added the check refuses, so the build would fall back to main's flags. - **Real builds** of the game's lift by main and by this PR, and with `LONGSHOT_LIGHT_PASSES=0` (Build time). - **In the game** on this PC (Game speed): 22 runs, no crash, no shader or pipeline difference between A and B. **Not tested:** - A real clang older than LLVM 22 (none on this PC). The check relies on LLVM's "Unknown command line argument" error, which LLVM gives for any option it doesn't know (checked above with a made-up one). - The fast float regions (#38) in the game with this PR. They merged after the game runs above (the lift there is from before them). Their header's two plain helpers, `a64_ff_enabled_` (called at every region) and `a64_ff_check` (`A64_FASTFP=check` only), are `always_inline` here like the rest of it, and `tests/test_light_passes.py` checks it, so no helper stays a call; the game wasn't timed with fast float regions in it. - Linux. The rule is the same Python; the AppImage's clang is LLVM 23, and an older system clang falls back to main's flags (the compiler check). - A make_game.py build through the launcher. The switch is read by build.py alone. **Must be tested:** - steamdeck, or a 4-core CPU (Windows or Linux): build main and this PR, run Hyrule Field headless and uncapped for a few minutes on each, interleaved, at least 3 runs each. Compare the game threads' CPU and the fps, expecting them within about 1-2% of each other (Test Farm: @Beanstalk steamdeck or a 4-core CPU: compare the game threads' CPU and fps of main and this PR in Hyrule Field, uncapped) ## Risks **What could break:** game speed on CPUs with few cores, if the ~3% larger code of the light chunks costs more there than the +0.75% game CPU measured here. Correctness: none expected (`-opt-disable` skips only passes LLVM marks optional, the same code compiled less; the game-free checks and 22 + 22 game runs found nothing). **Turning it off:** `LONGSHOT_LIGHT_PASSES=0` (those chunks compile again with main's flags), or revert the commit. **Compatibility:** the lifter's header changes, so the first build after updating translates the game again (once), and the light chunks compile again (their flags are in their keys). Saves, `longshot_options.ini`, the shader and pipeline caches, the vk ABI and the builder's tools: nothing changes. ## Issues See #362 ## 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`. - [x] `python -I -B tests/run_all.py` passes (any failure that also fails on `main` is named). - [x] No game files, dumps, build output or generated files. - [x] `third_party/` untouched (a new folder with a `PROVENANCE.md` instead). A deliberate change to a64-kit's lifter header, listed in its `PROVENANCE.md` note with the tree-sha256 updated in the same commit, as CONTRIBUTING allows. - [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 game-free test added for the fix, failing on `main` and passing here. - [x] A check under `tests/` that reads changed source updated in this PR, not weakened. (`tests/test_light_passes.py` is new; no existing check changed.) - [x] Docs updated. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
VFPX_HEADER's 7 SSE helpers (a64_v_ult, abs, big, zero, nonfin, subn, ovf), VSET_HEADER's and FPX_FZ_HEADER's non-SSE
fallbacks were plain static inline: -O1's module inliner inlined them, but lifted chunks compiled without it
(LONGSHOT_LIGHT_PASSES) left the 7 a64_v_* as real calls in 46 of 56 chunks, +4.6% game-thread CPU. always_inline
puts them back inline there. At full -O1 the objects keep their sizes and .text (a few dozen bytes differ: the COFF
timestamp and a few offsets) and the exe's sections are the same sizes.

nx2/fastfp.py's FASTFP_HEADER, appended to the same a64_fpx.h, had two plain static helpers: a64_ff_enabled_, which
A64_FF_ON calls at every fast float region, and a64_ff_check (A64_FASTFP=check only). Both are always_inline now, as
the rest of that header already was. test_fastfp_regions.py's hook follows the enable line.

A deliberate a64-kit change: listed in its PROVENANCE.md note, tree-sha256 updated
(python -I scripts/check_third_party.py --update a64-kit), and nx2/fastfp.py's KIT_TREE moved on with it (its copy of
emit_function is unchanged: test_fastfp_override.py compares them). The lift's output changes, so a build lifts again
once.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
A lifted chunk whose functions are all under LONGSHOT_LIGHT_PASSES_KB (1024) KB of C, and, while the giants are split
(LONGSHOT_SPLIT_GIANTS, on by default), under split_giants.MIN_KB (256 KB: no function the splitter cuts), compiles at
-O1 with -mllvm -opt-disable=<the module passes: inliner, ipsccp, globalopt, function-attrs ...>. The giants, the split
chunks, the hot pieces and every non-lifted file keep their flags. LONGSHOT_LIGHT_PASSES=0 turns it off.

- build.py: light_passes_kb(split), lifted_flags, source_flags (the per-source choice main() made inline);
  largest_function shared with mem_need; lifted_largest keeps the largest function in the hash record
  (hash_cache.json), so a build that knows a lifted file doesn't read it again. The flags are in the object keys.
- docs/development.md: the switch's row.
- tests/test_light_passes.py: which sources get the light flags (default, split off, =0, the KB bar, kept files, the
  object key, the hash record), and that every static inline helper of a64_fpx.h is always_inline.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
perf(build): light passes for the split chunks too (their pieces compile light)
Some checks failed
Website / Website on Cloudflare (pull_request_target) Has been skipped
PR description / Description follows the template (pull_request_target) Successful in 4s
beanstalk/approval needs a second approval (sensitive paths)
CI / Conventional Commit title (pull_request) Has been cancelled
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been cancelled
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been cancelled
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been cancelled
CI / Workflow lint (actionlint) (pull_request) Has been cancelled
Guide screenshots / Guide images and local UI source review (pull_request) Has been cancelled
Third-party parts / As their notes say (pull_request) Has been cancelled
Third-party parts / The same as upstream (pull_request) Has been cancelled
ae701d2886
The alternative rule: a chunk is light by its lifted functions' size alone (under 1024 KB), whether or not
LONGSHOT_SPLIT_GIANTS cuts some of them, so its pieces compile without the module passes too. Measured on the game's
lift (Ryzen 5 5600, --jobs 4, same conditions): 56 chunks, 3,437 -> 2,705 compiler-s (-21.3%), the same function
symbols in every object, no header helper out of line, .text +3.19%.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Author
Member

Tested in game: Windows 11, RX 6700 XT (AMD 26.10.1), Ryzen 5 5600: Hyrule Field from a pinned save, headless and uncapped, 11 + 11 interleaved runs of main's flags against this PR's (built from 6f53b75e, this head before the rebase and the fastfp lines). No crash, no shader or pipeline difference between the two, fps the same (58.73 against 58.64), game-thread CPU +0.75% (load-adjusted). The fast float regions (#38) were not in that lift: see Not tested.

Tested in game: Windows 11, RX 6700 XT (AMD 26.10.1), Ryzen 5 5600: Hyrule Field from a pinned save, headless and uncapped, 11 + 11 interleaved runs of main's flags against this PR's (built from 6f53b75e, this head before the rebase and the fastfp lines). No crash, no shader or pipeline difference between the two, fps the same (58.73 against 58.64), game-thread CPU +0.75% (load-adjusted). The fast float regions (#38) were not in that lift: see Not tested.
Author
Member

@Beanstalk steamdeck, or any 4-core CPU: build main and this PR, then run Hyrule Field uncapped for a few minutes on each, interleaved, at least 3 runs each. Compare the game threads' CPU and the fps, expecting them within about 1-2% of each other (on this 6-core PC: game-thread CPU +0.75%, fps the same).

@Beanstalk steamdeck, or any 4-core CPU: build main and this PR, then run Hyrule Field uncapped for a few minutes on each, interleaved, at least 3 runs each. Compare the game threads' CPU and the fps, expecting them within about 1-2% of each other (on this 6-core PC: game-thread CPU +0.75%, fps the same).
Member

@madebyjordan only members of BigBeans can start the farm. One of them can approve this request by reacting 👍 to it.

@madebyjordan only members of `BigBeans` can start the farm. One of them can approve this request by reacting 👍 to it.
Author
Member

@Beanstalk steamdeck, or any 4-core CPU: build main and this PR, then run Hyrule Field uncapped for a few minutes on each, interleaved, at least 3 runs each. Compare the game threads' CPU and the fps, expecting them within about 1-2% of each other (on this 6-core PC: game-thread CPU +0.75%, fps the same).

@Beanstalk steamdeck, or any 4-core CPU: build main and this PR, then run Hyrule Field uncapped for a few minutes on each, interleaved, at least 3 runs each. Compare the game threads' CPU and the fps, expecting them within about 1-2% of each other (on this 6-core PC: game-thread CPU +0.75%, fps the same).
Member

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

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

Beanstalk test farm

Commit d7bba51 · tier untrusted · approved by nobody yet · dashboard

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

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

<!-- beanstalk:sticky --> ### Beanstalk test farm Commit `d7bba51` · tier **untrusted** · approved by nobody yet · [dashboard](https://beanstalk.magicbean.dev/prs/1002) This diff touches sensitive paths, so it needs two members of `BigBeans`: `nx2/build.py`, `nx2/fastfp.py` A member of `BigBeans` can review this commit and comment `@Beanstalk` to test it.
madebyjordan force-pushed perf/light-passes from ae701d2886
Some checks failed
Website / Website on Cloudflare (pull_request_target) Has been skipped
PR description / Description follows the template (pull_request_target) Successful in 4s
beanstalk/approval needs a second approval (sensitive paths)
CI / Conventional Commit title (pull_request) Has been cancelled
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been cancelled
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been cancelled
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been cancelled
CI / Workflow lint (actionlint) (pull_request) Has been cancelled
Guide screenshots / Guide images and local UI source review (pull_request) Has been cancelled
Third-party parts / As their notes say (pull_request) Has been cancelled
Third-party parts / The same as upstream (pull_request) Has been cancelled
to d7bba51442
Some checks failed
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
CI / Python source checks (ubuntu-24.04, part 1/2) (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) Failing after 12s
CI / Workflow lint (actionlint) (pull_request) Successful in 13s
Third-party parts / As their notes say (pull_request) Successful in 18s
PR description / Description follows the template (pull_request_target) Successful in 4s
beanstalk/approval not approved yet
2026-11-16 11:14:17 +00:00
Compare
Author
Member

Reviewed and updated: rebased on main 8a4aa282 (clean, no conflicts) and one fix commit, d7bba514.

The fix: -mllvm -opt-disable is new in LLVM 22 (LLVM 20 and 21 don't have it). The README's Linux build without the AppImage uses the system's clang and says an older one still builds, but such a clang would have failed every light chunk ("Unknown command line argument"). build.py now asks the compiler once (light_flags_work: one tiny compile from stdin). If it refuses, the build prints a line saying so and every lifted chunk keeps main's flags. tests/test_light_passes.py checks the fallback, that main() asks, and that a real clang takes the flags exactly when it is LLVM 22 or newer. The docs row says it needs LLVM 22.

Checked:

  • run_all.py --jobs 4 on main 8a4aa282: 560 passed, 19 failed. On this head: 561 passed, the same 19 failed. None of the 19 reads build.py's flags or the lifter.
  • clang 23.1.5 takes the flags. A plain static inline helper stays a call, always_inline is still inlined, and nothing extra is printed.
  • The kept-lift path and the hash record's largest look right.
  • The lift key after #22 still hashes a64_lift.py and fastfp.py.

The Test Farm approval was for ae701d2. It needs approving again for d7bba514, and a second BigBeans member still has to approve it.

Reviewed and updated: rebased on main 8a4aa282 (clean, no conflicts) and one fix commit, d7bba514. **The fix:** `-mllvm -opt-disable` is new in LLVM 22 (LLVM 20 and 21 don't have it). The README's Linux build without the AppImage uses the system's clang and says an older one still builds, but such a clang would have failed every light chunk ("Unknown command line argument"). `build.py` now asks the compiler once (`light_flags_work`: one tiny compile from stdin). If it refuses, the build prints a line saying so and every lifted chunk keeps main's flags. `tests/test_light_passes.py` checks the fallback, that `main()` asks, and that a real clang takes the flags exactly when it is LLVM 22 or newer. The docs row says it needs LLVM 22. **Checked:** - `run_all.py --jobs 4` on main 8a4aa282: 560 passed, 19 failed. On this head: 561 passed, the same 19 failed. None of the 19 reads build.py's flags or the lifter. - clang 23.1.5 takes the flags. A plain `static inline` helper stays a call, `always_inline` is still inlined, and nothing extra is printed. - The kept-lift path and the hash record's `largest` look right. - The lift key after #22 still hashes `a64_lift.py` and `fastfp.py`. The Test Farm approval was for ae701d2. It needs approving again for d7bba514, and a second BigBeans member still has to approve it.
HumanBean deleted branch perf/light-passes 2026-11-16 11:19:50 +00:00
Owner

A build-time measurement on Linux, from after the merge. The description lists Linux as untested.

Hardware: Ryzen 9 7900X (24 threads), 30 GB, CachyOS, clang from the dev deps.
Method:

  • This PR's 3 commits rebased onto main @ 43f40b87, built twice as a dev_packs.py pack on a base of that main.
  • The two builds: LONGSHOT_LIGHT_PASSES=0 first, then the default. Both with LONGSHOT_OBJ_STORE=0, so every lifted chunk compiled.
  • Each build alone, under the timing lock (--timing --cpu-only, no game or other build beside it).
LONGSHOT_LIGHT_PASSES=0 default (light passes)
Lifted chunks without the module passes 0 62 (build: 62 lifted chunks without -O1's module passes)
compiled in 364 s 206 s
the build took 7:34 3:44
The whole pack (dev_packs.py pack) 462 s 231 s

On 24 threads the compile is 43% shorter and the whole pack half as long. That's more than the 21% on 4 jobs in the description. One caveat: this is one pair, with the off build first. The second build may have had a warmer disk cache, though with no object store the compile itself can't reuse objects. The runtime side wasn't measured here.

🤖 Generated with Claude Code

A build-time measurement on Linux, from after the merge. The description lists Linux as untested. **Hardware:** Ryzen 9 7900X (24 threads), 30 GB, CachyOS, clang from the dev deps. **Method:** - This PR's 3 commits rebased onto `main` @ 43f40b87, built twice as a `dev_packs.py pack` on a base of that main. - The two builds: `LONGSHOT_LIGHT_PASSES=0` first, then the default. Both with `LONGSHOT_OBJ_STORE=0`, so every lifted chunk compiled. - Each build alone, under the timing lock (`--timing --cpu-only`, no game or other build beside it). | | `LONGSHOT_LIGHT_PASSES=0` | default (light passes) | |---|---|---| | Lifted chunks without the module passes | 0 | 62 (`build: 62 lifted chunks without -O1's module passes`) | | `compiled in` | 364 s | **206 s** | | `the build took` | 7:34 | **3:44** | | The whole pack (`dev_packs.py pack`) | 462 s | **231 s** | On 24 threads the compile is 43% shorter and the whole pack half as long. That's more than the 21% on 4 jobs in the description. One caveat: this is one pair, with the off build first. The second build may have had a warmer disk cache, though with no object store the compile itself can't reuse objects. The runtime side wasn't measured here. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
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!1002
No description provided.