diff --git a/VERSION b/VERSION index 0b9c0199..e4737652 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -0.3.12 +0.3.13 diff --git a/docs/pr-review-kit/01-rules.md b/docs/pr-review-kit/01-rules.md new file mode 100644 index 00000000..30a3dba1 --- /dev/null +++ b/docs/pr-review-kit/01-rules.md @@ -0,0 +1,91 @@ +# Rules for taking a PR + +## 1. What to review first + +1. Fixes before features. A PR that fixes a bug, a glitch or a crash goes first; feature PRs wait. +2. Order fixes by reach: how many players the bug hits and how badly. Windows and default settings first, rare + hardware and unusual setups later. +3. Scale the depth of the checks to the reach. A crash many players hit and anything on the frame path get the full + checks. A rare case (a CPU without AVX, an unusual setup) gets the minimal fix, one targeted check and a short + note. A crash fix on rare hardware is still worth taking: cut the checks around it, not the fix. +4. Before testing, find out where the bug reproduces: OS, GPU vendor and generation, game version, settings. If the + symptom cannot appear on the hardware at hand (an NVIDIA paging bug on an AMD machine), say so and do not run + tests that cannot decide it. +5. Check a feature PR against the designs in `docs/milestones/`. A feature with a design (mods, cheats) goes in as + part of that design. +6. Several PRs on one topic: compare them before taking either. Another PR may already do it right. + +## 2. How to read the diff + +- The author's claim is a hypothesis. Read the whole diff: races, wrong semantics, edge cases, leaks, lock order. +- Check the behaviour against evidence: how yuzu, Ryujinx, LAS Recomp, SavageWindRecomp, nxnative and MacNativeGames + do the same thing in `refs/` (`tools/fetch_refs.sh` recreates it); the Vulkan spec; hardware docs + ([docs/maxwell.md](../../docs/maxwell.md)); upstream issues. +- Weigh two things for every change: its cost on the hot path, and how it fails (device lost, hang, stale data, weak + or non-AVX CPUs, other GPU vendors, Wine/Proton). +- Read the code a hypothesis depends on before running the game: the game's functions in Ghidra or + `generated/`, our path in `runtime/`. A run confirms what the code could not rule out. It is one run, not a + series of variants. +- Order the work so the cheapest check that could refute the PR's idea runs first. Refuted: stop, write down why, + no build, no benches. + +## 3. What a PR needs + +- **Proof.** The bug reproduced before the fix, the same repro after, both results side by side: a screenshot, a log + line, a probe, a differential test. A fix without a reproduced failure is not proof. Where a repro is impossible + on the hardware at hand, say so; the fix is then taken only on strong static evidence in the code. Where a repro is + risky (device lost or a TDR can hang the machine), write the recipe and let the owner decide. +- **Frame-path changes** get whole runs of the heavy scene with the switch off and on, at least two each + ([02-performance.md](02-performance.md)). Zero new slow frames is a hard bar. +- **A switch.** A change on the hot path or in rendering sits behind an env or `totk.ini` switch, so a player can turn + it off and we can compare. +- **Nothing changes for players outside the feature.** The DLSS PRs touched shared code; they went in once every + path that runs without DLSS was gated on DLSS being on. +- **A fix for one setup keeps the default for everyone.** The PRs that raised the low memory block from 6 to 10 GiB for + all players were rejected; the right shape is 6 GiB plus the extra where it is needed. +- **Parts we cannot run** (Linux-only code, an HDR display, RTX-only paths) are gated so they cannot touch anyone + else, or wait for a report from someone with that hardware. Note them as unrun. +- **Project tests** from [03-correctness.md](03-correctness.md): lifter differential tests, probes, `--selftest`, + `tools/check_content.py --staged`. +- **Text the player sees** goes into the catalog: `runtime/ui_text.h` ids and `runtime/ui_text.c` entries in every + language the menu has (English, Russian, Brazilian Portuguese, Simplified Chinese), and `installer/text/*.json` for + the installer. No hardcoded sentences, no second string table. +- **A new setting** is described in `totk.ini.example` and [docs/settings.md](../../docs/settings.md). +- **Licences.** MIT, BSD, ISC, zlib and Apache-2.0 code may be copied, with its header and a row in + `THIRD_PARTY_NOTICES.md`. yuzu, suyu and other GPL code is read for behaviour only; we write our own. + +## 4. Reasons to reject or rework + +- No test or repro for a change that is not trivial. +- Slow: a state copy per draw, a global atomic counter on the hot path, synchronous file I/O or a GPU allocation on a + game or render thread, new slow frames. +- Changes behaviour for everyone to serve one setup, or is on by default without a run in a scene where it acts. +- "Fixes" a crash by turning a feature off for a vendor. A crash that goes away with a feature off points at the bug; + the feature gets fixed. +- Breaks another feature (a preview that loses anti-aliasing). +- Fake features: labelled FSR4 or frame generation, and not that. +- Wrong measurements: percentiles over window means, counters over the wrong set. +- Generated C edited by hand instead of the generator (`recomp/`). +- A disallowed licence or pasted GPL code. + +## 5. Finishing a good PR + +A good PR that misses the project's scheme (hardcoded text, conflicts, layout, comment style) is brought to it while +merging, not sent back to the author for another round. When only part of a PR is good, take that part and note what +was left out and why. + +A bug found outside the PR under review is not fixed on the spot: search the open PRs on that topic, report the bug +with them, and let the owner decide. + +## 6. Merging, branches, commits + +- Each PR or wave of PRs gets its own branch `task/` from a fresh `dev` and its own build dir. It merges into + `dev`. +- Once the review is done, the symptom is gone on one paired shot and the probes pass, merge into `dev` and hand the + build to players: they test in game faster and wider than our routes. The wider checks (other routes, validation, + fps cost) follow as a separate diff. Speed never skips the review of the diff itself. +- `main` only with the owner's explicit yes. Push only when told to. +- A commit message is a plain English sentence, no `feat:`/`fix:` prefixes. +- The version lives in the repo-root `VERSION` file; the owner decides when it moves. +- After a merge, record which PRs went in, what was reworked, what was rejected and why. The reason for a rejection + goes into the PR as a plain English comment. diff --git a/docs/pr-review-kit/02-performance.md b/docs/pr-review-kit/02-performance.md new file mode 100644 index 00000000..a48c4657 --- /dev/null +++ b/docs/pr-review-kit/02-performance.md @@ -0,0 +1,97 @@ +# Performance: no lost frames on weak hardware + +## Who we tune for + +- The goal is many more fps on modest hardware, and Steam Deck later (Zen 2 4c/8t APU, shared LPDDR5, the exe runs + through Proton/Wine). +- The developer's machine (Ryzen 9 7900X + RX 9070) is fast and its numbers do not carry over. A laptop with an + i7-9750H and a GTX 1050 Ti is a sample of a weak machine, not the target to fit constants to. +- What weak hardware measured: + - GTX 1050 Ti (4 GiB, 214 MiB BAR, no ReBAR): the GPU read imported host pools over PCIe, 110-120 ms a frame + against 4.3 ms on the RX 9070. The VRAM mirror brought it to 10-11 ms; that machine is now CPU-bound at 25-45 fps, + replay 25-30 ms a frame. + - The same write-watch scan costs about 3x the CPU time there. + - NVIDIA and desktop AMD GPUs have no ASTC: textures decode in a compute shader. CPU decodes before that made + 0.4-0.7 s load frames on the 1050 Ti. +- Wine emulates `GetWriteWatch` with `mprotect` and a fault per first write. Anything relying on cheap OS memory + tricks (write-watch, `VirtualProtect` freezing, fault handlers) is checked against Wine's implementation. +- The port uses about half of even a weak CPU, so the frame's critical path is the limit, not throughput. TotK keys + per-core data by `GetCurrentProcessorNumber` without locks, so the game's threads share three virtual cores on any + host. In a fight the main thread and five job workers keep 2.6 of the 3 busy: guest code speed sets the fps. +- Perf work builds and measures 1.4.3. A 1.2.1 build is for a change about to merge with a large gain. + +## Gain ceiling first + +Before writing or taking a perf change, compute its ceiling: the share of the code it removes times the share of the +frame that code holds on the critical path, on weak hardware. A ceiling of a few percent or less is not worth it. + +- Use the critical path (`TOTK_CRIT` + `tools/crit_path.py`, heavy frames only), not one thread's profile. On the weak + laptop the submit thread is 55% replay, yet the critical path of heavy frames is 67% guest code, 15% + `nvnSyncWait`, 13% core waits and wake latency. +- Changes that can move the frame by 10% or more are usually design changes. Polishing a hot function from a flat + profile almost always gives zero. + +## A neutral safe change stays + +An optimization that measures neutral on the fast machine stays on by default when: + +- upstream (`refs/`, other ports) reports a gain for it, especially on weak CPUs or GPUs; +- the static read leaves no hazard, and the probe or differential test passes; +- whole heavy-scene runs off/on x2 show no fps loss and no new slow frames; +- a switch turns it off. + +"No gain here" is not a reason to drop a safe change with upstream evidence. A regression or a hazard nobody ruled +out is. + +## How to measure + +- **By game time, never by frame counts.** Run length, analysis windows, A/B blocks and input scripts go by the world + clock (`--seconds`, `TOTK_CRIT=w-`, `TOTK_PROFILE_FRAMES=w-`, `TOTK_SHOTS=w-:`). The + same frame count at another fps is another scene. +- **Check a scripted run reached the world.** Title menus on a slow boot eat button presses; confirm the run is in the + world before trusting its numbers. +- **Whole runs off and on, two each at least.** An in-run A/B on a moving scene lies: the A and B blocks land on the + same game seconds every run, so a content difference repeats. One in-run A/B showed "-11% replay"; whole runs gave + 5.84/5.73 against 5.76/5.73 ms, nothing. In-run A/B only on a static scene (standing still). +- **Spread.** One script on near-identical builds gave 1% lows from 31.5 to 50 fps. Compare medians of three runs, + never one run against one run. +- **A quiet machine.** `tools/run_game.py --quiet` takes the machine-wide lock; no other `totk.exe`, build or test runs + meanwhile. One game at a time. +- **A warm shader cache, prepared properly.** Shader and pipeline caches are not copied between build dirs: + `totk.exe --prepare-shaders` or `--warm-shaders` in that dir. The AMD driver cache is keyed to the exe path and + limited in size: preparing another build dir can evict this one's libraries (40-220 ms per new effect in play). +- **A heavy scene.** A fight with a large enemy and a crowd, fps limit at the maximum (`TOTK_FPS_LIMIT=360`). Compare + one shot with the scene's reference before trusting numbers. +- **No base runs by habit.** Run the candidate alone and judge it against the targets: max fps, zero slow frames + (`perf: slow frame`), no black or flat frames, no new validation errors. Glitches are found by looking at shots and + frame dumps, not by diffing metrics. Run a base build only when a specific question needs a side-by-side. + +| What | How | +|---|---| +| fps, worst frame, render-thread buckets, GPU busy, VRAM | `--env TOTK_TRACE=perf,sched`, then `python tools/perf_summary.py ` | +| the frame's critical path | `TOTK_CRIT=w-` + `TOTK_CRIT_OUT=`, then `python tools/crit_path.py ` | +| sampling profiler | `TOTK_PROFILE=` + `TOTK_PROFILE_FRAMES=w-`, then `tools/prof_report.py ` | +| A/B on a static scene | `TOTK_AB=`, then `tools/ab_summary.py --skip ` | +| VRAM pressure on a large card | `TOTK_VRAM_LIMIT_MIB=` caps the budget the port sees | + +## What the hot path must not do (Windows host) + +- **Files.** The game threads (main, job workers) and the render thread never open, read, write or flush a file, and + never wait for a thread that does. Opening a 20-byte file in a 139k-file folder: 0.1 ms idle, 11-40 ms in play while + the translator, the pipeline cache and the save wrote to the same volume. A save's `FlushFileBuffers` and + `MOVEFILE_WRITE_THROUGH`: 93-135 ms. Saving the pipeline cache under its lock on the present thread froze the replay + every 20 s. File I/O goes to a background thread; results come back in memory. +- **Waits.** Short waits spin on the counter; waits over 1 ms use the high-resolution timer. A waitable timer wakes + 0.3-0.5 ms late; the SDK's 20 us sleeps took 460-515 us. A 1 ms timer thread does not help: it gave more slow frames. +- **GPU allocations.** VMA's `vkAllocateMemory` of a 256 MiB block under its lock: 8-23 ms. A new block on the render + thread is a hitch. +- **128-bit division.** `(unsigned __int128)t * num / den` compiles to the library call `__udivti3`; counter + conversions that way took a tenth of the game threads' time in a fight. Use the precomputed scale (`platform.h` + `PlatScale`). +- **Per-draw copies and counters.** A pipeline-state copy per draw, a global atomic counter, a scan of every page each + frame: on a weak CPU each is frames. +- **Memory kept per frame.** Anything allocated per texture initialization or per frame must be freed. One copy kept + per texture init grew host memory by ~44 MiB a game minute until a commit failure after hours (#670). Check private + memory over a few idle minutes for a PR that stores per-object state. +- **Scheduling.** Any timing or scheduling change is checked for slow frames. A preempt check at every host call made + one bug rarer but added 50-75 ms CPU hitches and was reverted. diff --git a/docs/pr-review-kit/03-correctness.md b/docs/pr-review-kit/03-correctness.md new file mode 100644 index 00000000..9c7f163e --- /dev/null +++ b/docs/pr-review-kit/03-correctness.md @@ -0,0 +1,92 @@ +# Correctness: checks that keep behaviour intact + +## Lifter and generated C + +- Generated C is never edited by hand: change the generator in `recomp/`. +- `recomp/layout.py` alone decides module bases. +- Every change to the lifter or the CPU headers (`runtime/cpu.h`, `runtime/simd.h`) passes the differential tests + against Unicorn, all run with `.venv`: + +| Test | Checks | +|---|---| +| `tests\diff\lift.py` | instructions sampled from the modules; `--coverage` lists the words the lifter rejects | +| `tests\diff\simd.py` | the whole FP/SIMD encoding space | +| `tests\diff\atomic.py` | exclusive load/store and ARMv8.1 atomics | +| `tests\diff\func.py` | whole functions as the generator emits them: loops, jump tables, calls | +| `tests\flags_check.py` | the function-local flag helpers against the packed ones | +| `tests\excl_mt.py` | the exclusive monitor under contention and ABA, on several threads | +| `tests\jumptables_check.py` | `recomp/jumptables.py` against Unicorn: 0 disagreements on 1.2.1 and 1.4.3 | + +- A `--cpu v2` build (no AVX2) passes the same tests with `--cflags=-march=x86-64-v2`. Players without AVX exist. +- A compile error in generated C on a line the generator could not have written is a bit flip on disk or in memory. + Regenerate and compare hashes; leave `recomp/` alone. + +## Runtime + +- From the build dir: `totk.exe --selftest`, `--probe-kernel`, `--probe-vkexec`, `--probe-nvn-tex`, `--probe-shader` + pass. +- Settings: `totk.exe --probe-cfg` and `python tests\settings_doc_check.py`. +- Button prompts: `.venv-py314\Scripts\python tests\romfs_prompts_test.py`. Build dirs carry only `romfs-patches`; to + test PC or Xbox prompts in game, generate the overlay first: + `.venv-py314\Scripts\python tools\make_romfs_patches.py --version --prompts pc --out build\\romfs-patches-pc`, + then restart the game. +- Installer: `tests\installer_gui_test.py` (event model, form, catalogs, cancel, display scale). +- Shaders: `tools\shader_census.py --version --translate`, `tools\xlate_smoke.py`. A translator patch + (`tools/xlate/patches/`) needs `build/xlate` rebuilt and changes shader hashes: anything keyed to a shader hash + breaks with it. + +## GPU portability + +- New Vulkan code queries the feature, extension, format or limit it uses and keeps a working path or a logged + fallback without it (provoking vertex and subgroup size pinning in `vk_pipeline.c` are examples). +- Never hardcode what one GPU reports: alignments, subgroup size (RDNA4 may run wave64, old AMD Vega is wave64 only), + depth formats, `maxPushDescriptors`. +- One queue: every submit and present takes `vk_queue_lock`. Presenting from its own thread on a second queue gave + device lost on GTX 10-series in another port. +- RDNA1/2 bugs do not reproduce on RDNA4 (another driver branch); NVIDIA bugs do not reproduce on AMD. A Ryzen 7000 + iGPU is RDNA2 and runs the RDNA1/2 driver branch: a cheap testbed for those reports. +- Validation: a `--validation` run in the world shows no new messages. + +## Maxwell / NVN behaviour + +The port must do what the Switch GPU does, not what Vulkan does by default. The full list with sources: +[docs/maxwell.md](../../docs/maxwell.md), section 7. The traps a PR breaks most easily: + +- Provoking vertex: Vulkan takes the first vertex, NVN the last. +- Unwritten vertex outputs read (0, 0, 0, 1). +- A colour target outside the fragment shader's output map keeps its texel (write mask 0). AMD writes garbage there. +- Feedback loops: the G-buffer pass reads its own targets. It needs the feedback layout and a by-region barrier. +- Depth bias argument order, depth mode, depth clamp: checked against deko3d. +- Report timestamps: the engine's GPU time comes from them, and dynamic resolution and game speed follow it. + +## Timers and the real-time step + +- With `realtime` set, the game steps by a measured ratio, not whole 30 Hz units. A countdown remainder in + (0, FLT_EPSILON] is never stepped again, and a consumer testing `> 0` sees it active forever. That was "weapons + cannot be changed after a Fuse until a reload" (#18). +- Symptoms of this class: stuck until a reload or teleport, locked after an action, works sometimes. +- A PR touching the frame step, the pacer or the fps limit is checked for this class. + +## Threads and scheduling + +- ARMv8 `stlr` then `ldar` is ordered (RCsc); C11 release/acquire lets x86 reorder that store and load. Changes to + the lifter's barriers or atomics pass `tests\diff\atomic.py` and `tests\excl_mt.py`. +- A scheduler change is judged from one `TOTK_TRACE=sched` run by how long a ready, better thread waits for a core it + may use, plus the slow-frame count. Not by statistics over many runs. +- A crash that looks like a race: rule out the save first. One reported crash was the save itself; it crashed the + same way on a real Switch. + +## Files and caches + +- A crash leaves zero-filled files. Caches are validated on load, not trusted because they exist. +- The pipeline cache is dropped when vendor, device or `pipelineCacheUUID` change. +- Unicode paths: W APIs with UTF-8 to UTF-16 conversion. +- A failure that happens once and does not come back: rerun before debugging it as a code bug. Broken caches and bit + flips happen. + +## Game content boundary + +- The repository is public. No game files, and nothing extracted or generated outside `build/` and `generated/`. +- Keys never appear in logs, commands, files, issues or comments. +- Every file the generator emits carries the `GENERATED_MARKER` defined in `tools/check_content.py`. +- `python tools/check_content.py --staged` before every commit. CI runs the same check. diff --git a/docs/pr-review-kit/04-knowledge.md b/docs/pr-review-kit/04-knowledge.md new file mode 100644 index 00000000..1bdc4570 --- /dev/null +++ b/docs/pr-review-kit/04-knowledge.md @@ -0,0 +1,97 @@ +# 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. diff --git a/docs/pr-review-kit/05-checklist.md b/docs/pr-review-kit/05-checklist.md new file mode 100644 index 00000000..1c6cdfd8 --- /dev/null +++ b/docs/pr-review-kit/05-checklist.md @@ -0,0 +1,49 @@ +# Per-PR checklist + +## Before reading + +- [ ] Fix or feature? Fixes first, ordered by how many players they reach. +- [ ] Where does the bug reproduce: OS, GPU vendor and generation, game version, settings? Can the hardware at hand + show it? +- [ ] Is the symptom in [04-knowledge.md](04-knowledge.md) or `docs/maxwell.md`? +- [ ] Another open PR on the same topic? Compare them. +- [ ] Feature: is there a design in `docs/milestones/`? + +## Reading the diff + +- [ ] The whole diff read, not the description: races, edge cases, lock order, leaks. +- [ ] Behaviour checked against `refs/` (Ryujinx, yuzu, LAS, SavageWind, nxnative, MacNativeGames), the Vulkan spec, + `docs/maxwell.md`. +- [ ] Hot-path cost: no file I/O, GPU allocations, waits, per-draw copies or global atomics on game or render threads. +- [ ] No memory kept per frame or per object without a free. +- [ ] Failure modes: device lost, hang, stale data, CPUs without AVX, NVIDIA/Intel/old AMD, Wine/Proton. +- [ ] New Vulkan code queries the feature and has a fallback; nothing hardcoded for one GPU. +- [ ] Invariants kept: queue order, GPU-written memory never frozen, VRAM pressure path, pins freed. +- [ ] Players without the feature see no change. The default for everyone stays for one setup's sake. +- [ ] New behaviour behind a switch. A new setting described in `totk.ini.example` and `docs/settings.md`. +- [ ] Player-visible text in the catalogs, in every menu language (`runtime/ui_text.c`, `installer/text/*.json`). +- [ ] Copied code: allowed licence, header kept, row in `THIRD_PARTY_NOTICES.md`. No GPL code. +- [ ] Generated C not edited by hand. +- [ ] Parts we cannot run (Linux, HDR, RTX-only) gated away from everyone else and noted as unrun. + +## Proof + +- [ ] Repro before the fix and the same repro after, side by side. +- [ ] Lifter or CPU headers: differential tests against Unicorn; `jumptables_check.py` 0 disagreements. +- [ ] Runtime: `--selftest` and the four probes pass. +- [ ] Settings: `--probe-cfg` and `tests\settings_doc_check.py`. Prompts: `romfs_prompts_test.py`, overlay generated + for a game check. +- [ ] Frame path: whole heavy-scene runs off/on, two each at least, by game time, quiet machine, warm cache prepared + in that build dir. No fps loss, zero new slow frames. +- [ ] Rendering: shots or a frame dump in a scene where the change acts; no black or flat frames; no new validation + errors. +- [ ] Perf PR: gain ceiling computed for weak hardware. + +## Decision + +- [ ] Taken, partly taken or rejected, with the reason written down and posted to the PR. +- [ ] What missed the project's scheme brought to it while merging. +- [ ] Bugs found outside the PR reported, not fixed on the spot. +- [ ] Merged into `dev` from `task/`. `main` only with the owner's yes. +- [ ] `python tools/check_content.py --staged` before the commit. +- [ ] Commit message: a plain English sentence, no `feat:`/`fix:`. diff --git a/docs/pr-review-kit/README.md b/docs/pr-review-kit/README.md new file mode 100644 index 00000000..9ad0e06c --- /dev/null +++ b/docs/pr-review-kit/README.md @@ -0,0 +1,32 @@ +# PR review kit + +Rules and background for a tester or reviewer who takes community PRs into `dev`. One goal: no PR breaks the +game's behaviour or costs frames on weak hardware. + +## The short version + +1. A PR description and "works for me" prove nothing. Read the diff yourself and check it against `refs/`, the + Vulkan spec and upstream issues. +2. Almost every change needs a test: a repro before and after, a probe, a differential test, or whole runs with the + switch off and on. +3. The developer's machine is fast; players run weak machines. "Neutral here" says nothing about them, in either + direction. +4. A player without the problem sees no change: the new path sits behind a switch and the old path stays as it was. +5. Nothing goes into `main` without the project owner's explicit yes. Accepted work lives in `dev` first. + +## Files + +| File | Covers | +|---|---| +| [01-rules.md](01-rules.md) | triage order, what a PR needs, reasons to reject, merging and commits | +| [02-performance.md](02-performance.md) | target hardware, gain ceiling, how to measure, what the hot path must not do | +| [03-correctness.md](03-correctness.md) | lifter, tests and probes, GPU portability, Maxwell behaviour, timers, threads, game content | +| [04-knowledge.md](04-knowledge.md) | invariants of recent changes, fixed bug classes, open risks, past PR decisions, our mistakes | +| [05-checklist.md](05-checklist.md) | the per-PR checklist | + +The public docs this kit builds on: [docs/architecture.md](../../docs/architecture.md), +[docs/building.md](../../docs/building.md) ("Checks"), [docs/maxwell.md](../../docs/maxwell.md), +[docs/settings.md](../../docs/settings.md), [docs/tester-guide.md](../../docs/tester-guide.md), `AGENTS.md`. +Working with a coding agent: give it this folder and `AGENTS.md` before the first review. + +State as of 2026-11-06. The code and `docs/` win over this text where they differ.