Files
Triforce-Source/docs/lazy-writeback.md
ruckus7382sfgsgdf 6f338c8f56 Triforce v0.5.0
In-game mods (GameBanana browser, search and installs, with the Mask Salesman), code-patch and cheat mods, the devs' test18 to test45 work (full performance overlay, frame pacing on, steady frame rate, save export and import, bug capture, new options rows, Setup's Mods page and Add to Steam), occlusion queries and new defaults, Auto resolution that scales, replay helper threads and robust buffers off by default, the options in sections.
2026-11-17 22:40:50 -06:00

186 lines
17 KiB
Markdown

# Lazy write-back: built, on by default
**Since options_version 5 (2026-11-16): on by default, at the owner's word, with the row and `RX_VK_LAZY_WB` to
turn it off; still never on AMD's driver by the row alone. The status below is from before.**
**Status (2026-11-15): built behind the hidden Debug tab's Lazy write-back row, off unless set, and `RX_VK_LAZY_WB`
(`=1` on, `=0` off, `=2` the self-check) over it. Nobody has run it in the game.** The design below is what was built;
"As built" at the end says how, and what only the game can show. The note was first written when it was studied for the
port of NX2navi's features and left out, because in this code base it cannot be proven correct without running the
game; the owner then asked for it to be built all the same, off by default, so that it can be turned on and compared.
The reasons in "Why it is not built" still stand as the things to watch for.
## What it is
What a shader writes into a mirrored pool lives in the pool's VRAM mirror. At the end of every submission the renderer
copies it back into guest memory, in case the CPU reads it (`gpu/vk/vk_memory.cpp`, the end of
`memory_end_submission`). The game's CPU reads very little of it. NX2navi stopped copying a range once it had gone
back one time, and copies it only when something touches it: "about a third more frames" in open areas, with 66 MiB a
frame no longer crossing PCIe (7 to 9 ms of a frame's 13 to 15 ms of GPU time there).
How NX2navi knows about a touch: it takes the access away from the range's pages (no read, no write). The first access
faults, the fault handler has the renderer copy the range down, gives the pages back and runs the access again
(NX2navi's `runtime/memory.c` "Lazy write-back", `runtime/vk_memory.c` `lazy_fetch`). Around that sit a thaw before every
kernel call that is handed guest memory, a list of ranges in flight, a window between the replay's last check and its
hand-over, a hold after a touch, and a choice by driver (`wb_lazy_choice.h`: off on AMD's driver after two reports of
the game ending in play, off outside Windows). It took several releases of play tests to get there, and one of its
refinements still loses the device on some loads.
## What is different here
- **CPU writes are known late, CPU reads never.** Lifted stores mark their page in a table (`A64_MARK`, the soft
write watch) and the renderer collects the marks at the next submission (`memory_collect_written`). A load is a
plain pointer access (`A64_PTR`) with no hook. So "copy it when the CPU touches it" has only two possible sources
here: page protection, as in NX2navi, or the calls the game makes before it reads.
- **Most of the gain is already taken another way.** Since 2026-11-09 a write-back is a compute pass that compares
the mirror with a VRAM shadow of guest memory and writes only the words that differ (`wb_diff`, on by default).
Measured where NX2navi measured (Hyrule Field, about 69 MB a frame of written ranges): the whole copies took 4.4 ms
of the GPU's 13, the pass takes about 0.7 ms. What a lazy write-back could still save here is that pass, the pages
it reads into the shadows, and the waits of captures for write-backs still on the GPU (`wb_pages`, the "late"
pages of `take_capture`). Nobody has measured how much that is.
- **The order in which the GPU's words reach guest memory is tuned by play.** The exposure meter is a sum the GPU
adds to and the CPU reads and clears; the readback waits in `vk_replay.cpp` `invalidate`, the late pages, the
deferred syncs and the report words cut out of write-backs (`memory_cpu_owned`) each fixed a flicker that only
showed in the game (white flashes, blinking cells, a dark frame every 15 to 30). A lazy write-back moves every one
of those moments.
## Who reads what is written back
Everything below would see old bytes while a copy is owed, unless it is made to pay first.
| Reader | Where | Can it be caught? |
|---|---|---|
| The game's own code | lifted loads, any thread | Only by a fault. `nvnBufferInvalidateMappedRange` and `nvnMemoryPoolInvalidateMappedRange` reach the renderer (`host/nvn_native.c`, `rx_nvn_invalidate`), and it already waits there for the range's write-back. Whether the game calls one before every read of GPU results is not known; `HOS_NVN_LOG_FLUSH` logs the calls |
| NVN event words | `nvnEventGetValue`, `hos_nvn_event_value` (the present poll, `host/hos_thread.c`) read guest memory with no call into the renderer | A hook in the host |
| Host code given game buffers | `memcpy` and the like through `GP()`: audio voices on the mixer thread, the movie's packets, the codec, `nn_libc.c` | By a fault, on that thread |
| The kernel | `ReadFile` and `WriteFile` straight on guest pointers (`host/nn_fs.c` `read_at` and the write beside it: every file read, every save); the same as `pread`/`pwrite` on Linux | **No.** A call into a page without access fails with an error and no fault (`host/mkw_glue.c` says so of reserved pages). Each needs a thaw before it, as NX2navi has |
| The renderer's CPU reads | captures (`capture_make` on the game's thread and its helpers, `guarded_copy`, which drops a page that faults on Windows and is a plain `memcpy` on Linux), `memory_read_as_submitted`, texture uploads (`vk_texture.cpp` `guest_bytes`), shader code, the bank's descriptors | By a fault, but on threads that hold `pools_mu` or `replay_mu`, which a copy must not need |
| The GPU through the import | every `vkCmdCopyBuffer` from `Pool::buffer` (`mirror_make`, `mirror_pieces_make`, `mirror_sync`'s live pages, `memory_rb_refresh`, `late_deferred_bound`, the shadows' fill) and every binding `gpu_buffer_bind` or `gpu_buffer` gives the import for | Never by a fault: each site has to pay first or bind the mirror |
| Code that takes guest memory for complete | a mirror given back or remade (`mirror_free`, `mirrors_give_back`, `demote_trials`, `pieces_set_direct`, `retire_pool` with its inheritance), `texture_flush_to_guest` | Each has to pay first |
And three things undo a page's protection behind the renderer's back on Windows: `import_pool` commits its whole
range again (`VirtualAlloc(MEM_COMMIT, PAGE_READWRITE)`, which its own comment says resets protection), `hos_commit`
does the same for the game's mappings, and `hos_mem.c` discards and decommits pages.
## A design for Triforce
The states of a guest page of a mirrored pool, as a write-back sees them:
| State | Guest memory holds | How it is left |
|---|---|---|
| current | everything the GPU wrote | a written binding of a later submission: **written** |
| written | all but this submission's writes | the submission's end: copied (the diff pass), then current; or, when the page went back once before and nothing forbids it, no copy: **owed** |
| owed | an older version; the mirror alone has the GPU's | a reader: **paying**; a later written binding: stays owed, the newer write joins the same debt (one copy pays for all of them, mirror to guest, so they land in order by construction) |
| paying | being copied by one thread | the copy done and waited for: current. Every other reader of the page waits for that copy, none starts a second |
Rules that keep it correct:
1. A page is owed only whole, only in a pool with a mirror in memory there (not a piece left in guest memory), only
when the mirror holds every CPU write to it (`page_gen(page) <= synced_gen`: a copy from the mirror would
otherwise put older bytes over the CPU's), and never where the replay writes words itself (the report words).
2. Every reader in the table above pays before it reads. For CPU reads that means the page has no access while it is
owed and the fault handler pays; for the kernel a thaw before the call; for the GPU's reads and for code that gives
a mirror up, a call that pays the range first.
3. A CPU write to an owed page pays first, like a read (the write faults). It does not drop the debt: the write
covers part of the page and the rest is the GPU's. Only a write of the whole page, which nothing here can
recognise, could drop it. The page then goes the usual way (marked, collected, synced into the mirror), and is not
owed again for a while (NX2navi holds it 1 s, doubling to 32 s while it keeps being touched).
4. A payment copies after everything submitted so far, in a command buffer of its own that the paying thread waits
for; the part being recorded checks at its end whether a range it left owed was paid meanwhile and copies it then.
5. The shadows of the write-back diff stay true without change: an owed page was not written by the pass, so the
shadow still equals guest memory, and a payment is the same pass run later.
6. A capture's wait (`wb_pages`) has nothing to wait for on an owed page: no submission writes it back. The wait
moves into the payment.
The page-state logic belongs in a header of its own with tests for the rules above (each reader pays first; a CPU
write pays and does not drop; debts merge; one payer at a time), as the write generations have theirs
(`gpu/vk/write_gen_table.h`).
## Why it is not built
None of these can be settled by a test without the game:
- **The set of kernel accesses.** One missed `ReadFile` into an owed page is a short read handed to the game, with no
fault and no log. The list above is what a search of `host/` found, not a proof; libraries and drivers that are
handed guest pointers (the movie decoder, audio) were read, not run.
- **The driver.** The pages are imported into Vulkan as host memory (`VK_EXT_external_memory_host`; a `udmabuf` on
Linux). Taking their access away while the import lives is what NX2navi's AMD reports point at. Importing a pool
whose pages have no access is likely to fail outright.
- **Locks.** The fault can come on any thread, including the replay thread and the capture helpers while they hold
the renderer's locks, and on Linux inside a signal handler. NX2navi's rules for this (ranges in flight, the
window, fetches outside its freeze lock) were found by profiles and stalls in play.
- **The game's timing.** See "tuned by play" above. Paying at the first touch instead of at the submission's end
changes when the exposure meter, the event words and the culling's results appear to the CPU.
- **Whether it is worth it.** With the diff pass in place the saving is unmeasured and may be small.
What was considered and rejected as a shortcut: paying only at `nvn*InvalidateMappedRange` and the host's own reads,
with no page protection. It needs no fault handler and no thaw, but it is right only if the game announces every read,
which nobody knows; a read that is not announced gets old data silently. `RX_VK_WB_MAX_KB` is the same bet made by
size, and is off by default for that reason.
## What to do first, in the game
1. Measure what is left to gain: `RX_VK_PASS_TIMING` gives the GPU time of "wb diff" and "wb copies" a frame, and the
log's "write-back diff (600 submits)" and "a capture taken" lines give the bytes compared and the takes that waited
for late pages. `RX_VK_NO_WRITEBACK=1` is the upper bound on frame rate (its picture is wrong wherever the CPU reads
results: do not judge the picture with it).
2. If that is worth the work: log which written-back ranges the game announces before reading
(`HOS_NVN_LOG_FLUSH`, `RX_VK_LOG_INVALIDATE`, `RX_VK_LOG_WRITEBACK`), and build the page probe NX2navi used before
its lazy write-back (protect a written-back range, log the first access with its thread and address, give the page
back): that turns "the CPU does not read most of it" from NX2navi's game build into a fact about this one, and
finds the kernel accesses on the way.
3. Then the host side (the fault hook, a thaw before `read_at` and the save writes, the commits that reset
protection), the renderer side (rules 1 to 6), a Debug tab row that is off by default, and the same choice by
driver NX2navi ended with.
## As built (2026-11-15)
Steps 1 and 2 above were not done first: the owner asked for it built behind a row, so that the first run with it on
is the measurement. What is where:
- **The page states**, `gpu/vk/wb_lazy_state.h`, with the rules and a threaded stress test in
`tests/test_wb_lazy_state.py`. A page is not owed at once: it is first WATCHED (read-only, still copied at every
submission) until a collection of the write watch and a capture, both numbered after the watch began, have come
and named no CPU write to it. That is rule 1 for the writes the renderer learns of late; the renderer adds the rest
of it: the CPU's newest write generation for the page no newer than its pool's `synced_gen` (`lazy_page_takes`).
That asks `cpu_gens`, the CPU's writes alone, and not the one table of generations: the first build asked that one,
where every storage buffer a draw or a dispatch writes is stamped while it is recorded (`memory_stamp_gpu`) and
`synced_gen` is raised only at the submission's end, so every page being written back looked newer than its sync
and the owner's first session with the row on watched and owed nothing (`tests/test_lazy_wb_cpu_gens.py`). A CPU write to a watched page faults and ends the watch with no copy; to an owed
page it pays first. A payment between a recording's end and its submit leaves the rest PENDING until that submit
(`memory_lazy_submitted`, called from `submit_recording` under the queue's lock). A touch holds its 64 KB block
for a second, doubling to 32 s, as NX2navi does. Whether it runs: `wb_lazy::choose`.
- **The renderer**, `gpu/vk/vk_memory.cpp` "lazy write-back": `lazy_runs` at each write-back (after the CPU's words
are cut and the runs clipped to a mirror's resident pieces; never a page with event words), the payment (`lazy_pay`:
its own command buffer after everything submitted, the held submits flushed first, waited for; the shadows told of
the pages, rule 5), `lazy_settle` before every copy out of an import and every binding given the import (rule 2 for
the GPU), and before a mirror, a piece, a retired pool or an import is given up; `import_pool` holds the pages
while it commits and imports. The fault handler is the process's first vectored handler, added when the renderer
starts, ahead of host/mkw_glue.c's. Locks: see the section's comment (a payment needs neither `pools_mu` nor
`replay_mu`, and logs nothing). `tests/test_lazy_wb_hooks.py` holds these hooks in place.
- **Several payments at once** (2026-11-16, NX2navi's `wb_lazy_unlocked`): each payment holds one of four slots, a
command buffer and a fence of its own (`gpu/vk/wb_lazy_payers.h`); it was one payer at a time, so a thread that
touched another owed page, or the replay giving a mirror up, waited for the first one's copy before its own went onto
the queue. Two payments never have the same pages (the table's PAYING has one payer), and each copy still goes onto
the one queue after everything before it. `RX_VK_LAZY_PAYERS=1`: one at a time again. The threaded stress test runs
with four slots and with one. What it does not change: a payment for a mirror given up still runs on the replay
thread under `pools_mu` (NX2navi moved its own out of its pool lock as well); moving it would mean reworking every
give-up path, for payments of which the owner's sessions have a few a minute.
- **The host**: `hos_guest_io_begin` / `hos_guest_io_end` (`host/rx_backend.c`) around every kernel call on guest
memory and every change of guest pages' state: `read_at` and the file writes (the saves too) in `host/nn_fs.c`, the
image's read, `hos_commit`, the discards and decommits of `host/hos_mem.c` and `host/hos_svc.c`, the host zstd
decoder's one-shot, and the debug dumps. `tests/test_lazy_wb_host.py` reads `host/*.c` for kernel calls that do
neither, and every exception is in its list with a reason. Audio, the movie and the codec reach guest memory with
the CPU only (`memcpy` and the like): their touches fault and pay.
- **Linux**: off (`wb_lazy::choose`), the row not shown. **AMD's driver**: the row alone leaves it off;
`RX_VK_LAZY_WB=1` turns it on there.
- **The self-check**, `RX_VK_LAZY_WB=2`: guest memory is the eager copy (every copy still made); a payment reads the
mirror's pages, what it would have copied, and compares them with guest memory. A difference is logged with its
address at the next 600-submit line (`MISMATCH at guest`), not from inside the fault.
What only the game can show: whether the driver keeps an import whose pages have no access (NX2navi's AMD reports),
whether the list of kernel calls is whole in practice (a missed one is a short read with no fault), how often the game
touches what is owed (a touch costs a GPU round trip on the touching thread), and the timing of the exposure meter and
the event words. The 600-submit line `vk: lazy write-back (600 submits)` says what it saved and who paid; with
`RX_VK_LAZY_WB=2` the `check` line says whether it would have been right.