WIP: perf(nvn): a recording thread reuses the texture copy it last got at an address (HOS_NVN_TEX_COPY_CACHE=1 to try it) #2026
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!2026
Loading…
Reference in a new issue
No description provided.
Delete branch "siantm/Longshot:perf/nvn-tex-copy-cache"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Summary
A recording keeps the textures it refers to by pointer to an immutable copy (
tex_copyinhost/nvn_native.c),because the game may finalize or reuse a texture object after recording, before the submit; the copies are kept in a
table, one per content. Every texture a recording refers to (SetRenderTargets, the texture copies, the blits) went
through that table: FNV-1a a byte at a time over the whole texture object, then
pin_locktaken exclusively, by everyrecording thread, for a texture bound the same way pass after pass.
With
HOS_NVN_TEX_COPY_CACHE=1, each recording thread keeps, for 64 slots of object addresses, the copy it last gotthere. When the object at that address still holds what the copy holds, that copy is returned without the hash or the
lock. It is the copy the table would give: a copy is told apart by the object's bytes before its serial (the last
member, which a
_Static_assertkeeps so), read as they are by the table's hash, the table's comparison and thecache alike (
pin_hash,pin_same), and made byte for byte; the table keeps one copy per content, and copies arenever freed or moved (
pins_growmoves the table's slots, not the copies), so a kept pointer stays good. A textureinitialized again at the same address with the same content (TOTK's transient targets: a new serial each frame) still
hits; anything else goes to the table. The result expected: fewer hashes of texture objects and fewer exclusive
pin_locksections on the recording threads; the same copies.Both ways: the table's hash and comparison read the object's bytes before its serial directly instead of a struct
copy of the object (whose padding need not be kept), a new copy is made byte for byte, and the recordings' log line
(every 50,000 recordings) counts the lookups and those a thread's kept copy answered; each recording thread counts its
own and adds them to the shared totals every 1,024 lookups, so no shared count is touched per lookup.
The switch:
HOS_NVN_TEX_COPY_CACHE(new, an attempt, bool, its row ingpu/vk/switches.def), off unless set,since nothing of it is measured in the game: unset or
=0is main's lookup, every texture through the table;=1(any value but
0,false,off,noor empty) turns it on. It is read at the first texture a recording refers toand cached; threads recording together may each read the variable, and all keep the first answer stored. An empty
value in
longshot_env.txton Windows removes the variable (off, as unset).From the local integration commit d1e33769 on
exp/x86-asm-sync, where it had no switch and was not measured. Priorwork: a forge search (tex_copy, pin_hash) finds no pull request on it; #1812 (GummiNaomi, closed unmerged by its author
with no change at 4 or 16 cores) worked on the recordings' copies, not on the texture copies.
Read first:
pin_hash,pin_same,tex_copy_cache_onandtex_copyinhost/nvn_native.c, thentests/test_nvn_tex_copy_cache.py.Testing
Tested: Windows 11, i7-9700, RTX 4060, the builder's llvm-mingw clang 23; head
ec5c6569on main7c23d2be(main has since added only contributed pipeline-state lists, #2041). Queue jobfb-2023-5of this PC's job queue, every check in a hidden console:tests/test_nvn_tex_copy_cache.pyat the test commit9a19cb1ffails on the branch's earlier code (the switch on when unset); at the head,tests/run_all.py --strict --exact tests/test_nvn_tex_copy_cache.py tests/test_switch_table.py tests/test_recording_log_handoff.py tests/test_host_alloc_wait.py: 4 passed;tests/test_nvn_tex_copy_cache.pyagain with no--ccand noCC(llvm-mingw found throughLONGSHOT_MINGW): passes;tests/run_all.py --strict --changed 7c23d2be: 52 checks, 40 passed, 9 failed, 3 skipped (Linux-only); the 9 failures fail on main @7c23d2betoo, run from a base worktree in the same job:tests/test_crash_dialog.py,tests/test_dev_ab.py,tests/test_dev_packs.py,tests/test_frame_overlap.py,tests/test_host_guest_writes.py,tests/test_linux_pressure.py,tests/test_present_queue_default.py,tests/test_target_reuse_memory.py,tests/test_vk_occlusion_queries.py;host/nvn_native.ccompiles with the game build's own compile command (syntax only). The whole suite (mise run test) and lint did not run here (Still to test).It has NOT run in the game on this PC yet.
Still to test:
Castle Town Market walking through the crowd, on main @
7c23d2be, this PR unset and this PR withHOS_NVN_TEX_COPY_CACHE=1, each warmed a minute, then at least three interleaved three-minute runs of each (ABC ABCABC), expecting the same picture, the same texture copies count in the recordings' log line, most lookups answered by
a kept copy with it set, and average fps, 1% lows, median and p99 frame times and peak host memory of this PR with it
set at least those of the other two; a difference beyond the runs' spread is a gain or a loss, one within it is no
difference measured (by hand)
main, on this PR unset and on this PR with
HOS_NVN_TEX_COPY_CACHE=1, warmed and interleaved, expecting the samepicture and no FATAL (the test farm: linux+nvidia, linux+amd, windows+amd, windows+intel, steamdeck: Kokiri Forest
and Castle Town Market three minutes, main, HOS_NVN_TEX_COPY_CACHE unset and =1, warmed and interleaved, the log,
frame times and a screenshot)
python3 -I -B tests/test_nvn_tex_copy_cache.py --cc gcc, expecting PASS (by hand)mise run testandmise run lintat this head, expecting every failure tofail on main too and lint to pass (by hand; neither tool is installed on this PC)
Measurements
Verdict: not measured: no micro-benchmark of this port and no run in the game on this PC yet (the branch did not
measure it either), so it is off by default; the in-game A/B is in Still to test. The texture copies count alone
cannot show it (it counts contents, not lookups); the log line's lookup counts can.
Risks
What could break: with it set, a recording given a copy of another texture's content would draw with the wrong texture
or target; the cache returns a kept copy only when
pin_samefinds it equal to the object, the table's owncomparison, and the test checks every copy against its object over 20,000 lookups with objects rewritten in between,
one copy per content, a serial-only change, two threads, and a table grown while full, on and off. Memory with it set:
1 KiB of thread-local slots on each thread that records. Unset (the default), what changes from main: the table hashes
and compares the object's bytes before its serial without copying the object first, makes a copy byte for byte, and
the log line has two more counts. Turn it off: unset it or
HOS_NVN_TEX_COPY_CACHE=0.Host code: the runtime is rebuilt; nothing changes for players' saves, options or caches.
Checklist
Ready for review
main; the title is a Conventional Commit.mise run testpasses (any failure that also fails onmainis named).main, or Measurements says why there is nothing to measure.third_party/untouched; nothing GPL-incompatible.When it applies
gpu/vk/switches.def.Assisted-by:/Co-Authored-By:trailers.Ready to merge
main, measured again or a comment says why the numbers still hold.Every texture a recording refers to (SetRenderTargets, the texture copies, the blits) went through tex_copy's table of immutable copies: FNV-1a a byte at a time over the whole texture object, then pin_lock taken exclusively, by every recording thread, for a texture bound the same way pass after pass. Each thread now keeps, for 64 slots of object addresses, the copy it last got there; when the object at that address still holds what the copy holds (the bytes before the serial, which a _Static_assert keeps as the last member), that copy is returned without the hash or the lock. It is the copy the table would give: the table keeps one copy per content (pin_same: the object with its serial left out), and copies are never freed or moved (pins_grow moves the table's slots, not the copies they point at), so a kept pointer stays good. A texture initialized again at the address with the same content (TOTK's transient targets, a new serial each frame) still hits; anything else goes to the table. From the branch's local integration commit d1e33769 on exp/x86-asm-sync, which had it with no switch and no measurement ("Not measured yet"). HOS_NVN_TEX_COPY_CACHE (new, kill switch, its row in gpu/vk/switches.def): on by default, as the branch shipped it; =0 looks every texture up in the table, as before. Read once, published atomically (threads that come first together keep one answer). Not measured. Test: tests/test_nvn_tex_copy_cache.py compiles the real tex_copy, its switch's reader and the copies' table cut from the source, and runs 20,000 lookups over 300 object addresses rewritten in between (a new serial with the same content, another content, another texture's content), on and off, then a second thread: one copy per content, every copy holding its object's content, the same copies either way; on, a repeated look takes no lock; off, every look takes it. The test sets the switch in each run's own process (unset, 0, off, No, 1, yes, 2, and 0 again) and sets it the other way after its first read, which must not change the answer. The C compiler is --cc, $CC, LONGSHOT_MINGW's clang on Windows, then clang, gcc or cc. Assisted-by: Claude CodeRecommendation: Request changes. The cache and the table can disagree about texture bytes because they compare different representations. The fixture also misses the serial-only and thread-local cases that justify the cache, and the default-on speedup remains unproven.
Recording threads can skip the texture hash and exclusive lock when they reuse a texture at the same address. The change adds a 1 KiB thread-local array and a probe on the active path. The replay still receives immutable texture copies, but the two lookup paths need a shared definition of equality.
@fixwill do (10)host/nvn_native.c:2318: The cache compares the stored bytes directly, while pin_same and pin_hash first assign the texture to temporary structs. (more on the line)gpu/vk/switches.def:131: The entry says an empty value disables the cache. (more on the line)tests/test_nvn_tex_copy_cache.py:139: The fixture only checks lock avoidance on an immediate repeat with no intervening write. (more on the line)tests/test_nvn_tex_copy_cache.py:148: The worker starts after the main thread finishes lookups and only checks the returned pointers. (more on the line)tests/test_nvn_tex_copy_cache.py:112: The main thread settles the switch before the worker starts. (more on the line)tests/test_nvn_tex_copy_cache.py:80: The fixture creates at most 40 pins, so it never grows a populated table. (more on the line)tests/test_nvn_tex_copy_cache.py:43: The fixture requires pthreads even on Windows. (more on the line)tests/test_nvn_tex_copy_cache.py:174: A compiler command such as CC='ccache gcc' is passed as one executable name, so the test fails before compiling. (more on the line)host/nvn_native.c:2316: Add profiling-only per-thread hit and miss counters or use lock-wait profiling. Keep shared counters out of the timed hot path.40bfceb0, seven commits past the stated base75317e1f. Clear the box until the branch is current, then update the tested commits and rerun the comparison or explain why the results still apply.For the author (1) (a run, a measurement or a decision)
host/nvn_native.c:2316: The planned texture-copy count measures unique pins, so it can stay the same even if every cache lookup misses. (more on the line)Checks: Still running:
CI / Conventional Commit title (pull_request),CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request),CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request),CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request),CI / Workflow lint (actionlint) (pull_request),CI / Website build and checks (pull_request),Guide screenshots / Guide images and local UI source review (pull_request),Third-party parts / As their notes say (pull_request),Third-party parts / The same as upstream (pull_request).More: does it help, other systems, switches, what was read
Does it help: Unproven. The PR reports 38 of 47 selected Windows checks passing at
ca876a10, including the new fixture and switch-table check. It reports the other nine failures on base75317e1fas well. The fixture demonstrates that an immediate repeated lookup can avoid the lock. There are no in-game FPS, frame-time, hit-rate or lock-wait measurements.Other systems: The same host path serves color and depth attachments, buffer-to-texture and texture-to-buffer transfers, texture blits, and texture clears on every Vulkan device. Replay consumes the copies through const pointers, and table growth only moves the slots. Descriptor registration, submit ordering, GPU allocation, save, audio, input and runtime file formats are outside the diff. Windows, Linux and Steam Deck all need gameplay coverage because the host-side change precedes device selection.
Switches: Adds HOS_NVN_TEX_COPY_CACHE, a developer kill switch that defaults to on and has a sorted entry in gpu/vk/switches.def. Setting it to 0 forces table lookups while retaining the switch check. Measurements have yet to establish the right default. The table's empty-value promise disagrees with Windows config-file loading.
Reviewed:
ca876a1056against75317e1f31: Read AGENTS.md, CONTRIBUTING.md, the Forgejo template, the developer standards, the full commit and diff, the full new fixture, and all changed host and switch-table lines. Read the relevant texture writers, guest-range and environment helpers, table and recording callers, and Vulkan replay consumers. Skimmed unchanged portions of host/nvn_native.c and the switch table, plus test-runner and build integration. The named Windows logs were absent from the checkout, so the run evidence came from the PR description. docs/review-checklist.md was absent. No generated files or translations changed.; nothing run (a code review).Checked and fine:
Testing: Static review only. No build, test or project script was run. The author reports selected Windows checks. The required author-PC gameplay run had yet to happen when the PR opened, and a full suite run, Linux host and GCC verification, Tier 1 gameplay runs and CI results are still outstanding.
Overlaps and merge order: No overlapping open PR identified in the supplied material or checkout history. The description identifies #1812 as closed and covering recording copies.
Automated code review by BeanBot (gpt-6.2-sol), on the pull request's opening. Nothing was run; a maintainer decides.
@ -128,6 +128,7 @@ SW(HOS_NVN_REC_SHIFT, tune, int, "16", "The page shift (12-24) the command recorSW(HOS_NVN_STRICT, diag, bool, "off: an unimplemented NVN call is logged once and answered 0", "Stops the game at the first NVN call that is not implemented.")SW(HOS_NVN_SYNC_BLOCK, attempt, bool, "off: nvnSyncWait honours the game's timeout", "An nvnSyncWait poll waits for the GPU without a timeout.")SW(HOS_NVN_SYNC_LOG, diag, int, "off", "Logs fences, sync waits and event reads with the caller: first 30000, or 400 from the n-th present.")SW(HOS_NVN_TEX_COPY_CACHE, kill, bool, "on: a recording thread keeps the texture copy it last got for each of 64 object addresses and reuses it while the object holds the same", "=0 (or false, off, no, empty; any other value is on) looks every texture up in the copies' table under its lock, as before. Read once, at the first texture a recording refers to.")L2 (minor): The entry says an empty value disables the cache. On Windows, putting HOS_NVN_TEX_COPY_CACHE= in longshot_env.txt goes through host/hos_main.c's _putenv, which removes the variable and leaves the cache on. Document 0 as the portable file override and state the empty-value exception, or preserve empty boolean values through file loading and test that path.
@ -2292,0 +2313,4 @@kept here stays good; a texture initialized again at the address (TOTK's transient targets: a new serial, thesame content) still compares equal, anything else goes to the table. Not measured yet */static _Thread_local struct { uint64_t at; const nvn_tex *pin; } last[64];const int cache = tex_copy_cache_on();L9 (minor): The planned texture-copy count measures unique pins, so it can stay the same even if every cache lookup misses. Interleave base, head off and head unset on matched hardware, builds and player settings in Kokiri Forest and a heavier scene such as Castle Town Market. Report average FPS, 1% lows, median and p99 frame times, cache hits or lock waits, and host memory. Cover the affected Tier 1 configurations before choosing the shipping default.
@ -2292,0 +2315,4 @@static _Thread_local struct { uint64_t at; const nvn_tex *pin; } last[64];const int cache = tex_copy_cache_on();const unsigned k = (unsigned)((t >> 4) ^ (t >> 10)) & 63;if (cache && last[k].at == t && !memcmp(last[k].pin, o, offsetof(nvn_tex, serial))) {L1: The cache compares the stored bytes directly, while pin_same and pin_hash first assign the texture to temporary structs. nvn_tex has padding before L and within L, and C struct assignment can change padding. If the copy into the pin leaves different padding from the guest object, an unchanged texture can keep missing the cache even when the table finds the same pin. Use one key for hashing and both comparisons, and preserve its bytes when creating a pin. If padding should be ignored, canonicalize it consistently for all three operations.
@ -0,0 +40,4 @@ROOT = Path(__file__).resolve().parents[1]FIXTURE = r"""#include <pthread.h>L7: The fixture requires pthreads even on Windows. A checkout using the documented Clang and Visual Studio SDK route can select clang from PATH and then fail on pthread.h. A MinGW fixture linked to a shared pthread runtime also needs that DLL discoverable when launched from the temp directory. Use native Windows threads and a Windows lock in the fixture, and keep pthreads for Linux.
@ -0,0 +77,4 @@@CODE@#define NOBJ 300#define NCONTENT 40L6 (minor): The fixture creates at most 40 pins, so it never grows a populated table. The cache relies on a pin staying valid through that operation. Force a populated resize in the fixture and check that a previously cached address still returns its original pin with the expected lock count.
@ -0,0 +109,4 @@int main(int argc, char **argv) {if (argc != 2) return 2;test_on = atoi(argv[1]);read_once(tex_copy_cache_on, "HOS_NVN_TEX_COPY_CACHE", test_on);L5 (minor): The main thread settles the switch before the worker starts. The fixture would pass if the first-use atomic publication were replaced with a racy plain static. Add a concurrent cold-start case that exercises publication, for example using a controlled environment-reader stub and checking that all callers return the same winning value.
@ -0,0 +136,4 @@tex_copy(&pin, (uint64_t)(uintptr_t)&objs[i]);check(i, pin);calls++;if (!changed) { /* (the same lookup again at once: on, this thread's cache has it whatever came before) */L3: The fixture only checks lock avoidance on an immediate repeat with no intervening write. A cache that also compares serial would pass those checks and miss the transient-target case. Add a deterministic sequence that primes one address, rewrites only its serial, then checks pointer identity and the lock-count delta with the switch on and off.
@ -0,0 +145,4 @@}}pthread_t t;if (pthread_create(&t, NULL, other, NULL) || pthread_join(t, NULL)) return 35;L4: The worker starts after the main thread finishes lookups and only checks the returned pointers. Removing _Thread_local would still pass and would let concurrent recorders race on the slot address and pointer. Prime one address on the main thread, assert that the worker's first lookup takes the lock and its repeat hits, then verify the main thread's entry survived the worker replacing its own slot.
@ -0,0 +171,4 @@clone's folder), else clang, gcc or cc on PATH"""for c in (given, os.environ.get("CC")):if c:return shutil.which(c) or cL8 (minor): A compiler command such as CC='ccache gcc' is passed as one executable name, so the test fails before compiling. Accept a compiler argument vector for CC while preserving literal executable paths, including Windows paths with spaces.
ca876a1056ec5c656995WIP: perf(nvn): a recording thread reuses the texture copy it last got at an address (HOS_NVN_TEX_COPY_CACHE=0 to disable)to WIP: perf(nvn): a recording thread reuses the texture copy it last got at an address (HOS_NVN_TEX_COPY_CACHE=1 to try it)Thank you for the review (#issuecomment-64262). Pushed
ec5c6569, rebased on main @7c23d2be(main has since added only pipeline-state lists, #2041) (the branch's own commit unchanged by the rebase,git range-diff); test commit9a19cb1f(it fails on the branch's earlier code: queue jobs fb-2026-1 and fb-2023-5), fixec5c6569. All checks named below ran in queue jobs on this PC (fb-2026-1, fb-2023-5); nothing has run in the game.Default: there is no measurement in play, so
HOS_NVN_TEX_COPY_CACHEis now off by default (kind attempt): unset is main's lookup through the table,=1turns the kept copies on. The in-game A/B that could turn it on is in Still to test. The title says so.ec5c6569with one key, the object's bytes before its serial as they are:pin_hashhashes them andpin_samecompares them directly (no struct copy, whose padding need not be kept), the cache compares withpin_same, and a new copy is made withmemcpy, so its bytes are the object's. A kept copy is then returned exactly when the table's own comparison finds it equal. The fixture checks every copy the cache returns is the table's copy of that content; with this compiler the struct copies kept the padding, so there is no case that failed before.ec5c6569: the row says off unless set,=0off everywhere, and an empty value inlongshot_env.txton Windows removes the variable (off, as unset); with the default off, an empty value no longer turns anything on or off differently.9a19cb1f: an object looked up, initialized again with only its serial new, then looked up: the same copy, no lock with it on and the lock off; then another content takes the lock and gives that content's copy.9a19cb1f: the main thread caches an object; a second thread's first look takes the lock and its second does not (on); that thread then looks up every other object (one of them shares the slot); the main thread's next look still takes no lock. The lock count is per thread, so a shared cache fails both checks.9a19cb1f: a separate build oftex_copy_cache_onwith its variable reader replaced by one that waits until eight threads have come in and answers each differently; all eight keep one answer, five runs. The main fixture's first read is a lookup's.9a19cb1f: the main thread caches an object, another thread makes 33,000 more copies (the table grows from 65,536 slots while full of copies), and the main thread's next look gives the copy it had, without the lock on and through the grown table off.9a19cb1f: Windows threads (CreateThread) on Windows, pthreads elsewhere, and the lock is a counting spin lock of the fixture's own, so no pthread header or DLL is needed on Windows.9a19cb1f:--ccandCCgo throughtests/compiler_command.py'sparse_compiler(a path with spaces kept, a command with arguments split), thenLONGSHOT_MINGW's clang, then the clone'sllvm-mingw, then clang, gcc or cc. It ran with no--ccand noCCin fb-2023-5.ec5c6569: each recording thread counts its lookups and those its kept copy answered, and adds them to shared totals every 1,024 lookups (no shared count per lookup); the recordings' log line prints them, off and on. The fixture checks a new thread's 2,048 lookups add 2,048 and 2,047 (on) or 0 (off). The A/B is pending, for the owner: main, this PR unset and with=1on matched builds and settings in Kokiri Forest and Castle Town Market, with average fps, 1% lows, median and p99 frame times, the log line's lookup counts and host memory, and the Tier 1 runs before a default is chosen; Still to test lists them.7c23d2be, which Tested names; main has since added only contributed pipeline-state lists (#2041), so the current-main box stays unticked; the checks were run again at the new head (Tested). The whole suite and lint did not run on this PC (pre-commit and ruff are not installed here); they are in Still to test, and themise run testbox stays unticked.@Beanstalk This adds HOS_NVN_TEX_COPY_CACHE, off by default: with HOS_NVN_TEX_COPY_CACHE=1 the textures NVN recordings refer to (render targets, copies, blits) keep their looked-up copy (host/nvn_native.c); unset, main's way. It has not run in the game on these PCs yet. Please play Kokiri Forest and Hyrule Field, two minutes each, the PR against main on the same PC, on the PR's side with HOS_NVN_TEX_COPY_CACHE=1 and with it unset, with a picture in each compared with main's, on Linux with NVIDIA, Linux with AMD (RADV) and the Steam Deck. The same picture (no wrong or missing textures) and the same texture copies count either way, no crash or FATAL line; set, most lookups answered by a kept copy in the log line and frame time p99 equal to unset or better. Please report that line's counts.
@siantm only members of
BigBeanscan start the farm. One of them can approve this request by reacting 👍 to it or to this comment.View command line instructions
Checkout
From your project repository, check out a new branch and test the changes.