feat(host): HOS_NATIVE_ZSTD in the in-run A/B #1726
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
3 participants
Notifications
Due date
No due date set.
Dependencies
No dependencies set
Reference
MagicBeanDev/Longshot!1726
Loading…
Reference in a new issue
No description provided.
Delete branch "zeldaootr/Longshot:ab-native-zstd"
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
Whether a native zstd decode keeps its virtual core (
HOS_NATIVE_ZSTD=2) or gives it up (=1) could only be compared across separate runs, which differ by more than most changes are worth:HOS_NATIVE_ZSTDwas read once, soHOS_ABcould not alternate it. This PR lets the in-run A/B flip that rule, so both sides share one run and one scene state:HOS_AB=HOS_NATIVE_ZSTD=<1 or 2>,<seconds>,<warm-up>alternates the mode in force with that value. It is for developers and testers measuring the zstd core rule on their own hardware. The default, every run withoutHOS_AB, the decoder, andHOS_NATIVE_ZSTD=0(the lifted decoder, which cannot be flipped) do not change.Since #1875 the default comes from the renderer's device policy while the switch is unset: 1 (the core given up) on every GPU except Intel integrated GPUs, which keep 2; a value set still wins. The A/B flips whichever mode is in force, set or the GPU's default, as
hos_ab_valuedoes for the other wired switches (their normal value is the one in force, default included): on a GPU whose default is 1,HOS_AB=HOS_NATIVE_ZSTD=2measures keeping the core against it.Why: #1632 made the native zstd decode keep its virtual core, which fixed load freezes on an Arc 155H. On a Steam Deck OLED that default costs about a third of the frame rate where the game decodes in the background (Kokiri Forest in our runs), and another Deck sees no difference because its scene is not decoding. Separate runs can't settle that kind of question cheaply; an in-run A/B can. Still open: why Kokiri decodes in the background on one Deck and not on another (#1477).
Read first:
zs_core()inhost/hos_zstd.creturnshos_ab_value("HOS_NATIVE_ZSTD", mode);hos_zstd_streamuses it to decide whether to wrap the chunk inhos_vcore_away/hos_vcore_back. An A/B value other than 1 or 2 is taken as 2 and logged once.zs_mode(), the on/off choice and the mode in force (the value set, else the GPU's default throughHOS_OPT_NATIVE_ZSTD), is unchanged and still read once; until the renderer can answer, a call keeps the core (2) and the A/B flips that.gpu/vk/switches.def: theHOS_NATIVE_ZSTDrow (main'shwrow, its default by GPU) gains a sentence:HOS_ABmay flip it between 1 and 2, not to 0 (read once:dev.py ab --separate). Main's developing guide points to the rows ("HOS_AB may flip it") and totests/test_hos_ab.pyrather than listing the A/B's switches in prose, so that row is this PR's doc text now.tests/test_hos_ab.pylists the switch among the wired ones;tests/test_native_zstd.pydecodes streams with the value flipping at every other call and checks each call's core hand-over and the output, with the mode set (2 against 1, 1 against 2) and unset (the renderer's 1 against 2, its 2 against 1, and 2 against 1 before it can answer), plus a broken copy that never reads the A/B.See #1477
Testing
Tested: in the game on a Steam Deck OLED (SteamOS 3.9.5, RADV) with the A/B on, at 1b15e8a4d (this PR's patch on main before #1875, when main's default was 2; later rebases moved only doc and comment lines, and the one onto
3df5c13edkeepszs_coreas it was, now over the GPU's default): five runs of 340 to 460 s, two standing in Kokiri Forest, two in Hyrule Field (standing, then camera pans), one in the Castle Town market (standing, then a camera-pan cycle). All five ended normally (exit 0, no error lines) and the sides alternated every 5 s; the Kokiri and market logs' closingab:lines have no "never read" note, and the Field's say the switch was never read during the A/B, as expected where nothing is stream-decoded.On Windows 11 (Intel Core i9-13900K, NVIDIA GeForce RTX 4090, driver 621.24, 64 GB), by Jiro113 (#1726, their comment of 2026-11-19 13:58): built with llvm-mingw at
c03bcb70plus the two commits of #1729 (maindid not build on Windows without them then; this PR'shost/andnx2/are unchanged by them), withtests/test_native_zstd.py(zstandard0.25.0),tests/test_hos_ab.py,tests/test_switch_table.pyandtests/test_doc_anchors.pypassing there, run one by one. In the game,HOS_AB=HOS_NATIVE_ZSTD=1,3,60andRX_VK_FRAME_TRACE=1, three minutes walking in Castle Town's south market, closed through the control bridge: a closingab:line with frames on both sides and no "never read" note (side 0 54.7 fps, side 1 59.3 fps, -7.71 % at a 60 fps ceiling: DLSS Frame Generation 2x with V-Sync Auto on a 120 Hz screen), plus the two uncapped runs in Measurements.Game-free, on Linux x86-64, at this head (
7c5cf948aon main3df5c13ed):tests/test_hos_ab.pyandtests/test_native_zstd.pyfail at the test-only commitcbd3c4389(every new A/B case but=2against 0, which keeps the core either way) and pass here;tests/test_native_zstd.pyrun with thezstandardmodule (0.25.0): every part PASS. The 27 checks that readhost/hos_zstd.corgpu/vk/switches.def, plustests/test_device_policy.py(28 in all), here and on main3df5c13edin a clean worktree, same environment: 21 pass, 7 fail on both with the same messages (test_crash_dialog,test_dev_ab,test_frame_overlap,test_linux_pressure,test_present_queue_default,test_target_reuse_memory,test_vk_occlusion_queries: this PC's environment);test_native_zstd,test_hos_ab,test_switch_tableandtest_device_policypass on both.host/hos_zstd.ccompiled (-c, the build's host flags,-Wall) with gcc and clang for Linux and llvm-mingw 20261104 for Windows, at this head and on main3df5c13ed: no warnings on either.The whole
python3 -I -B tests/run_all.py(not--strict) was run at the previous head (88ff71239on main068fb8ebe), not again at this one: 74 failed both there and on main068fb8ebein the same environment (missing tools and modules, timing); 12 more failed in a run shared with two other full suites and each passed when run again alone (nx2/test_coop_spirv.py,nx2/test_default_point_size.py,nx2/test_draw_parameters.py,nx2/test_mesh_first_types.py,nx2/test_spirv_struct_identity.py,test_appimage_package_retry,test_fpx_sticky,test_mesh_fallback_layout,test_mesh_unreachable_outputs,test_pipeline_cache_file,test_pipeline_cache_save,test_pipeline_state_sources).The 74 checks that failed both at the previous head (
88ff71239) and on main068fb8ebenx2/test_nup_codec.py,nx2/test_nup_read_name.py,nx2/test_nup_stand_in.py,nx2/test_nup_verify.py,test_appimage_player_build,test_bug_report_defaults,test_capture_read_once,test_capture_readback_visibility,test_crash_dialog,test_crt_options,test_damage_debug_menu,test_dav1d_av1,test_dev_ab,test_dev_packs,test_discover,test_display_startup_failure,test_dlss_feature_size,test_draw_stream_visibility,test_failed_compile_keeps_objects,test_frame_overlap,test_fsr3fi_hud_layer,test_fsr_image_retirement,test_fsr_uniform_ownership,test_guest_imported,test_high_fps_fixes,test_host_guest_writes,test_hud_layout_row,test_insn_fixed_convert,test_libc_hooks,test_lift_cache,test_lift_lookups,test_linux_preflight,test_linux_pressure,test_linux_tools,test_linux_update,test_log_open_failure,test_make_game_cache,test_make_game_ngx,test_mise_build,test_missing_nup,test_mods_list,test_mods_size_table,test_native_zstd,test_ngx_sdk,test_nonuniform_image_arrays,test_parallel_init_order,test_pending_guest_import,test_perf_report,test_pipeline_play_cache,test_prepare_cache_save,test_prepare_stall,test_present_queue_default,test_present_source_crop,test_present_thread,test_profiling_mode,test_prompt_guide_lines,test_prompt_hand_guides,test_prompt_picture_tint,test_prompt_speed,test_psychov35_fsr3_fg,test_readback_timeout_source,test_recorder_sync,test_replay_write_order,test_slow_frames,test_song_note_cue,test_staging_burst,test_texel_buffer_ownership,test_thinlto_tls,test_upscaler_rows,test_vbytes,test_vcore_escape,test_vk_occlusion_queries,test_walk,test_walk_keyStill to test:
ab:line with frames on both sides (by hand)Measurements
Verdict: the A/B works and resolves the rule's cost in one run, scene by scene. On a Steam Deck OLED, side 1 (
=1, the core given up) against side 0 (2, main's default when these runs were made): standing in Kokiri Forest 34.4 % less frame time, 19.1 against 29.1 fps (two runs); in the Castle Town market 15.7 % less, 14.7 against 17.4 fps (one run); in Hyrule Field no difference, 33.9 against 34.0 fps (two runs), because nothing is stream-decoded there and the switch was never read. On Windows with an RTX 4090 (Jiro113) the gap is far smaller and two runs don't settle it. This PR changes no default, so it has no before/after of its own: the table's columns are the A/B's two sides in the same runs.These runs were taken with this PR on main before #1875, whose default was 2. On current main (
3df5c13ed) the default on these PCs (a Steam Deck, an RTX 4090) is 1, so the same comparison isHOS_AB=HOS_NATIVE_ZSTD=2with the sides swapped; the A/B code is unchanged, and #1875 cites these numbers beside its own.Baseline: both columns are this PR's build (1b15e8a4d, v3.0.0-5-g1b15e8a4d) within the same runs: the before side is the rule in force, then main's default (
HOS_NATIVE_ZSTD2), the after sideHOS_NATIVE_ZSTD=1. That is the comparison this PR exists for; main cannot alternate the rule. 1b15e8a4d is this PR's patch before the rebases (onto868f6be87and now068fb8ebe), which moved only doc and comment lines: the code is the same.Setup: Steam Deck OLED, SteamOS 3.9.5, RADV VANGOGH (Mesa 26.2.0-devel 5c65d4fc31), AMD Custom APU 0932, 16 GB, GPU clock set by hand to 1600 MHz; Kokiri Forest standing, daytime; Hyrule Field after a teleport from Kokiri, 30 s standing then camera pans; the Castle Town market (child) after a teleport, standing, then one camera-pan cycle; 1280x800, Minimum, Render 50%, the game's own upscaler, sharpness 30, frame generation off, frame pacing on, no cap; headless, fresh options, no
longshot_env.txt.RX_VK_FRAME_TRACE=1 HOS_AB=HOS_NATIVE_ZSTD=1,5,150(5 s periods after 150 s); five runs (Kokiri 2, Field 2, market 1), each about 300 s of A/B;scripts/ab_summary.pyon the frame traces (both runs of a scene together, transition frames left out, bootstrap interval with seed 1) and each log's closingab:line. To reproduce: a save standing in Kokiri Forest (or teleport to the market or Hyrule Field), the settings above, the two switches inlongshot_env.txt, thenpython -I scripts/ab_summary.py <game folder>/logs/longshot_frames.csv.HOS_NATIVE_ZSTD2 (side 0, then the default): this PR @ 1b15e8a4dHOS_NATIVE_ZSTD=1(side 1): this PR @ 1b15e8a4dEach run's sides:
The logs' closing lines (the host's own count, before
ab_summary.pyleaves out the periods' edges):The Field's "never read" note is the A/B working as it should: no stream decode happened there during the A/B, so both sides ran the same code and the difference is noise. The gap exists only while the game decodes in the background: another Steam Deck OLED saw none standing in Kokiri, with its decode threads idle (#1477). In the market run MemAvailable fell to 576 MiB at its lowest (one sample under 768 MiB), in a run both sides shared; in Kokiri and the Field it stayed above 1.6 GiB. All five runs exited 0 with no error lines. The Kokiri and the Field have two runs each; the market one run of 57 interleaved periods.
On Windows (Jiro113's runs, their numbers): Windows 11, Intel Core i9-13900K, NVIDIA GeForce RTX 4090 (driver 621.24), 64 GB; this PR at
c03bcb70with the two commits of #1729. Castle Town's south market (child), walking a scripted route through the control bridge, 2560x1440 windowed, HDR10, DLAA, frame generation off, V-Sync off, Reflex on, frame pacing on, no cap (HOS_FPS_MAX=1000);RX_VK_FRAME_TRACE=1 HOS_AB=HOS_NATIVE_ZSTD=1,5,150, two runs of about 315 s of A/B (126 periods together). Over both runs side 1 (=1) has 4.39 % less mean frame time, 65.7 against 62.8 fps, with a 95 % interval of -9.09 to +0.23 % that holds 0: the gap is far smaller than on the Deck and two runs don't settle it (run 2 alone -5.59 %, interval -10.81 to -0.91 %; run 1 -3.18 %, interval -11.70 to +4.50 %). The tail is shorter with 1 (p99 37.15 against 28.51 ms in run 1, 34.38 against 24.04 in run 2); the median is a little longer with 1 (14.31 against 14.66 ms over both).HOS_NATIVE_ZSTD2 (then the default)HOS_NATIVE_ZSTD1The switch: no new switch;
HOS_NATIVE_ZSTD(2 keeps the virtual core, 1 gives it up, 0 the lifted decoder) ships at main's default, unchanged (unset: the GPU's, 1 except on Intel integrated GPUs, which keep 2; a value set wins), and is still read once withoutHOS_AB; with it, the A/B may alternate the mode in force with 1 or 2. Measured on a Steam Deck OLED (Kokiri, the market, Hyrule Field) and on Windows 11 with an RTX 4090 (the market, by Jiro113). Off (noHOS_AB), the added cost is one load a decode call; it was not timed apart.Risks
A flip between two decode calls of one stream could break a decode; the test runs exactly that at every other call, and the rule touches nothing the stream keeps. Without
HOS_ABnothing changes, so it is off unless a developer turns it on; a revert is enough to undo it. A player notices nothing after updating: saves,longshot_options.iniand the caches are untouched.Checklist
Ready for review
main; the title is a Conventional Commit.mise run testpasses (any failure that also fails onmainis named). [at this head: the checks that read the changed files, the same as on main3df5c13ed; the whole suite at the previous head, Testing]main, or Measurements says why there is nothing to measure. [the A/B's two sides in the same runs; main cannot alternate the rule: Baseline]third_party/untouched; nothing GPL-incompatible.When it applies
gpu/vk/switches.def. [HOS_NATIVE_ZSTD's default, the GPU's from the device policy, unchanged; its row says what the A/B may flip]tests/that reads changed source is updated, not weakened.c03bcb70;host/hos_zstd.ccompiled for both at this head]HOS_NATIVE_ZSTDrow ingpu/vk/switches.def]Assisted-by:/Co-Authored-By:trailers.Ready to merge
main, measured again or a comment says why the numbers still hold. [the head is not pushed yet; the numbers are from 1b15e8a4d, the same A/B code, on main before #1875 (default 2): Measurements says how they map onto the new default]Tested in game: Steam Deck OLED, SteamOS 3.9.5, RADV (Mesa 26.2.0-devel): two Kokiri Forest runs with HOS_AB=HOS_NATIVE_ZSTD=1,5,150 at 1b15e8a4d (the same code before a rebase), both ended normally with both sides counted.
Tested on Windows: it builds, and the A/B alternates and closes as Must be tested asks.
Build: Windows 11, llvm-mingw. This PR at
c03bcb70, with #1729's two commits on top (19937d05,44ab7f74), because main does not build on Windows without them since #475; this PR'shost/andnx2/are unchanged by them. The checks this PR touches pass there, run one by one (notrun_all.py):tests/test_native_zstd.py(withzstandard0.25.0),tests/test_hos_ab.py,tests/test_switch_table.py,tests/test_doc_anchors.py, and #1729'stests/test_descriptor_array_census.py. In the game: that tree'slongshot.exeandlongshot_vk.dll(scripts/dev_packs.py), over the game data of a folder built at544229a2.Hardware: Intel Core i9-13900K, NVIDIA GeForce RTX 4090 (driver 621.24), 64 GB, Windows 11
Must be tested:
HOS_AB=HOS_NATIVE_ZSTD=1,3,60andRX_VK_FRAME_TRACE=1, a save walking in Castle Town's south market for three minutes, driven and closed through the control bridge (itsquit: the game's own close, which prints the line). The log's lastab:line, frames on both sides and no "never read" note (and no "taken as 2" line):The frame trace has the
ab_sidecolumn andscripts/ab_summary.pyreads it (61 periods; side 1 -7.65 %, 95 % interval -11.08 to -4.64 %). That run had DLSS Frame Generation 2x with V-Sync Auto (FIFO on a 120 Hz screen), which holds the game to 60 frames a second: side 1 sits at that ceiling (median 16.64 ms), side 0 just above it (median 17.06 ms, 57.4 % of its frames at 16.7 ms or more against 48.7 %), and its p99 is 37.59 ms against 26.17.Uncapped, as in the Deck runs: the tail is shorter with 1 in both runs, p99 37.15 against 28.51 ms and 34.38 against 24.04 (
ab_summary.pygives no interval for p99), but the mean moves much less than on the Deck (a different scene too: walking in the Market, not standing in Kokiri), and two runs don't settle it. Over both runs side 1 has 4.4 % less mean frame time (62.8 against 65.7 fps), with a 95 % interval of -9.09 to +0.23 % that holds 0; run 2 alone shows a gap (-5.59 %, interval -10.81 to -0.91 %), run 1 doesn't (-3.18 %, interval -11.70 to +4.50 %). The median is a little longer with 1 (14.31 against 14.66 ms over both). Same PC and scene as the capped, profiled cell in #1477 (comment); these runs have no profiling switches.Scene: Castle Town's south market (child), walking a scripted route through the control bridge; 2560x1440 in a window, HDR10, DLAA, frame generation off, V-Sync off, Reflex on, frame pacing on, no cap (
HOS_FPS_MAX=1000)Method:
RX_VK_FRAME_TRACE=1 HOS_AB=HOS_NATIVE_ZSTD=1,5,150, about 315 s of A/B a run (63 periods), two runs;scripts/ab_summary.pyon both frame traces (the game's own frames); the build aboveHOS_NATIVE_ZSTD2 (default),c03bcb70+ #1729HOS_NATIVE_ZSTD1,c03bcb70+ #1729Side 1 less side 0, both runs: -0.699 ms (-4.39 %), 95 % interval -1.447 to +0.037 ms (-9.09 to +0.23 %). The table's frames are
ab_summary.py's: the frame trace's, without the last, unfinished period; the closing lines count the host's presents.If a
docs/tested/file for these runs would help, I can write its text.Measurements now include the Deck's other two scenes. In the Castle Town market,
=1gives 17.4 fps against 14.7 at the default (-10.65 ms, 95 % interval -13.17 to -8.05, 57 periods). In Hyrule Field the two sides match (34.0 against 33.9 fps, interval -0.69 to +0.61, 74 periods), because nothing is stream-decoded there and the log says the switch was never read. Jiro113's Windows build and run (#1726, 2026-11-19 13:58) settles Must be tested and the Windows box; the new commit adds onedocs/tested/file per Deck run (five), and run_all's 49 failures are named, all of them the same onmain. Thank you @Jiro113 for the Windows build and runs.WIP: feat(host): HOS_NATIVE_ZSTD in the in-run A/Bto feat(host): HOS_NATIVE_ZSTD in the in-run A/B6edf79347f88ff712398Rebased onto main
068fb8ebe, the docs and tools revamp (head88ff71239, both code commits kept). Main no longer lists the in-run A/B's switches in prose:docs/dev/developing.mdpoints to theirswitches.defrows, so this PR's doc text is now theHOS_NATIVE_ZSTDrow ingpu/vk/switches.def(1 and 2 may be flipped, 0 may not), andhos_zstd.cdrops itsdocs/tested/reference. Main removed the tested-configurations catalogue, so the commit with the fivedocs/tested/run files is dropped and their numbers live in the description's Measurements, which now follows the new template. The game-free checks fail nothing that main doesn't also fail on this PC, andtests/test_native_zstd.py, run with thezstandardmodule, passes.One thing for a reviewer to weigh, now that main has
dev.py ab: because this PR wiresHOS_NATIVE_ZSTDinto the in-run A/B,dev.py ab --env HOS_NATIVE_ZSTD=0would pick an in-run A/B for it, and the value 0 cannot be flipped in a run (a stream begun on libzstd can't go on in the lifted decoder), sozs_coretakes it as 2 and logs that once. Both sides would then run the same code and the write-up would read "within the spread". Today only the switch's row ingpu/vk/switches.defwarns of it ("HOS_AB may flip it between 1 and 2, not to 0 (read once: dev.py ab --separate)").I have not changed
scripts/devtools/ab.pyhere, since that is another topic and another owner's file. Two ways it could be closed, whichever you prefer:dev.py abrefusing an in-run A/B when the game logs that it took the value as another (the log line is there to key on), or a per-switch list of values the in-run A/B accepts next totests/test_hos_ab.py's WIRED list. Say which and I'll do it in a follow-up.Same picture on a Ryzen desktop:
HOS_NATIVE_ZSTD=1cuts the Market's slow frames by about a third. Would you take the default to 1 per platform in this PR, or do you mind if I open a PR for that which builds on this one?Ryzen 9 9900X, RTX 4070 SUPER, Windows 11, main
89c3d21e; a recorded Market walk with camera turns, 4K DLSS Quality:=2(2 runs)=1(3 runs)No hang at a load in ~20 runs with
=1. Since #1632's Core Ultra 7 155H hasn't been checked after #1553 yet, I'd suggest=1everywhere except Intel iGPUs for now.Thanks, that matches the Steam Deck. Please go ahead and open the default change as its own PR on top of this one: this PR only adds the switch to the in-run A/B, and I would rather keep it to that so it can merge without waiting on the per-platform decision.
For your PR, the Deck numbers from #1477 (Steam Deck OLED, v3.0.0, Minimum, Render 50%, uncapped, in-run A/B): Kokiri Forest 19.1 fps at
=2against 29.1 at=1(-18.00 ms a frame, CI -18.78 to -17.19), the Market 14.7 against 17.4, Hyrule Field no difference (the switch is never read there). So=1on the Deck is supported by what I measured; I have no Intel iGPU to say anything about that exception, and no hang at a load in my runs with=1either. I can run your PR on the Deck when it is up.Opened it as #1875:
HOS_NATIVE_ZSTDdefaults to 1 everywhere except Intel iGPUs, which keep 2.If you'd like to run it on the Deck, a test in Kokiri Forest and the market against main would show whether your gain holds with the per-GPU default; the log should say
HOS_NATIVE_ZSTD=1, this GPU's default.88ff7123987c5cf948a7Rebased onto main
3df5c13ed, after #1875 made the default the GPU's (1 except on Intel integrated GPUs) while the switch is unset: the A/B now flips whichever mode is in force, set or the GPU's default, as the other wired switches do, and the test adds those unset cases (head7c5cf948a, test commitcbd3c4389). The checks that read the changed files and the Linux and Windows compiles match main; the in-game numbers are from before the rebase, when the default was 2, and the description now says how they map onto the new default.View command line instructions
Manual merge helper
Use this merge commit message when completing the merge manually.
Checkout
From your project repository, check out a new branch and test the changes.