Files
totk-pc-recomp/docs/pr-review-kit/04-knowledge.md
T

98 lines
7.6 KiB
Markdown

# Knowledge base
Before investigating a symptom, or trusting a PR that "fixes" it, look for it here. Search by what the player sees
(black, magenta, flicker, slow motion, missing, stale, streaks) and by the object (sky, grass, shadow, fog, HUD).
## Invariants of recent changes
A PR that touches these areas must keep them.
- **Queue order.** When anything is submitted, every earlier part is already on the queue. Present, uploads, readbacks
from guest threads and the `vkDeviceWaitIdle` sites rely on it. The recorder thread now begins, ends and submits
the parts it records; the submitting thread still waits for that submission, so the order holds.
`TOTK_REC_END=0` restores the old split.
- **GPU-written memory is never frozen.** Storage-buffer stores, copies and fills land in imported guest memory
without a fault or a write-watch bit, so a region only the GPU writes looks idle. Such regions are never frozen
read-only, and a frozen region is thawed before a GPU write. LAS Recomp never changes the protection of imported
memory because of NVIDIA. A suspected cause of NVIDIA "write invalid" device faults (#788, #802), not proven.
- **VRAM pressure.** Under pressure, released textures whose storage the game has given to another texture go first:
30 s after release and once no finalized slot has bound them for 600 submits. Clean mirrored entries wait 5 s.
Both stop once use is back under the line. A PR touching texture lifetime is tested with `TOTK_VRAM_LIMIT_MIB`.
- **Texture pins are freed.** Each pin counts the recording copies naming it and is freed 1200 submits after its last
use unless the replay holds it as a render target. Before that, pins leaked ~44 MiB a game minute (#670).
## Fixed bug classes
If a PR touches this code, confirm the fix still holds.
| Symptom | Cause | Where the fix is |
|---|---|---|
| lime silhouettes in grass; rectangles in the sky | a target outside the output map must keep its texel; zero-filling it wiped the half-res depth | `vk_pipeline.c` `target_wmask` |
| stale grass maps in the far terrain for a second after a hit | write-back of a texture the CPU had rewritten | `vk_texture.c` `write_back` |
| cut grass stays standing; fire does not spread (#132) | CPU reads of GPU-rendered textures without an invalidate | `vk_texture.c` `vk_texture_write_back_small`, `nvn_ext.c` `nvn_pool_invalidate` |
| cloud and fog volumes empty for the session | a one-shot draw skipped instead of waiting for its pipeline | `vk_exec_draw.c` `prepare_draw` |
| tile rectangles | storage buffers bound by Ryujinx first-use order, not the c0 slot | `vk_exec_draw.c` `ssbo_slot` |
| black dialog background and loading map | 3D targets rejected, the grading LUT never written | `vk_exec.c` `resolve_target` |
| streaks on cliffs | primitive restart ignored | `vk_exec_draw.c` `restart_for` |
| streaky map screen | the newest texture picked at shared storage | `vk_texture.c` `vk_texture_by_id` |
| dark 16x16 blocks on the ground, sage spirit not drawn | G-buffer feedback loop | `vk_exec_draw.c`, `TOTK_FEEDBACK` |
| magenta cave walls, brown sky | CPU-filled textures without a flush | write-watched mirrors, `vk_memory.c`, `vk_texture.c` |
| black 3D scene | deferred texture binds | `nvn_api_cmd.c` `Bind*Deferred` |
| HUD prompt boxes, black stamina wheel | `nvnTextureCompare` ignored the channel mapping | `nvn_api_obj.c` |
| crash on world load | `GetCommandMemoryUsed` did not follow the driver's sizes; the game sizes model heaps from it | `nvn_api_cmd.c` |
| 20 fps | a yield back-off starting before 2 ms | `kernel.c` SVC 0x0B: no back-off |
| weapons locked after a Fuse (#18) | timer remainder in (0, FLT_EPSILON] with the real-time step | patch under the `realtime` setting |
| magenta/blue garbage or device lost on RDNA1/2 (#5) | writes into 3D BC block views | in `dev` |
| black window after a driver update | a pipeline cache from another driver | `vk_pipeline.c` drops the cache by UUID |
## Known open risks
A PR touching these needs stronger proof.
- Buffer textures are not replayed and bind a stand-in: light and decal lists may read 0.
- New GPU-only colour images start undefined; feedback effects may show garbage.
- Clears with a partial channel or stencil mask are skipped (`W_CLEAR_MASK`, `W_STENCIL_MASK`).
- 8-bit indices are widened on the CPU at record time; a copy in the same submission gives stale indices.
- `UpdateUniformBuffer` is a copy between full barriers and ends the render pass (fps outdoors).
- Report timestamps carry host time at fence completion: the engine's GPU time is wrong.
- The game's SVC-free spin loops burn a host core (843 in `main`).
- Images aliased onto one GPU-only pool allocation do not see each other's data on AMD.
## Past PR decisions
| PR | Decision | Why |
|---|---|---|
| #690 shrine snapshots | rejected | a pass restart per copy, a `VkPipeState` copy per draw, broken `bind_sig` skip; fps loss |
| #674 | rejected | a global STXR counter on the hot path |
| #660 | rejected | the preview loses anti-aliasing |
| #713, #576 | rejected | low memory block 10 GiB for everyone; should be 6 GiB plus the extra where needed |
| #573 | rejected | dynamic resolution off by default for everyone, the 1.4.3 site never run |
| #568, #569 | rejected | fake FSR4 and frame generation |
| #487 | rejected | wrong metrics: percentiles over window means, counters over the wrong set |
| #451, #380 | rejected | not painless to take |
| #566, #594, #534 DLSS | taken with changes | #594's shared paths gated on DLSS being on; nothing changes without DLSS |
| #489 | partly taken | the runtime part checked by a frame dump; the installer's DLL download was the owner's call, its pinned hash re-checked |
| #519, #582 amiibo | rewritten by us | took the data-format fixes; left out the features and the Linux event rework |
| #483 vs #585 | #585's mapping kept | #483's stick glyph mapping was rewritten unasked while #585 already had it right |
| #528 rain | taken after a check | code review fine, merged only after a run on a rain save |
| #767 | taken with our fix | the default was skipped with `prompts = xbox\|pc` when those folders did not exist |
| #625 frame queue | taken, off by default | a new frame queue, one field run with it on |
| #743 UB overlay | waiting | +25% in a Depths fight on an RTX 4080; needs review, fight runs x2 and shots on AMD |
## Our mistakes, not to repeat
- **"-11%" was an A/B artifact** of a moving scene. Whole runs off/on showed zero.
- **Micro-optimizations from a flat profile** (1-3% of samples each) gave 26.2 against 26.4 ms on the weak laptop:
nothing. Nobody had computed a ceiling.
- **A scheduler patch merged on run statistics** added 50-75 ms hitches. Slow frames are a hard bar.
- **Ten game runs on lock theories** where one Ghidra read of the game's code narrowed it at once.
- **45 minutes of builds and benches** on an idea its own first thread census had refuted: the game pins 53 of 56
threads itself. The cheapest refuting check goes first; when it refutes, stop and write the idea down.
- **Tests of a bug that could not appear on the hardware at hand** (NVIDIA paging on an AMD machine): 245k tokens and
37 minutes for nothing. Ask first where the bug reproduces.
- **Turning the recorder off for a vendor** instead of finding its bug. Stopped: the feature gets fixed, not silenced.
- **Bisecting code when every build crashed the same way at once.** The cause was a bad page of a game file in the OS
file cache. When all builds fail identically, suspect inputs and caches first.
- **A duplicate issue closed with a bare "Same as #N"** lost the logs and links. Move everything useful to the issue
that stays open first: hardware, driver, version, when it happens, workarounds, links from comments.