perf(hos): splice the host's memcpy, memset and string hooks into the lifted SDK #1209
No reviewers
Labels
No labels
area/accessibility
area/audio
area/input
area/install
area/menu
area/renderer
area/saves
area/tooling
area/upscaling
beanstalk: approved
beanstalk: failed
beanstalk: needs approval
beanstalk: running
beanstalk: tested
ci: approved
good first issue
gpu/amd
gpu/igpu
gpu/intel
gpu/nvidia
help wanted
kind
bug
kind
chore
kind
docs
kind
feature
kind
performance
kind
question
needs measurements
platform/linux
platform/macos
platform/steam-deck
platform/windows
preview
priority
critical
priority
high
priority
low
regression
risk
high
risk
low
risk
medium
status
blocked
status
confirmed
status
duplicate
status
invalid
status
needs-info
status
wontfix
ci: approved
No milestone
No project
No assignees
4 participants
Notifications
Due date
No due date set.
Dependencies
No dependencies set
Reference
MagicBeanDev/Longshot!1209
Loading…
Reference in a new issue
No description provided.
Delete branch "dyst/Longshot:perf/host-libc-hooks"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Type: perf · Risk: medium · Tested on: Windows 11, RTX 3080, in the game (Kokiri Forest, Hyrule Field) and game-free; Linux game-free · Needs: a Linux run in the game
Why
The game copies, clears and compares memory with the SDK's own
memcpy,memset,memcmpand string functions, run astranslated code: one byte-for-byte translation of ARM copy loops for every call, and for
memcpyan indirect jump throughthe SDK's own import table on top. The SDK's
memcpyalone is 58th in the hot list, called from 1,112 places in the game.host/nn_libc.chas had host versions of all six since the fork, but nothing in Longshot's lift ever called them, sothey never ran. This is for the CPU-bound frames in the worklist's 2.1 rows (Castle Town and Hyrule Field when the CPU is
the limit, Kokiri Forest while the camera turns).
What changed
The standalone lift now starts the SDK's
memcpy,memmove,memset,memcmp,strlenandstrcmpwith a call ofthe host's version. The host does the call when it stays inside the guest window and returns at once; otherwise, or with
HOS_GUEST_LIBC=1, the SDK's own translated code still runs, unchanged, right behind it.nx2/entry_hooks.py(new) reads theENTRY_HOOK_SYM(sym)hookshost/*.cdefines, finds each symbol where thesdk module defines it (the image's symbol table, as the HLE set is found), and wraps the emit so that function's C
starts with
{ extern int entry_sym_<sym>(Ctx *A64_NOESC); if (entry_sym_<sym>(c)) return; }. Direct calls, tail callsand indirect calls all enter through that line.
nx2/lift.pyinstalls the wrap at module level (so the emit's newprocesses have it too) and calls
entry_hooks.addin the standalone lift before discovery; it logsentry hooks: 6 of 6 (...)andentry hooks spliced: N. The table goes to the emit processes with the others(
nx2/chunks.pyEMIT_TABLES), and the hooked functions keep their registers in the context (Lifter.no_local).nx2/make_game.pylift_keynames the hooks, so adding or removing one lifts again.ENTRY_HOOK_SYM_FROM(sym, min)(host/hos.h) is a hook called only when x2, the size, isminor more.The spliced line tests the size itself (
if (c->x[2] >= 8ULL && entry_sym_memset(c)) return;), so a smaller call staysin the lifted code at the cost of one compare.
memsetis gated at 8 bytes andmemcmpat 16: below those the call cost1-4 ns more than it saved (micro-benchmark below).
memmoveswitches to non-temporal stores at about 1.75 MB. Its copy then took 1.4x the liftedcopy's time and left the destination out of the cache, so the game's next read of it took 4-5x as long (micro-benchmark
below). Copies and fills over 256 KB (
LIBC_PIECE) now go in pieces below that size (copy_pieces,fill_pieces).Each piece is marked once written, and the lifted loop's interrupt poll (
A64_POLL, the virtual cores' hand-off) runsbetween pieces. Overlapping copies go forward or from the end, as
memmovewould.host/nn_libc.c.memcmpandstrcmpnow return their result zero-extended in x0, as the SDK's 32-bit resultleaves it (they sign-extended before). The first hooked call logs which version is in use (
libc: ...). WithHOS_HLE_STATS=1thehle:linescount the calls the host took (
libc_memcpy,libc_memmove,libc_memset,libc_memcmp,libc_strlen,libc_strcmp)and those done in pieces (
libc_pieced). The counting is out of line, so the small calls' path stays as short. How the switch isread is unchanged apart from atomic loads.
host/hos.h: the comments say what splicesENTRY_HOOK_SYM, and thatENTRY_HOOK(addr)is not spliced in Longshot.memcpyjumps through its import tableto an optimized copy that handles overlapping ranges in either direction, as
memmovedoes. Itsmemmovehandlesoverlap and passes non-overlapping copies on to
memcpy. Itsmemsetstores the value's low byte. All three return thedestination in x0 unchanged.
memcmpandstrcmpreturn the difference of the first unequal bytes, compared unsigned,as a 32-bit value.
strlencounts up to the NUL. The host'smemmove,memset,memcmploop andstrlengive thesame result in every case.
HOS_WRITTEN(hos_mark_written), which marks every 4 KB pageof the written range after the data is written (for each piece, once that piece is written). The translated stores mark
the same pages: each store marks the page of its first and its last byte, and a copy writes every byte of its range. The
set of pages marked is identical; the only difference is timing: the host marks a piece's pages once it is copied, where
the lifted loop marks them as it goes. One mark per page, so a copy inside one page is one store.
docs/development.mdhas a row forHOS_GUEST_LIBC.Measurements
Verdict: in the game, a small gain in Kokiri Forest with the camera turning, 38.6 fps against 37.7 (+2.3%, all three of this PR's runs above all three of main's), and level in CPU-bound Hyrule Field (50.6 against 50.6), where the first version of these hooks lost 3.8%. Micro-benchmark
(below): the host path is as fast or faster than the SDK's lifted functions at every size it now takes, 2-9x faster from
128 bytes, and large copies no longer leave their destination out of the cache.
Hardware: Windows 11 Pro, Ryzen 9 3900X, one thread pinned (core 4), the job queue idle
Scene: none (micro-benchmark); in the game: Kokiri Forest from the repository's
kokiri-startsave, the camera turning, and Hyrule Field (the debug teleport toHyruleField_Child), the camera still; uncapped, headlessMethod: the SDK's lifted
memcpy(f_8572f020, whose import-table jump goes to the optimized copyf_8575cdc0),memset,memmove,memcmp,strlenandstrcmp, cut out of the lift of main @ c167 and compiled as the hot pieces are (-O2,x86-64-v3, write marks on, the call site's indirect-jump cache). Each was timed against the same function with this PR's
spliced line first, and against the hooks before this change (5839334c). The window was at the game's guest base, warm
caches, best of 7 runs of 4,000,000/(n+32) calls, medians over 3-4 runs of the whole set. For large copies: one copy of
cache-warm data, then a read of every line of the destination.
How to reproduce: the harness is not in the PR because it compiles the game's lifted code; any lifted
gen/code_*.cwith the functions above and the hooks fromhost/nn_libc.cwill do71b1edd8(lifted SDK)00ad3e5bThe first in-game A/B (main @
71b1edd8against 5839334c, Ryzen 9 3900X, RTX 3080, warm) lost 3.8% in CPU-bound HyruleField (1% lows 29.5 to 24.7 fps) and was level in Kokiri Forest. The micro-benchmark found no small-size cost large
enough to explain that. It did find the non-temporal large copies, which match both the lower average and the worse 1%
lows. This commit fixes those copies.
In the game, the re-run (main @
5c284721against this PR @00ad3e5b; Windows 11 Pro N, Ryzen 9 3900X, 64 GB, RTX 3080, a hard drive; one game folder updated in place between the two (make_game.py --update, warm stores), an unmeasured run of each scene first, then the order main, PR, PR, main, main, PR, one 45 s window per scene after each install withab2.py; through the PC's job queue (--mode timing); medians of 3):5c28472100ad3e5bWith
HOS_HLE_STATS=1(one untimed Hyrule Field run), the host takes in a typical 5 s of play about 229,000memcpy, 202,000memset, 100,000strcmp, 56,000strlen, 29,000memcmpand 4,800memmovecalls, and copies in pieces about once (974 times in the 5 s that held the teleport's load). So the large copies happen in loads, rarely in play: they fit the first version's worse 1% lows, but the Field average it lost may also have been the tinymemsets now gated below 8 bytes (the busiest hook), or partly that set's own spread (its two runs were 5% apart).Flags and settings
HOS_GUEST_LIBCexisted already but did nothing, because the hooks never ran. Now it switches them off.HOS_GUEST_LIBC(set)Testing
Tested: in the game on Windows 11 (Measurements: the re-run, the counters, the log lines). Game-free on Windows 11 (TDM gcc for the fixtures, llvm-mingw clang for the objects), as follows.
tests/test_libc_hooks.py(new):a64_lift.Lifter: the hooked function starts with the hook's line andthe rest of its text is unchanged. A symbol in another module, an HLE'd symbol, an address that is no entry and an
undefined symbol are left out.
mod 16, every overlap in both directions. memcmp and strcmp with bytes above 0x7f. The marks must be set after the
data.
between pieces counted.
lifted body under its size and the host from it.
HOS_GUEST_LIBC=1.python -I -B tests/run_all.py --jobs 8 --changed longshot/main(the checks that read the changed files, on main @5c284721):96 passed, 8 skipped, 10 failed. The 10 failures also fail on a clean
mainworktree, with the same failing cases:test_make_game_cache,test_linux_preflight,test_walk_key,test_failed_compile_keeps_objects,test_job_queue,test_missing_nup,test_run_all_changed,test_crash_dialog,test_vk_occlusion_queries, andtest_walk(nolz4module in this Python).
host/nn_libc.ccompiled with llvm-mingw clang at the build's host flags. A lifted-shaped function with the splicedline compiled against the generated
a64.h.python:3.12, gcc 14):nn_libc.ccompiled;test_libc_hooks,test_guest_copies(its mmap fixture)and
test_lift_entry_belowpass.Not tested: Linux and macOS in the game; Castle Town Market (its teleport's measured window was a blank screen, on main too).
Must be tested:
libc: ... are the host'sline, no picture or behaviour change, and fps the same or higher.Risks
What could break:
the SDK's behaviour, including overlapping copies and the exact x0.
data.
most one piece (about 10 us).
own non-temporal threshold (a share of the L3). The pieces keep copies below it there too, but that was not measured.
Turning it off:
HOS_GUEST_LIBC=1(same exe), or revert the commit.Compatibility: The lift key changes, so the next build lifts the game again and recompiles the lifted files that hold
these six functions. Saves,
longshot_options.ini, the shader and pipeline caches and the vk ABI are unchanged.Questions for reviewers
memcmp/strcmpnow zero-extend x0, which is exactly what the SDK's code leaves there. Any caller reads only w0, sothis changes nothing for compiled code, but it does differ from the hooks as written before. Is the change welcome?
memcpykeeps it. Should that be wider?ENTRY_HOOK(addr)(by address) is still not spliced, and no hook uses it. Should this splice handle it too, or shouldthe macro be removed?
CPU and on Linux before merge?
nx2/lift_fixes.pydoes for its entry goto) rather than a lifter table, becausethird_party/a64-kitstays untouched. Is a wrapper OK here?Checklist
Everyone
type(scope): description) of the status line's type.main.python -I -B tests/run_all.pypasses (any failure that also fails onmainis named).third_party/untouched (a new folder with aPROVENANCE.mdinstead).When it applies
Assisted-by:/Co-Authored-By:trailers.tests/that reads changed source updated in this PR, not weakened.🤖 Generated with Claude Code
Tested in game: Windows 11, RTX 3080: Kokiri Forest (turning) and Hyrule Field, main
5c284721against this PR, 3 warm interleaved runs each: Kokiri +2.3%, Field level; all 6 hooks spliced and logged as the host'sWIP: perf(hos): splice the host's memcpy, memset and string hooks into the lifted SDKto perf(hos): splice the host's memcpy, memset and string hooks into the lifted SDKReviewed
00ad3e5b36328883bc4065ddc08d21f9350b1dc7, code and posted evidence only. Request changes; not ready for final merge approval. No builds, tests, generators or games were run for this review, and no source changes were made.Code finding: the newly activated
memcmp,strlenandstrcmphooks do not enforce the guest-window boundary promised by this PR and documented byhos_guest_range()inhost/hos.h. See the inline comment. Copy/fill hooks have the check; compare/string hooks still form uncheckedGP()pointers and enter the native CRT. The new boundary fixture iterates only throughMEMSET, so it misses all three readers. Please close that path and extend the fixture before enabling these hooks for all callers.Readiness evidence to settle before marking ready:
tests/run_all.py --changed longshot/main(96 passed, 8 skipped, 10 baseline-matched failures). Current guidance requires the whole suite before a PR is ready. Please provide that full-run result and baseline explanations, or leave the box unticked with the reason and keep WIP. I am not treating the documented baseline failures or skips as passes.docs/tested/files for the new measured runs. Add one self-contained run record per measured session, with build/settings/method/results, and retain the applicable tested-configurations checklist item. The documented six warm interleaved gameplay sessions should have their corresponding records.The implementation otherwise has several good safeguards: SDK-only symbol selection, preserving the original lifted body on a declined hook,
no_localfor hooked entries, emit-worker transport of the hook table, and lift-key inclusion of hook names/size gates. Large overlapping copies select the correct direction, mark each completed piece after writing it, and poll between pieces. The new test exercises these semantics across alignments, overlap boundaries, size gates and signed byte differences. Its worker-table/splice integration assertions are source/wiring checks, not an actual spawned-worker integration run.Evidence acknowledged, not independently rerun: the author's revised Windows A/B reports Kokiri 37.7 -> 38.6 fps (+2.3%, three PR runs above all three baseline runs), Hyrule Field 50.6 -> 50.6 fps, and Linux game-free compilation/fixtures. The earlier 3.8% Field loss was followed by a revised implementation and another interleaved A/B; I am reviewing that revision, not repeating the old regression as an unresolved finding. Market was not successfully measured, as disclosed. Linux gameplay and portability/performance of the platform CRT remain unproven here.
On the reviewer questions: zero-extending the documented 32-bit SDK compare result is appropriate; keep the initial scope at SDK definitions; there is no need to add address hooks or remove the unused macro in this PR; and the emit wrapper is a reasonable way to keep vendored a64-kit untouched. Linux validation is already mandatory in Testing; Intel CPU threshold testing would strengthen the recommendation but I am not inventing an additional merge gate beyond the stated coverage.
Related open work: #1202 rewrites lifted lane-permute idioms; it is not the same optimization as activating these six SDK entry hooks. No duplicate libc-hook PR was found in the open-title search. Main has moved beyond the measured merge base, so any subsequent rebase should retain the documented rationale for the evidence or remeasure affected paths.
@ -56,2 +131,2 @@ENTRY_HOOK_SYM(memcmp) {if (guest_libc()) return 0;ENTRY_HOOK_SYM_FROM(memcmp, 16) {if (guest_libc() || ARG(2) < 16) return 0;[P2] Check the guest window before taking the compare/string hooks. Unlike memcpy/memmove/memset above, memcmp does not validate either [argument, argument+n) before GP() and the native CRT call; strlen and strcmp below likewise accept unchecked starting addresses and do not bound their scans to HOS_SPACE_END. For example, memcmp with x0=HOS_SPACE_END-8 and x2=16 still returns handled rather than declining before a host read crosses the window. hos.h explicitly documents that GP alone can wrap to an arbitrary host address. These bodies existed before, but this PR newly splices them into the SDK entries, making the unchecked paths live by default. Validate both memcmp ranges before forming the pointers, and use bounded guest-window handling for the string readers that declines before any out-of-window access. Extend the boundary fixture to the three readers: its current loop stops at MEMSET, so the advertised outside-window fallback is not checked for them. No in-game crash is claimed from this code-only review.
The copies and fills check the guest window, and a large one goes in pieces that are marked after they are written. I read head
00ad3e5b. It applies onto current main. The three readers do not, which is the change already asked for on this head.memcmp,strlenandstrcmpform a host pointer withGPand call the C library before either range is known to lie in the guest window.hos_guest_rangeis what the copies use, and its comment saysGPalone can wrap to any host address. Amemcmpwhose first address is 8 bytes before the end of the window and whose length is 16 still returns handled.strlenandstrcmpwill scan until a NUL, including past that end.Decline those three before any host read.
memcmptakes both ranges throughhos_guest_range.strlenandstrcmpstop at the end of the window, and a missing NUL there is the lifted body. The outside-window check intests/test_libc_hooks.pystops atmemset. It should include these three.The Linux run in Must be tested is still open: the same two scenes, the
libc:line, no change in the picture, and fps the same or higher. The measured sessions have no file underdocs/tested/. The full-suite box is ticked, and Testing namesrun_all.py --changed.A Linux run in the game, on a Steam Deck OLED: the hooks run, the frame rate is the same, and the game reaches play 4 to 7 s sooner.
HOS_GUEST_LIBC=1(the game's own)libc: memcpy, memmove, memset, memcmp, strlen and strcmp are the host'sunset, and... are the game's ownwith the switch.544229a2alone, the same day: 29.05 and 29.16 fps in the wide view.Hardware and method: Steam Deck OLED (AMD Custom APU 0932, 4 cores / 8 threads, RADV VANGOGH), SteamOS 3.9.5, 16 GB, on the charger, the GPU at a manual 1600 MHz. One game build on the Deck by the Linux builder (
--jobs 4), no hot list: main544229a2with this PR and three others merged locally (#120900ad3e5b, #11584e889b09, #1377e4a1471d, #875d51401bc), each measured by its own switch in that one binary. Headless runs from a save, 720 presents measured once the scene has settled, the player's settings (a low internal resolution, 768x432 passes; a texture budget of 2,800 MB) with the frame cap lifted (HOS_FPS_MAX=1000), numbers from the game's own log lines. No picture check (no display). 0 fatal lines in the 18 starts and 2 tours of the session.View command line instructions
Checkout
From your project repository, check out a new branch and test the changes.