diff --git a/.gitignore b/.gitignore index 66d8ebec..b5647747 100644 --- a/.gitignore +++ b/.gitignore @@ -17,6 +17,9 @@ __pycache__/ /generated/ # Button art a release carries (tools/make_launcher.py --prompt-art); a checkout may hold it for a test build /prompt-art/ +# The shared pipeline list a release carries (tools/pipeline_list.py merge; tools/prepare_shaders.py reads it here) +/tools/data/pipeline_list.bin +/data/pipeline_list.bin *.xci *.xcz *.nsp @@ -39,6 +42,8 @@ __pycache__/ # tools/make_*.py assemblers when the game is built; tools/check_content.py refuses them in a commit) /runtime/*_spv.h *.spv +# The menu font's bytes as a header for compilers without #embed (tools/build_shaders.py EMBEDDED) +/runtime/ui/roboto_ttf.h # Build outputs *.exe @@ -81,3 +86,6 @@ desktop.ini # Agent task worktrees (tools/worktree.py) /.worktrees/ + +# The release folder (tools/make_release.py): nx2navi_xlate.exe with its id file, hactool, ninja and the DLLs +/bin/ diff --git a/AUDIT.md b/AUDIT.md new file mode 100644 index 00000000..a74b8332 --- /dev/null +++ b/AUDIT.md @@ -0,0 +1,2242 @@ +# NX2navi audit + +This file holds the audit's state across sessions: the project context, the subsystem map, the threads and what they +share, the path of one frame, the allocators, pools and caches, the leads for Phase 3, the findings ledger and what +has been reviewed. + +- Phase 1 (map, no code changes): written 2026-11-10 on branch `audit`, cut from `test-all-fixes` at `ed36773d`. +- Phase 2 (baseline and instrumentation): done 2026-11-10 on branch `claude/audit-phase2-a12eef`. It has three + instrumentation commits (`c1ed77e4`, `d49a4dea`, `3a88b363`) and fixes nothing. See section 11. +- Phase 3 (the eight passes): started 2026-11-10 and stopped at the user's request before its end. Section 12 says what is done and what is left. +- Phase 4 (fixes): started 2026-11-10 at the user's word; 17 fix commits, section 13 says which are verified. +- Phase 5: not started. + +Citations name our code by file and function; a `~line` after them is a hint taken at `ed36773d` and will drift. + +Rules this file follows: + +- A **finding** is labelled "confirmed" (reproduced, or shown by tool output) or "suspected" (from reading code only). +- A **lead** is something seen while mapping that Phase 3 should look at. Every lead is suspected, and none is a + finding yet. +- Where the docs and the code disagree, the map follows the code. Section 6 lists every disagreement. + +--- + +## 1. Project context + +**What it is.** A static recompilation of *Ocarina of Time*, the Switch 2 release (ARM64, game version 1.1.1), into a +native Windows x86-64 executable with a Vulkan renderer. The launcher builds the game on the player's PC from the +player's own dump. Design: `docs/architecture.md`. Build and checks: `docs/building.md`. Launcher: `docs/launcher.md`. +Maxwell behaviour the Vulkan path must match: `docs/maxwell.md`. + +The runtime also carries code for other builds of the game, gated on `rt_game_version` (`host.h`): 110, 121 and 143. +`tools/make_game.py` writes `rt_game_version = 111`. The audit targets 1.1.1. Some files (`mouse_direct.c`, +`menu_cursor.c`, parts of `ov_zstd.c`) describe themselves as 1.4.3 features; which of their paths run on 1.1.1 is +not determined yet. + +### Repository layout + +| Folder | What it holds | +|---|---| +| `recomp/` | The recompiler: an ARM64-to-C lifter and generator in Python. `gen.py` is the generator, `lifter.py` the decoder, `simd_c.py` the NEON/FP lowering, `flags.py` and `regs.py` the locals for flags and registers, `jumptables.py` the jump tables. `layout.py` alone decides module bases. `patches.py` and `patches-v111.txt` hold the game-code patch sets. | +| `runtime/` | The host runtime in C and C++: 125 `.c` files, 15 `.cpp`, 70 headers. | +| `launcher/`, `installer/`, `tools/` | The build kit. `tools/make_game.py` is the build a player runs. | +| `tests/` | The checks. | +| `docs/` | The design. | + +The recompiled output is not in the repository: it is generated under ignored folders. + +### Stack + +- Our own static recompiler. It is written in Python and outputs C with GNU extensions. +- The runtime is C11 (plus C++ for the menu, DLSS frame generation and AMD FidelityFX), built with MSYS2 UCRT64 Clang. +- A Vulkan 1.3 renderer with `VK_EXT_mesh_shader`, `VK_EXT_external_memory_host` and the graphics pipeline library + where the driver has it. Device memory goes through Vulkan Memory Allocator. +- Shaders are translated to SPIR-V by a separate translator process (`nx2navi_xlate.exe`) into an on-disk cache, + prepared at install time. +- SDL3 for gamepads and audio output, Win32 for the window, keyboard and mouse. libopus for voice, libvpx and dav1d for + movies, libzstd, and Dear ImGui for the menu. + +### Targets + +- PC only. There is no fixed resolution or frame rate. +- The frame limit (`NX2NAVI_FPS_LIMIT`, `cfg.c` default 60, live; 30 to 240, `display` or `unlimited`) counts frames + the game draws. Frame generation multiplies on top of it. +- Reference PC: RTX 5090. The user plays at a 120 limit with DLSS frame generation x2 and HDR. +- Minimum: 16 GB RAM and a Vulkan 1.3 GPU with mesh shaders. + +### Memory budget + +- **Guest application pool.** The pool is `rt_app_pool_bytes`, which `tools/make_game.py` generates as 9809 MiB. + - `memory.c` `mem_init` (~860) actually sets the limit to `NX2NAVI_APP_POOL` when that is set. Otherwise it uses + `rt_app_pool_bytes + res_heap_extra_bytes()`, and the extra comes from the resolution settings (`resolution.c`). + So the pool can be larger than 9809 MiB. + - The limit is enforced in `mem_set_heap_size` (~899) and `alias_map` (~1080). The heap is also capped at + `HEAP_CAP` (12 GiB). +- **VRAM.** VRAM follows the driver's heap budget (`VK_EXT_memory_budget`, `vk_memory.c` `vram_query`). + `NX2NAVI_VRAM_BUDGET_MB` caps it (`vk_memory.c` `budget_cap`, a test switch). +- **CPU and GPU memory are separate.** The game's guest memory pools are imported into Vulkan as host memory. On a + discrete GPU they are mirrored into device-local buffers (`vk_memory.c`). + +### Game logic rate + +- The game ships with whole-vsync 30 fps steps. +- Patch set `ostep` makes it step by the clock, up to 240 game frames a second. The step is written each present by + `frame_rate.c` `frame_step_present`, then `ocarina_step`, then `ocarina_step_write`. +- Several known bugs come from game code that assumes the original rate. + +### Commands for the later phases + +Phase 1 ran nothing. + +- **Dev builds** run from `C:\Users\PC\Documents\deepseek-harness\default-workspace`: + - `C:\msys64\ucrt64\bin` first on PATH, with system Python 3.12; + - a copy of `work\build_rt_allfix.py` pointed at this worktree. +- **Scripted game runs** use a runner script with an input script and a save folder; a Kakariko Village save exists. + Useful settings: `NX2NAVI_TRACE=perf` and `NX2NAVI_PROFILE`. +- **Launcher tests:** `python -m unittest tests.launcher_test`. +- **Runtime self-checks:** `nx2navi.exe --selftest`, `--probe-kernel`, `--probe-vkexec`, `--probe-vkmem`, + `--probe-cfg`, `--probe-prewarm`. +- **Unit checks that build one file with the rest stubbed:** the `tests\*_check.py` files listed in + `docs/building.md`, "Checks". Examples: `logq_check.py`, `sync_wake_check.py`, `save_share_check.py`, + `save_zip_check.py`, `frame_step_check.py`, `wb_lazy_check.py`, `target_frames_check.py`. + +### Known problems at the start of the audit + +These are what the user or players see. None is a finding until it is reproduced or traced. + +**Stutter and speed** +- Stutter and frame-time spikes at uncapped frame rates in the user's own play. Not reproduced in scripted runs. +- Big towns run slower than the field in play. Kakariko Village measures 135-138 fps in scripted runs on the reference + PC; the user reports heavy slowdowns in play. + +**Rendering** +- White, untextured ground after long play under VRAM pressure. A fix is in; it is unconfirmed. +- A one-frame dark shadow at the Castle Town gate. Switch `depth_alias` addresses it and is off by default. +- Foliage flicker on Linux with an AMD card. Open. + +**Crashes and device loss** +- A device loss on an RX 6600, and a crash while fighting on AMD cards. Lazy write-back is now off by default on AMD's + Windows driver (`wb_lazy_choice.h`, `vk_memory.c` `vk_mem_lazy_decide`). Untested: there is no AMD card here. +- Crashes with third-party overlay layers injected into the process. + +**Logic tied to the frame rate** +- The rupee pick-up popup stays above Link above 60 fps. Patch set `opickup` addresses it; it is proven statically, + not seen in game. An item jingle glitches the same way. +- The ocarina song recorder rounds wrongly at high frame rates: four sites, unfixed. + +**Other** +- The shader cache pack grows with every translator change. +- The replay on its own thread (`NX2NAVI_REPLAY_ASYNC=1`) has a known fault and stays off. +- `tests.installer_test` cannot be imported on this PC. + +### Parts of the audit prompt that do not apply + +The prompt was written for a port to the Switch 2. This project goes the other way: a Switch 2 game recompiled for +the PC. + +- **"On device", "Switch 2 build", "docked", "handheld".** Do not apply. There is no device build and no docked or + handheld mode. The only targets are Windows (and an in-progress Linux build, `docs/building.md`), at whatever + resolution and frame limit the player picks. No substitute target is invented here. +- **"Display list buffers".** The game does not build N64-style display lists. It records NVN command buffers, which + the runtime replays into Vulkan. The prompt's display list is read as the NVN command buffer throughout. +- **"Recompiler config".** The configuration is `recomp/patches-v111.txt` plus the generator's options. Our host code + is `runtime/`. +- **"Emulated RAM".** Guest memory: the game's address space at fixed host addresses below 2^39 (`memory.c`). +- **"Target frame rate".** The player's frame limit, not a fixed 30 or 60. +- **"Stays inside its memory budget".** Two budgets: the guest pool above (CPU side) and the driver's VRAM budget. + Process commit charge matters too: `vk_texture.c` evicts on commit pressure, `commit_evict`. +- **"Test route ... a boss ... save, quit, reload".** Applies as written, on PC. The Phase 2 baseline also needs the + route at the user's own settings (a 120 limit, DLSS frame generation x2, HDR), because the stutter reports come from + those. +- **"Original-game crashes handled more gracefully".** Applies. On the PC, a guest fault goes to the crash handler: + `platform/win32.c` `crash_veh`, then `main.c` `crash_handler`. + +### Sanitizer builds (Phase 2): what the code says + +This was written before Phase 2 tried anything. The results are in section 11.4: +- UBSan (trap mode) built and ran the route, with one report (F-1-02). +- ASan built but cannot start: its shadow covers the guest's fixed windows, as feared below. +- TSan does not exist here. + +**AddressSanitizer and UndefinedBehaviorSanitizer on Windows** + +- *Fixed reservations.* The runtime reserves guest memory at fixed addresses below 2^39 before anything else + (`memory.c` `mem_init`): + - the module window; + - the 256 MiB kernel region; + - a 14 GiB low region (stacks and heap); + - a 64 GiB alias region. + + It re-executes itself when a range is taken (`NX2NAVI_REEXEC`, `REEXEC_LIMIT` 20). An ASan shadow mapping placed in + that range would make every start re-execute and then fail. Whether the Windows ASan runtime's shadow placement + collides is not determined. +- *Faults are part of normal operation.* The runtime registers a vectored exception handler first + (`platform/win32.c` `plat_mem_fault_hook`, `AddVectoredExceptionHandler(1)`) and takes access violations on purpose: + - write-watch freeze and thaw (`memory.c` `thaw_fault`); + - lazy write-back pages (`memory.c` `lazy_fault`, which runs a GPU copy inside the handler); + - probe pages. + + ASan on Win64 commits its shadow memory on demand from an exception handler of its own. The order of the two + handlers, and whether ours tolerates the faults ASan takes, would need a test. +- *Stack tricks.* + - Guest threads reserve 256 MiB host stacks (`kernel.c` `HOST_STACK`). + - Guest code runs on fibers (`kernel.c` `kern_fiber_initialize`, `plat_fiber_*`). + - Frames are left by non-unwinding jumps (`plat_jmp_go`, used for ExitThread). + - Asynchronous preemption suspends a thread and rewrites its instruction pointer to `kern_ap_stub` + (`kernel.c` `ap_try`). + + ASan's fake stacks and its stack bookkeeping would need fiber annotations and probably + `detect_stack_use_after_return=0`. +- *Generated code.* Instrumenting the generated C would put a shadow check on every guest load and store. That is + slow, but possible in principle. Instrumenting only `runtime/` is the smaller first step. +- *Toolchain.* Whether MSYS2 UCRT64's clang ships the ASan and UBSan runtimes for the `x86_64-w64-windows-gnu` + target was not checked. + +**ThreadSanitizer** + +- It does not exist for Windows targets. +- The Linux build (`runtime/platform/linux.c`) is the only place it could run. Its memory layout would have to accept + the fixed guest reservations below 2^39 and the userfaultfd write watch; not determined. +- It would also see the guest's own lock-free per-core data, which the kernel keeps safe by its virtual-core rule + (section 3.3), as races. Expect noise there. + +--- + +## 2. Subsystem map + +There are 22 subsystems. Files are under `runtime/` unless the path says otherwise. + +| # | Subsystem | Files | What it owns | +|---|---|---|---| +| 1 | Recompiler (build time) | `recomp/*.py`, `recomp/patches-v111.txt` | Lifting ARM64 to C; module bases (`layout.py`); jump tables; patch sets (`patches.py`). Output is generated C under ignored folders (never edited by hand). | +| 2 | Process entry and boot | `main.c`, `boot.c`, `loader.c`, `hostfn.c`, `dispatch.c`, `patches.c`, `guest_setjmp.c`, `fma.c`, `cpu.h`, `simd.h`, `simd_fp.h` | Command line and modes; loading the lifted modules at their bases, linking host overrides (`HOST_OVERRIDE`/`HOST_OBSERVER` tables, `hostfn.c`); the indirect-branch table (`rt_dispatch`); runtime switching of patch sets (`rt_patch_on`, `rt_patch_switch`); guest setjmp/longjmp; the boot sequence and shader/pipeline prewarm wait (`boot.c` `rt_boot`, `boot_wait`). | +| 3 | Kernel and scheduling | `kernel.c`, `kernel.h`, `kernel_ap_stub.h`, `svc.c` | Guest threads (one host thread each), six virtual cores and their hand-off, preemption (`core_kick`, async preemption), waits and events, the handle table, fibers, system events, SVC entry. | +| 4 | Guest memory | `memory.c`, `platform/win32.c` (reserve, commit, write watch, fault hooks) | The fixed guest address space; heap, stacks, alias region and app-pool limit; the kernel-region allocator; write watch; freeze/thaw of idle regions; lazy write-back of GPU writes (armed pages fetched on fault). | +| 5 | Services (in-process Horizon) | `ipc.c`, `ov_system.c`, `net_offline.c`, `nfp.c`, `amiibo.c`, `swkbd.c`, `swkbd_win.c`, `swkbd_sdl.c`, `ov_media.c` (Opus) | `sm:` and the service table; oe/applet/am/account/time and others answered on the host; offline sockets; amiibo; the software keyboard window. | +| 6 | Files: RomFS, decompression, mods | `romfs.c`, `romfs_path.h`, `restbl.c`, `ov_zstd.c`, `mods.c`, `cheats.c` | The read-only game RomFS from the player's image with overlays (`romfs-patches*`, mods); the resource size table; host zstd decode with dictionaries; mod scan and order; cheats from the mods' cheat files. | +| 7 | Save data | `fs_host.c`, `save_share.c`, `save_zip.c`, `sha256.c` | The game's save mount on the host file system, the save transaction (work copy, commit, swap, backups), recovery at start, import and export zips. | +| 8 | Settings and logging | `cfg.c`, `cfg.h`, `logq.c`, `main.c` (log sink, crash handler), `perf.c` (switches `rt_knob`, `rt_ab`) | Every setting with its default (`nx2navi.ini`, `NX2NAVI_*`), live changes and saving; the log queue and its writer thread; log rotation; the crash report. | +| 9 | Frame pacing and game timing | `frame_rate.c`, `nvn_api_obj.c` (`present_period`, `pace`, `nvnWindowAcquireTexture`), `rtss_limit.c`, `resolution.c`, `widescreen.c`, `dynres.c` | The frame limit and present slots; the game's frame step (`ostep`); the world clock; the RivaTuner limit hand-off; render resolution, aspect and dynamic resolution. | +| 10 | NVN front end | `nvn_api_core.c`, `nvn_api_cmd.c`, `nvn_api_obj.c`, `nvn_ext.c`, `nvn_procs.c`, `nvn_procs.inc`, `nvn_tex.c`, `tex_deswizzle.c`, `ov_gfx.c`, `nvn.h`, `nvn_api.h`, `nvn_obj.h`, `nvn_hmap.h`, `nvn_pool_index.h` | The NVN API the game calls: devices, queues, memory pools, textures and samplers, command buffer recording into op records, deferred binds, recording copies and pins, submit and present entry points, texture layout and deswizzle. | +| 11 | Replay and submission | `vk_backend.c`, `vk_exec.c`, `vk_exec_draw.c`, `vk_exec_xfer.c`, `vk_exec.h`, `vk_rec.c`, `vk_rec.h`, `vk_sync.c`, `vk_usnap.c`, `vk_target_frames.h` | Replaying NVN op records into Vulkan command buffers, draws, binds, the bindless pools, copies, events and counters, event order across queues; the recorder thread's packet ring; timelines, submit batching, the completion thread; the uniform snapshot; frame hold. | +| 12 | GPU memory | `vk_memory.c`, `vk_vma.cpp`, `vk_headroom.c`, `vk_gpa.c`, `vk_gpa.h`, `vk_vaddr.c`, `wb_lazy_choice.h` | Import of guest pools, VRAM mirrors and their eviction, shadow storage, upload batches and staging, deferred destruction, write-back of GPU writes, the lazy write-back's GPU side, the device address table, the VRAM budget, the headroom spare. | +| 13 | Textures | `vk_texture.c`, `vk_astc.c`, `tex_astc.c`, `tex_astc_mt.c`, `vk_formats.c`, `tex.h` | The texture image cache and its eviction (release, staleness, idle, disuse, VRAM and commit pressure), samplers, texture detail, uploads and ASTC decode (GPU, CPU fallback). | +| 14 | Shaders | `gfx_shader.c`, `gfx_shader_guess.c`, `gfx.h`, `tools/xlate/` (translator source), `tools/vendor/` (pinned translator) | Translation through child processes, the memory cache, the disk cache and pack, the carry of the previous translator's translations, prewarm and preparation, disk-read budget. | +| 15 | Pipelines | `vk_pipeline.c`, `vk_warm_hint.h`, `vk_caps.c` | Graphics and compute pipelines, stage libraries and fast links, background workers, the boot prewarm and prebuild, driver cache warm checks, the pipeline cache file and autosave, records (`pipeline-keys.bin`, `compute-used.bin`), device capability decisions. | +| 16 | Device and present | `vk_device.c`, `gfx_present.c`, `gfx_window_win.c`, `gfx_window_sdl.c`, `gfx_wsys.h`, `vk_hdr.c`, `vk_fsr.c`, `vk_color.c`, `vk_tonemap.c`, `vk_contact.c`, `gfx_null.c` | Instance and device, the queue lock, the swapchain, the present blit and FSR 1, HDR, colour adjustment, the window thread, the vsync thread, the scene upscaler stand-in, contact shadows. | +| 17 | Upscaling and frame generation | `vk_dlaa.c`, `vk_dlaa.h`, `vk_ffx.cpp`, `vk_fg.cpp`, `vk_dlssg.c`, `dlssg/nx2_sl.cpp`, `vk_mvprev.c`, `vk_mvsurvey.c`, `vk_mvcheck.c` | DLSS/DLAA through NGX, FSR 3.1 upscaling and frame generation, DLSS frame generation through `nx2navi_dlssg.dll`, motion vectors. | +| 18 | Audio | `audren.c`, `audren.h`, `audio_mixer.c`, `audio_effects.c`, `audio_reverb.c`, `audio_capture.c`, `ov_audio_input.c`, `menu_sound.c` | The game's audio renderer (`audren:u`) on a host render thread, the mixer and its SDL output ring, effects, the microphone, menu sounds. | +| 19 | Movies | `ov_movie.c`, `ov_movie2.c`, `movie.h` | Host VP9 (libvpx) and AV1 (dav1d) decoders standing in for the SDK's, with their threads and frame queues. | +| 20 | Input | `input.c`, `input_win.c`, `input_sdl.c`, `input_map.c`, `input_ds3.c`, `input_ds3_win.c`, `ov_input.c`, `mouse_direct.c`, `motion_fusion.c`, `camera_speed.c`, `menu_cursor.c` | Gamepads (SDL3, XInput, DualShock 3), keyboard and mouse, bindings, the state the game's HID calls read, rumble, motion, mouse camera, camera speed rewrite, menu pointer. | +| 21 | In-game menu and overlay | `ui/*.cpp`, `ui_text.c`, `menu_assets.c`, `folder_pick_win.cpp`, `folder_pick_sdl.c`, `perfmon.c`, `perfmon.h`, `sysinfo.c` | The Dear ImGui menu drawn on the present path, its art and fonts from the game's files, the performance overlay and its sampler, save export/import from the menu. | +| 22 | Diagnostics | `perf.c`, `prof_win.c`, `prof.h`, `flight.c`, `vk_dump.c`, `vk_crumbs.c`, `rdoc.c`, `discord_rpc.c`, `*_probe.c` | Frame timing and counters, the sampling profiler, the flight recorder, frame dumps, GPU breadcrumbs, the external capture hook, Discord presence (not diagnostics but a side service), the runtime probes. | +| — | Platform | `platform/platform.h`, `platform/win32.c`, `platform/linux.c`, `platform/common.c`, `platform/fp_x86.h` | Threads, locks, events, atomics, fibers, virtual memory, write watch, fault and crash hooks, files (atomic writes), child processes, CPU reservation. | +| — | Build kit and launcher | `tools/make_game.py`, `tools/prepare_shaders.py`, `tools/*`, `launcher/*`, `installer/*` | The player's build, shader preparation, updates, save import/export from outside the game. Not part of the running game; mapped only by what the docs say. | + +--- + +## 3. Threads + +### 3.1 Primitives + +From `platform/platform.h` and `platform/win32.c`. + +- **`PlatMutex`.** A Windows SRW lock, taken exclusive or shared. Not recursive. +- **`PlatRMutex`.** A recursive mutex: an owner and a depth over a `PlatMutex` (`platform/common.c`). +- **`PlatCond`, `PlatEvent`, `PlatOnce`.** Condition variables, events, and one-time init. +- **`plat_thread_new` / `_ex`.** Creates a joinable thread: suspended `CreateThread`, named, then resumed. + - The default stack reservation is 16 MiB (`PLAT_STACK_DEFAULT`). + - `plat_thread_spawn` does the same and then detaches. Detaching closes the handle and leaves the small + `PlatThread` struct (commented as intended). +- **Per-thread handles.** These `__thread` handles are never closed when a thread exits: + - the high-resolution waitable timer behind `plat_wait_ns`; + - the `plat_file_pread` and `plat_file_pwrite` events. + + See lead L-26. +- **`NVN_BLOCKING` and `kern_core_away`.** A guest thread that makes a long host call gives its virtual core away + first, then takes it back after the call. This covers submit, present, fence waits, shader translation, `nn::fs` + calls and pool setup. + +### 3.2 Thread table + +About 55 kinds of thread. "Detached" means started with `plat_thread_spawn` and never joined. Priorities are the +platform's seven levels; "normal" when nothing sets one. + +#### Process, kernel and system + +| Thread (name) | Entry | Started by, when | How many | Ends | +|---|---|---|---|---| +| Process main thread | `main.c` `main` → `boot.c` `rt_boot` | OS | 1 | Blocks in `plat_thread_join` on guest main; `rt_fatal` if guest main returns | +| "guest main" | `kernel.c` `guest_main` → `kern_main_thread` → `boot.c` `guest_main` (runs `nn::init::Start`) | `kernel.c` `kern_run_on_guest_main` (~1469) from `rt_boot` after the prewarm wait | 1, 256 MiB stack reserved | Joined by the main thread | +| "guest" | `kernel.c` `thread_main` (~1383): waits for `StartThread`, takes a core, `rt_call(entry)` | SVC `CreateThread` (0x08, `kern_svc_inner` ~1562) | One per guest thread; detached; 256 MiB reserved stack each | `ExitThread` (0x0A) → `thread_finish`; a thread created and never started waits forever (lead L-12) | +| (guest fibers) | `kernel.c` `fiber_main` | `kern_fiber_initialize` (~2206) | Up to `FIBER_MAX` 1024 | Not threads: they run on whichever guest thread switches to them | +| "prewarm" | `boot.c` `prewarm_main` (~348): `vk_pipeline_prewarm`, `gfx_shader_prepare_recorded`, `gfx_shader_carry_start` | `rt_boot` (~407) before the modules load | 1 | Joined, or detached by `boot_wait` after `NX2NAVI_PREWARM_WAIT_MS` or 60 s without progress; then runs on during play | +| "log" | `logq.c` `log_main` (~114) | `main.c` `log_open` → `logq_async` (~125), game runs, unless `NX2NAVI_LOG_ASYNC=0` | 1, detached | Never ends; `logq_sync` turns the queue off | +| "save commit" | `fs_host.c` `commit_main` → `commit_run` → `save_commit_locked` | `fs_host.c` `save_commit` (~601) on each `nn::fs::Commit` with a dirty save | One per Commit, detached; inline when the spawn fails | After the commit | +| PGO flush | `platform/win32.c` `pgo_flush_thread` | Constructor, only with `NX2NAVI_PGO_GEN` (instrumented builds) | 1 | Never | +| Open folder | `platform/win32.c` `open_folder_main` | `plat_open_folder` (menu) | Per call | After `ShellExecuteW` | +| Exception handlers | `platform/win32.c` `fault_veh` (first), `crash_veh` (last), `crash_filter` | Registered by `plat_mem_fault_hook` (from `memory.c` `mem_init`) and `plat_crash_hook` (from `main.c`) | — | Run on the faulting thread; `crash_veh` → `main.c` `crash_handler` → `plat_exit(71)` | +| "reap" (Linux only) | `platform/linux.c` `reap_main` | Child process start | Per child | When the child exits | + +#### Graphics: replay, submission, present + +| Thread | Entry | Started by, when | How many, priority | Ends | +|---|---|---|---|---| +| Game submit thread(s) | `nvn_api_core.c` `nvnQueueSubmitCommands` → `vk_backend.c` `submit_sync` → `vk_sync.c` `submit` → `vk_exec.c` `vk_exec_record` | The game | Guest threads | — | +| "The recording thread" | Whichever guest thread first spends 0.5 s in `vk_exec_record` | `vk_exec.c` `rec_claim` (~1643) | Raised to highest priority unless `NX2NAVI_RECORDER_PRIO=0`. Gets a reserved core (`plat_cpu_reserve`) with `NX2NAVI_RECORDER_CORE=1`, or `auto` with 12 or more usable CPUs | — | +| Game present thread | `nvn_api_obj.c` `nvnQueuePresentTexture` → `vk_backend.c` `vk_be_present` | The game | Guest thread | — | +| "vk present" | `vk_backend.c` `present_main` (~75) | `present_image` (~252) at the first present | 1, detached, normal | Never | +| "vk replay" | `vk_backend.c` `replay_main` (~406) | `replay_enqueue` (~472), only with `NX2NAVI_REPLAY_ASYNC=1` (`cfg.c` default 0) | 1, detached; becomes the recording thread | Never | +| "vk recorder" | `vk_rec.c` `rec_main` (~61) | `rec_begin` (~179) at the first submission part | 1. On unless AMD (`NX2NAVI_VK_RECORDER`, `rt_knob` default "0" on AMD, else "1"). Takes the priority of whichever thread called `rec_begin` first | Never (handle kept, never joined) | +| "vk completion" | `vk_sync.c` `completion_main` (~382) | `vk_sync_start` (~471) | 1, normal | Joined in `vk_sync_shutdown` | +| "vsync" | `gfx_present.c` `vsync_main` (~175) | `vsync_ensure` (~210) | 1, detached, highest | Never | +| "fg present" | `gfx_present.c` `ng_thread` (~1098) | `ng_ready` (~1180), only when `vk_ngxfg_wanted()`; the comment at ~925 says 0 on Windows | 1, detached | Never | +| "vk headroom" | `vk_headroom.c` `headroom_main` (~157) | `vk_headroom_start` from `vk_device.c` `vk_init`; off with `NX2NAVI_VRAM_HEADROOM=0` | 1, detached, below normal | After `vk_headroom_stop` | +| "mem census" | `vk_memory.c` `census_main` (~3138) | `heap_log`, only with `NX2NAVI_MEM_CENSUS=1` | At most one at a time | After one walk | + +#### Pipelines + +| Thread | Entry | Started by, when | How many, priority | Ends | +|---|---|---|---|---| +| "pipe worker" | `vk_pipeline.c` `pipe_worker` (~3533) | `workers_start` (~3623), first use | `plat_cpu_usable()/4` clamped 2..`MAX_WORKERS` (4). Below normal for prebuild jobs, normal otherwise | Never | +| "pipe lib worker" | `vk_pipeline.c` `lib_worker` (~3500) | `workers_start` (~3638), with GPL and `NX2NAVI_PIPE_WAIT` not `draw` | Pipe-worker count or 2 | Never | +| "pipe prewarm" | `vk_pipeline.c` `warm_builder` (~4015) | `prewarm_run` (~4186) on the prewarm thread | min(cpus, 64) | Joined; ends at `PREWARM_PIPE_MS` (20 s) unless `NX2NAVI_PREWARM_FULL=1` | +| "pipe list" | `warm_builder` (~5942) | `seed_pipelines`, preparation modes only | min(cpus, 64) | Joined | +| "big compute" | `vk_pipeline.c` `bg_main` (~5140) | `bg_start` (~5252) by the last `lb_worker`; `NX2NAVI_LIB_PREBUILD_BIG_BG` (default 1) | 1, below normal; raised to normal when a dispatch waits for it | Joined in `lb_stop` | +| "lib prebuild" | `vk_pipeline.c` `lb_worker` (~5418) | `lb_start` (~5707) from the boot prewarm; `NX2NAVI_LIB_PREBUILD` | `NX2NAVI_LIB_PREBUILD_THREADS` or 2 (max 16). Idle priority, normal around `P.lock` and shader loads | When the list is done | +| "lib warm check" | `vk_pipeline.c` `lw_main` (~5572) | `lw_start` (~5649); `NX2NAVI_LIB_WARM` (default 1) | 1, below normal | Joined in `lw_stop` | +| "lib warm" | `vk_pipeline.c` `lw_worker` (~5532) | `lw_main` when the driver cache is cold | cpus/4 clamped 2..6, idle | Joined in `lw_stop` | +| "lib warm" | `vk_pipeline.c` `lb_warm_worker` (~5733) | `lb_warm_prepared` (~5794), preparation modes only | min(cpus, 64) | Joined | +| "pipe autosave" | `vk_pipeline.c` `autosave_main` (~6390) | `vk_pipeline_autosave` (~6402) from the present thread, once | 1, detached, below normal, 500 ms loop | Never; not stopped by `vk_pipeline_shutdown` (lead L-15) | + +#### Shaders + +| Thread | Entry | Started by, when | How many, priority | Ends | +|---|---|---|---|---| +| "xlate" | `gfx_shader.c` `xlate_worker` (~2070) | `start_workers` (~2127), first async job | `NX2NAVI_XLATE_PROCS` (default 2, 1..32) | Never | +| "shload" | `gfx_shader.c` `load_worker` (~2093) | Same | `LOADERS` = 3 | Never | +| "use preload" | `gfx_shader.c` `use_preload` (~1304) | `use_preload_start` (~1335) | 1, below normal | After the scan | +| "shader ids" | `gfx_shader.c` `ids_write_main` (~506) | `ids_note` (~515), once | 1 | After one write | +| "shader prewarm" | `gfx_shader.c` `warm_worker` (~2314) | `gfx_shader_prewarm` (~2399) from `prewarm_run` | cpus, 1..64. Translator children raised to `NX2NAVI_PREWARM_XLATE` or min(cpus/2, 16) meanwhile | Joined | +| "shader prepare" | `gfx_shader.c` `prep_worker` (~2732) | `prepare_files` (~2787), preparation modes | 1..64 | Joined | +| "shader carry" | `gfx_shader.c` `carry_main` (~3194) | `gfx_shader_carry_start` (~3305) from `prewarm_main`; `NX2NAVI_SHADER_CARRY` (default 1) | 1, lowest; own translator child at idle priority | After one pass | +| Translator processes | `nx2navi_xlate.exe --serve` | `gfx_shader.c` `child_start` (~533) via `plat_child_start` | Pool `S.s[MAX_SVC=32]`, limit `NX2NAVI_XLATE_PROCS`, raised during prewarm | Kept for the life of the process | +| "astc" | `tex_astc_mt.c` `worker` (~58) | `pool_init` via `plat_once` at the first large CPU ASTC decode | Up to 7 | Never | + +#### Audio and movies + +| Thread | Entry | Started by, when | How many, priority | Ends | +|---|---|---|---|---| +| "audren" | `audren.c` `render_thread` (~517) | `audren_manager_handler` cmd 0 (~682) on the game's IPC thread | One per open renderer, highest | Joined in `renderer_close` | +| SDL audio output | `audio_mixer.c` `sdl_pull` (~320) | SDL's own device thread, `SDL_OpenAudioDeviceStream` in `stream_open` (~344) | 1 per stream | When the stream is destroyed | +| SDL audio capture | `audio_capture.c` `received` (~26) | SDL's own thread, `mic_open` (~98) | 1 per mic | `mic_close` | +| "movie" | `ov_movie.c` `worker` (~238) | `ov_ctor` (~454) on a game thread | One per VP9 decoder (`MAX_MOVIES` 16), plus libvpx's own threads (`VPX_THREADS` 4) | Joined in `destroy` | +| "movie decoder" | `ov_movie2.c` `decoder_thread` (~483) | `ov_initialize` (~601) | One per decoder, plus dav1d's own threads (8) | Joined in `stop_thread` | +| "movie convert" | `ov_movie2.c` `convert_thread` (~443) | `ov_initialize` (~603) | One per decoder | Joined in `stop_thread` | +| "movie convert" (stripes) | `ov_movie2.c` `stripe_run` (~269) | `run_stripes` (~287), per converted picture | 5 per call, created and joined each frame (lead L-34) | Joined | + +#### Input, window and menu + +| Thread | Entry | Started by, when | How many | Ends | +|---|---|---|---|---| +| "pads" | `input.c` `up_main` (~416) | `sdl_start` (~458) at the first poll | 1, detached | Never (unless SDL init fails) | +| "motion" | `input.c` `motion_main` (~1159) | `input_motion_start` (~1186) from `ov_input.c` `ov_six_start` | 1, detached, 250 Hz loop | Never, also after the sensor stops | +| "ds3-scan" | `input_ds3_win.c` `scan_thread` (~122) | `ds3_read` (~276) with `NX2NAVI_DS3` | 1, detached, 256 KiB stack | Never | +| "window" | `gfx_window_win.c` `window_main` (~643): the Win32 message loop | `wsys_open` (~729) | 1, detached | When `GetMessage` returns <= 0 | +| "folder dialog" | `folder_pick_win.cpp` `pick_main` (~51) | `pick` (~90) from the menu | Per pick | After the dialog | +| "save export" | `ui/menu.cpp` `share_export_main` (~1116) | `rows_saves` (~1176) | One at a time (`g_share_busy`) | After the export | +| "menu-art" | `ui/menu_art.cpp` `decode_all` (~48) | `menu_art_start` (~66), once | 1 | After decoding | +| "camera speed" | `camera_speed.c` `search_main` (~262) | `cam_speed_tick` (~304) on the present path | One at a time (`searching`) | After one search | + +#### Monitoring, profiling and other + +| Thread | Entry | Started by, when | Ends | +|---|---|---|---| +| "discord" | `discord_rpc.c` `discord_main` (~193) | `discord_init` from `main.c` | Never ("there is no shutdown path") | +| "rtss" | `rtss_limit.c` `worker` (~245) | `start` (~319) at the first `rtss_limit_want` | Never | +| "perfmon" | `perfmon.c` `sampler` (~360) | `perfmon_mode(2)` (~404) from the menu's overlay | When the full overlay is turned off | +| Profiler sampler | `prof_win.c` `sampler_main` (~242), time-critical, suspends every other thread each 1 ms | `prof_sampler_start` (~386), only with `NX2NAVI_PROFILE` | When `prof_sampler_write` stops it (waits 2 s) | +| "flight dump" | `flight.c` `dump_main` (~231), below normal | `start_dump` (~311), with `NX2NAVI_FLIGHT` | After one dump | + +#### Threads inside libraries + +Not enumerated: + +- the GPU driver; +- NVIDIA Streamline and NGX; +- AMD FidelityFX (its frame-generation presenter; `vk_device.c` makes two more graphics-family queues for it, + `vk_fg_queues`); +- SDL's internal threads; +- libvpx and dav1d workers. + +### 3.3 Shared state and what protects it + +Each line names a piece of shared state, the threads that touch it, and the rule. "Protection not found" marks state +touched from more than one thread where no lock or atomic rule was found. That is a lead for Phase 3 pass 2, not a +finding. + +#### Kernel (`kernel.c`) + +- **`G` (`PlatMutex`, ~114).** Header comment: "every wait hangs on one global lock G with one condition variable per + thread". It guards: + - the handle table `g_h[MAX_H]`, `g_all`, `g_wait`, `g_core_owner[]`, `g_core_wait`; + - every `RtThread` wait and core field, event `signaled` and `refs`; + - `g_next_id`. + + Threads: every guest thread at SVCs and waits, plus the waiter that suspends a holder (`ap_try`, `dg_sample`). +- **Lock-free reads, documented.** + - `g_core_wait` in `rt_spin_gate` and the SleepThread yield ("a racy look"). + - `t->preempt` at checkpoints. + - `host_depth`. + - TLR+0x100 and TLR+0x102 ("any thread may read them"). +- **Guest per-core data.** Kept without locks by the game itself, made safe by the virtual-core rule. A guest thread + runs guest code only while it holds a core, and gives it up only where Horizon would switch. + `NX2NAVI_FREE_CORES=1` turns the gate off. +- **`g_se_lock`** (rwlock, ~2062): the `g_se[512]` system-event table. +- **`g_fiber_lock`** (rwlock, ~2133): `g_fibers[]`. The `Fiber` fields written by `kern_fiber_initialize` outside the + lock: protection not found (guest threads re-initialising and switching to a fiber). +- **Lazy one-time init outside `G`:** protection not found (guest main and the first guest threads). + - `cores_enabled` (~341), with `diag_init` and `ap_init`. + - `g_spin_on`, and `lim` in `kern_svc`. + - `mode` in `wake_sync_waiters`. + +#### Guest memory (`memory.c`) + +- **`lock`** (rwlock, ~50): heap size, alias bookkeeping, `stack_maps`, `module_perm`, `map_gen`. + - `mem_read_hold` keeps it shared over long reads. + - `stack_move` (~997) reads `heap_size` before taking `lock`: protection not found (guest threads mapping against + `SetHeapSize`). +- **`frz_lock`** (~75). It guards: + - the freeze/thaw times; + - the lazy write-back segments `lzs`; + - the hot list and probe hits; + - every `lz_*` counter. + + Taken by any faulting thread inside the exception handler (`thaw_fault`, `lazy_fault`, `probe_fault`). The comment + calls it a leaf lock, but the back end's `lz_fetch` (`vk_memory.c` `lazy_fetch`: a GPU copy and a wait of up to + 10 s) and `lz_clean` run under it (section 6, D-05). +- **Atomic flags read without the lock:** `frz[]`, `prb[]`, `lzr[]`, `nfrz`, `nprb`, `frz_count`, and `lz_n` in + `mem_lazy_note` (documented). +- **`klock`** (~1284): the kernel-region allocator's free lists and bump pointer. +- **Write watch.** `plat_mem_written` (`GetWriteWatch` with reset) is called from `vk_memory.c` (~748, ~2606, ~2882) + under `vk_memory.c`'s `gen_lock` on the replay side. `memory.c` itself takes no lock for it. +- **Lock orders:** `lock` → `frz_lock` (commit, decommit, protect); `klock` → `frz_lock`. + +#### Save data (`fs_host.c`) + +- **`tx_lock`** (~220): "taken before lock, never inside it". It guards: + - the save transaction (`ready_root`, `ready_seq`, the working copy, commit and swap steps); + - the backup rotation; + - `fs_save_export`. + + The commit thread takes `tx_lock` alone. +- **`lock`** (rwlock, ~48): slot assignment and release in `mounts[]`, `files[]`, `dirs[]`. +- **`pend_lock` and `pend_cv`** (~562): `commit_pending`, `exiting`. `save_writers`, `save_dirty`, `save_changed_ns` + and `storage_ready` are atomics. +- **Protection not found:** + - the `files[].h` handle used after `file_of` (~1068) drops the shared lock while `close_file` may close it (guest + threads); + - `dirs[]` contents read in `read_directory` (~1307) while `close_directory` frees them; + - `remove_failed` and `remove_error` (commit thread and guest threads). + +#### Logging and settings + +- **`logq.c`.** `Q.q` guards the buffer; `Q.io` guards writes and the output, and is taken first. + - `logq_sync` try-locks each for up to 500 ms, then writes without them (documented). + - The log file is appended with whole writes (`plat_append_write`). +- **`cfg.c`.** `set_lock` (~28) covers `cfg_set`, `cfg_reset` and `cfg_save_to`. Readers take no lock: "an entry is + complete before n_entries counts it, and value pointers are swapped atomically". + - `cfg_memo` is per thread. + - `getenv`-based reads against `cfg_setenv` → `_putenv_s` while the game runs (`gfx_present.c` ~90): protection + not found. + +#### Files, services and the rest of the CPU side + +**RomFS, decompression, IPC** +- `romfs.c`: + - `lock` (rwlock, ~83) guards the handle tables. + - Protection not found: `mount_names` read by `romfs_owns` while `romfs_mount` writes it; a handle used after + `handle_source` unlocks while `romfs_close` closes it. +- `ov_zstd.c`: + - `dict_lock` guards the dictionaries ("never freed: another thread may be decoding with one"). + - `stream_lock` covers slot claim and drop only; a slot's stream fields belong to the thread that holds it. + - A "spent" slot can be handed out while the old thread still reads it: protection not found (lead L-11). +- `ipc.c`: + - `g_applet_lock` guards the applet message ring. + - Protection not found: `IpcSession` domain fields changed during dispatch by any thread using the session; the + session pointer is used without a reference while `CloseHandle` may free it. + +**System services** +- `ov_system.c`: + - `lock` and `message_cv` guard the message queue. + - `account_lock` guards account state. + - `fonts.lock` guards the shared fonts. +- `net_offline.c`: `lock`, then `G` through `kern_event_clear`. +- `amiibo.c`: `g_amiibo_lock`. +- `swkbd.c`: `one` serialises keyboards. +- `loader.c`: `plt_lock`. +- `guest_setjmp.c`: `jt_lock`. + +**Written once at start, then read-only** +- `dispatch.c`: the dispatch table is sealed read-only. +- `hostfn.c`: the registry is fixed at seal ("guest threads start after that"). + +**Patches, mods, cheats** +- `patches.c`: `rt_patch_on[]` bytes are written atomically by `rt_patch_switch`. +- `mods.c`: `mods[]` is changed by `mods_move` and `mods_set_enabled` (menu) while romfs, cheats and boot read it. + Protection not found. + +#### NVN front end + +- **`nvn_api_cmd.c`** + - `copy_lock` (~417): "guards the two maps, the counters and every prefix", and `zombies[]`. Order: `copy_lock`, + then `pin_lock`. + - `pin_lock` (~257): pins and the pin queue. + - `pool_lock` (~86): the recording-buffer pool. + - `cb_lock` (~41). + - `nvn_submit_prepare_async` writes `prefix->deferred` after unlocking (~1294): protection not found. +- **`nvn_api_core.c`** + - `pool_lock` (~75): "guards gva and index". + - `submit_lock` (~638): only with the asynchronous replay. + - With the default synchronous replay there is no front-end submit lock. `q->submits++` and + `nvn_submits_in_frame++` (~634, ~676) are plain increments, and `nvnQueuePresentTexture` resets + `nvn_submits_in_frame` (`nvn_api_obj.c` ~868). Protection not found if the game submits and presents from + different threads. +- **`nvn_api_cmd.c` `nvn_submit_prepare` → `resolve_deferred`** rewrites op records in place, unlocked. Another + thread may be replaying the same handle under `sub_lock`. Protection not found (sync mode). +- **`nvn_api_obj.c`** + - `live_lock` guards the live-texture copies. + - `img_fence[]` and `last_present_fence` are written at present and read at acquire. Protection not found if those + come from different threads. + +#### Replay, submission and the queue + +- **`vk_sync.c` `sub_lock`** (~31): "Submissions: one at a time, so timeline values are signalled in the order they + are handed out". + - It is held across all of `submit()`: the whole `vk_exec_record` replay, `vk_upload_flush`, the prologue and + `queue_submit`. + - Through that it guards vk_exec's `X` state, the recorder's producer side (`vk_rec.h`: every producer holds it), + and vk_memory's per-submission lists ("submit lock"). + - Taken by: game submit threads (sync), the replay thread (async), the present thread (its empty submission) and + memory probes. +- **`st_lock`, `cv_work`, `cv_done`** (~39): `issued`, `done`, `reserved`, `stop` and the completion queue. Shared + with the completion thread, which runs callbacks and `vk_mem_collect` outside the lock. +- **`start_lock`** (~26): device start-up and the completion thread handle. +- **The queue lock `g_ql`** (`gfx_present.c` ~42, recursive). + - `vk.h` ~213: "Every submission to ctx->gfx_queue (and xfer_queue when shared) takes this lock". + - `vk_queue_lock` also flushes held submissions; the `_raw` forms do not. + - Submit batching `H` is guarded by it (`vk_sync.c` ~58). + - Callers of `vkQueueSubmit2`: + - `vk_sync.c` `hold_flush_locked`: from `queue_submit`, `hold_release` (fence waiters; the completion thread only + try-locks), and `vk_queue_lock`; + - `gfx_present.c` `present_image` (~1542); + - `vk_memory.c` `vk_upload_flush` (~3750) and `lazy_fetch` (~2582); + - `vk_fg.cpp` `submit_game`. + - Callers of `vkQueuePresentKHR`: `gfx_present.c` `flip_locked` (~313) and `ng_present` (~991), through Streamline + in `vk_dlssg_present`. + - `vkDeviceWaitIdle` without `g_ql`: `vk_pipeline.c` `vk_pipeline_shutdown` (~6412) and `vk_device.c` `destroy_all` + (~548); see D-11. +- **`vk_backend.c`** + - `pl` and `pcv` (~41): the present job (`job`, `pending`, `busy`). Taken by the present thread and every + `vk_present_drain` caller. + - `rl` and `rcv` (~279): the asynchronous replay ring (`RQ_CAP` 1024). + - `PH` (present held, ~338) and `FH` (frame hold, ~145): protection not found. Touched by the game present thread + and the submit thread(s) in sync mode, and `FH` by the recording thread (`vk_frame_hold_left`). +- **`vk_exec.c`** + - `bcs_lock` (~172): the BC stand-ins ("the replay adds and reads; destroy_tex (any thread) removes"). + - `ET.lock` (~1061): the event-order trace. + - Called outside `sub_lock` from `vk_backend.c` (~220-232, ~360, ~549): `vk_exec_held()`, `vk_exec_held_ready()`, + `vk_exec_frame_log`, `vk_exec_pending_draws_take`, `vk_exec_gate_wait`. Protection not found when the presenting + and the recording thread differ. +- **`vk_exec_draw.c`** + - `spare_lock` (~134): spare descriptor pools and chunks; the replay takes them, the completion thread returns them. + - `pool_lock_` (~1951): the bindless pool layout's lazy creation. + - The texture lock is held throughout the bindless pool sync. +- **`vk_exec_xfer.c`** `cpu_ev_lock` (~458): the CPU event signals. Guest threads (`nvnEventSignal`) against the + replay. +- **`vk_usnap.c`** + - `free_lock`: the free arenas. + - `gather_lock`: the collect buffers, shared by the submitting thread and the replay thread. + - `tq_lock`: the taken-snapshot queue. + - The lazy `U.mode` init: protection not found (benign). +- **`vk_rec.c`.** A lock-free single-producer ring. + - `head` and `tail` are atomics; `wake_ev` is an auto-reset event. + - The producer is any thread holding `sub_lock`. + - `OWNED(cb)` reads `rec_live` and `rec_cb` without atomics from other threads that record into other command + buffers: protection not found (benign by value, per the mapping pass). + +#### GPU memory (`vk_memory.c`) + +**Documented order:** `pool_lock` → `shadow_lock` → `gen_lock`. + +| Lock | Guards | Taken by, and order | +|---|---|---| +| `pool_lock` (~105) | Pool index, physical list, page tables, `mlist` (mirrored pools) | Shared on lookups, exclusive on init, finalize, map and mirror changes | +| `gen_lock` (~729) | Page-generation tables, `snap_*`, `mgen`/`sgen` | The replay, guest threads (`vk_guest_written`), the completion thread (`vk_gpu_written`), textures (`vk_mem_gen_lock`) | +| `shadow_lock` (~1035) | Shadow storage | After `pool_lock`, before `gen_lock` | +| `flush_lock` (~1609) | Flush ranges per pool | Order `pool_lock` → `flush_lock` | +| `dirty_lock` (~983) | Perf census | — | +| `mirror_stat_lock` (~1622) | Mirror summary | — | +| `retire_lock` (~1982) | `retiring[]` | Finalizing guest thread vs the completion thread | +| `snap_pool_lock` (~2221) | Write-back snapshot chunks | — | +| `lz_init_lock` (~2553) | One-time lazy write-back setup | — | +| `cmd_lock` (~3460, recursive) | The upload batch, deferred destruction `dead[]`, the staging cache and arena | Held from `vk_upload_begin` to `vk_upload_end`; order `cmd_lock` → `g_ql` | + +Protection not found: +- `PoolRec.mstate`: set to `MS_ON` after `pool_lock` is released in `mirror_create` (~1949), read by `vk_pool_fini` + (guest) and `vk_gpu_written_back` (completion thread). See L-07. +- `PoolRec.st_*`: "the log reads and clears them without a lock" (acknowledged). + +#### Textures (`vk_texture.c`) + +- **`tex_lock`** (~119, recursive). It guards: + - the texture cache (`by_key`, `by_addr`); + - the texture and sampler slots, the sampler cache; + - the released lists; + - the eviction state. + + Taken by the replay, guest threads (register, release, ReadTexels/WriteTexels, `guest_read`, `range_gone` from pool + finalize) and the present path (`vk_texture_get`). + - Orders: `tex_lock` → `cmd_lock` (`init_image(e, vk_upload_begin())`); `tex_lock` → `gen_lock`; + `tex_lock` → `pool_lock` (shared). +- **`owned_lock`** (~165): GPU-written mirrored textures. "Changed under tex_lock and owned_lock; read under either". + +#### Pipelines and shaders + +**`vk_pipeline.c`** + +- **`P.lock`** (~71). It guards: + - the pipeline, layout and library hash tables; + - the job queues; + - the prebuild bookkeeping and statistics. + + `work_cv`, `done_cv`, `lib_cv` and `A.idle` go with it. Builds run with `P.lock` released. +- **`cache_rw`** (~520). Creates against `P.cache` hold it shared; `cache_save` takes it exclusive, by trylock only. +- **Other locks:** + + | Lock | Guards | + |---|---| + | `save_lock` | One cache save at a time; order `P.lock` → `save_lock` at shutdown | + | `cu_io` | `compute-used.bin` | + | `PB.lock` | Pipeline binaries | + | `K.io` | `pipeline-keys.bin` | + | `VO.lock`, `FB.lock`, `CU.lock`, `LB.stat` | Small tables and statistics | +- **Not protected:** `BG.building` is written by "big compute" without `P.lock` and read under it (benign per the + mapping pass). + +**`gfx_shader.c`** + +| Lock | Guards | +|---|---| +| `cache_lock` (~135) | The memory cache | +| `S.lock` | Translator children | +| `F.lock` | "one translation per id at a time" | +| `ids_lock` | `identities.txt` | +| `failed_lock` | Failed keys | +| `X.lock` with `work`/`done`/`lwork` | Job queues | +| `load_lock` | The disk-read budget | +| `RC.lock`, `rec_io` | Record files; order `rec_io` → `RC.lock` | + +- `use_files` is filled by "use preload" and published by an atomic flag. +- `gfx_shader_drop_memory` (probe only) frees it while it may still be filling: protection not found. +- The code drops threads to idle or lowest priority, and raises them to normal around `cache_lock`. The comment says + why: "use_store takes the cache lock the render thread reads under". + +#### Present, window and menu + +- **`gfx_present.c` `g_pl`** (~125, recursive): the swapchain and present state. Order `g_pl` → `g_ql`. + - Held across the 5 s fence wait, the 1 s acquire and `create_swapchain`. + - Taken by the present thread, the boot thread (`gfx_present_boot`) and the window thread (`gfx_window_resize`). +- **`g_start_lock`** (recursive): window and vsync start. Order `g_start_lock` → `g_pl`. +- **`g_vs_lock`**: vsync events; exclusive in `gfx_vsync_bind`, shared in the vsync thread. +- **`g_mv_lock`**: the movie frame (decoder threads write, the present thread reads). +- **`ng.m` and `ng.cv`**: the NGX presenter hand-off. `ng.interval`, `ng.tried` and `ng.n`: protection not found + (non-Windows only). +- **Menu (`ui/menu.cpp`).** + - "ImGui runs on the present path only, under gfx_present.c's present lock; the event functions only queue." + - `open_lock` → `ev_lock`, and `open_lock` → `cur_lock` (`input_win.c`) through `input_menu`. + - `g_share_lock`; `g_pick_lock` (`amiibo_page.cpp`). +- **`menu_assets.c`** `dicts` and `ndicts`: lazily loaded without a lock from the "menu-art" thread and the present + thread. Protection not found. +- **`gfx_window_win.c`.** The window thread owns its state. Settings arrive by `PostMessage`; `wsys_resize` and + `wsys_probe_*` call into it synchronously. + +#### Audio, movies and input + +**Audio** + +- **`audren.h` `AudioRenderer.lock`.** It guards voices, mixes, effects, sinks, state and mixer render state, between + the game's IPC thread (`request_update`) and the render thread. + - Unlocked: `GetState`, `time_limit`, and `g_game_prio`. Protection not found (benign ints). +- **`audio_mixer.c`.** The output ring is single-producer single-consumer and lock-free ("the SDL audio thread drains + that ring without taking any lock"): `wr`/`rd` atomics. + - The stream fields are changed only after the stream is destroyed. + - `change_events[16]`: the slot index is reserved before the slot is stored. Protection not found for the slot + contents. + - `host_volume` and `sink_dump` statics: protection not found if two renderers are open. +- **`menu_sound.c`.** Per-voice atomics. `started` is plain while `menu_sound_play` is called from the window thread, + the polling thread and the present path: protection not found. +- **`audio_capture.c`.** Relies on the SDL stream lock. + +**Movies** + +- **`ov_movie.c`.** `g_lock` → `Movie.mu`. + - `find()` releases `g_lock` before the movie is used while `destroy` may free it: protection not found (L-08). +- **`ov_movie2.c`.** `lock` ("queues, frames, flags") and `codec` (dav1d use). + - `ov_decode` reads `v->dav1d` without either while `finalize` closes it: protection not found. + - Static timing totals: protection not found (benign). + +**Input** + +- **`input.c`.** + - `lock` guards the pads, state, script, binds and DualShock 3 state. + - `up_lock` with `up_go` and `up_done` guards the update hand-off to the pad thread. + - `sdl_lock` is held around SDL gamepad calls; others only try-lock it. + - Order: `lock` → `up_lock` → `sdl_lock` (trylock). + - `mouse_sens_get` statics: protection not found. +- **`ov_input.c`.** `lock`; `vib_lock` → `input.c` `lock`. The `rumble_cfg` statics written outside `vib_lock`: + protection not found. +- **`input_win.c`.** Mouse deltas are interlocked; `cur_lock` serialises cursor updates. + +**Frame rate and resolution** + +- **`frame_rate.c`.** + - The step words on the patch page are atomics: "one 64-bit and one 32-bit store per present; the guest reads the + floats on its own threads". + - `limit_hz`, `limit_seen`, `limit_read` and `fps60_set` in `frame_limit_live` are reached from three threads: the + presenting guest thread, the menu's present path (`frame_step_limit_hz`), and the mouse camera thread + (`frame_step_game_hz`). Protection not found. +- **`resolution.c`.** `renderer` (written by `res_fn_hit` on any guest thread) and `R.sw`/`R.sh` (DLAA vs the menu): + protection not found. +- **`camera_speed.c`.** `applied`, written by the search thread and read by the poll thread: protection not found. + +### 3.4 Lock order (observed) + +These orders were observed in the code; only a few are documented in comments. + +- `sub_lock` → `g_ql`, `cmd_lock`, `st_lock`, `tex_lock`, `pool_lock`, `gen_lock`. +- `tex_lock` → `cmd_lock`, `gen_lock`, `pool_lock`. +- `cmd_lock` → `g_ql`. +- `g_start_lock` → `g_pl` → `g_ql`. +- `rl` → `st_lock`. +- Async `submit_lock` → `copy_lock`, `gather_lock`, `tq_lock`, `rl`. +- `start_lock` → `st_lock`, `sub_lock`, astc `g_lock`. +- `P.lock` → `save_lock`; `rec_io` → `RC.lock`. +- `memory.c` `lock` → `frz_lock`; `klock` → `frz_lock`. +- `fs_host.c` `tx_lock` → `lock`. +- `ov_movie.c` `g_lock` → `Movie.mu`; `ov_media.c` registry → decoder. +- `input.c` `lock` → `up_lock` → `sdl_lock` (trylock). +- `ov_input.c` `vib_lock` → `input.c` `lock`. +- `menu.cpp` `open_lock` → `ev_lock`, `cur_lock`. +- Kernel `G` is innermost against the other modules. + +No inversion was found in what was read. Not checked: +- `frz_lock` against the GPU-side locks `lazy_fetch` takes (`g_ql`); +- any lock held by a thread that faults into `fault_veh` (L-05). + +--- + +## 4. The path of one frame + +This is the default configuration: replay on the submitting thread, recorder thread on (not on AMD), a discrete GPU +with VRAM mirrors, no frame generation. Steps are in order, function by function. + +### 4.1 The game's CPU frame (guest threads) + +1. **Acquire.** `nvn_api_obj.c` `nvnWindowAcquireTexture` (~813). + 1. Gives the core away (`NVN_BLOCKING`). + 2. Picks the next image index. + 3. `sleep_until(o->avail[idx])`: the image's previous present slot plus one period. This is back-edge pacing at + the frame limit, using `plat_wait_ns` and then `plat_yield`. + 4. Waits for the GPU to finish that image's newest present (`fence_wait`, `NX2NAVI_ACQUIRE_WAIT` default 1; 2 + waits for the newest present of any image). + 5. `frame_start`. +2. **Game logic.** The game's update runs on its own threads, stepped by the value `frame_rate.c` wrote at the last + present (section 4.4). Audio, movie and input services answer on the threads that call them. +3. **Recording.** The game records command buffers through `nvn_api_cmd.c`: the `nvnCommandBuffer*` entry points. + - Each call appends an op record (`op_hdr` plus payload) to recording memory. + - `CallCommands` is inlined at record time (`inline_recording`). + - Deferred binds are noted, to be resolved at submit. + - Nothing reaches Vulkan yet. +4. **Submit.** `nvn_api_core.c` `nvnQueueSubmitCommands` (~627). + 1. `NVN_BLOCKING`; `q->submits++`. + 2. `nvn_submit_prepare(h, n)` resolves deferred binds in place. + 3. `gfx_backend()->submit` → `vk_backend.c` `vk_be_submit` → `submit_sync` (~383). + +### 4.2 Replay into Vulkan (on the submitting thread) + +5. **`submit_sync`.** + 1. If a present is waiting for held work, the held work goes first (`held_resume`, `ph_flush`). + 2. `vk_present_drain` waits until the present thread has taken and submitted its job. + 3. `vk_exec_gate_wait` handles a submission that begins with a wait for a CPU signal. + 4. `vk_texture_new_submit` bumps the submit epoch. Every 8th epoch it also runs the texture VRAM pressure check + `sweep_pressure` and the evictions. + 5. `vk_sync_submit` → `vk_sync.c` `submit` (~573). +6. **`submit`.** + 1. Takes `sub_lock`. + 2. `fence = issued + 1`. + 3. `take_slot` → `claim_slot` reuses or allocates a command buffer. + 4. `vkBeginCommandBuffer`, `ts_begin` (GPU timestamps with `NX2NAVI_TRACE=perf`). + 5. `rec_begin` hands the part to the recorder ring. + 6. `vk_exec_record`. +7. **`vk_exec_record`** (`vk_exec.c` ~1666). + 1. `nvn_pins_sweep`. + 2. `vk_exec_event_sync(1)`: a CPU signal after this point counts as late. + 3. `vk_mem_mirror_begin`: the pages the CPU wrote (write watch) and the ranges the game flushed are queued as + copies into the VRAM mirrors. + 4. `vk_usnap_begin` copies every uniform range the submission binds from CPU-written pools. + 5. `evo_resume` lets held submissions whose signal came go on. + 6. For each command handle, `walk()`. +8. **`walk`** (~1532) dispatches each op: + + | Ops | Handler | + |---|---| + | `OP_SET_RT` | `set_rt` | + | Clears | `clear_color`, `clear_ds` | + | Viewport, scissor, stencil, bias, blend state | Stored in `ex`, marked dirty | + | Draws, dispatches, binds | `vk_exec_draw.c` `vk_exec_op_draw` | + | Copies, event signals, counters, conditional rendering | `vk_exec_xfer.c` `vk_exec_op_xfer` | + | `OP_WAIT_EVENT` | `vk_exec_wait_event`. An unmet wait ends the pass, and the rest of the submission is held (`cont_push`) until the signal is replayed | + | `OP_BARRIER` | `barrier_to_why` | + | (long submissions) | `maybe_split` sends a part early: `vk_sync_split` → `split_part` → `queue_submit` | +9. **A draw** (`vk_exec_draw.c` `op_draw`, `op_draw_idx`, mesh and dispatch variants) → `prepare_draw_ex` (~3856). + 1. **Per-command-buffer resources and the pass.** + 1. `cb_res` provides transient chunks and descriptor pools for this command buffer. + 2. `vk_exec_pass_begin` begins dynamic rendering. Its targets are resolved through `resolve_rt` and the texture + cache. + 2. **Shaders.** + 1. `shader_for` → `gfx_shader.c` `gfx_shader_get_async` searches, in order: + 1. the memory cache; + 2. the disk cache, read within `load_budget`: 1/8 of wall time, 2 ms at once; + 3. the "shload" or "xlate" workers. + 2. A draw whose shader is not ready: + - reads the rest of the submission ahead (`vk_exec_ahead`), so later pipelines' stage libraries are queued; + - is skipped when its targets are per-frame (`vk_exec_targets_recent`); + - otherwise waits from the frame's wait pool (`frame_wait`, `pipe_frame_wait_ms`). + 3. **Pipeline.** + 1. `vk_pipeline.c` `vk_pipeline_graphics_async` looks up the pipeline hash. A miss is fast-linked from stage + libraries and queued for an optimised build on the pipe workers. + 2. Waits come from `link_budget`, `frame_wait` (full-screen draws), or `last_wait` when the frame hold has no + allowance left. + 3. A pending pipeline skips the draw (`draw_skipped`); the count feeds the frame hold. + 4. **Bind and record.** + 1. `bind_pipeline`. + 2. Dynamic state: `vk_pipeline_set_dynamic_delta`. + 3. `record_fixed`: viewport, scissor, depth bias, stencil. + 4. `bind_resources` (~3189), under the texture lock: + - `pool_sync` → `pool_refill`: the bindless texture and sampler descriptor sets, at most `pool_create_budget` + new entries per refresh and `pool_create_ms` per frame; + - uniform and storage buffers resolved through `vk_mem_lookup` and the uniform snapshot; + - push descriptors. + 5. `feedback_barrier`, when the draw reads a target of its own pass. + 6. `bind_vertex_buffers`. + 7. `vk_exec_oq_draw` (occlusion queries). + 8. `vkCmdDraw*`. + + Every `vkCmd*` goes through the `rc_*` wrappers (`vk_rec.h`), which copy the arguments into the ring. The + "vk recorder" thread makes the real calls in order. +10. **End of the recording** (`vk_exec_record` ~1736). + 1. `vk_exec_pass_end`. + 2. `vk_exec_barrier`, `vk_exec_pool_marks`. + 3. If there are write-backs (`NX2NAVI_WB_SPLIT`), `vk_sync_split_exec` ends the part that signals the executed + timeline `exec_tl`. + 4. `vk_mem_mirror_end` records the copies of what the GPU wrote into mirrors back to guest memory. With lazy + write-back, it arms those pages instead. + 5. `vk_usnap_end`. + 6. Per-command-buffer views are handed to the completion queue. +11. **Back in `submit`.** + 1. `rec_end_cb`: the recorder ends the command buffer. + 2. `vk_upload_flush(0)`: the texture and staging uploads this submission asked for are submitted first. + 3. `prologue`: + - `vk_mem_shadow_sync` (shadow mode); + - `vk_mem_gpa_sync`; + - `vk_mem_lazy_part_end`; + - the mirror copies (`vk_mem_mirror_prologue`) in a command buffer of their own. + 4. `queue_submit` (~115) takes `g_ql` raw and holds the submission. Up to `NX2NAVI_SUBMIT_BATCH` (default 4) are + held, for at most `HOLD_NS` (0.5 ms), then `hold_flush_locked` → `vkQueueSubmit2`. + 5. `vk_mem_note_submit`. + 6. `issued = fence`, broadcast to the completion thread. + 7. Releases `sub_lock`. +12. **Wait after the frame's first submission.** Back in `nvnQueueSubmitCommands`, the first submission of each frame + waits until the GPU has executed that submission's own passes. The wait is `exec_wait` on `exec_tl`, governed by + `NX2NAVI_SUBMIT_FINISH`, default mask 1. The comment explains why: the game rewrites data those passes read + without a fence. + +### 4.3 GPU completion ("vk completion") + +13. **`completion_main`** (`vk_sync.c` ~382). + 1. Waits on the timeline semaphore. It uses 100 ms steps, or `HOLD_NS` while submissions are held, flushing aged + held submissions with a trylock. + 2. Runs the `vk_completion_add` callbacks in FIFO order up to the reached value: + - `cb_done`: chunks and descriptor pools go back to the spares; + - GPU-write stamps (`note_gpu_write`); + - `arena_done` for the uniform snapshot arenas; + - write-back snapshot chunks; + - counter reports (`write_counter`); + - `mirror_retire`, `gpa_retire`. + 3. Sets `done` and wakes fence waiters. + 4. Calls `vk_mem_collect`: deferred destruction and retired upload batches. + +### 4.4 Present + +14. **The game presents.** `nvn_api_obj.c` `nvnQueuePresentTexture` (~858). + 1. `movie_tick` hands over movie frames that are due. + 2. `res_present`, `wide_present`. + 3. `NVN_BLOCKING`; `nvn_submits_in_frame = 0`. + 4. `present_period` → `frame_rate.c` `frame_step_cap_ns` gives the limit's period. While RivaTuner holds the + limit it returns 0. + 5. `pace()` keeps the phase: early waits for the slot; late by less than a period presents now; later restarts. + 6. `gfx_backend()->present` → `vk_backend.c` `vk_be_present(t, crop, slot)`. + 7. `o->avail[idx] = slot + period`; the image's fence. + 8. `frame_step_present(slot, interval)`: `ocarina_step` writes the game's next step (patch set `ostep`) to the + patch page or the game's time manager, and the world clock advances. + 9. `rt_frame_presented`. +15. **`vk_be_present`** (sync). + 1. Frame counter; `vk_dlssg_submitted`; `perf_present`. + 2. With `NX2NAVI_PRESENT_HELD` (default on in sync mode), a present that finds held work waits for it, up to + `PH_MAX` (8) submissions. + 3. Otherwise `present_image` (~215): + 1. Frame-level work: `vk_exec_frame_log`, `dynres_frame`, `vk_dlaa_frame`, `vk_sampler_aniso_live`, + `vk_mem_census`. + 2. `vk_texture_get(t)` gets the presented texture's image, possibly recording an upload. + 3. `frame_hold` checks for skipped draws, a resize or an area load. If it holds the frame, the previous + picture stays and this present is dropped (`NX2NAVI_FRAME_HOLD_MS`, 120 ms allowance). + 4. `vk_hdr_present_source`. + 5. `vk_upload_flush(0)`. + 6. The `PresentJob` goes to the "vk present" thread. At most one job waits, so the caller blocks while one is + pending. +16. **"vk present" `present_main`** (~75). + 1. `vk_thumbs_frame` (flight recorder), `vk_dlssg_present_frame`. + 2. `vk_present_blit` → `gfx_present.c` `present_image(defer=1)` (~1323), under `g_pl`. + 3. `vk_sync_submit(NULL, 0)`: an empty submission so deferred destruction waits for the blit. It may also replay + held work. + 4. `wait_until(pace_smooth(...))`: back-edge pacing to the slot. `NX2NAVI_PACE_SMOOTH` keeps a floor of 7/8 of + the recent interval. + 5. `vk_present_flip` → `flip_locked` → `vkQueuePresentKHR` under `g_ql` (or `vk_dlssg_present` / + `vk_fg_present`). + 6. `perfmon_shown`, `vk_pipeline_autosave`. +17. **What `present_image` (gfx_present.c) does,** under `g_pl`: + 1. `flip_locked` for the previous blit; the swapchain is remade if dirty. + 2. `vkWaitForFences` on the slot (5 s); `vkAcquireNextImageKHR` (1 s), or the frame-generation acquire. + 3. `window_settings_live`, `cam_speed_tick`. + 4. `menu_overlay_frame`: the ImGui layout, the font upload on the first frame. + 5. Record: + 1. bars; + 2. `put_picture`: blit, or FSR 1 (EASU, RCAS), colour, HDR encode; + 3. `hudless_record`; + 4. `movie_overlay`; + 5. `menu_overlay_draw`; + 6. capture and thumbnail; + 7. `vk_fg_frame`, `vk_dlssg_frame`, `ng_record`. + 6. `vkQueueSubmit2` under `vk_queue_lock`: waits on acquire, signals render-done, fences the slot. + 7. The flip is deferred to `vk_present_flip`. + +### 4.5 With `NX2NAVI_REPLAY_ASYNC=1` (off by default) + +- **Submit.** `nvnQueueSubmitCommands` takes the front-end `submit_lock` and runs `nvn_submit_prepare_async`. That + clones recordings still read by queued submissions. +- **Queueing.** `vk_be_submit` copies the handles, takes the uniform snapshot now (`vk_usnap_take`), and + `replay_enqueue`s. That reserves the timeline value under `rl`, and waits while the 1024-item ring is full. +- **Replay thread.** "vk replay" runs steps 5 to 11 for each item, and `present_image` for each present item. +- **Present.** The game's present waits until the previous present was handled ("frame bound"), without giving up + its core (L-43). +- **What changes:** + - event order across queues is off; + - the present-held logic is off; + - `exec_wait` becomes a full fence wait. + +### 4.6 Where a frame can stall + +Collected from the path; these are leads, not findings. + +**Waits in the path** +- The acquire's pacing sleep and GPU fence wait (step 1). +- `vk_present_drain` at every submit (step 5). +- The wait after the first submission of every frame (step 12). +- Shader and pipeline waits from the frame's pools (step 9). +- The texture pressure sweep every 8th submit, under `tex_lock` (step 5). +- The present thread's 5 s fence and 1 s acquire waits under `g_pl` (step 17). + +**Contention** +- `g_ql` held across `vkQueuePresentKHR` (step 16), which `queue_submit` waits behind. +- `sub_lock` held across a whole replay, which the present thread's empty submission waits behind. + +**Other sources** +- Lazy write-back faults on any guest thread, which wait for GPU work under `frz_lock`. +- Pool finalize, which waits for the GPU (`vkQueueWaitIdle`) on a guest thread. + +--- + +## 5. Allocators, pools and caches + +"Limit" names the constant, setting or variable that bounds it, or "none found". "Frees" says when its memory goes +back. + +### 5.1 Guest memory and kernel (CPU side) + +| # | What it holds | Owner | Limit | Frees | +|---|---|---|---|---| +| 1 | Guest address space reservations (`memory.c` `mem_init` ~818): module window, kernel region (`RT_KERNEL_SIZE` 256 MiB), 14 GiB low region (stacks 256 MiB, heap), 64 GiB alias region, host-function window | `memory.c` | Fixed sizes | Never released; pages decommitted on heap shrink, `UnmapPhysicalMemory`, stack unmap | +| 2 | Guest heap and alias mappings (the application pool) | `memory.c` `mem_set_heap_size`, `alias_map` | `NX2NAVI_APP_POOL`, else `rt_app_pool_bytes` (9809 MiB) + `res_heap_extra_bytes()`; heap `HEAP_CAP` 12 GiB | Committed on demand, decommitted when shrunk or unmapped | +| 3 | Kernel-region allocator (`mem_kernel_alloc`, power-of-two classes, `KCLASSES` 29, `KCOMMIT` 64 KiB steps): thread TLR and TLS, shared fonts (up to 64 MiB each), the exception page | `memory.c`, `klock` | The kernel region; "kernel region exhausted" is fatal | Free lists; never decommitted | +| 4 | Moved stacks `stack_maps[4096]`, `alias_pages` (16 MiB calloc), `module_perm[]` | `memory.c` | Fixed | Commit/decommit on map/unmap; tables never freed | +| 5 | Lazy write-back segments `lzs` | `memory.c`, `frz_lock` | None found (realloc doubling from 256) | When touched, thawed or released before a mirror eviction; the array never shrinks | +| 6 | Lazy write-back hot list `lz_hots` | `memory.c` | `LZ_HOTS` 1024 | Replacement | +| 7 | Guest thread host stacks | `kernel.c` | 256 MiB reserved each, committed on demand | At thread exit | +| 8 | `RtThread` + `Cpu` | `kernel.c` | — | When the thread has exited and its handle is closed | +| 9 | Handle table `g_h` | `kernel.c` | `MAX_H` 4096; fatal when full | Slots freed at `CloseHandle` | +| 10 | Fibers | `kernel.c` | `FIBER_MAX` 1024; 256 MiB reserve each | At `FinalizeFiber` | +| 11 | System-event table `g_se` | `kernel.c` | 512; fatal "table full" | Entries never removed (L-10) | +| 12 | Events | `kernel.c` | — | When `refs` reach 0 | +| 13 | Critical-section trace buffer | `kernel.c` | `CRIT_N` × 32 B, only with `NX2NAVI_CRIT` | Never | +| 14 | Dispatch table | `dispatch.c` | `TABLE_SPAN_LIMIT` 1 GiB reserved; host hash `HOST_CAP` 8192 | Never (sealed) | +| 15 | Host-function registry | `hostfn.c` | `MAX_HOSTFN` 4096 | Never | +| 16 | Guest `jmp_buf` table `jt` | `guest_setjmp.c` | `JMP_N` 1024; fatal beyond | Never removed (L-10) | +| 17 | Loader tables (hash, functions, PLT slots) | `loader.c` | — | Never | + +### 5.2 Files, services, settings, logs (CPU side) + +| # | What it holds | Owner | Limit | Frees | +|---|---|---|---|---| +| 18 | Log queue `Q.buf`, `Q.out` | `logq.c` | `LOGQ_CAP` 1 MiB each; a larger line is written by its own thread | Never | +| 19 | Log file | `main.c` | `LOG_CAP` 64 MiB, `LOG_KEEP` 5 rotations | Rotated at start | +| 20 | Early log buffer | `main.c` | 32 KiB static | — | +| 21 | Settings entries and strings | `cfg.c` | `CFG_MAX_KEYS` 512 | Old strings kept on every change "for readers" (L-24) | +| 22 | Per-thread settings memo `cfg_memo` | `cfg.c` | 256 per thread | Thread exit | +| 23 | RomFS index, overlays, open counters, `handles[65536]` | `romfs.c` | Fixed | Never | +| 24 | RomFS whole-image mapping | `romfs.c` | Only with `NX2NAVI_ROMFS_MMAP` | Never | +| 25 | zstd dictionaries | `ov_zstd.c` | `NDICT` 32, each ≤ `MAX_DICT` 64 MiB; beyond, the guest decoder runs | Never ("another thread may be decoding with one") | +| 26 | zstd stream contexts | `ov_zstd.c` | `NSTREAM` 16 | Kept with the slot | +| 27 | Per-thread `ZSTD_DCtx` in `host_decode` | `ov_zstd.c` | One per thread | Never | +| 28 | Save file tables `mounts`, `files`, `dirs` | `fs_host.c` | 16, 1024, 256; fatal when full | Slots at close | +| 29 | Directory listings | `fs_host.c` | — | At `CloseDirectory` | +| 30 | Copy buffers (commit, import) | `fs_host.c` | `COPY_CHUNK` 1 MiB, 2 MiB | Per call | +| 31 | Save backups on disk | `fs_host.c` `rotate_backup` | `SAVE_BACKUPS` 3 | Oldest removed | +| 32 | Save zip read and write buffers | `save_share.c`, `save_zip.c` | `MAX_ZIP` 512 MiB, members 256 MiB, 4000 files | After staging | +| 33 | Mods table | `mods.c` | `MAX_MODS` 512 | Never | +| 34 | Cheats | `cheats.c` | None found (realloc) | Never | +| 35 | IPC sessions and domain objects | `ipc.c` | — | Sessions at refs 0; domain sub-objects not freed (L-25) | +| 36 | Offline socket events | `net_offline.c` | `NEFD` 64; spare events 64 | Spare events never closed | +| 37 | System message queue | `ov_system.c` | 32; dropped silently when full | — | +| 38 | Applet message queue | `ipc.c` | 32; dropped with a log line | — | +| 39 | Detached `PlatThread` structs, per-thread timer and file events | `platform/win32.c` | One set per thread | Never (L-26) | + +### 5.3 Audio, movies, input, menu, diagnostics + +| # | What it holds | Owner | Limit | Frees | +|---|---|---|---|---| +| 40 | Audio renderer tables (voices, pools, mixes, sinks, effects) | `audren.c` `renderer_new` | Voices ≤ 1024, mixes ≤ 256, sinks ≤ 256, effects ≤ 4096; game's work buffer 0x10000 | At renderer close | +| 41 | Mixer output ring | `audio_mixer.c` | `RING_FRAMES` 16384 × 6 channels (about 340 ms); prefill `NX2NAVI_AUDIO_PREFILL_MS` 0..500, default 20 | At mixer close | +| 42 | Mixer work buffers, splitter ids (reallocated every update), limiter delay | `audio_mixer.c` | Limiter ≤ 6 × 192000 floats | At close | +| 43 | Effect delay lines, 3D reverb (made lazily on the render thread) | `audio_effects.c`, `audio_reverb.c` | Delay ≤ 20000 ms at ≤ 192 kHz | At close | +| 44 | Guest AUX/capture rings, circular sinks | `audio_mixer.c` | ≤ 16M samples (fatal above); sink ≤ 256 MiB | At close | +| 45 | Audio change events | `audio_mixer.c` | 16 slots; events past 16 never signalled or closed (L-25) | Never | +| 46 | Menu sounds | `menu_sound.c` | 7 sounds ≤ 10 s each; 8 voices | Never | +| 47 | Microphone ring | `audio_capture.c` | 2 s | `mic_close` | +| 48 | VP9 decoder buffers: `IN_BUFS` 4 × `IN_CAP` 2 MiB (guest-visible), `OUT_BUFS` 8 NV12 frames, libvpx context | `ov_movie.c` | `MAX_MOVIES` 16 decoders | `release_codec`, `destroy` | +| 49 | AV1 decoder queues: `QMAX` 8 pictures, `INMAX` 8 samples, `CQMAX` 2, 16 registered frames; per-picture Y16/U16/V16 temporaries | `ov_movie2.c` | Fixed counts | `clear_queues`, `finalize`; `Video` struct at `ov_dtor` | +| 50 | Opus decoders | `ov_media.c` | None found (one per guest object) | At Finalize | +| 51 | Input script events | `input.c` | Script file size | Never | +| 52 | Motion ring | `motion_fusion.c` | `MOTION_RING` 64 | — | +| 53 | Menu art pixels (14 arts) | `ui/menu_art.cpp` | A few MB | Never ("the pixels stay"); GPU images by `menu_art_release` | +| 54 | Menu asset dictionaries | `menu_assets.c` | 8; per asset ≤ `MAX_RAW` 512 MiB | Never | +| 55 | Menu event queue | `ui/menu.cpp` | `EV_MAX` 256 | — | +| 56 | Perf overlay history and histograms | `perfmon.c`, `perf.c` | `PERF_HISTORY` 120; fixed bins | Static | +| 57 | Profiler tables | `prof_win.c` | About 15 MB static, `SLOW_DUMPS` 64 | Static | +| 58 | Flight recorder ring and thumbnails | `flight.c`, `gfx_present.c` | `NX2NAVI_FLIGHT_FRAMES` (600, 64..7200) | Never; dump jobs freed by the dump thread | +| 59 | Camera speed copies and temporaries | `camera_speed.c` | `copies[16]`; temporaries ≤ 64 MiB | Per search | + +### 5.4 GPU memory (`vk_memory.c`, `vk_headroom.c`, `vk_gpa.c`) + +**How the VRAM budget works.** + +- *Computation.* `vram_query` sums `heapUsage` and `heapBudget` over the device-local heaps (`VK_EXT_memory_budget`; + the driver's figure counts every process). `NX2NAVI_VRAM_BUDGET_MB` caps it (`budget_cap`). + `vk_mem_vram_live` counts free space inside VMA's blocks as room. +- *Mirrors.* `mirror_create` evicts idle mirrors (`mirror_evict`) only when that frees enough. It may then exceed the + budget while mirrors total no more than half of it (`MIRROR_SHARE` 2), asking textures for the room + (`vk_texture_want_room`). Otherwise it refuses the pool, which stays imported (read over PCIe). +- *Textures.* `vk_texture.c` `sweep_pressure` runs every 8 submits. Its limit is `NX2NAVI_TEX_VRAM_PRESSURE` percent + of the budget, default 80. +- *Headroom.* The headroom thread keeps one spare block per memory type while usage plus two blocks stays at or under + 85 % of VMA's budget. It does not apply the cap (D-04). + +| # | What it holds | Owner | Limit | Frees | +|---|---|---|---|---| +| 60 | Pool records: imported host pools (`import_pool`), physical pools (dedicated device-local, `alloc_physical`, no budget check), virtual pools (page tables) | Guest threads via the back end | None found | Pool finalize; mirrored ones by `mirror_retire` on the completion thread | +| 61 | VRAM mirrors of imported pools | Replay | The budget rules above; `NX2NAVI_MEMORY` auto/import/mirror/verify; `NX2NAVI_MIRROR_EVICT` (default 1) | Pool finalize, or `mirror_evict`: idle ≥ `MIRROR_IDLE` 120 submissions, ≤ `MAXV` 64 candidates, oldest first. Deferred to fence +2 | +| 62 | Mirror retry state | Replay | `RETRY_SOON` 16, `RETRY_SUBS` 600 submissions; a pool refused for `MR_ALLOC` is never retried (L-23) | — | +| 63 | Per-submission copy lists (`pend`, `wbl`, `mregions`) | Replay | Grow only | Reset each submission | +| 64 | Flush ranges per pool | `flush_lock` | `FLUSH_RANGES` 32 | — | +| 65 | Page-generation tables (`gen_chunk`, `cgen_chunk`, 256 MiB chunks of uint32 on first stamp) | `gen_lock` | `RT_ADDRESS_LIMIT` | Shutdown | +| 66 | Shadow storage per imported pool, and base copies (one 4 KiB malloc per GPU-written page) | Shadow mode (`NX2NAVI_SHADOW`; Linux default) | None found | Pool finalize (L-24) | +| 67 | Write-back merge snapshot chunks | Replay / completion | ≥ `SNAP_CHUNK` 1 MiB; pool ≤ `SNAP_POOL_N` 128 and budget/64 clamped 64-256 MiB; `NX2NAVI_WB_MERGE_MAX` 32 MiB | At fence; the excess destroyed | +| 68 | Lazy write-back command buffer and fence | `lz_init_lock` | One | Never freed explicitly | +| 69 | Upload batches (command buffers and fences: inflight and spare) | `cmd_lock` | Grow only | Reused; shutdown | +| 70 | Staging cache | `cmd_lock` | `STG_CACHE` 24 buffers, `STG_CACHE_BYTES` 192 MiB | At batch retire | +| 71 | Staging VMA pool | — | `STG_BLOCK` 64 MiB blocks, `STG_MIN_BLOCKS` 2; requests ≤ 32 MiB | — | +| 72 | Staging arena | `cmd_lock` | `ARENA_CHUNK` 8 MiB, ≤ 2 MiB per request, `ARENA_KEEP` 8; `NX2NAVI_STG_ARENA` | At fence; shutdown | +| 73 | Deferred destruction list `dead[]` (images, views, buffers, host frees) | `cmd_lock` | None found | `vk_mem_collect` on the completion thread once the stamped value is reached | +| 74 | Headroom spare (half a VMA block per device-local type; block `NX2NAVI_VMA_BLOCK_MB` 64, 16..256) | "vk headroom" | 85 % of VMA's budget; `NX2NAVI_VRAM_HEADROOM=0` off | Replaced, dropped when there is no room or commit is low, at stop | +| 75 | Device address table (L1 65536 entries, `BLOCKS` 1024 × 16 MiB L2, `RECS` 65536, about 17 MiB) | `gpa_lock` | Fixed; when exhausted, logs and shaders read zeros | Free lists at fence +1 | +| 76 | VMA allocator (`preferredLargeHeapBlockSize` = `vk_vma_block_size`) | `vk_device.c` | — | Shutdown | + +### 5.5 Textures (`vk_texture.c`, `vk_astc.c`) + +**Texture cache eviction.** + +- *Release overflow.* `sweep_released`: `RELEASED_MAX` 2048 entries, and `NX2NAVI_TEX_RELEASED_MB` (default RAM/32 + clamped 512-2048 MiB, raised by budget/4 up to 8192). +- *Stale.* `drop_stale`: `STALE_FRAMES` 120 presents, `GPU_STALE_FRAMES` 1800. +- *Overwritten.* `drop_overwritten`: `OVERWRITTEN_KEEP` 600. +- *VRAM pressure.* `PRESSURE_STEP` 32 per check. +- *Idle.* `evict_idle`: idle for `IDLE_ROUNDS` 240 pool walks and `STALE_FRAMES`; `EVICT_STEP` 64 per check. +- *Disuse.* `evict_disused`: unsampled for `DISUSE_SECONDS` 120; retired, then destroyed after the pool sets turn over. +- *Commit pressure.* `commit_evict`: `COMMIT_EVICT_STEP` 256 MiB, `COMMIT_LOW_KEEP` 256 MiB; `NX2NAVI_TEX_PROC_COMMIT_MB` + (minimum 24576). +- *Destruction.* Deferred (`vk_defer_image`, `vk_defer_free`). + +| # | What it holds | Owner | Limit | Frees | +|---|---|---|---|---| +| 77 | Texture image cache (`by_key`, `by_addr`). Memory comes from: pool memory; a VMA sub-allocation ≤ `SUBALLOC_MAX` 32 MiB; a reused image (`NX2NAVI_TEX_REUSE`); its own allocation (dedicated ≥ `DEDICATED_MIN` 32 MiB) | `tex_lock` | No count cap; the evictions above | The evictions above | +| 78 | Disuse holds | `tex_lock` | `HOLDS_MAX` 65536; cleared when full | — | +| 79 | Image memory requirements cache `img_reqs` | `tex_lock` | None found | Shutdown | +| 80 | Reusable released images | `tex_lock` | ≤ 128 searched per create | With the release sweep | +| 81 | Texture and sampler slots | `tex_lock` | Texture slots ≤ 1<<20 (fatal beyond); sampler slots ≤ 4096 | Shutdown | +| 82 | Sampler cache | `tex_lock` | None found; keyed by parameters, DLSS LOD bias and anisotropy; `vkCreateSampler` failure is fatal (L-19) | Shutdown | +| 83 | Failed-create hold ring | `tex_lock` | 32 entries, 2 s | — | +| 84 | ASTC decode scratch | `vk_astc.c` `g_lock` | ≥ `SCRATCH_MIN` 32 MiB, `CHUNK_OUT` 16 MiB pieces; new per upload batch unless `NX2NAVI_ASTC_SCRATCH_KEEP=1` | Deferred | +| 85 | CPU ASTC worker pool | `tex_astc_mt.c` | 7 threads | Never | + +### 5.6 Replay, submission, present (`vk_exec*.c`, `vk_usnap.c`, `vk_rec.c`, `vk_sync.c`, `gfx_present.c`) + +| # | What it holds | Owner | Limit | Frees | +|---|---|---|---|---| +| 86 | Per-command-buffer resources (transient host-coherent chunks, descriptor pools, written ranges) | Replay; `spare_lock` | `CHUNK_BYTES` 4 MiB; spares `SPARE_POOLS` 64, `SPARE_CHUNKS` 16; allocation failure is fatal | `cb_done` on the completion thread | +| 87 | Image view cache (`view_of`, `views_by_image`) | Replay | No count limit | With the image (`vk_exec_image_gone`) | +| 88 | Bindless texture and sampler pool sets | Replay | `VK_POOL_SETS` 4 (fewer when the device has no room), `VK_POOL_TEX` 32768 × 16 kinds, `VK_POOL_SAMP` 4096; change log 1<<20 | Shutdown | +| 89 | Mesh indirect ring and count buffer | Replay | `MESH_RING` 4096 × 12 B, `MESH_COUNTS` 4096; wraps | Never destroyed (allocation handle discarded, L-30) | +| 90 | Fixed draw tables (stand-ins, shader table 2048×4, and others) | Replay | Fixed | Shutdown | +| 91 | BC stand-ins | `bcs_lock` | `BC_STANDINS` 64 | — | +| 92 | Held submissions (deep copies of recordings for event order) | Replay | `CONT_MAX` 36, `EVO_QUEUES` 16 | When replayed | +| 93 | Completion callbacks per GPU write, report, event | Replay | — | When run | +| 94 | Pending counter reports | Replay | `PENDING` 1<<16 | — | +| 95 | Occlusion query ring | Replay | `OQ_N` 4096; when full, draws go uncounted | — | +| 96 | Uniform snapshot arenas (with a host copy under DLSS) | `free_lock` | ≥ `ARENA_MIN` 4 MiB each; `MAX_RANGE` 64 KiB per binding; free list never trimmed | `arena_done` at fence; destroyed only at shutdown | +| 97 | Uniform snapshot GPU-write list `U.wr` | Replay | Pruned only while snapshots are on (L-29) | `wr_prune` | +| 98 | Recorder packet ring | `vk_rec.c` | `RING_WORDS` 1<<21 (16 MiB static); a packet > 1/4 ring is fatal; a full ring spins | Static | +| 99 | Command buffer slots | `sub_lock` | Grow only | Reused after their fence | +| 100 | Completion queue | `st_lock` | Grows ×2 | Entries run and drop | +| 101 | GPU timestamp pairs | `vk_sync.c` | `TS_PAIRS` 1024 | — | +| 102 | Async replay ring | `rl` | `RQ_CAP` 1024 with back-pressure | — | +| 103 | Recording-buffer pool | `nvn_api_cmd.c` | `POOL_SLOTS` 16, `POOL_MAX_BYTES` 4 MiB | Reused | +| 104 | Texture pins | `nvn_api_cmd.c` | `NVN_PIN_AGE` submissions without references | Swept | +| 105 | Recording copies and zombies | `copy_lock` | None found | Zombies once their submissions are replayed | +| 106 | Live-texture copy table | `live_lock` | One per storage address | — | +| 107 | GVA window | `nvn_api_core.c` | `GVA_MAX` 1024 ranges; full → `gva_alloc` returns 0 | — | +| 108 | Swapchain images and views, present command buffers and fences, capture buffer, thumbnails | `g_pl` | `MAX_IMAGES` 16 | On swapchain remake, release | +| 109 | HDR, FSR 1, tonemap targets and source views | `vk_hdr.c`, `vk_fsr.c`, `vk_tonemap.c` | `SLOTS` 8 source views | Remade on a size change after `vkDeviceWaitIdle` | +| 110 | DLSS features and work images, motion-vector blocks | `vk_dlaa.c` | `DLSS_SIZES` 5; a size unused for 3600 evaluations is freed; `MVM_SLOTS` 16 | — | +| 111 | Frame dump read-back buffers | `vk_dump.c` | `PNG_CAP` 2 GiB, `INFLIGHT_CAP` 3 GiB; debug only | After writing | +| 112 | GPU breadcrumbs | `vk_crumbs.c` | `GP_SLOTS` 16384 | — | +| 113 | Address bind reports | `vk_vaddr.c` | None found while `NX2NAVI_VA_REPORT` is on | Never | + +### 5.7 Pipelines and shaders (memory and disk) + +| # | What it holds | Owner | Limit | Frees | +|---|---|---|---|---| +| 114 | Pipelines and their fast-link variants, hash `pipes[4096]` chained | `P.lock` | None found; never evicted | Only at `vk_pipeline_shutdown`: `vk_program_release` is a weak no-op (D-03, L-24) | +| 115 | Pipeline layouts, set layouts, update templates | `P.lock` | None found | Shutdown | +| 116 | Stage libraries `libs[1024]` chained; failed builds cached as null | `P.lock` | None found | Shutdown (`libs_destroy`) | +| 117 | Library and pipeline job queues | `P.lock` | None found | When built; dropped at shutdown | +| 118 | `VkPipelineCache` in memory and `pipeline-cache.bin` | `cache_rw`, `save_lock` | File > `NX2NAVI_PIPELINE_CACHE_MAX_MB` (512) starts empty; in memory: the driver's, none found | Saved by "pipe autosave" at most every 20 s and at exit (waits ≤ 5 s) | +| 119 | Pipeline binaries `pipeline-binaries.bin` | `PB.lock` | `NX2NAVI_PIPE_BINARIES_MAX_MB` 1024; `NX2NAVI_PIPE_BINARIES` default 0 | — | +| 120 | `pipeline-keys.bin` and its `seen` set | `K.io` | None found (append-only) | Never | +| 121 | `compute-used.bin` | `cu_io` | `NX2NAVI_COMPUTE_KEEP` 512 | — | +| 122 | Large-compute builder's own pipeline cache | "big compute" | `NX2NAVI_BIG_BUILD_FREE_MB` 8192, `NX2NAVI_BIG_BUILD_MAX_MB` 4096 | Merged, then destroyed | +| 123 | Shader memory cache `buckets[4096]` (SPIR-V and reflection) | `cache_lock` | None found; "for the life of the process" | Only by the probe's `gfx_shader_drop_memory` | +| 124 | Use records `use_buckets`, `use_files` | `cache_lock` | `USE_FILE_BUCKETS` 65536 buckets; entries none found | Never | +| 125 | Failed shader keys | `failed_lock` | `FAILED_N` 4096; when full, failures are no longer remembered | — | +| 126 | Shader disk cache: `shader-cache/` loose files, `shader-cache.pack`, `in/*.in`, records | `gfx_shader.c`, `tools/make_game.py` | None found on size; translators listed ≤ `IDS_MAX` 8; packed once 1,000 loose translations exist (`PACK_LOOSE_MIN`) | The carry pass prunes old translators' entries; the pack is replaced by a pruned copy at the next start | +| 127 | Translation job and load queues `X.head`, `X.lhead` | `X.lock` | None found | When done | +| 128 | Translator child processes | `S.lock` | `NX2NAVI_XLATE_PROCS` (2), `MAX_SVC` 32; raised during prewarm | Kept for the process | +| 129 | GPU driver caches (per exe; NVIDIA's per-process disk cache on Linux) | The driver | Driver-defined | Driver-defined | + +That is 129 allocators, pools and caches. + +--- + +## 6. Docs and comments against the code + +The code is what the map follows. "Verified" means the item was checked directly at `ed36773d`. The others come from +the mapping passes' reading, cited, and not re-checked line by line. + +| # | Where | What it says | What the code does | Verified | +|---|---|---|---|---| +| D-01 | `docs/architecture.md` "Threads and cores"; `kernel.c` comment ~322 | Three application cores, three virtual cores | `kernel.c` `NCORE` = 6. Comment ~30: Switch 2 titles get cores 0-5. `NX2NAVI_CORES` can lower it | yes | +| D-02 | `docs/architecture.md` "Graphics" | A recorder thread makes the `vkCmd*` calls | Only where `NX2NAVI_VK_RECORDER` is on: the default is off on AMD (`vk_rec.c` ~170, `rt_knob("VK_RECORDER", amd ? "0" : "1")`) | yes | +| D-03 | `vk.h` ~687, `vk_backend.c` ~581 | `vk_pipeline.c` implements `vk_program_release` and drops a released program's pipelines | No strong definition exists; the weak no-op in `vk_backend.c` always runs | yes | +| D-04 | `vk_memory.c` ~656 | `NX2NAVI_VRAM_BUDGET_MB` caps "every decision here and in vk_texture.c" | `vk_headroom.c` `room` reads `vmaGetHeapBudgets` itself, without the cap | yes | +| D-05 | `memory.c` ~68 | "frz_lock is a leaf lock: nothing writes guest memory under it" | `lazy_drop_locked` and `lazy_piece_locked` call the back end's `lz_fetch` under it (a GPU copy into guest memory and a wait of up to 10 s); `mem_lazy_arm` calls `lz_clean` under it | yes | +| D-06 | `vk_memory.c` ~1744 vs the log line in `evict_enabled` ~1766 | The comment: "Mirrors never go to make room for textures". The log line: idle mirrors make room "for textures under VRAM pressure" | `mirror_evict` is called only from `mirror_create`. The comment is right; the log line is wrong | partly (comment read) | +| D-07 | `svc.c` ~45 `unimplemented[]` | 0x36 `SynchronizePreemptionState` is listed as never reached | `kernel.c` implements 0x36. The table is reached only after the kernel declines, so this has no effect | yes (listing) | +| D-08 | `audren.h` ~176 | "Every call but open/close/set_running runs with r->lock held" | `audio_mixer_pace_ns` (which can destroy and reopen SDL streams) and `audio_mixer_out_stats` run without the lock | no | +| D-09 | `ov_movie2.c` header ~16; `make_picture` ~311, ~333 | One host thread per decoder; make_picture runs on the decoder thread; "a frame the PC has no memory for is dropped" | A decoder thread, a convert thread and 5 stripe threads per picture; make_picture runs on the convert thread; the 8-bit fast path calls `rt_fatal` when its temporaries fail to allocate | no | +| D-10 | `input.c` ~7 | Every SDL gamepad call is made under `lock` | The pad thread makes them under `sdl_lock` only (the comment at ~401 describes the newer scheme) | no | +| D-11 | `vk_sync.c` ~54, `vk_fsr.c` ~105 | Every idle wait takes the queue lock | `vk_pipeline.c` `vk_pipeline_shutdown` (~6412) and `vk_device.c` `destroy_all` (~548) call `vkDeviceWaitIdle` without `g_ql` | no | +| D-12 | `vk_pipeline.c` `bg_main` comment ~5143 | `bg_queue` runs on the replay thread | Its callers are in `lb_compute`, which runs on `lb_worker` threads | no | +| D-13 | `vk_rec.c` ~32 | `rec_prio` is the submitting thread's priority | It is captured once at the first `rec_begin`, from whichever thread holds `sub_lock` then, and never follows `rec_claim`'s raise | no | +| D-14 | `nvn_api_cmd.c` ~417 | `copy_lock` guards every prefix | `nvn_submit_prepare_async` writes `prefix->deferred` after unlocking (~1294) | no | +| D-15 | `gfx_shader.c` ~3 | More translator processes for the boot prewarm only | If `boot_wait` detaches the prewarm, the raised limit (up to 16) stays during play until the prewarm returns | no | +| D-16 | `ui/menu_art.cpp` ~4; `gfx_window_sdl.c` ~6; `menu_sound.c` ~10 | The window thread uploads the art; the window thread makes every SDL video call; the menu thread is the only producer of sounds | The present path uploads the art; several SDL video calls run on the caller's thread; sounds are started from the window, polling and present threads | no | +| D-17 | `ov_input.c` ~2, `flight.c` ~10, `audio_mixer.c` ~786 | `input_poll` in `input_win.c`; `perf_present` in `prof_win.c`; `audio_renderer.c` | They are in `input.c`, `perf.c` and `audren.c` | no | +| D-18 | `vk_fg.cpp` ~51 | The game's queue is shared with the recorder | The recorder never submits (`vk_rec.h`: "submitting and the command pool stay on the submitting thread") | no | +| D-19 | `platform/win32.c` ~473 | The timer handle is "one handle per thread, kept until exit" | Kept until process exit: never closed when a thread exits | no | +| D-20 | Task context and docs: app pool 9809 MiB | — | `memory.c` `mem_init` adds `res_heap_extra_bytes()` (resolution settings), and `NX2NAVI_APP_POOL` overrides it | yes | + +--- + +## 7. Leads for Phase 3 + +Phase 3 went through every lead; the note in italics after each number says what became of it (a ledger ID of section 8, or struck with the reason). + +Every lead is suspected, from reading code only, and none is a finding. Each line gives the place and the +suspicion. + +### Crashes, hangs, data loss (pass 1, 2, 8) + +- **L-01** *(Phase 3: F-2-04, suspected.)* `fs_host.c` `save_commit`, `commit_run`. A second Commit while the first runs: the first thread clears + `commit_pending` while the second waits for `tx_lock`, so `save_wait_commit` may return early and a write may land + during the second copy. +- **L-02** *(Phase 3: F-1-09, suspected.)* `fs_host.c` `file_of`, `read_directory`; `romfs.c` `handle_source`. A handle or listing is used after the + lock is dropped while another guest thread may close it. +- **L-03** *(Phase 3: F-8-02, suspected; the transaction itself confirmed atomic.)* `fs_host.c`. Crash and `rt_fatal` paths do not call `fs_save_flush`. Recovery is left to `save_recover` at + the next start; pass 8 should interrupt each commit step and check it. +- **L-04** *(Phase 3: F-4-05, suspected; the AMD-crash part struck.)* `memory.c` `lazy_drop_locked`, `vk_memory.c` `lazy_fetch`. A GPU copy and a wait (10 s, then fatal) inside + the exception handler under `frz_lock` serialise every other fault, arm and thaw. It is a candidate for the AMD + crash and device-loss reports, and for hitches where lazy write-back is on. +- **L-05** *(Phase 3: struck: nothing under `frz_lock` touches guest pages, and the handlers never take `lock`.)* `platform/win32.c` `fault_veh` → `memory.c` handlers. A fault on a thread that already holds `frz_lock` + (or `lock`, in `stack_move`'s copy) would re-take a non-recursive lock. +- **L-06** *(Phase 3: struck: the completion thread runs a submission's callbacks before the fence the game waits for, and mirrored records are freed on that same thread.)* `vk_memory.c` `vk_gpu_written_back`. A `PoolRec` from `vk_mem_lookup` is used after `pool_lock` is dropped, + on the completion thread, while `vk_pool_fini` may destroy it. +- **L-07** *(Phase 3: struck: reachable only through F-2-05.)* `vk_memory.c` `mirror_create`. `mstate = MS_ON` is set after `pool_lock` is released; a concurrent finalize + may skip `mirror_forget` and leave the record in `mlist`. +- **L-08** *(Phase 3: struck: only a method racing its own destructor, a fault of the game's.)* `ov_movie.c` `find`. The movie is used after `g_lock` is released while `destroy` may free it. + `ov_movie2.c` `ov_decode` reads `v->dav1d` unlocked against `finalize`. +- **L-09** *(Phase 3: F-1-03, suspected.)* `ipc.c` `ipc_svc` 0x21/0x22. The session is used without a reference while `CloseHandle` may free it. + Domain fields are unlocked. +- **L-10** *(Phase 3: F-1-07 and F-1-08, growth confirmed; `files[1024]` struck (slots are freed at close).)* Fixed tables that are never emptied, each fatal when full, for multi-hour sessions: + - `kernel.c` `g_se[512]`: system events, bound by `ov_system.c` `ov_report_event` and `net_offline.c`; + - `guest_setjmp.c` `jt[1024]`; + - `fs_host.c` `files[1024]`. +- **L-11** *(Phase 3: F-1-04, suspected; the fiber and bind parts struck.)* Concurrency in the kernel and zstd: + - `kernel.c` `kern_fiber_finalize`, `kern_fiber_initialize`: fiber fields outside `g_fiber_lock`; + - `kernel.c` `kern_bind_system_event`: check-then-create; + - `ov_zstd.c` `stream_take`: a spent slot reused while still read. +- **L-12** *(Phase 3: struck: such a thread holds no core, and the thread count stays 84-85.)* `kernel.c` `thread_main`. A thread created but never started (or closed first) waits forever, keeping its + stack reservation. +- **L-13** *(Phase 3: F-4-09, suspected; the crash and race parts struck.)* `camera_speed.c` `search_main`. It rewrites every byte-pattern match of the camera speed array across the + guest heap and alias region, while the game runs. +- **L-14** *(Phase 3: F-6-01, suspected; not reproduced in 54 logs.)* `menu_assets.c` `dicts_load`. Lazy dictionary load without a lock, from the "menu-art" thread and the + present thread. +- **L-15** *(Phase 3: struck: the game never shuts the device down; only probes do.)* `vk_pipeline.c` `autosave_main`. It is never stopped and outlives `vk_pipeline_shutdown`; `vkDeviceWaitIdle` + at shutdown runs without `g_ql` (D-11). +- **L-16** *(Phase 3: F-1-06, F-2-01, F-2-02, F-2-03; overlapping submits confirmed.)* Sync-mode races: + - `vk_backend.c` `PH`, `FH`, `vk_exec_held` and `nvn_submits_in_frame`; + - `nvn_api_core.c` `q->submits`; + - `nvn_api_cmd.c` `resolve_deferred` in place. + + All of these apply if the game submits and presents from different threads. +- **L-17** *(Phase 3: struck: this game has no such patch sets, so the function returns before the switch.)* `frame_rate.c` `frame_limit_live`. It is reached from three threads without a lock, and can call + `rt_patch_switch` concurrently. +- **L-18** *(Phase 3: struck: the environment is written only at start and just before exit.)* `cfg.c` `raw_get`. `getenv` races with `cfg_setenv` → `_putenv_s` while the game runs + (`gfx_present.c` ~90). +- **L-19** *(Phase 3: struck as a crash lead: these fire only when memory is gone; the measured 175-178 samplers are far from the driver's limit. The texture part is in F-3-01 and F-3-02.)* Fatal on allocation failure: staging, transient chunks, samplers (`vk_texture.c` `sampler_for`), the AV1 + picture temporaries. A texture create failure triggers no eviction, only a 2 s hold. +- **L-20** *(Phase 3: F-1-10, suspected; not determined (no dungeon or boss).)* `audio_mixer.c` and `audren.c`. `rt_fatal` on game-supplied parameters during RequestUpdate, with the + renderer lock held. + +### Memory and VRAM (pass 3) + +- **L-21** *(Phase 3: F-3-01, suspected; not reproduced.)* `vk_texture.c` `upload` (~2411). A failed GPU ASTC decode leaves the texture marked uploaded and + uninitialised until its storage changes. This is one candidate for the white ground after long play. +- **L-22** *(Phase 3: F-3-02, suspected; not reproduced.)* `vk_texture.c` `evict_disused`, `retire_sweep`, `create_tex`. Retired or failed textures show stand-ins; + re-creation is limited per frame (`WANT_PER_FRAME` 32). Another candidate for white or untextured ground. +- **L-23** *(Phase 3: F-3-03, suspected; not reproduced.)* `vk_memory.c` `mirror_create`. A pool refused for `MR_ALLOC` is never retried and is read over PCIe for + life. A candidate for towns running slower in long play than in fresh scripted runs. +- **L-24** *(Phase 3: struck as unbounded growth (each item is bounded by the game's content or the player's changes; flat across the reload); F-3-12 for the memory the shader cache keeps.)* Growth without a limit for the life of the process: + - pipelines, libraries, layouts and the shader memory cache (`vk_program_release` is a no-op); + - the sampler cache; + - shadow-storage base copies (`vk_memory.c` `sbase_make`, one 4 KiB copy per GPU-written page, kept until the pool + is finalized; shadow mode only); + - `pipeline-keys.bin`; + - `cfg_set`'s old strings. +- **L-25** *(Phase 3: F-3-04 and F-3-05, suspected; the offline socket part struck (spare events are reused).)* Leaked kernel objects per call: + - `audio_mixer.c` change events (beyond 16); + - `ipc.c` domain sub-objects; + - `net_offline.c` spare events. +- **L-26** *(Phase 3: F-3-06, suspected.)* `platform/win32.c`. Per-thread timer and file-event handles are never closed. One "save commit" thread per + Commit and one "camera speed" thread per search leak a few handles each. +- **L-27** *(Phase 3: F-3-07, suspected.)* `vk_headroom.c` `room`. It ignores `NX2NAVI_VRAM_BUDGET_MB`, so a capped test run is not the small card it + claims to be. +- **L-28** *(Phase 3: struck: bounded by the armed pages; 84-144 ranges measured.)* `memory.c` `lzs`. Lazy write-back segments grow without a cap, and every fault and arm scans them linearly. +- **L-29** *(Phase 3: F-3-08, suspected for the non-default mode.)* `vk_usnap.c`. `U.wr` grows without pruning when `NX2NAVI_UBO_SNAPSHOT=0`. The arena free list is never + trimmed. +- **L-30** *(Phase 3: F-3-09, suspected.)* `vk_exec_draw.c` `mesh_ring_entry` (~5048). The mesh ring's allocation handle is discarded, so it is never + destroyed (shutdown only). + +### Stutter (pass 4) and performance (pass 7) + +- **L-31** *(Phase 3: F-7-01, suspected; the A/B is not valid yet.)* `nvn_api_core.c` `nvnQueueSubmitCommands` and `nvn_api_obj.c` `nvnWindowAcquireTexture`. Every frame waits + for the GPU twice (after its first submission, and at acquire for the image's last present). At 120 fps and above, + a slow GPU frame becomes a CPU stall. This is the first suspect for the uncapped-rate spikes. +- **L-32** *(Phase 3: F-4-07, suspected; the lock part struck.)* `vk_sync.c` `submit`. `sub_lock` is held over a whole replay; the present thread's empty submission waits + behind it, and held work may then replay on the normal-priority present thread. +- **L-33** *(Phase 3: F-4-06, suspected.)* `gfx_present.c` `flip_locked`, `create_swapchain`, `movie_overlay`, `hudless_record`. + `vkQueuePresentKHR` and `vkDeviceWaitIdle` run under `g_ql`, which `queue_submit` waits for. `vk_memory.c` + `vk_upload_flush(1)` waits for fences under `cmd_lock`. +- **L-34** *(Phase 3: F-4-10, suspected; the motion thread and the recorder spin struck.)* Thread churn and polling: + - `ov_movie2.c` `run_stripes` creates and joins 5 threads per frame; + - `input.c` `motion_main` takes `lock` 250 times a second forever; + - `vk_rec.c` `wait_space` spins without yielding; + - `vk_pipeline.c` `vk_pipeline_compute` polls every 1 ms without a limit. +- **L-35** *(Phase 3: F-7-03, suspected.)* `vk_texture.c` `sweep_pressure`, `evict_idle`, `evict_disused`. Each scans the whole cache under `tex_lock` + on the submitting thread every 8 submits. +- **L-36** *(Phase 3: F-4-04, the time confirmed.)* `vk_memory.c` `vk_pool_fini`. `vk_upload_flush(1)` plus `vkQueueWaitIdle` on a guest thread per finalized + pool: a hitch at area changes. +- **L-37** *(Phase 3: struck for the default settings: the boot waits without a cap.)* `boot.c` `boot_wait` → detach. A prewarm still running in play keeps up to 16 translator processes and + cpus-many worker threads busy. +- **L-38** *(Phase 3: F-4-08, suspected; the audio part struck.)* The present path does slow work under the present lock: `ui/menu.cpp` `menu_overlay_frame` (`cfg_save`, + `vkQueueWaitIdle` for the font, art uploads); `audio_mixer.c` reverb allocation and device enumeration on the + highest-priority render thread. +- **L-39** *(Phase 3: F-7-02, suspected.)* `vk_rec.c` `rec_begin`. The recorder thread keeps the first caller's priority, not the recording thread's + highest, and may sit outside the reserved core. +- **L-40** *(Phase 3: struck: fences are added in order.)* `vk_sync.c` completion queue. It is FIFO, not ordered by fence, so one late callback holds back the frees + behind it. +- **L-41** *(Phase 3: kept as a rule of method, not a finding.)* `prof_win.c` sampler. Time-critical, suspending every thread each 1 ms. Phase 2 must not compare profiled + runs with unprofiled ones. +- **L-43** *(Phase 3: struck: the core is already given away before the wait.)* `vk_backend.c` `vk_be_present` (asynchronous replay only). The "frame bound" wait (~561-567) blocks the + game's present thread without giving its virtual core away, unlike `replay_drain` and `replay_enqueue`. + +**Leads added by Phase 2's measurements** (section 11.3). They are measured, but their causes are not traced. + +- **L-44** *(Phase 3: F-4-01, confirmed.)* A periodic stall in the Market. In `bl_market_1`, after the script ended (Link standing, segment + `market-end`), every 8th frame took 25-30 ms from frame 13042 to 13786 (90 frames). The same pattern appears 5 times + in `bl_market_2`. Nothing is named: + - no render-thread wait, no work mark; + - GPU 3.15 ms per frame, "bound: cpu"; + - 6 submits per frame, so it is not `vk_texture.c` `sweep_pressure`'s every-8-submits rhythm. + + A profiled run (`NX2NAVI_PROFILE_SLOW`) would name it. +- **L-45** *(Phase 3: not a growth of the host's replay (its time stays 5.5 ms); the cause is not determined.)* The CPU frame grows while standing in Hyrule Field toward dusk (`bl_fieldlong`). + - Over 9 minutes the frame went from about 7.1 to 8.4 ms (140 → 118 fps). + - The GPU's time stayed at 4.37 ms, and every window was "bound: cpu". + - The size lines are flat, except released textures (165 → 542). +- **L-46** *(Phase 3: struck: 32512 is the game's own fixed pool, full from the start.)* `texture pool slots 32512/32768` in every area and run: the registered texture slots the bindless pool + covers (`vk_texture.c` `pool_slots`, `VK_POOL_TEX` 32768). What happens to a slot past `VK_POOL_TEX` was not checked. +- **L-47** *(Phase 3: F-4-02 and F-4-03, confirmed.)* The first one or two world frames after every save load take 48-68 ms and 26-36 ms, with nothing named. + +### Logic that assumes the original rate (pass 8) + +- **L-42** *(Phase 3: F-8-05, F-8-06, F-8-07, suspected; `res_present` and the mouse camera struck.)* Assumptions in the host code: + - `input.c` `shake_stick` uses `SHAKE_SIDE_NS`, two frames at 30 fps; + - `dynres.c` defaults its target to 16.7 ms whatever the limit; + - `resolution.c` `res_present` gives up after 1800 presents ("half a minute at 60 fps"); + - `frame_rate.c` `movie_cap_hz` forces 60 during movies; + - `mouse_direct.c` `camera_input` scales by the 30 Hz ratio. + + Already known in game code: the pick-up popup (`opickup`), the item jingle, and the ocarina recorder's four + rounding sites. + +--- + +## 8. Findings ledger + +Phase 2 entered F-1-01 and F-1-02. Phase 3 (section 12, stopped before its end) added the rest. "Suspected" rows come from reading code and are not bugs until reproduced; "confirmed" rows name the run or tool output that shows them. + +| Field | Meaning | +|---|---| +| ID | `F--`, e.g. `F-1-03` | +| Severity | S1 crash, data loss or out-of-memory; S2 hitch, unbounded memory growth or major visual bug; S3 minor visual or UI bug; S4 optimization | +| Subsystem | A row of section 2 | +| Location | `file` `function` (~line) | +| What happens | — | +| How to trigger | — | +| Status | confirmed (reproduced, or shown by tool output, with the evidence) or suspected (code reading, with the reasoning) | +| Proposed fix | — | +| Risk of the fix | Including whether it changes gameplay timing or behaviour, the save format, or crosses subsystems (those need the user's approval first) | +| Lead | The L-number it came from, if any | +| Fix commit / verification | Phase 4: the commit, the repro, and what showed the fix works | + +| ID | Sev | Subsystem | Location | What happens | Trigger | Status | Fix | Risk | Lead | Commit / verified | +|---|---|---|---|---|---|---|---|---|---|---| +| F-1-01 | S1 | Save data (7) / the game's own loader | Lifted `f_700112b3b0` = `main+0x112b3b0`, called from `main+0x74d7b0`/`0x74d660` | The process dies with `FATAL: access violation (0xc0000005) at host … (nx2navi+0x42419ae), reading address 0x150` in guest code while a save loads. **Cause traced (Phase 3, 12.3):** the save names the area `HyruleCastle_Child` (twice in `progress.sav`); the 1.1.1 RomFS has only `Banc/HyruleCastle/HyruleCastle_Static` and `_Dynamic`, with no `_Child` area. The game opens `Banc/HyruleCastle/HyruleCastle_Child_Static.bcett.byml.zs` (twice), then `.byml`, then the `_Dynamic` pair, gets "not found" for each, reads `Banc/GameBancParam/HyruleCastle_Child.game__banc__GameBancParam.bgyml`, and then reads through a null area object at +0x150. The host answered correctly: the files do not exist. The save's header bytes match the other 11 saves. | Load the test install's slot 1 (`E:\NX2navi-060b\game\profile\save\\slot_01`: Kokiri Forest, child, 3 hearts, autosave dated 11/5/2026 12:07 a.m., blank thumbnail, `caption.sav` 11638 bytes against about 40 KB for the others) as the only slot (`E:\nx2devrun\out\audit\saves\one_d1`), then Load. Runs `probe_d1`, `probe_d1b`, `probe_d1_all`, `f101_fs` | confirmed: 4 of 4, including `ocarina_all.exe` (no audit code) and a file trace. Where the save came from (another game version, or an edited save) is not determined. It is the only Kokiri Forest save available | The host cannot repair the save. It can make the failure readable: when an area's `Banc//_Static.bcett.byml` is asked for and absent, log one line that names the area and say in the crash report that the loaded save names an area this game version does not have (and see F-6-02 for showing it) | None for a log line. Refusing the load would change game behaviour: ask the user first | — | `58a8d21d`. The crash stays (the save cannot load). Verified that it now explains itself, run `p4_d1`: `RomFS: the game asked for the area HyruleCastle_Child (Banc/HyruleCastle/HyruleCastle_Child_Static.bcett.byml.zs), which this game version does not have; the save being loaded names it and cannot be loaded here`, and after the FATAL `fatal: the game asked for the area HyruleCastle_Child, which this game version does not have; a save that names it cannot be loaded` | +| F-1-02 | S4 | In-game menu (21) | `ui/menu_skin.cpp` `skin_atlas_fill`, lambda `lattice` (~265) | `x * 374761393` and `y * 668265263` are signed `int` multiplications that overflow for x ≥ 6 (undefined behaviour; on this compiler they wrap, so the grain looks as meant) | Any start: the menu's font atlas is filled at start-up | confirmed by UBSan: a trap `ud1 0xc` (multiply overflow) at `nx2navi+0x11782fd2`, `addr2line` → `menu_skin.cpp:265` (run `san_ubsan`, section 11.4) | Do the hash in `unsigned` (`(unsigned)x * 374761393u + …`) | None: the same bits, no gameplay or format change | — | `cebdd4a9`. UBSan build without the ignore list (`ocarina_ubsan_fix.exe`), the route: `p4_ubsan` went through the whole route (261 s of world time) with no trap: the start no longer stops at `menu_skin.cpp:265`, and none of the changed code tripped a check | +| F-1-03 | S1 | Services (5) | `ipc.c` `ipc_svc` 0x21/0x22 (~516), `kernel.c` `kern_handle_get` (~2008), `ipc_handle_closed` (~237) | `kern_handle_get` returns the session without a reference and `dispatch` uses it unlocked. A CloseHandle on another guest thread frees it mid-request. Domain tables (`objects`, `nobjects`) are also written unlocked while `dispatch` reads them | A guest thread closes a session while another is inside SendSyncRequest on it (the console keeps the session alive). The sessions here are made at boot, plus the audio renderer and amiibo | suspected (code read, `kern_handle_get` re-read by the auditor); not seen in any run | Take a reference under the kernel lock for the length of the request, released through the path `ipc_handle_closed` uses | Low; services only | L-09 | — | +| F-1-04 | S1 | Files (6) | `ov_zstd.c` `stream_drop` (~340), `stream_take` (~326) | `stream_drop` clears the slot by pointer, not by owner: thread A looks up spent slot k for its stream and unlocks; thread B takes slot k (all 16 slots taken); A's `stream_drop` zeroes it; thread C takes it as free and resets the decoder context B is decoding with. The asset B decodes is corrupted | More than 16 stream states alive, so that slots are reused, with loader threads decoding at once. Phase 2 saw 0 of 16 slots taken at every snapshot (snapshots fall outside loads) | suspected (code re-read by the auditor) | `stream_drop(st, s)` clears only when `st->s == s`, under `stream_lock` | None | L-11 | `32f2a41a`. Not reproduced before, so not shown fixed. Regression: the route with the fixed exe: `p4_route` went through every segment with no FATAL and committed the save five times. Its frame rates cannot be compared with the baseline: the exe name is new and it has a pipeline cache folder of its own, so pipelines were still compiling on other threads (Kakariko 118.1 fps against 140.7; 17 frames over 25 ms in the 12 s after the reload, against 0 and 6) | +| F-1-05 | S1 | Textures (13) | `vk_texture.c` `same_content` (~2489-2493), `upload` (~2264-2272) | `same_content` hashes a texture's guest storage with no readability check and no read hold; `upload` hashes it after `mem_readable` but outside `mem_read_hold`. If the game unmaps the storage between the check and the hash, the render thread reads decommitted memory: an access violation in host code | A texture of at most `CHASH_MAX` bytes whose storage is freed while a page change sends it through `make_fresh` / `make_fresh_snap` | suspected (code re-read by the auditor). Whether a change can be reported for a range just unmapped was not traced | Hash under `mem_read_hold`; in `same_content` treat a failed hold as "changed" | Low, textures only | — | `a9005e5c`. Not reproduced before, so not shown fixed. Regression: the route with the fixed exe: `p4_route` went through every segment with no FATAL and committed the save five times. Its frame rates cannot be compared with the baseline: the exe name is new and it has a pipeline cache folder of its own, so pipelines were still compiling on other threads (Kakariko 118.1 fps against 140.7; 17 frames over 25 ms in the 12 s after the reload, against 0 and 6) | +| F-1-06 | S1 | Replay (11) | `vk_exec.c` `vk_exec_held_ready` (~1261), `cont_walk` → `cont_free` (~1332) | `vk_exec_held_ready` reads the head continuation of each event queue (`evq[s].head->at`, `->since`) without `sub_lock`. A second submitting thread inside `vk_sync_submit` can free that continuation meanwhile: a read of freed memory, then `vk_exec_event_met` through a dangling pointer | Held (event-order) work at the moment two guest threads are in submit or present. The precondition is confirmed: submits overlap from the pause menu's opening (F-2-01) | suspected (code re-read by the auditor) | The front-end lock of F-2-01, or read under `sub_lock` | Low to medium; see F-2-01 | L-16 | — | +| F-1-07 | S1 | Process entry (2) | `guest_setjmp.c` `slot_of` (~101), `ov_setjmp` (~127) | The `jmp_buf` table `jt[1024]` keys on the buffer's guest address and entries are never removed; when it is full `ov_setjmp` ends the process with "setjmp: more than 1024 buffers" | A long session: every new `jmp_buf` address takes an entry for good | confirmed growth, the fatal itself not reached: `mem: sizes … setjmp buffers` went 10 → 22 and 8 → 23 across one save, title and reload (section 11.3). At +12 to +15 per reload the table lasts about 70 reloads if the addresses keep changing; whether they level off was not measured | When full, replace the entry set longest ago and log once; a `longjmp` to a replaced buffer stays fatal as now | Low: only the overflow path changes | L-10 | `7dfa809c`. The full table was not reached in any run, so the new path has not run. Not reproduced before, so not shown fixed. Regression: the route with the fixed exe: `p4_route` went through every segment with no FATAL and committed the save five times. Its frame rates cannot be compared with the baseline: the exe name is new and it has a pipeline cache folder of its own, so pipelines were still compiling on other threads (Kakariko 118.1 fps against 140.7; 17 frames over 25 ms in the 12 s after the reload, against 0 and 6) | +| F-1-08 | S1 | Kernel (3) | `kernel.c` `kern_bind_system_event`, `g_se[512]` (~2060-2095) | The system-event table keys on the event's guest address and entries are never removed; full is fatal ("table full") | A long session with many reloads | confirmed growth, the fatal not reached: `system events` went 8 → 10 across one reload in both route runs (about 250 reloads to the limit) | Reuse an entry whose event is no longer live (`se_live` 0) | Low | L-10 | `1a57cc21`. The full table was not reached in any run, so the new path has not run. `tests\sync_wake_check.py` (builds `kernel.c`) passes. Not reproduced before, so not shown fixed. Regression: the route with the fixed exe: `p4_route` went through every segment with no FATAL and committed the save five times. Its frame rates cannot be compared with the baseline: the exe name is new and it has a pipeline cache folder of its own, so pipelines were still compiling on other threads (Kakariko 118.1 fps against 140.7; 17 frames over 25 ms in the 12 s after the reload, against 0 and 6) | +| F-1-09 | S1 | Save data (7), Files (6) | `fs_host.c` `read_directory` (~1307, no lock at all), `file_of` (~1068), `close_directory` (~1340); `romfs.c` `handle_source` | A directory listing or file handle is used after the lock is dropped (or with none taken): a CloseDirectory on another guest thread frees the listing `read_directory` is copying from; a CloseFile closes the host file a read is using | The game closes a handle on one thread while another uses it. That is a fault of the game's own; the console answers it with an error result, not a crash | suspected (code re-read by the auditor); not seen | Hold `lock` shared for the length of the call, or count users per slot | Low | L-02 | `d61cd9b9`. Directory listings only; file handles keep their window. Not reproduced before. `--probe-fs` and `tests\save_share_check.py` pass with the change | +| F-1-10 | S1 | Audio (18) | `audren.c` `need` (~66-70), `audio_mixer.c` parameter checks (~641-1045) | Parameters the game supplies in RequestUpdate (limiter, reverb, sink sizes) are checked with `rt_fatal`; the console's renderer returns an error result instead | An effect configuration outside the checked ranges. The route (five areas, the pause menu) tripped none; dungeons and bosses, whose effects differ, could not be reached | suspected; not determined by a run | Return the error result and log once instead of ending the process | Changes what the game is told in that case: ask the user first | L-20 | — | +| F-1-11 | S1 | Replay (11), GPU memory (12); cause not determined | The GPU fault is reported by `vk_crumbs.c` and the device-fault lines; the process ends in `vk_memory.c` ("upload submit failed (-4)") or `vk_sync.c` ("the wait for a submission's commands failed (-4; device lost?)") | The GPU reports a page fault and the device is lost while a save loads: `vk: device fault address 1: read invalid at 0x31f000000` (also `0x30b000000`, `0x311000000`), right after `vk: texture pool: an area load of about 4629 textures was made in 1 frames`; the GPU's last mark is `dispatch 3 of submission N: 293x1x1 groups, cs 3524d41df45a41e0`, started and finished | Loading the Hyrule Field day save (`saves\one_u3`) in `E:\nx2devrun` while the boot's pipeline prebuild is skipped there (F-4-11), so pipelines are built at their first draw | confirmed 3 times: runs `p3_l31_nosubmit` (`SUBMIT_FINISH=0`), `p3_l31_noacquire` (`ACQUIRE_WAIT=0`) and `p3_l31_default2` (default settings), three in a row. In the same state `p3_l31_default`, `p3_l31_nosubmit2` and `p3_market_prof` loaded without it; none of the earlier runs of Phases 2 and 3 (prebuild not skipped) had it. **Later data from the session diagnosing it** (its runs, `E:\nx2devrun\out\crash_matrix.txt`): the loss follows the lazy write-back's piece release, not the skipped prebuild: 0 lost in 15 loads of the night field save (`saves\one_u0`) with `NX2NAVI_WB_LAZY_CHUNK=0`, 0 in 10 with `NX2NAVI_WB_LAZY=0`, about 7 in 22 with it on, and one more in the day field (`out\bn_fday_new_2`). The read fault is at the first page of a 64 MiB device memory that holds a 26.6 MiB buffer and 125 images bound 2 s earlier. The mechanism is not known | `test-all-fixes` switches the piece release off by default (`6e3f29d4`, not on this branch: here `WB_LAZY_CHUNK` still defaults to 1). The cause itself is open | — | — | Not the audit's commit; the audit's own runs after it (`p4_*`, 7 save loads with the default) lost no device | +| F-1-12 | S3 | Replay (11) | `vk_sync.c` `completion_main` (~395-431) | After the device is lost the completion thread can still take the timeline as advanced: it ends the process only when `vkWaitSemaphores` or `vkGetSemaphoreCounterValue` return an error, and a lost device may answer both with success and a signalled value. It then runs the callbacks of submissions that never finished (frees, record reuse, counter reports) before the next checked call reports the loss, so the first symptom in the log is a wrong one | Any device loss (F-1-11) | symptom confirmed, mechanism suspected: in `p3_l31_noacquire` the line `vk: occlusion query slot 96 not available after its fence, counted as visible` comes six lines before `vk: device fault`. Reported by the session diagnosing F-1-11; the code was re-read by the auditor (the two result checks are there, a check of the device itself is not) | Ask the device whether it is lost before running callbacks (a cheap checked call, or the fault query), and end with the fault report first | Low: only the path after a loss changes | — | — | +| F-2-01 | S2 | NVN front end (10), Replay (11) | `vk_backend.c` `submit_sync` (~385-400), `ph_flush` (~366), `vk_be_present` sync branch (~546-557), `present_image` (~220-232) | The synchronous replay's front end takes no lock of its own. `ph_flush` is check-then-clear on `PH.on`, so two submitting threads can both present one held frame, and `present_image` (frame log, pending draws, `vk_dlaa_frame`, `frame_hold`, all unlocked globals) can run while another thread's replay writes the same state | Two guest threads inside QueueSubmitCommands or QueuePresentTexture at once, with a present held for event order | precondition confirmed, harm suspected. Run `p3_route`: `nvn: thread 36088 enters a submit on queue 0x134133020 while 1 other submit or present call run (overlap 1, frame 8086)`, then 31 more by frame 12847; the same in both Market runs from the pause menu's first frame. Four threads submit: one on 3 queues, the presenting thread on 4, two more on the present queue. No doubled present was seen (no "went out … after the game's present call" line in these runs) | One mutex around the synchronous `submit_sync` and the synchronous branch of `vk_be_present`; replays already serialise on `sub_lock` | Low to medium: a present may wait behind another thread's replay. No save or gameplay change, but it crosses subsystems 10 and 11: ask the user first | L-16 | — | +| F-2-02 | S3 | NVN front end (10) | `nvn_api_core.c` `nvnQueueSubmitCommands` (`nvn_submits_in_frame++`, ~676), reset in `nvn_api_obj.c` `nvnQueuePresentTexture` (~868) | A plain `int` is incremented by every submitting thread and reset by the presenter. A lost update gives a frame's first submission no GPU wait (the white-frame case the wait exists for) or one wait too many | The overlapping submits of F-2-01 | suspected; the overlap is confirmed | Make the counter atomic (fetch-add, exchange at the present) | None | L-16 | `ca06d5c8`. Not reproduced before, so not shown fixed. Regression: the route with the fixed exe: `p4_route` went through every segment with no FATAL and committed the save five times. Its frame rates cannot be compared with the baseline: the exe name is new and it has a pipeline cache folder of its own, so pipelines were still compiling on other threads (Kakariko 118.1 fps against 140.7; 17 frames over 25 ms in the 12 s after the reload, against 0 and 6) | +| F-2-03 | S3 | NVN front end (10) | `nvn_api_cmd.c` `resolve_deferred` (~1218-1252) | Deferred binds are resolved by copying new handles into the recording in place, without a lock. A continuation of an earlier submission of the same command handle, still held, is replayed later with the new handles | The same command handle submitted again while its earlier continuation is held | suspected | Copy the handles when a continuation of the handle is held, as the asynchronous path does | Low | L-16 | — | +| F-2-04 | S1 | Save data (7) | `fs_host.c` `save_commit` (~601-622), `commit_run` (~583), `save_touched` (~99) | Two Commits entered at once both pass `save_wait_commit`, both set `commit_pending`, and each starts a thread. The first thread clears `commit_pending` while the second still waits for `tx_lock`; a save write then passes `save_touched` and lands in the working copy while the second thread copies it. The committed save can mix files from before and after the write | Two guest threads calling Commit at the same moment, then a save write. One Commit after another (the only pattern seen) is safe: the second waits for the first | suspected (code re-read by the auditor); not seen. The transaction itself is confirmed atomic against a crash (12.3) | Count pending commits instead of a flag, or take `pend_lock` across the check and the start | Low; the save format is untouched | L-01 | `b2f9ea4c`. Not reproduced before (it needs two Commits at once). With the change `--probe-fs` still reads `a crash at each of 6 commit steps recovers to the old save 3 times, the new one 3 times, mixed 0 times; 3 backups` and `tests\save_share_check.py` passes | +| F-2-05 | S2 | Replay (11) | `vk_backend.c` `submit_sync` (~392-396) | A submission stopped at an event wait returns its fence value while its remainder is still held for a later replay. The game's wait on that value can return before the held part is even recorded; if the game then reuses what that part reads, the held replay reads newer memory | Event-order holds (dialogue scenes are the known case) | suspected; needs a counter of fence waits that return with continuations held | Signal the value only once the held remainder has been replayed, or count such returns first | Changes when the game's fence waits return (timing): ask the user first | — | — | +| F-3-01 | S2 | Textures (13) | `vk_texture.c` `upload` (~2404-2413, ~2451); `vk_astc.c` `vk_astc_record` (~566-572) | When the GPU ASTC decode cannot be recorded (its scratch buffer of 32 MiB or more fails to allocate, or no pipeline), `upload` logs "not decoded on the GPU: left as it was" and still sets `uploaded = 1`. The image keeps what its memory held before. It is not retried: the content hash was taken from the storage, so equal bytes written again are skipped as unchanged | An allocation failure, which needs the commit or the device heap exhausted (the budget cap never fails an allocation), at an area load. This is one candidate for the white ground after long play | suspected (code re-read by the auditor). Not reproduced: the line "not decoded on the GPU" is in none of the logs here, the user's recent ones included. A capped run cannot fail an allocation, so it would not reproduce this | On a failed record leave `uploaded` and `chash_ok` clear so the next lookup retries, with a limit, or fall back to the CPU decode | Low, textures only | L-21 | `054bd556`. Part only: the content hash is forgotten after a failed decode, so the next write uploads. A texture whose decode failed is still not uploaded again until its storage is written: that part is open. Not reproduced before. Not reproduced before, so not shown fixed. Regression: the route with the fixed exe: `p4_route` went through every segment with no FATAL and committed the save five times. Its frame rates cannot be compared with the baseline: the exe name is new and it has a pipeline cache folder of its own, so pipelines were still compiling on other threads (Kakariko 118.1 fps against 140.7; 17 frames over 25 ms in the 12 s after the reload, against 0 and 6) | +| F-3-02 | S2 | Textures (13), Replay (11) | `vk_texture.c` `held_out` (~1853), `slot_resolve` (~3109-3124), `evict_disused` (~1863); `vk_exec_draw.c` `make_dummy` (~354-382) | A texture evicted for disuse leaves a hold that ends only at a shader mark or a lookup outside the pool refresh. If a pool-indexing shader that cannot be marked is built after evictions have started, further evictions stop but the keys already held stay held, and what only that shader samples shows its stand-in for good. The stand-ins are 1x1 images moved from UNDEFINED to GENERAL with no clear, so their colour is undefined | VRAM over 80 % of the budget or low commit, textures unsampled for 120 s, then an unmarkable pool shader. A second candidate for the white ground | suspected (code re-read by the auditor for `make_dummy`). The run planned for it (the route under a 6 GiB cap) was not done before Phase 3 was stopped | Clear the holds (and cancel retiring textures) when the first unmarkable shader appears; clear the stand-ins to a defined colour | Low; gives back VRAM that was freed | L-22 | — | +| F-3-03 | S2 | GPU memory (12) | `vk_memory.c` `refuse` (~1745), `vk_mem_use` (~2140-2146) | `refuse` sets a retry time only for a budget refusal (`r->retry_sub = why == MR_BUDGET ? … : 0`). A pool whose mirror allocation failed (`MR_ALLOC`) stays refused until it is finalized and is read over the bus for the rest of the session | A device-local allocation failure (heap or commit exhausted) at the pool's first use | suspected (line re-read by the auditor). Not reproduced: `failed 0` in every `mem: mirror` line of every run here; the budget cap gives budget refusals, never this one | Give `MR_ALLOC` the same retry, and keep the refusal reason in the record so the counters stay right | Low | L-23 | `94ee6e78`. Not reproduced before, so not shown fixed. Regression: the route with the fixed exe: `p4_route` went through every segment with no FATAL and committed the save five times. Its frame rates cannot be compared with the baseline: the exe name is new and it has a pipeline cache folder of its own, so pipelines were still compiling on other threads (Kakariko 118.1 fps against 140.7; 17 frames over 25 ms in the 12 s after the reload, against 0 and 6) | +| F-3-04 | S3 | Audio (18), Kernel (3) | `audio_mixer.c` change events (~1213-1218, ~1296, ~1365) | Each call of the audio device's change-event commands makes a new kernel event, which takes a slot of the handle table (`MAX_H` 4096, fatal when full) and is never closed; events past the 16th are never signalled | Each call of those commands. Handles grew 112 → 116 and 112 → 117 across one reload (section 11.3); which calls took them was not traced | suspected; the handle growth is measured, its source is not | One shared event per kind, as the other audio commands already use | Low | L-25 | — | +| F-3-05 | S3 | Services (5) | `ipc.c` domain objects (`objects[32]`, `ipc.h` ~54; CloseVirtualHandle ~428) | A domain's object table is never compacted and closing a virtual handle frees nothing; the 33rd object is answered with an unknown-command error | A domain session that opens and closes sub-objects repeatedly (the applet proxy), for instance at each return to the title | suspected; needs a run with `NX2NAVI_TRACE=ipc` counting the commands per title return | Free the slot on close and reuse it | Low | L-25 | — | +| F-3-06 | S4 | Platform | `platform/win32.c` `sleep_timer` (~478), `plat_file_pread` / `plat_file_pwrite` events (~1267, ~1526), `plat_thread_detach` (~73) | Per-thread timer and event handles are never closed when a thread exits, and a detached thread's small record stays. One "save commit" thread per changed Commit and one "camera speed" thread per search leak about two handles each | Every save and every sensitivity change | suspected; tens per hour against a limit of millions | Close them when the thread ends | None | L-26 | — | +| F-3-07 | S4 | GPU memory (12) | `vk_headroom.c` `room` (~112-120) | The headroom thread measures against the driver's budget, not the capped one, so under `NX2NAVI_VRAM_BUDGET_MB` it still keeps its spare blocks. A capped test run understates what a small card does | Any capped run | suspected (code read). The cap is a test switch | Compare against the smaller of the driver's budget and the cap | None outside capped runs | L-27 | — | +| F-3-08 | S3 | Replay (11) | `vk_usnap.c` `vk_usnap_drop` (~433), `vk_usnap_begin` (~358), `arena_get` (~90) | With uniform snapshots switched off (`NX2NAVI_UBO_SNAPSHOT=0`, not the default) the GPU-write list is appended on every write and never pruned, and its linear scan slows without limit. In the default mode the list is pruned (199-250 entries at every snapshot) but the free arenas are never trimmed (3-6 arenas, 12-24 MiB measured) | Only with the switch off | suspected for the off mode; the default mode's sizes are measured and flat | Return early in `vk_usnap_drop` when snapshots are off; trim arenas idle for some submissions | None | L-29 | `3966d878`. Non-default mode only; not run in that mode. Not reproduced before, so not shown fixed. Regression: the route with the fixed exe: `p4_route` went through every segment with no FATAL and committed the save five times. Its frame rates cannot be compared with the baseline: the exe name is new and it has a pipeline cache folder of its own, so pipelines were still compiling on other threads (Kakariko 118.1 fps against 140.7; 17 frames over 25 ms in the 12 s after the reload, against 0 and 6) | +| F-3-09 | S4 | Replay (11) | `vk_exec_draw.c` `mesh_ring_entry` (~5044-5053), `mesh_count_buf` (~4990) | The allocation handles of the mesh ring (48 KiB) and the count buffer (16 KiB) are dropped, so neither is ever freed | Once per process | suspected; a fixed 64 KiB | Keep the handles and destroy them at shutdown | None | L-30 | — | +| F-3-10 | S3 | Textures (13) | `vk_texture.c` `upload` (~2336-2342 with ~2272) | When a texture's storage is released during its upload it is uploaded as zeros, but the content hash already holds the bytes from before. If the game maps the same bytes back, `same_content` matches and the upload is skipped: the texture stays zero | Storage unmapped in the middle of an upload, then mapped again with equal content | suspected (code read) | Clear `chash_ok` whenever the bytes that reached the image are not the storage's (the same change as F-3-01) | Low | — | `054bd556`. Not reproduced before, so not shown fixed. Regression: the route with the fixed exe: `p4_route` went through every segment with no FATAL and committed the save five times. Its frame rates cannot be compared with the baseline: the exe name is new and it has a pipeline cache folder of its own, so pipelines were still compiling on other threads (Kakariko 118.1 fps against 140.7; 17 frames over 25 ms in the 12 s after the reload, against 0 and 6) | +| F-3-11 | S4 | GPU memory (12) | `vk_memory.c` `refuse` (~1747) | The log quota for mirror refusals is shared by all reasons (12 lines), so allocation-failure refusals can go unlogged behind budget refusals; only the `failed` count in the `mem: mirror` line shows them | Many budget refusals before the first allocation failure | suspected (code read) | A quota per reason | None | — | `94ee6e78`. With F-3-03. Not reproduced before, so not shown fixed. Regression: the route with the fixed exe: `p4_route` went through every segment with no FATAL and committed the save five times. Its frame rates cannot be compared with the baseline: the exe name is new and it has a pipeline cache folder of its own, so pipelines were still compiling on other threads (Kakariko 118.1 fps against 140.7; 17 frames over 25 ms in the 12 s after the reload, against 0 and 6) | +| F-3-12 | S4 | Shaders (14) | `gfx_shader.c` memory cache (`buckets`, `mem_insert`) | The shader memory cache keeps every shader's SPIR-V and reflection for the life of the process, after its pipelines are built | Always | confirmed size: `shader memory cache 3564, 386.2 MiB` to `3676, 395.4 MiB` in every area, flat across the reload (section 11.3). It is bounded by the game's shaders, not growing | Drop the SPIR-V of shaders whose pipelines are all built, keeping what later variants need | Medium: a later pipeline variant would have to read the shader again from disk | L-24 | — | +| F-4-01 | S2 | Replay (11), Textures (13) | `vk_exec_draw.c` `pool_unres` (~2231-2244), `pool_sync_entries` (~2496-2510) | The list of texture pool slots that resolve to no entry grows duplicates: a slot that resolves between two walks has its flag cleared but stays listed, and when it stops resolving `pool_unres` appends it again. Every 8th pool check walks the whole list, calling the slot retry for each copy, under the texture lock. In the Market the list reaches several times the number of slots that exist, and the walk becomes a stall | Standing in the Market (adult) for about a minute. It then repeats every 8th frame; game threads registering textures wait for the lock too | confirmed (12.3): `slots without one` 134371 and 160385 in `p3_market_t1`, 115652 in `bl_market_1`, 88824 in `bl_market_2`, against 32768 slots; the walk's own timer gives about 15 ms a walk in the last window; `texture lock held over 1 ms: 7792 ms (581 holds) … max 33.61 ms` from `bind_resources`; `slow replay frames 225 … its slowest op 20.0 ms (DRAW_MESH 225)`; 375 of 380 gaps between slow frames are 8 frames. In `p3_market_t2` the list fell back to 1273 and no stall came: it depends on timing | Never list a slot twice (drop the stale entry when its flag clears, or check membership), and bound the retries per walk | Low: the walk's result is unchanged, only its length. Textures and replay only | L-44 | `015a89dc`. Before: 134371 and 160385 list entries, walks of about 15 ms, 225 frames over 25 ms standing in the Market (`p3_market_t1`). After: three runs of three (`p4_market_1` to `_3`): the list stays at 524-3192 entries and the walk at 0.008-0.026 ms per switch; standing after the pause tour no frame reaches 20 ms (worst 14.2, 17.3 and 18.3 ms at 118.5, 145.7 and 139.6 fps); the texture lock is held over 1 ms for at most 149 ms in a period (longest hold 4.34 ms), against 7792 ms (33.61 ms) before | +| F-4-02 | S3 | Upscaling (17) | `vk_dlaa.c` `evaluate` (~1645-1675), `release_kept` | A DLSS feature is created on the replaying thread the first time a render size is used, after a device idle wait when kept features are released first | The first frame of the scene after a load, the first frame of the pause menu (its own size), and each reload | confirmed with the mark added in `c85892ab`: `DLSS feature creates 23.5 ms` in the load frame, `16.4 ms` of a 22.4 ms frame at the pause menu's first frame (`p3_market_t1` frame 5663), `43.8 ms` and `44.9 ms` at the reload (`p3_route` frame 20156, `p3_route_cold` frame 18952) | Create the feature for the known sizes ahead of use (at boot or during the load), or on a worker with the previous output shown meanwhile | Medium: one more thread on the device; no gameplay change | L-47 | — | +| F-4-03 | S3 | Replay (11) | `vk_exec.c` / `vk_exec_draw.c` replay of the first frames after a load | One or two frames some 10 frames after a load's big frame take 48-95 ms. With the columns added in `df6766aa` they read as replay time and nothing else: `slow frame 2122: 95.0 ms; blocked pipeline 0.0 xlate 0.0 texture 0.0 astc 0.0 fence 0.0 pacing 0.0 drain 0.0; replay 93.6` | Every save load | confirmed that the time is the replay's; which part of it is not determined (the timed Market run's nearest frame shows 2867 draws against the usual 1250-1900, slowest single draw 8.7 ms) | Not proposed until the part is named (a timed run with `NX2NAVI_REPLAY_TIME=1` on the route) | — | L-47 | — | +| F-4-04 | S2 | GPU memory (12) | `vk_memory.c` `pool_fini` (~382-387), `pool_init` | A pool's finalize flushes the uploads and calls `vkQueueWaitIdle` under the queue lock, on a guest thread, once per used pool; the lock blocks the render thread's submits and the present for that time. Pool initialize imports and allocates on the calling thread | Area changes and boot, when the game makes and frees many pools | confirmed for the time, suspected for the idle wait as its cause: `slow frame 459: 45.8 ms; … on any thread: pool init/finalize 45.8 ms (2, 288.0 MiB, longest 43.1 ms)` and `slow frame 522: 58.5 ms; … pool init/finalize 56.7 ms (71, 94.4 MiB, longest 3.0 ms)` (`bl_route_1`). The mark does not tell initialize from finalize | Wait for the pool's last fence instead of the whole queue, without holding the queue lock | Medium: the wait must still cover uploads and a present not yet drained | L-36 | — | +| F-4-05 | S3 | Guest memory (4), GPU memory (12) | `memory.c` `lazy_drop_locked` / `lazy_piece_locked` (~474-507), `vk_memory.c` `lazy_fetch` (~2600), `mirror_evict` (~1829) | A lazily written range is fetched with a GPU copy and a wait inside the fault handler while `frz_lock` is held, which stalls every other fault, thaw and the replay's skip check for that time. `mirror_evict` does the same while holding the pool lock exclusively | A CPU read of an armed range, a file read near GPU pools, or a mirror eviction, with GPU work queued | suspected (code read); no deadlock path was found. The AMD-crash part of the lead is struck: lazy write-back is off by default on that driver | Mark the range as being fetched and drop `frz_lock` for the copy and wait | Medium: touches the piece protocol; no gameplay or save change | L-04 | — | +| F-4-06 | S3 | Device and present (16), GPU memory (12) | `gfx_present.c` `flip_locked` (~306-316); `vk_memory.c` `vk_upload_flush(1)` (~3780-3791) | The present call runs under the queue lock that `queue_submit` waits for, and a blocking upload flush waits for its fences while holding `cmd_lock`, which every upload, deferred free and the completion thread need | A present that blocks (vsync modes, frame generation); texel reads, pool finalizes and menu art uploads | suspected (code read) | Note the fence, unlock, wait, lock again; a present queue of its own where the device has one | Low for the flush; medium for the queue | L-33 | — | +| F-4-07 | S3 | Replay (11), Device and present (16) | `vk_backend.c` `submit_sync` drain (~389), `gfx_present.c` present thread (~253, ~1339-1349) | Before each submit the game's thread waits for the present thread's whole job (slot wait, acquire, menu, its empty submission). Held work can then be replayed on the present thread, which runs at normal priority off the reserved core | A blocking acquire, or held work resumed by the present thread's empty submission | suspected (code read). The wait now shows as `drain` on the slow-frame line; it was 0.0 in every slow frame of the Phase 3 runs at these settings | Replay held work only on the submitting thread, or raise the present thread's priority | Low | L-32 | — | +| F-4-08 | S3 | In-game menu (21) | `ui/menu.cpp` `menu_overlay_frame` (~1729-1740), `vk_up` (~297); `ui/menu_art.cpp` `menu_font_upload` (~198), `upload_rgba` (~160) | With the overlay menu open, the settings file is written, and fonts and art are uploaded with queue idle waits, on the present thread under the present lock, which the game's next submit waits for | Opening the overlay menu, changing a setting or the scale | suspected (code read); the audio part of the lead is struck (it runs on the audio thread, on a change only) | Save settings on a worker; batch the art uploads; retire the old font with a deferred free | None to gameplay | L-38 | — | +| F-4-09 | S3 | Input (20), Guest memory (4) | `camera_speed.c` `search_main` (~218-247) | The search for the camera speed array reads the whole guest heap, including every lazily written page, so each such piece faults and is fetched from the GPU (F-4-05) while the game runs | Changing the stick sensitivity mid-game | suspected (code read); the crash and race parts of the lead are struck (each piece is read under a hold, writes thaw first) | Skip ranges that are lazily armed | Low | L-13 | — | +| F-4-10 | S4 | Pipelines (15), Movies (19) | `vk_pipeline.c` `vk_pipeline_compute` (~4949-4960); `ov_movie2.c` `run_stripes` (~287-301) | A dispatch whose compute pipeline another thread is building polls with 1 ms sleeps and the wait is not timed as a pipeline wait; each movie picture starts and joins four threads and allocates its planes anew | A compute pipeline not built yet; movies | suspected (code read) | A condition variable and the pipeline timer; a small worker pool and reused buffers | None | L-34 | — | +| F-4-11 | S2 | Pipelines (15) | `vk_pipeline.c` `pm_set` (~4276), `vk_pipeline_prewarm_marker_clear` (~4284; called only from `boot.c` ~379 and the prebuild's end ~4223), `pm_skipped` (~4241) | `pipeline-prewarm-running.txt` exists while the boot builds the recorded pipelines, so that a driver crash there is noticed. No orderly exit clears it. A game closed during that boot build leaves it, the next start reads that as "the last start died", writes `pipeline-prewarm-skip.txt`, and from then on every start on that GPU and driver skips the prebuild: each recorded pipeline is built at its first draw, in play | Close the game window (or end the process) while the boot still builds pipelines, then start again | confirmed by an incident in the shared run folder: at 22:50 a scripted run was closed by its runner during boot (most likely this session's first `p3_market_prof` attempt, which gave way to another game then; its log was replaced by the repeat, so this is not proven), and the next start, another session's `out\gate_off`, logged `vk_pipeline: the last start died while the boot built pipelines (E:\nx2devrun/pipeline-prewarm-running.txt was left); E:\nx2devrun/pipeline-prewarm-skip.txt now skips that prebuild on this GPU and driver (10de:2b85:9b404000)`. Every later start there logs `prewarm: 4063 recorded pipelines not built ahead of play`. No driver crash had happened. The file is still there: it was not deleted, as other sessions run in that folder | Clear the marker on every orderly exit (the window close, the guest's exit, the runner's close), so only a real crash leaves it; give the skip an expiry or a retry | Low; pipelines only | — | `6c0b0b10`. Reproduced and verified with `route\prewarm_close.py` (the window closed one second after the marker appears, each exe on its own pipeline cache folder). Before the fix (`ocarina_audit_p3b.exe`, `p4_prewarm_old`): `marker seen 2.8 s after the start … after the exit the marker is LEFT`, and the next start `took the first for dead; skip file WRITTEN`. After (`ocarina_audit_fix.exe`, `p4_prewarm_fix`): `after the exit the marker is gone`, next start `no such line; skip file absent`. A process that is killed still leaves the marker, as meant | +| F-5-01 | S3 | Textures (13) | `vk_texture.c` `alias_compatible` (~2567), `start_at` → `init_new` (~2755) | A new depth image made over a live depth target's memory starts cleared unless `depth_alias` is on and both are depth-only with one format; a shadow map that starts cleared shadows everything for one frame | The known one-frame dark shadow at the Castle Town gate | suspected cause of a known problem; `NX2NAVI_DEPTH_ALIAS_LOG=1` would line the dark frame up with an alias logged as cleared. Not run (the gate is not on the route) | Carry depth content across the alias for depth-stencil pairs and partial covers too | Rendering behaviour: needs the user's eye on the result | — | — | +| F-5-02 | S2 | GPU memory (12) | `vk_memory.c` shadow storage (`shadow_sync_pool` ~1248, default on for the Linux build ~1676) | On the Linux build CPU-written pools reach the GPU through a per-submission snapshot; a write made after the snapshot goes with the next submission, so per-frame instance data can be one frame behind the buffers around it | The known foliage flicker on Linux with an AMD card | suspected cause of a known problem; cannot be run here (no Linux machine, no AMD card). `NX2NAVI_SHADOW=0` on that machine would tell this from the shader-side suspects in `docs/maxwell.md` | Depends on that test | — | — | — | +| F-6-01 | S3 | In-game menu (21) | `menu_assets.c` `dicts_load` (~56-73, callers ~92, ~125) | The dictionaries are loaded lazily with no lock, and `ndicts` is set to 0 before the load: a second caller meanwhile sees "loaded, none" and gets nothing. The menu's fonts then fall back for the whole run, as the font read is tried once | The "menu-art" thread and the present path both asking during the first frames | suspected (code read). Not reproduced: 54 of 54 logs here show `menu: the game's interface fonts: text ClarimoUDPE, titles CetraDisplayPro` | Load once behind a `plat_once` | None | L-14 | `b4bfb7b6`. Not reproduced before (54 of 54 logs had the game's fonts). The fixed exe's runs show the game's fonts too. Not reproduced before, so not shown fixed. Regression: the route with the fixed exe: `p4_route` went through every segment with no FATAL and committed the save five times. Its frame rates cannot be compared with the baseline: the exe name is new and it has a pipeline cache folder of its own, so pipelines were still compiling on other threads (Kakariko 118.1 fps against 140.7; 17 frames over 25 ms in the 12 s after the reload, against 0 and 6) | +| F-6-02 | S3 | Launcher | `launcher/ui/app.py` `play_only` (~2175-2196) against `watch_game` (~1387-1399) | Started from the launcher, a fatal exit (codes 70, 71) shows the game's FATAL line; started from the Steam shortcut the launcher only logs the exit code, and the runtime raises no message itself: the window disappears | Any fatal exit of a game started from the shortcut, F-1-01 included | suspected (code re-read by the auditor) | Show the last FATAL line on codes 70 and 71 in `play_only` as well | Launcher only | — | — | +| F-6-03 | S4 | Settings (8) | `nvn_api_obj.c` `nvnWindowAcquireTexture` (~833), `perf.c` `rt_knob` | `NX2NAVI_ACQUIRE_WAIT` is read with `rt_knob`, which maps every value but "0" and "ab" to 1 and "ab" to 2: the documented mode 2 cannot be chosen, and "ab" selects it instead of alternating | Setting the key to 2 or ab | suspected (code read); a diagnostics switch | Read it as a number | None | — | `4b47a10a`. The value 2 was not run. Not reproduced before, so not shown fixed. Regression: the route with the fixed exe: `p4_route` went through every segment with no FATAL and committed the save five times. Its frame rates cannot be compared with the baseline: the exe name is new and it has a pipeline cache folder of its own, so pipelines were still compiling on other threads (Kakariko 118.1 fps against 140.7; 17 frames over 25 ms in the 12 s after the reload, against 0 and 6) | +| F-7-01 | S3 | NVN front end (10), Replay (11) | `nvn_api_core.c` `nvnQueueSubmitCommands` (~670-677, `NX2NAVI_SUBMIT_FINISH`, default mask 1), `nvn_api_obj.c` `nvnWindowAcquireTexture` (~832-843, `NX2NAVI_ACQUIRE_WAIT`) | Every frame the game's thread waits for the GPU to run the frame's first submission, and again at the acquire for the image's last present. While the GPU is ahead the waits are short; when the GPU is the slower side they make the CPU frame wait for it | Every frame; the cost should grow at high frame rates or with a loaded GPU | suspected; not determined. The A/B was started and is not valid: the run folder's pipeline state changed under it (F-4-11) and three of its runs lost the device (F-1-11). The one finished pair reads 99.9 fps with the waits and 121.1 without the submit wait in the day field, but the first run also carried more background pipeline builds. The comments say the submit wait prevents white frames in dialogue (3 % of frames without it) and the acquire wait is mostly covered by it | Depends on a valid A/B: drop the acquire wait when the submit wait is on, or wait on the passes' timeline | Changes when frames are drawn against the game's data rewrites (the white-frame case): ask the user first | L-31 | — | +| F-7-02 | S3 | Replay (11) | `vk_rec.c` `rec_begin` (~175), `rec_main` (~63); `vk_exec.c` `rec_claim` (~1650) | The recorder thread takes the priority of the thread that made the first submission and keeps it; later only the recording thread is raised and given the reserved core. The recorder then competes with some 85 guest threads, and the recording thread waits for it at the end of every part | Any load on the other cores | suspected (code read). The drains are measured: `recorder ring full 0 ms, drains 443 ms` over 49 s in `p3_market_t1`, about 0.07 ms a frame, so the cost was small on this PC | Raise the recorder's priority in `rec_claim` | Low | L-39 | — | +| F-7-03 | S3 | Textures (13) | `vk_texture.c` `sweep_pressure` (~2021), `evict_idle` (~1716), `evict_disused` (~1871) | Under VRAM or commit pressure, every 8th submission the eviction scans walk the whole texture table under the texture lock; a scan that finds nothing does not back off, so it repeats for as long as the pressure lasts | VRAM over 80 % of the budget, or the process's commit over its bound (installed RAM, at least 24 GiB; the baseline's private bytes reach 25.8 GiB) | suspected for the cost; the capped run planned for it was not done | Back off after an empty scan, or keep an order of use | Low | L-35 | — | +| F-7-04 | S4 | Diagnostics (22) | `nvn_api_obj.c` `nvnWindowAcquireTexture` (~839-841), `vk_sync.c` `vk_sync_fence_wait` | The acquire's GPU wait is counted as a fence wait and again as pacing, so the frame-time summary counts it twice and a frame bound by the GPU at the acquire reads as "pace" | Any frame that waits at the acquire | suspected (code read); diagnostics only | Count it once | None | — | — | +| F-8-01 | S2 | GPU memory (12), Textures (13) | `vk_memory.c` `gen_now` (~748), handed out in `vk_mem_changed` (~836) and nine other places; compared in `vk_mem_changed` (~848), `vk_mem_changed_snap` (~923); `DIRTY_UNSYNCED` = `UINT32_MAX` (~991) | The page write generation is a 32-bit counter with no handling of its wrap. After it wraps, new writes compare as older than everything, so CPU-written textures and mirrored pools stop being uploaded again (stale or wrong textures), and pages stamped before the wrap compare as always changed. 0 ("never stamped") and `UINT32_MAX` ("not scanned") are also handed out as real values at the wrap | One long session. The rate decides how long: an estimate from the code is 200-1000 generations a frame, which is 5 to 50 hours | suspected (the counter and the sentinel re-read by the auditor). The rate is not measured: `587e8494` adds it to the `mem: sizes` lines and `ocarina_audit_p3b.exe` is built with it, but no run was made before Phase 3 was stopped | Make the generations 64-bit | Crosses subsystems 12 and 13 (the tables and every compare): ask the user first. No gameplay or save change | — | — | +| F-8-02 | S1 | Save data (7), Settings and logging (8) | `main.c` `crash_handler` (~271-320), `dispatch.c` `rt_fatal` (~60-82), `fs_host.c` `save_commit` (~601-621) | The game's Commit returns once the commit is queued; a thread then copies and swaps (95-135 ms). The crash and fatal paths end the process without waiting for it. A crash inside that window leaves an unfinished copy, which the next start rolls back: the player loses a save the game reported as done | A crash or fatal within about a tenth of a second after a save | suspected (code re-read: `fs_save_flush` is called from the three normal exits only). The roll-back itself is confirmed safe (12.3) | Wait a bounded time for the pending commit in both paths, unless the crashing thread is the commit thread | Save path only; the format is unchanged | L-03 | `cd170dad`. Not reproduced before (a crash within a tenth of a second of a save). The new wait did not run in any run: no crash fell into a commit. `--probe-fs` and `tests\save_share_check.py` pass with the change | +| F-8-03 | S3 | Input (20) | `input.c` `pad_read` (~817-832), `sdl_enter` (~481) | While SDL searches for devices (a pad pulled, a wireless pad asleep) every poll returns the last state read before, so buttons and stick held at that moment stay held for the search's length (120-240 ms per device notification, longer with a slow driver) | Unplugging the controller while moving | suspected (code read); cannot be run here (no hand on the controller) | Stop replaying the last state after about 150 ms without a fresh read | Input only | — | — | +| F-8-04 | S3 | Input (20), In-game menu (21) | `ov_input.c` `npad_states` (~82-98) | The game is always told one controller is connected. A disconnect becomes "nothing pressed" and play goes on uncontrolled; the console would ask for a controller | A controller disconnect in play | suspected (code read) | Open the in-game menu when the primary pad goes away | Changes what the player sees on a disconnect (behaviour): ask the user first | — | — | +| F-8-05 | S3 | Frame pacing (9) | `dynres.c` `dynres_read` (~51-54) | Dynamic resolution's default target is 16.7 ms whatever the frame limit, and a step is held for 45 frames, not for a time: at a 120 limit it reacts only once the rate has fallen to about 55, and at 240 fps the resolution can change five times a second | `NX2NAVI_DYN_RES=1` (off by default, not in the menu) above a 60 limit | suspected (code read) | Derive the default target from the limit; hold steps for a time | None to gameplay | L-42 | — | +| F-8-06 | S3 | Input (20) | `input.c` `shake_stick` (~706-722) | The shake key swings the stick on a wall-clock period (two frames at 30 fps), so at 120 or 240 fps each side lasts 8 or 16 game frames; a game check that counts swings in frames could miss them | The shake key at a high frame limit | suspected; not determined (needs a fused item and the key at 30, 120 and 240) | Count game steps instead of time | Input timing: ask the user first | L-42 | — | +| F-8-07 | S3 | Frame pacing (9), Movies (19) | `frame_rate.c` `movie_cap_hz` (~194-209), `ov_movie2.c` `set_live` (~590, ~740) | The limit is held at 60 while a movie decoder is live, by design. A movie skipped without its end-of-stream picture or a Finalize would leave the decoder live and the game capped at 60 in play | Skipping a movie at a limit above 60 | suspected; not determined (no movie on the route) | End the cap when the decoder has had no sample for a time | Low | L-42 | — | + +--- + +## 9. What was reviewed + +Phase 1 read code to map it. It reviewed nothing for bugs. + +The map was made in this session by one auditor with four read-only mapping passes run in parallel: + +1. kernel, memory, save, settings and system services; +2. audio, input, movies, menu and diagnostics; +3. graphics threads and locks; +4. graphics allocators and caches. + +The auditor read the frame path directly and checked the items marked "verified" in section 6. The rest of the +mapping passes' statements are cited to file and function, not re-checked line by line. Phase 3 should treat them as +leads. + +### Read fully + +**By the auditor** +- `docs/architecture.md`, `docs/building.md`, `docs/maxwell.md`, `docs/launcher.md`, `AGENTS.md`. +- `platform/platform.h`. +- Read fully in the path's functions: + - `vk_backend.c` 40-450 and 537-636; + - `vk_sync.c` 50-190 and 370-649; + - `vk_exec.c` `walk`, `rec_claim`, `vk_exec_record` (1532-1771); + - `vk_exec_draw.c` `prepare_draw_ex` (3856-4073); + - `gfx_present.c` 300-354 and 1300-1610; + - `nvn_api_core.c` 600-697; + - `nvn_api_obj.c` 755-880. + +**By the mapping passes** +- `kernel.c`, `kernel.h`, `svc.c`, `dispatch.c`, `memory.c`, `fs_host.c`, `save_share.c`, `logq.c`, `boot.c`, + `main.c`, `hostfn.c`, `guest_setjmp.c`, `patches.c`, `platform/common.c`, `platform/win32.c` 1-1717. +- `audren.c`, `audren.h`, `audio_mixer.c`, `audio_capture.c`, `ov_audio_input.c`, `ov_movie.c`, `ov_movie2.c`, + `ov_media.c`, `movie.h`, `menu_sound.c`, `frame_rate.c`. +- `input.c`, `ov_input.c`, `input_win.c`, `input_sdl.c`, `input_ds3.c`, `input_ds3_win.c`, `motion_fusion.c`, + `mouse_direct.c`, `camera_speed.c`. +- `discord_rpc.c`, `rtss_limit.c`, `perfmon.c`, `perf.c`, `prof_win.c`, `flight.c`, `tex_astc_mt.c`, `dynres.c`, + `menu_cursor.c`. +- `gfx_window_win.c`, `gfx_window_sdl.c`, `folder_pick_win.cpp`, `ui/menu_art.cpp`, `ui/menu_win.cpp`. +- `vk_backend.c`, `vk_rec.c`, `vk_rec.h`, `vk_sync.c`, `vk_headroom.c`, `vk_vma.cpp`. +- `vk_usnap.c` (all but ~141-224). + +### Read in sections, with searches for threads, locks, allocations and caches + +**Large graphics files** +- `vk_memory.c`, `vk_texture.c`, `vk_pipeline.c`, `gfx_shader.c`. +- `vk_exec.c`, `vk_exec_draw.c`, `vk_exec_xfer.c`. +- `gfx_present.c` (1-490, 660-1676). + +**Other graphics and front-end files** +- `vk_device.c`, `vk_astc.c`, `vk_gpa.c`, `vk_vaddr.c`, `vk_dump.c`, `vk_dlaa.c`, `vk_fsr.c`, `vk_dlssg.c`, + `vk_fg.cpp`, `dlssg/nx2_sl.cpp`. +- `nvn_api_cmd.c`, `nvn_api_obj.c`, `nvn_api_core.c`, `nvn_procs.c`, `ov_gfx.c`. + +**CPU-side files** +- `ipc.c`, `romfs.c`, `cfg.c`, `ov_zstd.c` (not `decode()`), `ov_system.c`, `net_offline.c`, `amiibo.c`, `nfp.c`, + `swkbd.c`, `swkbd_win.c`, `cheats.c`, `mods.c`, `loader.c`. +- `ui/menu.cpp`, `menu_assets.c`, `resolution.c`, `ui_text.c`, `audio_effects.c`, `ui/amiibo_page.cpp`. + +### Searched only + +- `restbl.c`, `save_zip.c`, `input_map.c`, `audio_reverb.c`, `sysinfo.c`. +- `ui/perf_panel.cpp`, `ui/cheats_tab.cpp`. +- `vk_ffx.cpp`, `vk_hdr.c`, `vk_tonemap.c`, `vk_crumbs.c`. +- `nvn_tex.c`, `tex_astc.c`, `tex_deswizzle.c`. +- `platform/win32.c` 1717-2166 (load counters, child processes, IPC, restart). +- The header comment only, for the subsystem map: `vk_caps.c`, `vk_color.c`, `vk_contact.c`, `vk_mvcheck.c`, + `vk_mvprev.c`, `vk_mvsurvey.c`, `rdoc.c`, `nvn_ext.c`, `gfx_shader_guess.c`, `gfx_null.c`, `widescreen.c`. + +### Not opened + +**Runtime** +- `platform/linux.c` beyond the thread-creation search, and `platform/fp_x86.h`. +- `vk_formats.c` beyond its header, `fma.c`, `sha256.c`, `folder_pick_sdl.c`, `swkbd_sdl.c`, `input_sdl.h` and the + other headers not named above. +- `ui/binds_page.cpp`, `ui/option_rows.cpp`, `ui/menu_skin.cpp`, `ui/menu_sdl.cpp`. +- Every `*_probe.c` (probe modes only). +- `runtime/third_party/`, `runtime/shaders/`. + +**Outside the runtime** +- `recomp/` (the generator itself). +- The generated C (by the audit's rule). +- `launcher/`, `installer/`, `tools/`, beyond `tools/make_game.py` (searched for the app pool) and `tools/build_game.py` + (searched). +- `tests/`. +- `tools/xlate/` (the translator lowering and its patches). + +### Phase 3 coverage + +| Pass | Status | +|---|---| +| 1 Crashes and memory safety | leads done; F-1-01 traced; F-1-11 found and open | +| 2 Threading and races | leads done; overlapping submits confirmed by a run | +| 3 Memory and VRAM budget | leads done by reading; the capped run not done | +| 4 Shader stutter and hitching | leads done; three confirmed by runs | +| 5 Rendering correctness | the three known problems' suspected causes only; nothing run | +| 6 UI | the menu read for clear bugs only; nothing run | +| 7 Performance | leads done by reading; the L-31 A/B not valid yet | +| 8 Edge cases | save atomicity confirmed by the probe; the rest by reading; nothing else run | + +**What Phase 3 reviewed for bugs.** It read the code each lead cites, in these files, and no further: + +- Passes 1 and 2: `memory.c`, `vk_memory.c`, `vk_sync.c`, `vk_backend.c`, `vk_exec.c`, `nvn_api_core.c`, `nvn_api_obj.c`, + `nvn_api_cmd.c`, `guest_setjmp.c`, `kernel.c`, `ov_zstd.c`, `ipc.c`, `menu_assets.c`, `camera_speed.c`, `ov_movie.c`, + `ov_movie2.c`, `frame_rate.c`, `cfg.c`, `vk_pipeline.c`, `vk_texture.c`, `audren.c`, `audio_mixer.c`, + `platform/win32.c`, `fs_host.c` (the save transaction, read fully by the auditor). +- Pass 3: `vk_texture.c`, `vk_astc.c`, `vk_memory.c`, `vk_headroom.c`, `vk_usnap.c`, `vk_exec_draw.c` (the pool refresh + and stand-ins), `audio_mixer.c`, `ipc.c`, `net_offline.c`, `platform/win32.c`. +- Passes 4 and 7: `nvn_api_core.c`, `nvn_api_obj.c`, `vk_sync.c`, `vk_backend.c`, `gfx_present.c`, `vk_memory.c`, + `vk_texture.c`, `vk_exec_draw.c`, `vk_rec.c`, `vk_pipeline.c`, `vk_dlaa.c`, `boot.c`, `ui/menu.cpp`, + `ui/menu_art.cpp`, `ov_movie2.c`, `input.c`, `prof_win.c`, `perf.c`. +- Passes 5, 6 and 8: `input.c`, `ov_input.c`, `dynres.c`, `resolution.c`, `frame_rate.c`, `mouse_direct.c`, `main.c`, + `dispatch.c`, `ui/*.cpp`, `menu_assets.c`, `launcher/ui/app.py` (the two exit paths only), and for the known + rendering problems `vk_texture.c` (aliasing) and `vk_memory.c` (shadow storage). + +Still not reviewed for bugs: everything section 9 lists as "not opened", `recomp/`, the generated C, the translator, +and in the files above everything outside the functions the leads cite. + +--- + +## 10. Not determined in Phase 1 + +**Threads and synchronisation** +- Whether the game submits and presents from the same guest thread. Several sync-mode leads (L-16) depend on it. The + log line "vk: thread N is the recording thread" and a thread trace in Phase 2 would answer it. +- The threads inside the GPU driver, Streamline/NGX, FidelityFX, SDL, libvpx and dav1d, and what they touch of ours. +- What `plat_cpu_reserve` leaves for the recorder and pipeline threads on the reference PC. +- Which caller thread runs `tex_astc_mt.c`'s first large decode, `dynres_override`, `cheats_frame`, and + `rt_fatal_note_add`. + +**Version and platform** +- Which of the 1.4.3-specific files (`mouse_direct.c`, `menu_cursor.c`, `ov_zstd.c` patch set `zstd`) are active on + 1.1.1. +- Whether the Windows ASan runtime's shadow memory fits beside the fixed guest reservations, and whether TSan on Linux + accepts them (section 1). + +**Memory** +- Real sizes in play: how large the shader memory cache, the pipeline tables, the sampler cache, the lazy write-back + segment list and the deferred-destruction list get in a multi-hour session. + - Phase 2 now logs them (`mem: sizes`) and measured them over runs of up to 10 minutes (section 11.3): shader memory + cache about 3600 entries, 390 MiB; 3260-3360 pipelines; 175-178 samplers; 84-144 lazy ranges; 0-4 deferred + destructions at the snapshots. + - Multi-hour growth is still not measured. +- What the front end does when `vk_pool_init` fails for a physical pool. + +--- + +## 11. Phase 2: baseline and instrumentation + +Phase 2 was done on branch `claude/audit-phase2-a12eef`, cut from `audit` at `cc179d1d`. It added instrumentation in three +commits and fixed nothing. All the runs were on the reference PC (RTX 5090, driver 621.01), with the runtime of this +branch over the lifted game in `work\lift-pickup`, run from `E:\nx2devrun`. + +**The three instrumentation commits.** Each one built and each was shown working by a run. Each costs nothing while +`NX2NAVI_TRACE=perf` is off: a call and a branch per marked site; the size, scene and segment code runs only with the +trace. + +| Commit | What it adds | Shown working by | +|---|---|---| +| `c1ed77e4` (c1) | Work marks on any thread (`host.h` `PERF_M_*`, `perf.c` `perf_mark_add`): RomFS reads, zstd decodes, pipeline creates, guest memory maps, pool initialize/finalize, device memory allocations; named on the slow-frame line and per 60-frame window | `E:\nx2devrun\out\audit\c1_check` (exe `ocarina_audit_c1.exe`), Kakariko route | +| `d49a4dea` (c2) | Route segments (input-script `MARK`, `perf.c` `perf_segment`) with mean, 1% low and worst frame, RAM and VRAM; scene lines from area loads (`romfs.c` `scene_note`, `perf.c` `perf_scene`) with a memory snapshot once settled | `c2_check` (`ocarina_audit_c2.exe`), `mark_check.txt` | +| `3a88b363` (c3) | `mem: sizes` lines: entries and bytes of the caches, pools and tables (sixteen `*_sizes` functions, `perf.c` `sizes_log`), every 600 presents and with every snapshot | `probe_u0` (`ocarina_audit_c3.exe`) | + +Log lines from those runs: + +``` +c1: perf: slow frame 2186: 430.8 ms; blocked pipeline 0.0 xlate 0.0 texture 154.6 astc 26.4 fence 0.0 pacing 0.0; on any + thread: file reads 96.0 ms (597, 97.1 MiB, longest 0.7 ms), zstd decodes 404.2 ms (600, 336.3 MiB, longest 5.9 ms), + pipeline creates 3070.9 ms (25, 0.0 MiB, longest 463.9 ms), guest memory maps 0.1 ms (1, 5.0 MiB, longest 0.1 ms), + device memory allocations 99 (5464.9 MiB) +c1: perf: frame 120: work in the window; on any thread: file reads 0.0 ms (1, 0.0 MiB, longest 0.0 ms), pipeline creates + 2118.5 ms (17, 0.0 MiB, longest 342.6 ms), guest memory maps 0.0 ms (1, 0.0 MiB, longest 0.0 ms), pool init/finalize + 179.7 ms (33, 85.0 MiB, longest 16.1 ms), device memory allocations 1 (64.0 MiB) +c2: segment: 'kakariko-walk' frames 2264-4634, world 1.0-25.0 s: 2370 frames in 24.0 s, mean 10.11 ms (98.9 fps), 1% low + 47.2 fps (21.20 ms), worst 43.3 ms at frame 3491; over 25 ms 10, 50 ms 0, 100 ms 0; ram working set 11612 MiB, private + 23683 MiB; vram 8999 of 31419 MiB; on any thread: file reads 304.5 ms (981, 145.4 MiB, longest 10.0 ms), … +c2: scene: KakarikoVillage_Adult, HyruleField_Adult settled (no area loaded for 10 s) at frame 2812, world 7.6 s; ram + working set 11120 MiB, private 20721 MiB; vram 6650 of 31419 MiB +c3: mem: sizes frame 4200, pipelines and shaders: pipeline entries 3229; with a pipeline 2791; fast links 0; pipeline + failures 0; pipeline layouts 1249; … pipeline jobs queued or running 438; pipeline keys seen 3259, 0.1 MiB; shader + memory cache 3531, 384.4 MiB; of it reflection 7.4 MiB; failed shader keys 0/4096; … +c3: mem: sizes frame 4200, GPU memory and textures: pool records 4428; of them physical 1; VRAM mirrors 546, 744.6 MiB; … + textures 6334; released textures 58, 6.6 MiB; … texture pool slots 32512/32768; sampler slots 242/4096; +``` + +The c2 run printed the world clock before it starts as `-0.0`; c3 prints `-`. + +The c1 and c2 runs are each the first run of a new exe name, so they ran with a cold driver cache. Their large +pipeline-create sums come from that. In the warm baseline runs, `pipeline jobs queued or running` is 0 by the end of +the first area. + +**Running the instrumentation.** + +- `NX2NAVI_TRACE=perf`, plus `NX2NAVI_PERF_SLOW_MS=25` for a line per frame of 25 ms or more. +- A script line `@ MARK ` names the route's segments. +- `NX2NAVI_TEXUP_LOG_MS=16` adds the texture work per slow frame. +- The dev folder's `nx2navi.ini` sets `perf_overlay = full`. Every run here (the earlier ones as well) took the + overlay's counts and GPU timestamps. + +### 11.1 Instrumentation map + +Every line below is written only with `NX2NAVI_TRACE=perf` unless the row says "always". "Added" names the Phase 2 +commit; the rest existed at `ed36773d`. + +**Frame-time markers (what a hitch waited for)** + +| Marker the prompt asks for | Log line | Written by | State | +|---|---|---|---| +| Frame time per frame window | `perf: frame N: interval avg … max … (… fps)`, every 60 presents | `perf.c` `perf_present` | existed | +| Frame time over a period | `frametime: 60 s|exit: … mean … fps, 1% low … fps, over 25/50/100 ms`, worst frames with their waits (always) | `perf.c` `ft_report` | existed | +| Frame time per route segment (mean, 1% low, worst) | `segment: '' frames a-b, world …: … mean … ms (… fps), 1% low … fps (… ms), worst … ms at frame …; …; ram …; vram …` | `perf.c` `seg_close` | added (c2) | +| A hitch with its causes | `perf: slow frame N: … ms; blocked pipeline … xlate … texture … astc … fence … pacing …` (frames ≥ `NX2NAVI_PERF_SLOW_MS`, default 50) | `perf.c` `perf_present` | existed (render-thread waits) | +| Pipeline creation on the render thread | `blocked pipeline` in the two lines above | `vk_pipeline.c` → `perf_end(PERF_PIPE)` | existed | +| Pipeline creation on any thread | `; on any thread: … pipeline creates X ms (n, …, longest Y ms)` on the slow-frame line, and `perf: frame N: work in the window; on any thread: …` every 60 presents | `vk_pipeline.c` `pipe_create_in` → `perf.c` `perf_mark_add` | added (c1) | +| Shader translation | `xlate` / `shader xlate` in the perf lines; `shader disk reads` | `gfx_shader.c` → `perf_end(PERF_XLATE)` | existed | +| Texture decode and upload | `texture` / `astc` in the perf lines; `texup: frame N: …` per frame over `NX2NAVI_TEXUP_LOG_MS` (creation, uploads, staging, storage copy, ASTC record, flush, new device memory) | `vk_texture.c` `vk_texstat_frame` | existed | +| File IO | `file reads X ms (n, MiB, longest)` in the any-thread part | `romfs.c` `romfs_read` | added (c1) | +| File IO, which files | `fs rom ` per RomFS open (`NX2NAVI_TRACE=fs`) | `romfs.c` `fs_trace` | existed (opens only, no time) | +| Decompression | `zstd decodes X ms (n, MiB out, longest)` in the any-thread part; `zstd: N calls on the host …` running totals (always, every 16384 calls) | `ov_zstd.c` `tracked_decode`, `stream_run`; `count` | added (c1) / existed | +| Large allocations, guest side | `guest memory maps X ms (n, MiB)`: SetHeapSize, Map/UnmapPhysicalMemory | `memory.c` `mem_set_heap_size`, `alias_map` | added (c1) | +| Large allocations, GPU pools | `pool init/finalize X ms (n, MiB)`: NVN memory pool initialize and finalize with their imports, device memory, mirror retire and GPU waits | `vk_memory.c` `vk_pool_init`, `vk_pool_fini` | added (c1) | +| Large allocations, device memory | `device memory allocations n (MiB)`: every block and dedicated allocation VMA makes (no time; only while the headroom callback is installed, `NX2NAVI_VRAM_HEADROOM` default on) | `vk_headroom.c` `on_allocate` | added (c1) | +| Large allocations, host heap | — | — | **missing**: there is no single funnel for the host's `malloc`; the big host allocations are named in section 5 instead | +| GPU time and who bounds the frame | `perf: frame N: gpu avg … ; fence wait …; vram …; ram working set …, private …; bound: cpu|gpu|pace` | `perf.c` `perf_gpu_line` | existed | +| Per-thread samples of a slow frame | `prof: slow frame N (… ms) -> ` (`NX2NAVI_PROFILE`, `NX2NAVI_PROFILE_SLOW`) | `prof_win.c` | existed (changes timing: not for the baseline, L-41) | +| Per-frame record of any run part | `NX2NAVI_FLIGHT=1` dumps (`frames.tsv`) | `flight.c` | existed | +| Scene transitions | `scene: loads (frame, world)`; `scene: settled (no area loaded for 10 s) …; ram …; vram …` followed by the memory snapshot | `romfs.c` `scene_note` → `perf.c` `perf_scene`, `seg_frame` | added (c2) | +| Route segments | input script line ` MARK ` or `@ MARK `; `segment: '' starts at frame …` | `input.c` `script_apply` → `perf.c` `perf_segment` | added (c2) | + +**Memory figures** + +| Figure the prompt asks for | Log line | Written by | State | +|---|---|---|---| +| Process RAM | `ram working set … MiB, private … MiB` in `perf: frame N: gpu …` (every 60 presents) and in every `segment:` and `scene: … settled` line | `perf.c` `perf_gpu_line`, `mem_text` | existed / added (c2) | +| GPU memory | `vram U of B MiB` (driver budget figure, all processes) in the same lines; `mem: vram frame N: …`, `mem: vram by use frame N: …` (textures, released textures, mirrors, physical pools, ASTC scratch, headroom spare, other, free inside VMA blocks, outside VMA incl. swapchain/DLSS/pipelines/driver), heap lines, `mem: pools frame N` | `vk_memory.c` `vram_log`, `vram_use_log`, `heap_log`, `pool_census_log` | existed (every 600 presents) | +| Sampled per scene and after every scene transition | `scene: settled (no area loaded for 10 s) at frame …; ram …; vram …` followed by the `mem: vram…` lines and the four `mem: sizes` lines; and the same snapshot at every segment's end | `perf.c` `seg_frame`, `seg_close` → `mem_snapshot` → `vk_memory.c` `vk_mem_snapshot`, `perf.c` `sizes_log` | added (c2, c3) | +| Size of each cache and pool | `mem: sizes frame N, : name count[/limit][, MiB]; …` in four groups, every 600 presents and with each snapshot | `perf.c` `sizes_log`, `perf_size`; one `*_sizes` function per subsystem (`memory.c`, `kernel.c`, `guest_setjmp.c`, `fs_host.c`, `romfs.c`, `ov_zstd.c`, `cfg.c`, `vk_memory.c`, `vk_gpa.c`, `vk_texture.c`, `vk_exec_draw.c`, `vk_sync.c`, `vk_usnap.c`, `nvn_api_cmd.c`, `vk_pipeline.c`, `gfx_shader.c`) | added (c3) | +| Commit census (where committed memory lies) | `mem: commit census at frame …` | `prof_win.c` (`NX2NAVI_MEM_CENSUS=1`; it stalls frames by 65-240 ms, so not in the baseline) | existed | + +**Section 5's pools and caches against the figures.** By the numbers of section 5: + +- *A figure existed before Phase 2:* 60 (census by kind), 61 mirrors, 66 shadow storage (`shadow_log`), 73 deferred + destructions (count, "releases pending"), 74 headroom spare, 76 VMA blocks and heaps, 77 texture cache bytes (live and + released), 84 ASTC scratch, 110 DLSS memory (as DLSS reports it), 123 shader memory cache (count only, "shaders: N keys" + in the perf line), 129 the driver's share (only as "outside VMA"). +- *Added in Phase 2 (c3):* 2 guest heap and physical maps, 3 kernel region used and committed, 4 moved stacks, 5 lazy + write-back ranges (count and the array's room), 7/8 guest threads, 9 handles, 10 fibers, 11 system events, 16 setjmp + buffers, 21 settings and the replaced values kept, 23 RomFS handles, 25 zstd dictionaries, 26 zstd stream slots, 28/29 + save files and listings open, 60 pool records, 67 write-back snapshot pool, 69 upload batches, 70 staging cache, 72 free + staging arena chunks, 75 device address records and blocks, 77 texture count, 78 disuse holds, 79 image requirements, + 80 reuse keys, 81 texture and sampler slots, 82 samplers, 87 image views, 86 spare descriptor pools and transient chunks, + 92 held continuations, 93/100 completion queue, 96 free uniform snapshot arenas, 97 uniform snapshot GPU writes, 99 + command buffer slots, 103 recording-buffer pool, 104 texture pins and the sweep queue, 105 recording copies and zombies, + 114 pipeline entries, built pipelines and fast links, 115 layouts, 116 stage libraries, 117 library and pipeline job + queues, 120 pipeline keys seen, 123 shader memory cache bytes (SPIR-V and reflection), 125 failed shader keys, 127 + translation and load queues, 128 translator processes. +- *Still no size figure:* fixed-size or static tables that cannot grow (1, 6, 13-15, 17, 20, 52, 55-57, 64, 68, 85, 88-90, + 98, 101, 112); transient per-call buffers (30, 32, 63); off by default or debug only (24, 58, 102, 111, 113, 119); on disk + (19, 31, 118, 121, 126); and these that can grow and have no figure: 12 events, 22 per-thread settings memo, 27 + per-thread zstd contexts, 33 mods, 34 cheats, 35 IPC sessions and domain objects (L-25), 36 offline socket events + (L-25), 37/38 message queues, 39 per-thread handles (L-26), 40-47 audio tables, rings and change events (L-25), 48-50 + movie and Opus decoders, 51 input script, 53/54 menu art and dictionaries, 59 camera-speed copies, 62 mirror retry + state, 65 page-generation tables, 71 the staging VMA pool's blocks, 73 the bytes of the deferred destructions, 83 + failed-create ring, 86 live per-command-buffer chunks and pools, 91 BC stand-ins, 94 pending reports, 95 occlusion + queries, 96 uniform snapshot arenas in use, 106 live-texture copies, 107 GVA ranges, 108/109 swapchain, HDR, FSR and + tonemap targets (counted only inside "outside VMA"), 122 the large-compute builder's cache, 124 shader use records. + +### 11.2 Test route and coverage + +Everything the route uses lives outside the repository, under `E:\nx2devrun\out\audit`: + +- `route\make_scripts.py` writes the input scripts: `route\route_full.txt` and `route\scene_.txt`. +- `route\baseline.sh` is the batch. It drives `route\arun.sh`, a wrapper around the stripes runner that waits while any other + game runs. +- `route\baseline_table.py` reads the logs into the tables below. +- `saves\` holds the save folders, copied (read only) from the user's save (`E:\nx2fix\profile-user\save\`) and + from the test install's profile (`E:\NX2navi-060b\game\profile\save\`): + - `u0`-`u5` and `d0`-`d5` are the whole folder with slot *k* copied into slot 0. + - `one_u` and `one_d` hold slot *k* alone. +- `probes\` holds the probes that found where each save loads, and the menu explorations. +- Each run's log and screenshots are in `\`. + +**How the game is driven.** + +- The Load screen lists the saves newest first. The title's A presses take the top one. +- DPAD presses in the list are lost while it fades in. So each area is reached with a folder that holds one slot. +- The pause menu: + - opens on Items; + - L and R move across Collection, Equipment, Items and System; MINUS opens the map. + - System lists Save, Load, Options, Special Actions and Title Screen. Its column moves with the left stick, not the + DPAD. + - Save opens a dialog with Cancel focused. A "Saved." notice takes one A press of its own. +- The world clock (`frame_rate.c` `world_clock`) starts at the first load and never resets. So one timed script runs + through a return to the title and a reload. +- An area is seen through RomFS opens. A reload that finds the area still in the game's own cache opens nothing, and + logs no `scene:` line. +- The title screen's backdrop loads `Market_Adult` (and `HyruleField_Adult`) by itself. Every "scene" line before the + first save loads is the title's, not the save's. + +**Where each save loads** (probe runs `probe_`, scene lines and screenshots): + +| Save | Area (scene lines, then the screenshot) | +|---|---| +| user slot 0 | Hyrule Field at night, before the Market's gate (`HyruleField_Adult`, `Market_Adult`) | +| user slot 1 | Market, adult (ruined, fog) | +| user slot 2 | Kakariko Village by the graveyard path (`KakarikoVillage_Adult`, `Graveyard_Adult`) | +| user slot 3 | Hyrule Field by day (`HyruleField_Adult`, `KakarikoVillage_Adult`) | +| user slot 4 | Market, adult, at night | +| user slot 5 (`townsave`) | Kakariko Village, at the gate | +| test slot 0 | Death Mountain Trail (`DeathMountainTrail_Adult`) | +| test slot 1 | Kokiri Forest, child, 3 hearts. **Loading it crashes** (F-1-01) | +| test slots 2, 4 | Hyrule Field at night, by the Market | +| test slot 3 | Market, adult | +| test slot 5 | Kakariko Village, at the gate | + +**Coverage of the prompt's route** + +| Route step | Covered | How | +|---|---|---| +| Boot | yes | Every run: segment `boot` (first present to the script's first MARK) | +| File select | yes | Segment `title` (title, Continue, Load list, Load) | +| Kokiri Forest | **no** | The only Kokiri Forest save crashes when it loads (F-1-01). No other save is a child save, and scripted travel there is not possible. | +| Hyrule Field day/night transition | partly | Day (user slot 3) and night (user slot 0) are measured separately. The change itself: `bl_fieldlong`, a 10-minute stand in the day field (see the baseline). | +| Market | yes | User slot 1, adult Market (ruined, fog, ReDeads) | +| A dungeon with heavy effects | **no** | No save stands in a dungeon. Death Mountain Trail (test slot 0) is the heaviest outdoor area reachable, and it is measured as a stand-in, not as a dungeon. | +| A boss | **no** | No save is at a boss, and scripts cannot fight one | +| Pause menu and every subscreen | yes | Every run: Items, Equipment, Collection, Items, System, the map | +| Save, quit, reload | yes | `route_full.txt`: System → Save → Title Screen → Continue → the new save → Load, in one process | +| Return to the first scene | yes | `route_full.txt` walks Kakariko Village again after the reload (segment `kakariko-return`, from the save point at the gate, so the path differs from the first walk) | +| Added: Kakariko Village | yes | The town where players report slowdowns (section 1); the route's first scene | +| Added: Graveyard edge | yes | User slot 2 | + +### 11.3 Baseline + +**Settings and method.** + +- Runs: `route\baseline.sh`, exe `ocarina_audit_c3.exe` (commit `3a88b363`). +- Every run starts a fresh process on a fresh copy of its save. +- Settings A, the earlier town measurements' settings: `FPS_LIMIT=unlimited FRAMEGEN=0 HDR=0 GAME_ASPECT=16:9`, DLSS + performance from the ini, window 2560x1440. +- Settings U, the user's own: `FPS_LIMIT=120 FRAMEGEN=dlss FRAMEGEN_MULTIPLIER=2 HDR=1`. +- Two runs of each set. Each run is r1 or r2. +- All runs are warm. The exe had run more than 20 times before, so the driver cache was warm; the shared + `pipeline-cache.bin` and shader cache were warm too. +- r1 is compared with r2, never with the cold c1/c2 runs. + +**Columns.** + +- Frames over 25 ms are counted. +- RAM is the process's private bytes. The working set runs 10.1-11.2 GiB in the areas. +- VRAM is the driver's figure for the device-local heaps (`vk_mem_vram`) at the segment's end. +- "1% low" is the frame time at the slowest 1%, given as fps (`perf.c` `seg_close`, 50 us bins). + +**Segments.** + +- *Route* (`route_full.txt`, save `u5`): + - `title`: from the title to the world clock's start, so it includes the first save load; + - `kakariko`: 46 s walking the village; + - `pause-menu`: every subscreen; + - `save`; + - `title-return`; + - `reload`: the title, the Load list and the load; + - `kakariko-return`: 45 s walking from the save point. +- *Scene runs* (`scene_.txt`, one save each): + - `-settle`: 10 s standing right after the load; + - `-camera`: 13 s of camera turns; + - `-walk`: 9 s out and back; + - `-pause`: the subscreen tour. +- *Boot* (first present to the title's first MARK, about 2 s). Settings A: 227.3 / 210.9 fps, 1% low 90.9 / 77.8, + worst 45.8 / 46.7 ms (one frame over 25 ms: the boot's pool initialize, 43 ms in `vk_pool_init`), private 11.4 GiB, + VRAM 964 MiB. Settings U: 118.9 / 119.2 fps, worst 53.4 / 50.7 ms. + +| Run set | Segment | Frames r1 / r2 | Mean fps r1 / r2 | 1% low fps r1 / r2 | Worst ms r1 / r2 | Frames >25 ms r1 / r2 | RAM private MiB r1 / r2 | VRAM MiB r1 / r2 | +|---|---|---|---|---|---|---|---|---| +| route | title | 1414 / 1480 | 108.1 / 110.8 | 51.8 / 50.4 | 294.6 / 274.2 | 7 / 7 | 19901 / 20057 | 6546 / 6670 | +| route | kakariko | 6541 / 6561 | 140.7 / 141.1 | 90.9 / 92.2 | 15.0 / 14.1 | 0 / 0 | 24160 / 23891 | 10005 / 9634 | +| route | pause-menu | 4911 / 4914 | 223.2 / 223.4 | 152.7 / 149.3 | 20.7 / 20.6 | 0 / 0 | 21863 / 21796 | 8020 / 7906 | +| route | save | 3356 / 3357 | 240.0 / 240.0 | 215.1 / 217.4 | 10.5 / 9.5 | 0 / 0 | 21689 / 21638 | 7862 / 7762 | +| route | title-return | 2254 / 2258 | 205.1 / 205.3 | 59.5 / 59.7 | 20.2 / 17.9 | 0 / 0 | 21666 / 21752 | 7726 / 7754 | +| route | reload | 2830 / 2790 | 113.0 / 111.4 | 56.5 / 54.5 | 92.5 / 97.6 | 6 / 10 | 21778 / 21725 | 7916 / 7814 | +| route | kakariko-return | 7290 / 6186 | 160.2 / 136.0 | 98.5 / 76.6 | 12.3 / 64.8 | 0 / 6 | 25770 / 22599 | 11471 / 8596 | +| route_user | title | 1014 / 1028 | 76.8 / 78.2 | 46.5 / 46.0 | 290.6 / 279.9 | 8 / 8 | 20525 / 20603 | 7175 / 7239 | +| route_user | kakariko | 5494 / 5397 | 118.2 / 116.1 | 92.2 / 85.8 | 13.9 / 15.0 | 0 / 0 | 24070 / 23620 | 9942 / 9499 | +| route_user | pause-menu | 2640 / 2640 | 120.0 / 120.0 | 107.0 / 106.4 | 20.4 / 20.8 | 0 / 0 | 22122 / 22405 | 8349 / 8577 | +| route_user | save | 1680 / 1680 | 120.0 / 120.0 | 114.3 / 114.3 | 9.5 / 9.4 | 0 / 0 | 22048 / 22134 | 8279 / 8320 | +| route_user | title-return | 1207 / 1207 | 109.8 / 109.8 | 59.5 / 59.5 | 22.1 / 18.0 | 0 / 0 | 22139 / 22222 | 8262 / 8309 | +| route_user | reload | 2131 / 2106 | 85.2 / 84.2 | 57.5 / 41.4 | 52.1 / 54.1 | 3 / 19 | 22523 / 22576 | 8730 / 8725 | +| route_user | kakariko-return | 5083 / 5394 | 111.7 / 118.6 | 75.8 / 92.2 | 81.6 / 17.4 | 4 / 0 | 23321 / 25010 | 9360 / 10945 | +| market | market-settle | 1510 / 1573 | 151.2 / 157.5 | 76.6 / 77.2 | 15.6 / 18.7 | 0 / 0 | 19441 / 19349 | 6414 / 6305 | +| market | market-camera | 2255 / 2264 | 173.4 / 174.1 | 114.3 / 117.0 | 16.4 / 12.3 | 0 / 0 | 19744 / 19549 | 6436 / 6370 | +| market | market-walk | 1325 / 1314 | 147.1 / 146.0 | 78.7 / 79.1 | 17.7 / 17.6 | 0 / 0 | 19760 / 19586 | 6436 / 6372 | +| market | market-pause | 4713 / 4769 | 219.2 / 221.8 | 108.1 / 130.7 | 22.3 / 19.8 | 0 / 0 | 20325 / 20247 | 7019 / 7017 | +| fieldday | field-day-settle | 1282 / 1265 | 128.3 / 126.5 | 101.0 / 101.5 | 10.8 / 10.8 | 0 / 0 | 20487 / 20373 | 7015 / 6951 | +| fieldday | field-day-camera | 1825 / 1799 | 140.4 / 138.4 | 107.5 / 104.7 | 19.6 / 10.5 | 0 / 0 | 20677 / 20656 | 7045 / 7045 | +| fieldday | field-day-walk | 1228 / 1223 | 136.5 / 135.8 | 77.2 / 84.7 | 18.9 / 18.4 | 0 / 0 | 21535 / 21250 | 7815 / 7581 | +| fieldday | field-day-pause | 4704 / 4702 | 218.8 / 218.7 | 125.0 / 124.2 | 20.3 / 20.5 | 0 / 0 | 21909 / 21749 | 8244 / 8108 | +| fieldnight | field-night-settle | 1139 / 1111 | 113.9 / 111.1 | 97.6 / 94.8 | 11.7 / 12.0 | 0 / 0 | 20187 / 20283 | 6697 / 6695 | +| fieldnight | field-night-camera | 1748 / 1745 | 134.5 / 134.2 | 97.6 / 96.6 | 11.4 / 12.6 | 0 / 0 | 24265 / 24308 | 10283 / 10298 | +| fieldnight | field-night-walk | 1033 / 1049 | 114.8 / 116.6 | 83.3 / 96.2 | 34.4 / 12.2 | 1 / 0 | 23133 / 22958 | 8744 / 8719 | +| fieldnight | field-night-pause | 3643 / 3762 | 169.5 / 175.0 | 75.5 / 97.6 | 34.4 / 33.4 | 2 / 2 | 21686 / 21581 | 7783 / 7775 | +| trail | trail-settle | 1666 / 1662 | 166.6 / 166.1 | 133.3 / 131.6 | 10.1 / 8.6 | 0 / 0 | 19155 / 19151 | 5933 / 5933 | +| trail | trail-camera | 2057 / 2131 | 158.2 / 164.0 | 79.4 / 132.5 | 38.2 / 9.3 | 1 / 0 | 19638 / 19471 | 6202 / 6203 | +| trail | trail-walk | 1464 / 1459 | 162.6 / 162.1 | 131.6 / 128.2 | 8.8 / 8.7 | 0 / 0 | 19966 / 19793 | 6503 / 6495 | +| trail | trail-pause | 4795 / 4803 | 223.1 / 223.4 | 146.0 / 149.3 | 20.9 / 21.8 | 0 / 0 | 20290 / 20147 | 6902 / 6842 | +| graveyard | graveyard-settle | 1100 / 1091 | 110.0 / 109.1 | 89.3 / 86.2 | 13.7 / 12.9 | 0 / 0 | 19659 / 19659 | 5983 / 5983 | +| graveyard | graveyard-camera | 1776 / 1774 | 136.6 / 136.5 | 96.2 / 96.2 | 11.3 / 11.7 | 0 / 0 | 19977 / 19932 | 6232 / 6179 | +| graveyard | graveyard-walk | 1014 / 1018 | 112.8 / 113.1 | 61.9 / 66.0 | 21.5 / 17.9 | 0 / 0 | 20481 / 20591 | 6703 / 6790 | +| graveyard | graveyard-pause | 4633 / 4623 | 215.5 / 215.0 | 105.3 / 106.4 | 21.6 / 21.3 | 0 / 0 | 21065 / 21130 | 7273 / 7321 | + + +`route_user` is settings U, capped at 120. With frame generation the window shows twice the frames; the table counts +the frames the game draws. + +**The day/night change.** `bl_fieldlong`: user slot 3, 9.7 minutes of world time standing in Hyrule Field by day. + +- By the end the light reached dusk, not night. The full change is not covered. +- Over the stand the mean fell from 140 fps (`field-day-camera`) to 118 fps (`field-day-end`, 519 s, 61244 frames, 1% + low 96.2 fps, worst 16.2 ms, none over 25 ms). +- The GPU's time stayed at 4.36-4.37 ms per frame, and every window was "bound: cpu". +- The CPU frame grew by about 1.3 ms. The size lines at frames 13200 and 73200 are flat apart from released textures + (165 → 542, 36 → 478 MiB). Lead L-45. + +**Memory in the areas** (segment ends, r1; private RAM / VRAM in MiB): + +| Area | Private RAM | VRAM | +|---|---|---| +| Market | 19.4-20.3 GiB | 6.3-7.0 GiB | +| Death Mountain Trail | 19.2-20.3 GiB | 5.9-6.9 GiB | +| Graveyard edge | 19.7-21.1 GiB | 6.0-7.3 GiB | +| Hyrule Field by day | 20.4-21.9 GiB | 7.0-8.2 GiB | +| Hyrule Field by night | 20.2-24.3 GiB | 6.7-10.3 GiB | +| Kakariko | 23.9-24.2 GiB | 9.6-10.0 GiB | + +The `scene: … settled` snapshots are in each log. + +**Sizes at the end of the first scene and after returning to it** (route, settings A, `route\summary.md` has the full +lines): + +| Figure | r1 Kakariko | r1 after the reload | r2 Kakariko | r2 after the reload | +|---|---|---|---|---| +| VRAM in use (driver) | 10005 MiB | 11471 MiB | 9634 MiB | 8596 MiB | +| of it textures / released textures | 4731 / 2580 | 4908 / 3732 | 4673 / 2262 | 4996 / 892 | +| VRAM mirrors | 783 (619 pools) | 802 (577) | 783 (619) | 1206 (948) | +| outside VMA (swapchain, DLSS, pipelines, driver) | 1218 | 1134 | 1146 | 704 | +| Private RAM | 24160 | 25770 | 23891 | 22599 | +| Pool records / device address records | 4516 / 4515 of 65536 | 4600 / 4599 | 4516 / 4515 | 5145 / 5144 | +| Textures / image views | 8292 / 19194 | 9056 / 20833 | 8374 / 19305 | 8554 / 18666 | +| Texture pool slots | 32512 of 32768 | 32512 | 32512 | 32512 | +| Recording copies | 51656, 12.6 MiB | 77724, 20.3 MiB | 51721, 12.6 MiB | 82842, 22.6 MiB | +| Texture pins / pin sweep queue | 9076 / 9056 | 12321 / 12303 | 9126 / 9106 | 8460 / 8432 | +| Completion queue | 618 | 457 | 678 | 579 | +| Pipeline entries (all built) / layouts | 3258 / 886 | 3258 / 886 | 3354 / 894 | 3354 / 894 | +| Shader memory cache | 3564, 386.2 MiB | 3567, 386.2 MiB | 3657, 394.4 MiB | 3676, 395.4 MiB | +| Guest heap / physical maps | 6910 / 2674.5 MiB | 6910 / 2674.8 | 6910 / 2674.1 | 6910 / 2668.1 | +| Handles / system events / setjmp buffers | 112 / 8 / 10 | 116 / 10 / 22 | 112 / 8 / 8 | 117 / 10 / 23 | +| Lazy write-back ranges | 111 | 84 | 126 | 102 | + +Unchanged everywhere: + +- 84-85 guest threads, 3 fibers, 0 deferred destructions at the snapshot; +- staging cache 24 of 24, 8 free arena chunks, 17 of 128 write-back snapshot chunks; +- 0 shader failures, 0 translator processes, 0 pipeline jobs pending, 0 fast links; +- 4 zstd dictionaries, 21 settings, no replaced setting values. + +Growth across the return, in both runs: setjmp buffers (+12/+15, never removed, L-10), system events (+2), recording +copies (+26k/+31k). The VRAM figures differ between r1 and r2 because releases and mirror evictions fall at different +times. + +**Hitches and their causes.** `route\slow_causes.py` over all 15 baseline logs: + +- 287 frames of 25 ms or more. +- 132 have a render-thread wait or a work mark of at least a quarter of the frame. Mostly texture upload with zstd + decodes and file reads at an area load, fence waits right after it, and pool initialize/finalize. +- 30 have something named, but less. +- 125 have nothing named: + - 95 are the Market's periodic stall: 90 in r1, 5 in r2 (L-44); + - 20 are the one or two frames right after each save load, in every run: 48-68 ms, then 26-36 ms; + - 10 are single frames of 25-34 ms: 9 during the route's reloads, 1 in the night field. + +The unnamed time is outside the recorded waits and marks: the game's own threads or the driver. `NX2NAVI_PROFILE` with +`NX2NAVI_PROFILE_SLOW` can name them. It suspends every thread every millisecond (L-41), so it stayed out of the +baseline. + +**Other baseline observations** (recorded, not investigated): + +- The menu segments run at exactly 240.0 fps with `FPS_LIMIT=unlimited`: the game step's limit (`ostep`, up to 240 + game frames a second). +- In r2 the reload's area streaming ran into the `kakariko-return` segment. That gave 6 frames over 25 ms (worst + 64.8 ms: texture 26.2 ms, 1563 MiB of new device memory), against 0 in r1. The segment's mean depends on when the load + ends. + +### 11.4 Sanitizers + +| Build | Built | Ran | Reported | +|---|---|---|---| +| UBSan (`-fsanitize=undefined -fsanitize-trap=undefined -fno-sanitize=vptr -g1`, runtime only) | yes: `work\build_rt_audit.py` with `AUDIT_CFLAGS`, `work\rt_obj_ubsan`, `ocarina_ubsan.exe` | yes, the full route | one report, then a clean route (below) | +| ASan + UBSan (`-fsanitize=address` added, linked to `clang_rt.asan_dynamic-x86_64.lib`) | yes: `work\rt_obj_asan`, `ocarina_asan.exe` | no: it cannot start | — | +| TSan | no | no | — | + +**What was built and how.** + +- The MSYS2 UCRT64 clang (23.1.4) ships no sanitizer runtimes. `lib\clang\23` holds only headers, and the + compiler-rt package would have to be downloaded, which was not done. +- UBSan therefore runs in trap mode: every check is an `ud1` instruction whose operand names the check. The crash + handler logs the address, and `addr2line` on the `-g1` exe gives the line (`route\ubsan_once.sh`). +- The standalone LLVM 23.1.5 for the MSVC target (`C:\Program Files\LLVM`) carries the ASan runtime DLL. A MinGW UCRT + program linked against its import library works: a test program (`E:\nx2devrun\out\audit\san\t.c`) had its heap overflow + reported in full. +- Only `runtime/` was instrumented. The guest objects in `work\obj_pickup` are the uninstrumented ones (the generated + C is not built again). + +**UBSan results.** + +1. Run `san_ubsan`: a trap at start-up, in the menu thread's font atlas. + - `FATAL: illegal instruction (0xc000001d) at host … (nx2navi+0x11782fd2)`. + - The instruction is `ud1 0xc(%eax),%eax`: check 12, multiply overflow. + - `addr2line`: `ui/menu_skin.cpp:265`, the `lattice` lambda in `skin_atlas_fill`. + - Ledger F-1-02. +2. With that one check skipped for that file (`work\asan\ubsan_ignore.txt`), run `san_ubsan2` went through the whole + route (boot, title, Kakariko, every pause subscreen, save, title, reload, Kakariko, 282 s of world time) with no + further trap. + - UBSan stops at its first report. So this says: no other undefined behaviour of the instrumented kinds was reached + on this route in `runtime/`. + - Its cost: Kakariko 119.5 fps against 140.7. + +**ASan result.** It cannot run with the guest's fixed layout. + +- Started directly (`ocarina_asan.exe --version` with the DLL on `PATH`), the runtime wrote "memory: a fixed region is + taken; re-running the process" 20 times, then `FATAL: memory: the module window is not free after 20 attempts` + (exit 70). This is `memory.c` `mem_init` → `reexec_or_fail`. +- A probe under the same ASan DLL (`E:\nx2devrun\out\audit\san\vq.c`) shows why: + - the shadow starts at `0x80000000`; + - one reservation from allocation base `0x90000000` covers `0x100000000` to past `0x7010000000` (2046 GiB from + `0x100000000`, 1602 GiB from `0x7000000000`); + - so the module window (`MOD_MAIN_BASE`, `0x7000000000`) and the kernel region (`0x7010000000`) lie inside ASan's + shadow. +- The Windows ASan runtime chooses the shadow's place itself, and no option moves it. ASan needs the guest windows + moved above the shadow, which `recomp/layout.py` decides (a generator change across subsystems). Not attempted; + waiting for the user if wanted. +- The first `ASAN_OPTIONS` tried had a log path with a drive letter, whose colon the option parser takes as a + separator ("expected '='"). A path relative to the game folder works. + +**TSan.** + +- ThreadSanitizer has no Windows target. +- No Linux machine is here, and WSL is not installed ("The Windows Subsystem for Linux is not installed"). +- Not built, not run. + +### 11.5 What Phase 2 could not do + +- **Route steps:** + - Kokiri Forest is not covered: its only save crashes on load (F-1-01). + - Dungeon and boss: no save is in one, and scripted input cannot travel or fight there. + - The full day/night change: only dusk was reached in 9.7 minutes. +- **Saves:** no save of the user's loads as a child. The probes used copies of the user's slots (read only) and of the + test install's. +- **Sanitizers:** ASan cannot start (shadow over the fixed guest layout); TSan does not exist here. UBSan stops at its + first report, so each further report needs a rebuild with an ignore list. +- **Instrumentation not added:** + - a host `malloc` funnel for "large allocations" (there is none; the large host allocations are named by subsystem + instead); + - sizes for the items listed under "still no size figure" in 11.1; + - the game's own threads: their CPU time in a frame stays unnamed, as above. +- **Not measured:** + - the commit census (`NX2NAVI_MEM_CENSUS=1`), which stalls frames by 65-240 ms; + - long sessions: the longest run is the 10-minute field stand; the multi-hour growth that section 10 asks about is + not measured; + - an AMD or Linux machine (not available). + +--- + +## 12. Phase 3: the eight passes (stopped before its end) + +Phase 3 was started on 2026-11-10 on branch `claude/audit-phase2-a12eef` and stopped at the user's request before its +end. It changes no runtime behaviour: the four commits it adds only log under `NX2NAVI_TRACE=perf`. Nothing is fixed. + +**Where it stands.** + +- Every lead L-01 to L-47 has an outcome (section 7, in italics after each number). +- The ledger (section 8) holds 56 findings: 11 confirmed by a run or by tool output, 45 suspected from reading code. (F-1-12 was added during Phase 4.) +- Not done: the runs listed in 12.4. Until they are done, the findings they would settle stay suspected. + +| Severity | Confirmed | Suspected | +|---|---|---| +| S1 crash, data loss | 4: F-1-01, F-1-11, and the measured growth of F-1-07 and F-1-08 (their fatal was not reached) | 8: F-1-03, F-1-04, F-1-05, F-1-06, F-1-09, F-1-10, F-2-04, F-8-02 | +| S2 hitch, growth, major visual | 3: F-4-01, F-4-04 (the time), F-4-11 | 7: F-2-01, F-2-05, F-3-01, F-3-02, F-3-03, F-5-02, F-8-01 | +| S3 minor | 2: F-4-02, F-4-03 | 22 | +| S4 optimization | 2: F-1-02, F-3-12 | 7 | + +Of the eight suspected S1 rows, five need the game itself to misuse a handle or two guest threads to meet in a narrow +window (F-1-03, F-1-04, F-1-06, F-1-09, F-2-04), and none of them was seen in any run. + +### 12.1 How it was done + +- **Reading.** Four read-only passes went through the leads, one group of passes each: passes 1 and 2; pass 3; passes 4 + and 7; passes 5, 6 and 8. Each lead ended as a finding, a strike with its reason, or "needs a run". +- **Checked again by the auditor.** These claims were re-read in the code before they were entered: F-1-03 + (`kern_handle_get`), F-1-04 (`stream_drop`), F-1-05 (`same_content`), F-1-06 (`vk_exec_held_ready`, `ph_flush`), + F-1-09 (`read_directory`), F-2-04 (`save_commit`, `commit_run`), F-3-01 (`upload`), F-3-02 (`make_dummy`), F-3-03 + (`refuse`), F-4-04 (`pool_fini`), F-4-11 (the marker's callers), F-6-02 (`play_only`), F-8-01 (`gen_now`), F-8-02 + (the callers of `fs_save_flush`). The other suspected rows and the strikes rest on the reading passes alone. +- **Runs.** Exe `ocarina_audit_p3.exe` (commit `a1eebd03`), batch `E:\nx2devrun\out\audit\route\p3_runs.sh`, runs + `p3_*` under `E:\nx2devrun\out\audit`. The profiler was used once to name a cause, never to measure. +- **Logs read for evidence.** The 54 logs under `E:\nx2devrun\out\audit`, the five logs of the user's install + (`D:\test\logs`, read only) and five earlier copies of the user's logs. None holds the lines that F-3-01, F-3-02 or + F-3-03 would write. + +### 12.2 Instrumentation added in Phase 3 + +All four write only with `NX2NAVI_TRACE=perf`. + +| Commit | What it adds | Shown working by | +|---|---|---| +| `df6766aa` | `drain` and `replay` on the `perf: slow frame` line (`perf.c` `perf_present`) | `p3_route`: `perf: slow frame 2122: 95.0 ms; blocked pipeline 0.0 xlate 0.0 texture 0.0 astc 0.0 fence 0.0 pacing 0.0 drain 0.0; replay 93.6; on any thread: pipeline creates 561.6 ms (8, 0.0 MiB, longest 223.0 ms)` | +| `c85892ab` | Work mark `DLSS feature creates` (`host.h` `PERF_M_NGX`, `vk_dlaa.c` `evaluate` and the frame generation create) | `p3_route`: `perf: slow frame 20156: 108.7 ms; … replay 104.7; on any thread: pipeline creates 562.2 ms (4, 0.0 MiB, longest 294.7 ms), device memory allocations 16 (797.8 MiB), DLSS feature creates 43.8 ms (1, 0.0 MiB, longest 43.8 ms)` | +| `a1eebd03` | Which threads submit and present on which queue, and a line when such a call starts while another runs (`nvn_api_core.c` `nvn_call_note`) | `p3_route`: `nvn: thread 22980 presents on queue 0x134133020 (first at frame 0)`; `nvn: thread 36088 enters a submit on queue 0x134133020 while 1 other submit or present call run (overlap 1, frame 8086)` | +| `587e8494` | `page generations handed out` in the `mem: sizes` lines (`vk_memory.c` `vk_mem_sizes`) | Built (`ocarina_audit_p3b.exe` holds the text); **not yet shown by a run** | + +### 12.3 Evidence + +**F-1-01, the save that crashes on load** (run `f101_fs`, `NX2NAVI_TRACE=perf,fs`). + +- The save's `progress.sav` names `HyruleCastle_Child` twice. The other 11 saves name `HyruleCastle`. +- The 1.1.1 RomFS index has `Banc/HyruleCastle/HyruleCastle_Static` and `_Dynamic`, and `GameBancParam/HyruleCastle`. It + has no `HyruleCastle_Child` file. (Sixteen other areas do have `_Child` files.) +- The file trace, in order: + - `fs 8.028 rom content:/Banc/HyruleCastle/HyruleCastle_Child_Static.bcett.byml.zs` (twice), then the same name + without `.zs`, then the `_Dynamic` pair the same way; + - `fs 15.134 rom content:/Banc/GameBancParam/HyruleCastle_Child.game__banc__GameBancParam.bgyml`; + - then `FATAL: access violation … reading address 0x150` in `main+0x112b3b0`. +- None of those opens logged a `scene:` line, which `romfs.c` `romfs_open` writes only after the file is found: the host + answered "not found", which is right. +- So the host left nothing null. The save names an area this game version does not have, and the game does not check. + The first 12 bytes of the save match every other save here; where the save came from is not determined. + +**Interrupted save writes** (pass 8). `ocarina_audit_c3.exe --probe-fs`, in a temporary profile: + +``` +save tx: uncommitted writes visible to the game and dropped by a restart and by Unmount, commits kept; a crash at each +of 6 commit steps recovers to the old save 3 times, the new one 3 times, mixed 0 times; 3 backups +probe-fs: passed (186587 files, 64 sampled) +``` + +A commit interrupted at any of its six steps leaves the whole old save or the whole new one. What is left open is the +window before the commit thread has finished (F-8-02) and two Commits at once (F-2-04). + +**F-4-01, the Market stall** (lead L-44; runs `p3_market_t1`, `bl_market_1`, `bl_market_2`). + +- With the replay column, every slow frame is the replay: `slow frame 11303: 20.3 ms; … drain 0.0; replay 18.0`. + 375 of 380 gaps between slow frames are 8 frames. +- `NX2NAVI_REPLAY_TIME=1`: `slow replay frames 225, per frame: draws 23.2 ms (1253) … its slowest op 20.0 ms (DRAW_MESH + 225); texture lock held over 1 ms 19.9 ms`. +- `NX2NAVI_LOCK_TIME=1`: `texture lock held over 1 ms: 7792 ms (581 holds): 00007FF67A6C43C0 7791.1 ms (580, max 33.61 + ms)`. Against the link map that address is `bind_resources+0x1980`. A game thread waits behind it: + `vk_texture_register+0x2c 768.9 ms (1963, max 26.81 ms)`. +- The list walked there, from the `vk: texture pool sets:` line every 3600 pool switches (`slots without one`, and the + walk's own time per switch): + + | Run | at 10800 | 14400 | 18000 | 21600 | 25200 | 28800 | + |---|---|---|---|---|---|---| + | `p3_market_t1` | 22149, 0.070 ms | 5063, 0.082 | 134371, 0.148 | 111986, 0.249 | 160385, 0.324 | — | + | `bl_market_1` | 24323, 0.041 | 13506, 0.076 | 67223, 0.141 | 115652, 0.226 | 72314, 0.281 | 87258, 0.326 | + | `bl_market_2` | 49739, 0.034 | 6067, 0.073 | 70646, 0.119 | 62904, 0.188 | 77066, 0.245 | 88824, 0.301 | + | `p3_market_t2` (no stall) | 31397, 0.073 | 2792, 0.077 | 1297, 0.065 | 1300, 0.056 | 1273, 0.050 | 1327, 0.045 | + + Only 32768 slots exist, so a list of 160385 holds copies. In `p3_market_t1` the walk time grew from 0.249 to 0.324 ms + per switch over 3600 switches with 0.05 walks per switch: about 15 ms a walk. +- Elsewhere the list stays small: 203-4167 in Kakariko (`bl_route_1`), 1058-2126 in the field (`bl_fieldlong`). +- The profiled run (`p3_market_prof`) caught the stall at its end (frames 14239, 14247, 14255) but its 64 slow-frame + dumps were used up during boot, and the whole-run profile is 82 % blocked threads: it adds nothing to the above. + +**F-4-02 and F-4-03, the frames after a load** (lead L-47). + +- DLSS feature creates, from the new mark: 23.5 ms and 26.7 ms in the load's big frame (`p3_route` 2111, + `p3_route_cold` 2178); 16.4 and 15.6 ms at the pause menu's first frame (`p3_market_t1` 5663, `p3_market_t2` 5742: + the menu draws at its own size, `DLSS feature created at 2560x1440 -> 2560x1440`); 43.8 and 44.9 ms at the reload, + where `1 DLSS feature(s) released before the one for 1280x720 is made` comes first. +- The unnamed 48-68 ms frame of the baseline is a different frame, about 10 after the load's big one. It is the replay's + own time (the `df6766aa` line above), and its part is not named yet. + +**F-2-01, which threads submit** (this also answers section 10's first question). + +- `p3_route`: thread 28188 submits on three queues; thread 22980 submits on four and is the only one that presents; + thread 17368 submits on the present queue from frame 1079; thread 36088 from frame 8086. +- Frame 8086 is the pause menu's first frame (the segment starts at 8080). From there submits overlap: 32 or more + overlaps by frame 12847, and the same from the pause menu's first frame in both Market runs. +- So the game submits and presents from the same thread, and other threads submit at the same time. + +**L-45, the frame that grows toward dusk.** In `bl_fieldlong` the replay stays at 5.46-5.59 ms while the interval goes +from 7.96 to 8.5 ms, and the pool's freshness check stays at 0.034 ms with 6019 to 6825 listed entries. The growth is +outside the replay: the game's own frame, or host calls it makes. The night field's baseline is slower than the day +field's in the same way (111-114 fps standing against 126-128). The cause is not determined. + +**F-4-11 and F-1-11, the run folder's pipeline state and three device losses.** + +- At 22:50 `E:\nx2devrun\pipeline-prewarm-skip.txt` appeared (the ledger row quotes the line that wrote it). From then + on every start in that folder, of every session, skips the boot's pipeline prebuild. +- The file was not deleted: other sessions run there, and removing it is the user's call. Its own text says "Delete + this file to build ahead of play again." +- Runs before 22:50 (`p3_route_cold`, `p3_route`, `p3_market_t1`, `p3_market_t2`) are in the earlier state. Runs after + it (`p3_market_prof`, `p3_l31_*`) build pipelines in play and are slower: 99.9 fps standing in the day field against + 126-128 in the baseline. They cannot be compared with the baseline. +- In that state three runs in a row lost the device while the save loaded (F-1-11). All three show the same last GPU + mark, `dispatch 3 of submission N: 293x1x1 groups, cs 3524d41df45a41e0`, and a read fault at `0x30b000000`, + `0x311000000` or `0x31f000000`. + +### 12.4 What is left of Phase 3 + +- **F-7-01 (L-31), the two GPU waits.** A valid A/B: default, `NX2NAVI_SUBMIT_FINISH=0` and `NX2NAVI_ACQUIRE_WAIT=0`, + two runs each, in one pipeline state. `route\l31_table.py` reads them. +- **F-8-01, the generation counter's rate.** One route run with `ocarina_audit_p3b.exe`, reading `page generations + handed out` at two 600-frame lines. +- **F-3-01, F-3-02, F-3-03, F-7-03 (L-21, L-22, L-23, L-35).** The route under `NX2NAVI_VRAM_BUDGET_MB=6144` with a long + stand, for the disuse eviction and the scans. A budget cap cannot fail an allocation, so F-3-01 and F-3-03 need real + memory exhaustion to reproduce. +- **F-1-11.** Name the faulting read, and say whether the skipped prebuild causes it. +- **F-4-03.** A timed route run (`NX2NAVI_REPLAY_TIME=1`) to name the replay's part in the frame after a load. +- **Not reachable here, so not determined:** F-1-10 (dungeon and boss audio), F-5-01 (the gate), F-5-02 (Linux, AMD), + F-8-03 and F-8-04 (a hand on the controller), F-8-06 (a fused item), F-8-07 (a movie). +- **Not looked at:** pass 5 beyond the three known problems, and pass 6 beyond a read of the menu for clear bugs. The + game's own pause menu ignores the DPAD in its System column under scripted input; whether that is the game's own + behaviour was not checked. + +--- + +## 13. Phase 4: fixes + +Started 2026-11-10 at the user's word ("fix what was found"), on `claude/audit-phase2-a12eef`. One commit per fix. Nothing +is pushed. + +**Rules kept.** + +- A fix that would change gameplay timing or behaviour, the save format, or cross subsystems was not made; those wait + for the user (13.3). +- A suspected finding that was never reproduced cannot be shown fixed. Its row says "not reproduced before" and names + the regression checks that passed with the change. +- Exe: `ocarina_audit_fix.exe`, built from `d61cd9b9`. Its runs use a pipeline cache folder of their own + (`NX2NAVI_PIPELINE_CACHE`, `E:\nx2devrun\out\audit\pcache`), so they neither depend on the shared folder's skip file + nor change it. Batch: `E:\nx2devrun\out\audit\route\p4_verify.sh`. + +### 13.1 What was changed + +The ledger's last column (section 8) has each commit with its evidence. In short: + +| Finding | Commit | Change | Verified | +|---|---|---|---| +| F-4-11 prebuild skipped for good | `6c0b0b10` | Every orderly exit deletes the boot prebuild's running marker | yes: reproduced with the old exe, gone with the fixed one | +| F-4-01 Market stall | `015a89dc` | A pool slot without an entry is listed once | yes: three runs of three: the list at 3192 entries at most, no frame over 20 ms standing | +| F-1-01 save naming a missing area | `58a8d21d` | The log and the crash report name the area | yes, for the report; the save still cannot load | +| F-1-02 signed overflow | `cebdd4a9` | The hash is computed unsigned | yes: the UBSan route ran with no trap | +| F-1-07, F-1-08 tables fatal when full | `7dfa809c`, `1a57cc21` | Replace the oldest buffer; reuse a destroyed event's slot | no: the tables were never full in a run | +| F-2-04 two Commits at once | `b2f9ea4c` | Pending commits are counted | not reproduced before; the save probe and check pass | +| F-8-02 crash during a commit | `cd170dad` | The crash and fatal paths wait up to 2 s for a commit under way | not reproduced before; the save probe and check pass | +| F-1-09 listing freed under a reader | `d61cd9b9` | Directory reads hold the lock | not reproduced before; the save probe and check pass | +| F-1-04 zstd slot | `32f2a41a` | The slot is dropped by its stream state under one lock hold | not reproduced before | +| F-1-05 hash of unmapped storage | `a9005e5c` | Both hashes run with the storage held mapped | not reproduced before | +| F-3-10, part of F-3-01 | `054bd556` | The content hash is forgotten when the image does not hold the storage's bytes | not reproduced before | +| F-3-03, F-3-11 mirror never asked again | `94ee6e78` | A failed allocation is asked again like a budget refusal; four log lines per reason | not reproduced before | +| F-2-02 submit count | `ca06d5c8` | The count is atomic | not reproduced before | +| F-6-01 menu dictionaries | `b4bfb7b6` | Loaded once behind a once-guard | not reproduced before | +| F-3-08 uniform write list | `3966d878` | Pruned with snapshots off too | not run in that mode | +| F-6-03 `NX2NAVI_ACQUIRE_WAIT` | `4b47a10a` | Read as a number | the value 2 was not run | + +**Regression runs with the fixed exe.** + +- The route (`p4_route`): `p4_route` went through every segment with no FATAL and committed the save five times. Its frame rates cannot be compared with the baseline: the exe name is new and it has a pipeline cache folder of its own, so pipelines were still compiling on other threads (Kakariko 118.1 fps against 140.7; 17 frames over 25 ms in the 12 s after the reload, against 0 and 6) +- The Market (`p4_market_1` to `_3`, `NX2NAVI_REPLAY_TIME=1 NX2NAVI_LOCK_TIME=1`): three runs of three (`p4_market_1` to `_3`): the list stays at 524-3192 entries and the walk at 0.008-0.026 ms per switch; standing after the pause tour no frame reaches 20 ms (worst 14.2, 17.3 and 18.3 ms at 118.5, 145.7 and 139.6 fps); the texture lock is held over 1 ms for at most 149 ms in a period (longest hold 4.34 ms), against 7792 ms (33.61 ms) before +- The save transaction (`--probe-fs`): `a crash at each of 6 commit steps recovers to the old save 3 times, the new one 3 + times, mixed 0 times; 3 backups`, `probe-fs: passed (186587 files, 64 sampled)`. +- UBSan, no ignore list (`p4_ubsan`): `p4_ubsan` went through the whole route (261 s of world time) with no trap: the start no longer stops at `menu_skin.cpp:265`, and none of the changed code tripped a check + +### 13.2 A regression of the audit's own, repaired + +Phase 2's size lines (`3a88b363`) made `kernel.c`, `fs_host.c` and `vk_gpa.c` call `perf_size`. Three unit checks build +one of those files without `perf.c` and stopped linking: `tests\sync_wake_check.py`, `tests\save_share_check.py` and +`tests\gpa_check.py`. Commit `78033dc4` gives them a stub (and gives `save_share_check` the `mem_probing` stub it lacked +since an earlier commit that is not the audit's). + +Checks run after it, with the system Python 3.12: + +- pass: `logq_check`, `save_zip_check`, `frame_step_check`, `wb_lazy_check`, `target_frames_check`, `gpa_check`, + `mouse_stick_check`, `sync_wake_check`, `save_share_check`; +- `audio_input_check` does not link (`rt_knob` undefined); none of the audit's commits touches what it builds; +- not run: `warm_hint_check`, `flags_check`, `ds3_check` (they need the `unicorn` module, which this Python lacks), + `jumptables_check`, `mods_romfs_check`, `mouse_direct_check`, `tensor_lowering_check` (they need arguments or game + files). + +### 13.3 Not fixed + +**Waiting for the user** (the fix changes gameplay timing or behaviour, or crosses subsystems): + +- F-2-01 with F-1-06: one lock around the synchronous submit and present front end (subsystems 10 and 11). +- F-2-05: the fence value returned before held work is replayed (changes when the game's waits return). +- F-8-01: 64-bit page generations (subsystems 12 and 13). +- F-1-10: audio parameter checks answered with an error result instead of ending the process. +- F-8-04: opening the menu when the controller disconnects. +- F-8-06: the shake key's timing. +- F-7-01: the two GPU waits per frame (not measured yet either). +- F-4-05: the fetch inside the fault handler (touches the piece protocol of lazy write-back). + +**Not attempted.** + +- F-1-11, the device loss at a save load: another session is diagnosing it and tied it to the lazy write-back's piece release (the ledger row has its counts). `test-all-fixes` has that release off by default since `6e3f29d4`; this branch does not hold that commit. +- F-1-12, callbacks run after a lost device: entered from that session's report and one of the audit's own logs; not changed. +- F-4-02 (create the DLSS feature ahead of use), F-4-04 (the pool finalize's wait): each needs a design and a careful + run plan on the device's thread rules. +- F-4-03: its cause inside the replay is not named yet. +- F-3-02: the stand-ins' colour and the holds are rendering behaviour; they need the user's eye on the result. +- F-3-01's retry of a failed decode, F-3-12, and the remaining S3 and S4 rows (F-2-03, F-3-04 to F-3-07, F-3-09, F-4-06 + to F-4-10, F-5-01, F-5-02, F-6-02, F-7-02 to F-7-04, F-8-03, F-8-05, F-8-07). diff --git a/README.md b/README.md index f655f5d0..e8ed75b6 100644 --- a/README.md +++ b/README.md @@ -36,10 +36,10 @@ Report problems as issues, following [CONTRIBUTING.md](CONTRIBUTING.md). GPUs (one, two or three generated frames for every frame the game draws), or AMD FSR 3.1 (any GPU), a generated frame between every two the game draws, with the HUD kept out of it, for about twice the frame rate on a fast display; in a window of another shape than the picture, frames are generated inside the picture only, so the black - bars stay clean. With frame generation on, the frame limit counts the frames on screen, and with no limit chosen - it is the display's refresh rate. The frame limit can also be + bars stay clean. The frame limit counts the frames the game draws, and frame generation adds its + frames on top of it. The frame limit can also be handed to RivaTuner Statistics Server -- HDR on HDR displays: the game's own native HDR, or its SDR picture tone mapped to the display's peak, with exposure, highlights, shadows, contrast, saturation and gamma in the menu +- HDR on HDR displays: the game's own native HDR, or its scene tone mapped to the display's peak and matched to the game's mid grey and tone, with exposure, highlights, shadows, contrast and saturation in the menu - The game's known shaders prepared when the game is built, and the pipelines met in play built again in the background at each start, so play rarely stops to compile them; a shader or pipeline met for the first time can still hold a frame, and a draw that must wait for its pipeline has it built on worker threads, never on the game's @@ -62,14 +62,14 @@ Report problems as issues, following [CONTRIBUTING.md](CONTRIBUTING.md). Download `NX2navi-Setup-.exe` from the releases and start it next to your `.nup` dump. It is the only file you need. The launcher it -installs finds the dump, downloads the build tools, builds the game on your PC (10 to 25 minutes, once) and starts +installs finds the dump, downloads the build tools, builds the game on your PC (20 to 45 minutes, once) and starts it; afterwards it keeps the port up to date and rebuilds only what changed ([docs/launcher.md](docs/launcher.md)). [docs/README-BuildKit.md](docs/README-BuildKit.md) describes the same build by hand, [docs/building.md](docs/building.md) building from source. Settings are in the in-game menu and in `nx2navi.ini` ([nx2navi.ini.example](nx2navi.ini.example) lists every key). Controls: [docs/controls.md](docs/controls.md). Requirements: Windows 10 or later; an x86-64 CPU with SSE4.2 (AVX2/FMA machines get a faster build); 16 GB of RAM; about -30 GB free for the game and 1.5 GB for the launcher and its tools; a GPU with Vulkan 1.3, `VK_EXT_external_memory_host` +34 GB free for the game and 1.5 GB for the launcher and its tools; a GPU with Vulkan 1.3, `VK_EXT_external_memory_host` and `VK_EXT_mesh_shader`. The setup is not signed, so SmartScreen warns on its first start. ## Known issues diff --git a/THIRD_PARTY_NOTICES.md b/THIRD_PARTY_NOTICES.md index 40f8acd7..730cb572 100644 --- a/THIRD_PARTY_NOTICES.md +++ b/THIRD_PARTY_NOTICES.md @@ -28,6 +28,7 @@ Code copied or adapted from another project is listed here with its source, the | MacNativeGames block-linear deswizzler (address function; copy loop split out as `tex_bl_copy`) | https://github.com/ly05010419/MacNativeGames @ `b75be8cfa704df3701e86130c8ced268e79d6b11` (`third_party/d2r_gfx/gfx/tex/nvn_deswizzle.c`), Copyright (c) 2026 jhaizhou | MIT | `runtime/tex_deswizzle.c`, `runtime/tex.h` | | SDL 3.4.18, dynamic link, `SDL3.dll` copied next to `nx2navi.exe`. Developer builds use the MSYS2 build (`mingw-w64-ucrt-x86_64-sdl3`, which imports `libiconv-2.dll`, LGPL-2.1, unmodified, copied beside it); the installer release ships the upstream release `SDL3-3.4.18-win32-x64.zip`, which imports no libiconv | https://libsdl.org, Copyright (c) 1997-2026 Sam Lantinga | zlib | `runtime/input_win.c` (gamepad input, rumble, gyro and accelerometer) | | libopus (MSYS2 `mingw-w64-ucrt-x86_64-opus`), dynamic link, `libopus-0.dll` copied next to `nx2navi.exe` | https://opus-codec.org, Copyright (c) 2001-2023 Xiph.Org, Skype Limited, Octasic, Jean-Marc Valin, Timothy B. Terriberry, CSIRO, Gregory Maxwell, Mark Borgerding, Erik de Castro Lopo, Mozilla, Amazon | BSD-3-Clause | `runtime/ov_media.c` (nn::codec hardware Opus decoder) | +| Monocypher 4.0.2 (`monocypher.c`, `monocypher.h`, unmodified; licence text in `runtime/third_party/monocypher/LICENCE.md`) | https://monocypher.org/download/monocypher-4.0.2.tar.gz (SHA-512 `bf275d4c53ff94af6cdc723a4e002e9f080f4d1436c86c76bb37870b34807f1d7b32331d8ff8a1aeb369e946f3769021e03e63efac25b82efc5abf54dc084714`), Copyright (c) 2017-2023 Loup Vaillant, Michael Savage, Fabio Scotoni | BSD-2-Clause (dual-licensed with CC0-1.0; the BSD licence is the one used here) | `runtime/third_party/monocypher/` (compiled into `nx2navi.exe` for co-op: key derivation with BLAKE2b and the room's messages sealed with XChaCha20-Poly1305, `runtime/coop_proto.c`) | | Dear ImGui 1.91.9 (core and Vulkan back end, unmodified), as vendored by LAS Recomp | https://github.com/ocornut/imgui, via https://github.com/peiikai/LASRecomp @ `da35b83a9611d046a9a681aae668d7085954d37f` (`third_party/imgui/`), Copyright (c) 2014-2025 Omar Cornut | MIT | `runtime/third_party/imgui/` (compiled into `nx2navi.exe` for the in-game menu, `runtime/ui/`) | | SavageWindRecomp settings menu: two-pane option rows (row look, left / right stepping, hold speed-up, description pane), the menu style and tab bar | https://github.com/Revivedx/SavageWindRecomp @ `575ad88e02f9a89a9a885d90039d48af33c982f4` (`runtime/ui/option_rows.mm`, `runtime/ui/menu.mm`), Copyright (c) 2026 Revivedx and the Savage Wind Recomp contributors, Copyright (c) 2026 Peiikai | MIT | `runtime/ui/option_rows.cpp`, `runtime/ui/option_rows.h`, `runtime/ui/menu.cpp` | | SavageWindRecomp performance overlay: the frame ring and its one-second summary, the NVML calls, the sampling loop, the full panel's layout | https://github.com/Revivedx/SavageWindRecomp @ `575ad88e02f9a89a9a885d90039d48af33c982f4` (`runtime/perfmon.c`, `runtime/perfmon.h`, `perf_overlay_draw` in `runtime/ui/menu.mm`), Copyright (c) 2026 Revivedx and the Savage Wind Recomp contributors, Copyright (c) 2026 Peiikai | MIT | `runtime/perfmon.c`, `runtime/perfmon.h`, `runtime/ui/menu.cpp` | @@ -38,6 +39,7 @@ Code copied or adapted from another project is listed here with its source, the | MacNativeGames NX2navi resolution patches: output, swapchain and scene size sites and instruction words for 1.2.1 and 1.4.3, the data-page layout, the HeapDef heap names and sizes | https://github.com/ly05010419/MacNativeGames @ `aaf6ba1f494fabaa209d049e528d6f923dfe822a` (`runtime/game_patches.c`, `game_patches_v143.c`, `game_version.h`, `scripts/make_output_res_overlay.py`), Copyright (c) 2026 MacNativeGames contributors | MIT | `recomp/patches-v121.txt`, `recomp/patches-v143.txt`, `runtime/resolution.c` | | AMD FidelityFX Super Resolution 1.0 (`ffx_a.h`, `ffx_fsr1.h`, unmodified; licence text in `runtime/shaders/ffx/LICENSE.txt`) | https://github.com/GPUOpen-Effects/FidelityFX-FSR @ `a21ffb8f6c13233ba336352bdff293894c706575`, Copyright (c) 2021 Advanced Micro Devices, Inc. | MIT | `runtime/shaders/ffx/`, `runtime/shaders/fsr_easu.comp`, `runtime/shaders/fsr_rcas.comp` (compiled into `runtime/fsr_easu_spv.h`, `runtime/fsr_rcas_spv.h`) | | RenoDX shader library: the RenoDRT tone mapper (Daniele curve, OkLab hue and chrominance, highlights, shadows, contrast, flare, saturation, highlight saturation, blowout), the luminance upgrade of an SDR grade, its colour matrices, and the swap chain pass's gamma correction, gamut compression, peak clamp and PQ encode, ported from HLSL to GLSL | https://github.com/clshortfuse/renodx @ `bc0ead39917634e95c534f7e8cfb59ab82880747` (`src/shaders/tonemap.hlsl`, `tonemap/reno_drt.hlsl`, `tonemap/daniele.hlsl`, `draw.hlsl`, `colorgrade.hlsl`, `colorcorrect.hlsl`, `color/oklab.hlsl`, `color/rgb.hlsl`, `color/pq.hlsl`, `color/srgb.hlsl`, `color/gamma.hlsl`; setting names, ranges and defaults of `src/templates/settings.hpp`), Copyright (c) 2025 Carlos Lopez Jr. | MIT | `runtime/shaders/hdr_tonemap.frag` and `runtime/shaders/hdr_encode.comp` (compiled into `runtime/hdr_tonemap_spv.h`, `runtime/hdr_encode_spv.h`); the HDR settings of `runtime/cfg.c`, `runtime/vk_hdr.c` and `runtime/ui/menu.cpp` | +| RenoDX scene mapper for this game and its PsychoV35 tone mapper: the finite cone response in LMS with its mean, deficit and midpoint chroma, the highlights, shadows and purity grading, the exact fit to the target gamut, the mid grey anchor and tone slope of the game's curve, and the hue clip emulation, ported from HLSL and Slang to GLSL (the paths its scene mapper takes; without eye adaptation) | https://github.com/clshortfuse/renodx @ `59bd6f606a5d105bc6de52627332703c840443be` (`src/shaders/tonemap/psychov/test35.hlsl`, `src/games/zelda-oot-oz/scene_tonemap.slangi`, `shared.h`; setting names, ranges and defaults of its `addon.cpp`), Copyright (C) 2026 Carlos Lopez | MIT | `runtime/shaders/hdr_tonemap.frag` (compiled into `runtime/hdr_tonemap_spv.h`); the HDR settings of `runtime/cfg.c`, `runtime/vk_hdr.c` and `runtime/ui/menu.cpp` | | AMD Display Library (ADL) declarations: `AdapterInfo`, `ADLSingleSensorData`, `ADLPMLogDataOutput`, the `ADL_PMLOG_*` sensor numbers and the `ADL2_*` function signatures | https://github.com/GPUOpen-LibrariesAndSDKs/display-library @ `84c881cb2136f04287eb3af12de00a9e2867aa9e` (`include/adl_structures.h`, `include/adl_defines.h`, `include/adl_sdk.h`), Copyright (c) 2016 - 2022 Advanced Micro Devices, Inc. | MIT | `runtime/perfmon.c` | | Zstandard 1.5.7 (MSYS2 `mingw-w64-ucrt-x86_64-zstd`), static link | https://github.com/facebook/zstd, Copyright (c) Meta Platforms, Inc. and affiliates | BSD-3-Clause | `runtime/resolution.c` (the HeapDef table), `runtime/ov_zstd.c` (the game's zstd frames decoded on the host) | | musl `fma.c`, `fmaf.c` and `scalbn.c`, adapted into one file for the x86-64-v2 build | https://github.com/kraj/musl @ `5a56ad13e1e0790c06122978aad2a14d6b9efc1a` (mirror of https://git.musl-libc.org/cgit/musl), Copyright (c) 2005-2020 Rich Felker and contributors | MIT | `runtime/fma.c` (the correctly rounded fma/fmaf the FP lowering needs on CPUs without FMA3) | @@ -124,6 +126,7 @@ folder's `licenses/` and in each component's own folder. | zlib 1.4 (MSYS2 `mingw-w64-ucrt-x86_64-zlib`), static library | https://zlib.net, Copyright (C) Jean-loup Gailly and Mark Adler | zlib | linked into `NX2navi-Setup.exe` (its unzip) | | mingw-w64 CRT startup code and winpthreads 14.0.0, GCC 16.2.0's `libgcc` (MSYS2 packages), static | https://www.mingw-w64.org, https://gcc.gnu.org | mingw-w64: ZPL-2.1 / MIT / public domain; libgcc: GPL-3.0 with the GCC Runtime Library Exception | linked into `NX2navi.exe` and `NX2navi-Setup.exe` | | NVIDIA DLSS 310.9.1 (`nvngx_dlss.dll`, NVIDIA's own build, unmodified; pinned with its size and sha256 in `tools/dlss_pin.py`) | https://github.com/NVIDIA/DLSS @ `v310.9.1` (`lib/Windows_x86_64/rel/nvngx_dlss.dll`), Copyright NVIDIA Corporation | NVIDIA RTX SDKs License (https://github.com/NVIDIA/DLSS/blob/v310.9.1/LICENSE.txt); licensed for systems with NVIDIA GPUs only | `app//bin/` with `nvngx_dlss-NOTICE.txt`, also in the build kit's `bin/`; `tools/make_game.py` copies both beside the built game, where NGX loads the library (`runtime/vk_dlaa.c`) | +| Vulkan headers 1.4.363 (`include/vulkan/*.h` and `include/vk_video/*.h`, unmodified; the release pinned with its sha256 in `tools/vulkan_pin.py`) | https://github.com/KhronosGroup/Vulkan-Headers @ `v1.4.363`, Copyright 2015-2026 The Khronos Group Inc. | Apache-2.0 OR MIT | the Linux build kit's `toolchain/vulkan-headers/` (the AppImage of `tools/make_appimage.py`) with the repository's `LICENSE.md`; `tools/make_game.py` compiles the runtime against them on the player's PC, ahead of the system's headers. Never in this repository: a build fetches them | | NVIDIA DLSS 310.9.1 for Linux (`libnvidia-ngx-dlss.so.310.9.1`, NVIDIA's own build, unmodified; pinned with its size and sha256 in `tools/dlss_pin.py`) | https://github.com/NVIDIA/DLSS @ `v310.9.1` (`lib/Linux_x86_64/rel/libnvidia-ngx-dlss.so.310.9.1`), Copyright NVIDIA Corporation | NVIDIA RTX SDKs License (https://github.com/NVIDIA/DLSS/blob/v310.9.1/LICENSE.txt), the one licence of the repository's Windows and Linux libraries; licensed for systems with NVIDIA GPUs only | the Linux build kit's `bin/` (the AppImage of `tools/make_appimage.py`, unless made with `--no-dlss`) with `libnvidia-ngx-dlss-NOTICE.txt`; `tools/make_game.py` copies both beside the built game, where NGX loads the library (`runtime/vk_dlaa.c`) | | NVIDIA Streamline 2.14.16 runtime (`sl.interposer.dll`, `sl.common.dll`, `sl.dlss_g.dll`, `sl.pcl.dll`, `sl.reflex.dll`, NVIDIA's own builds, unmodified) and NVIDIA DLSS Frame Generation 310.9.16 (`nvngx_dlssg.dll`, as the Streamline SDK ships it) | https://github.com/NVIDIA-RTX/Streamline, SDK release 2.14.16 (`bin/x64/`), Copyright NVIDIA Corporation | Streamline: MIT; `nvngx_dlssg.dll`: NVIDIA RTX SDKs License, licensed for systems with NVIDIA GPUs only | `app//bin/dlssg/` with both licence texts and `dlssg-NOTICE.txt` (each file's sha256), when the release is made with `tools/make_launcher.py --dlssg`, and the build kit's `bin/dlssg/` with `tools/make_kit.py --dlssg` (the SDK release pinned with its size and sha256 and each file's sha256 in `tools/streamline_pin.py`); `tools/make_game.py` copies them beside the built game, where `nx2navi_dlssg.dll` (this repository's `runtime/dlssg/`, built with the Streamline SDK's MIT headers) loads them (`runtime/vk_dlssg.c`) | | Button prompt art: the 128x128 PNGs of the Input Prompts Pack V7 (`XGamepad`, `P5Gamepad` and `Keyboard_Mouse` styles), unmodified | the pack as licensed to the repository owner; never in this repository | the pack's licence, which allows redistributing these pictures in NX2navi's releases (confirmed by the repository owner, 2026-11-09) | `app//prompt-art/` and the build kit's `prompt-art/` when made with `--prompt-art` (`tools/prompt_art.py`); `tools/pad_prompts.py` draws the game's Xbox, PlayStation, Steam Deck (from the Xbox and PlayStation pictures) and keyboard and mouse prompts from them on the player's PC | diff --git a/docs/README-BuildKit.md b/docs/README-BuildKit.md index 481e2439..2c1ed488 100644 --- a/docs/README-BuildKit.md +++ b/docs/README-BuildKit.md @@ -13,7 +13,7 @@ downloads included, and keeps the game up to date. This page is the same build b NVIDIA). - Your own dump of the game as a `.nup` file (or its `exefs` and `romfs` folders), with the 1.1.1 update: program `0400486024DEC000`, main build `e0f3ccfa`. Other versions are refused. -- About 30 GB free on the disk you build to, besides the dump. +- About 34 GB free on the disk you build to, besides the dump. ## One-time setup (about 15 minutes) @@ -58,7 +58,7 @@ last draws the Xbox, PlayStation, Steam Deck and keyboard and mouse button promp meanwhile. If it stops, run the same command again: finished steps are skipped. When it says `finished`, start `C:\Games\Ocarina\ocarina.exe`. You can delete `C:\Games\Ocarina\build-cache` (about -5 GB) afterwards. +1.5 GB) afterwards. ## Linux @@ -78,6 +78,17 @@ RADV). It takes clang, clang++ and lld from `PATH` and links against the system' (GPL-2.0): `pip install --user zbic`, or in a virtual environment with the packages above. Vulkan Memory Allocator is one header: the system's (AUR `vulkan-memory-allocator`), else the build fetches the pinned 3.4.0 into `toolchain/vma/` and checks its hash. + The Vulkan headers must be release 363 (1.4.363) or newer: the runtime names extensions that older headers do not + declare (`VK_KHR_pipeline_binary` among them), and distributions with long support package older ones. The + AppImage carries the pinned headers (`toolchain/vulkan-headers/`, `tools/vulkan_pin.py`) and builds against them + whatever the system has; a build from a kit or a source checkout uses the system's when they are new enough and + otherwise fetches the pinned ones there once and checks their hash. The loader's library still comes from the + system (`vulkan-icd-loader`, `libvulkan-dev`, `vulkan-loader-devel`). + The compiler is the system's too. The releases are built with clang 23; an older one works as far as it compiles + the runtime (one without `#embed`, before clang 19, takes the menu's font from a header the kit carries). Before + its long steps the build checks every runtime source with that compiler and links against the libraries, so a + compiler, a header or a library it cannot use stops it in the first seconds, with the compiler's own words, and + not after the RomFS image. 2. The shader translator: a kit with `bin/nx2navi_xlate` has it; from a source checkout, build it once with `python tools/build_xlate.py` (needs the .NET 10 SDK). The build copies it beside the game. A kit also carries the @@ -133,8 +144,9 @@ switches at once, with a *DLSS multiplier* of 2x to 6x (above 2x on RTX 50 cards frames needed to reach the display's refresh rate (`framegen = dlss` and `fg_mult` in `nx2navi.ini`). The log says `ngxfg: DLSS Frame Generation available` when NGX found the library. -`tools/make_appimage.py` packs this kit into one `NX2navi-Linux--x86_64.AppImage` with its own Python, for -players without a source checkout: it checks for the packages above, installs zbic with pip on its first run, picks +`tools/make_appimage.py` packs this kit into one `NX2navi-Linux--x86_64.AppImage` with its own Python and the +pinned Vulkan headers, for players without a source checkout: it checks for the packages above (their Vulkan headers +are not needed), installs zbic with pip on its first run, picks `--jobs` from the memory, builds into `~/Games/Ocarina` (or the folder given after the dump) and writes `play.sh` beside the game. @@ -149,14 +161,18 @@ beside the game. driver keeps the prepared shaders' libraries in that cache, and a smaller limit drops the oldest as new ones come in (a 2048 MB cache could not hold them): every start then builds them again in the background, and play stutters, with some things missing for a few frames, until that is done. The log's `library warm` lines say when this happens. +- With 16 GB of RAM, give Windows a fixed page file whose initial size is at least 32 GB (System, About, Advanced + system settings, Performance Settings, Advanced, Virtual memory: untick the automatic management, Custom size with + an initial size of 32768 MB or more, Set, then restart). Windows counts the game's video memory + against RAM plus page file, and a page file Windows sizes itself grows too slowly for Hyrule Field: the game then + lets textures go and the ground can flash white or black. The log says `system commit low` when this happens. - **Screen** in the menu has Texture filtering (anisotropic, up to 16x, at once), Texture detail (Reduced and Low leave out the largest versions of the big surface textures so that the game fits the video memory of 6 and 8 GB cards; Automatic picks by the card), Upscaling (DLSS on NVIDIA RTX cards, FSR 3.1 on any card where `amd_fidelityfx_vk.dll` loads, FSR 4 on the Radeon cards AMD's FSR 4 libraries list it for), Frame generation (NVIDIA DLSS on RTX 40 and 50 cards, with a DLSS multiplier of 2x, or 3x and 4x on RTX 50 cards; FSR 3.1 on any card where it loads; it needs DLSS or FSR 3.1 - upscaling on, and the frame limit then counts the frames on screen; with no limit chosen it is the display's refresh - rate), HDR (the game's picture tone mapped to your display, with its own grading rows, or Native, the game's own HDR; turn HDR on in Windows first) and the + upscaling on; the frame limit counts the frames the game draws and the generated ones come on top), HDR (the game's picture tone mapped to your display, with its own grading rows, or Native, the game's own HDR; turn HDR on in Windows first) and the resolution. A setting that takes effect only when the game starts again says "after restart" once you change it, until you set it back, and the Restart button at the bottom then counts the settings waiting for it. - **Controls** in the menu has Button prompts: the game's own, or Xbox, PlayStation, Steam Deck or keyboard and mouse ones when diff --git a/docs/architecture.md b/docs/architecture.md index 69b58511..eada8886 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -45,6 +45,8 @@ from other projects, with its license, is listed in [THIRD_PARTY_NOTICES.md](../ order it logged them: a line waits for the queue's lock, and one that finds the queue full is written after everything queued before it. A fatal error, the crash report and the end of the process write the queue out first (`rt_log_sync`). `NX2NAVI_LOG_ASYNC=0` writes each line where it is logged. +- Co-op (`coop.c`, `coop_proto.c`, [coop.md](coop.md)): a host thread with a UDP socket to a relay (`tools/coop_relay.py`), + rooms of up to 8 players and a channel for messages between them; it never holds a virtual core. - OS calls the host makes go through `runtime/platform/` (`platform.h`, `win32.c`). #### Threads and cores @@ -128,10 +130,39 @@ keeps per-core data without locks and relies on that, so the host models it (`ru their stand-in, and the frame's later refreshes skip them (`runtime/vk_exec_draw.c` `pool_refill`). An area load spreads over several frames instead of holding one for 200-400 ms. - Mesh and task shaders run as `VK_EXT_mesh_shader`; indirect mesh draws read NVN's `{count, first}` record through a - ring of Vulkan `{x, y, z}` records filled on the GPU. + ring of Vulkan `{x, y, z}` records filled on the GPU. The copy cannot be recorded inside a pass, so the first such + draw of a pass fills the records of the mesh draws that follow it too, and the pass is not cut at each of them + (`runtime/vk_exec_draw.c` `mesh_ring_entry`). +- Mesh fallback (`mesh_fallback`: `auto` on a device without the extension, `1` on any device for testing): the task + and mesh stages run as compute dispatches and the result is drawn as ordinary triangles. + - The modules come from the translations the shader cache already holds, not from the translator + (`runtime/mesh_fb.c`): a translated task or mesh module is the program as a compute function over shared memory + plus an entry function that hands that memory to the mesh pipeline, and the fallback replaces the entry function + by one that copies the memory into a storage buffer. The translator, its identity and every cache key stay as + they are, so a device with mesh shaders keeps its shaders and never sees these modules, and a device without + needs no other cache or prepared shader list. + - A draw is: its record (the workgroup count, copied on the GPU when the game's record holds it); the task + dispatch, which writes each task workgroup's payload into the task buffer; a scan (`shaders/meshfb_scan.comp`) + that lists the mesh workgroups the tasks started, in task order, and writes their number into the record; the + mesh dispatch, which writes each workgroup's vertex lines and primitive bytes into its slot of the mesh buffer; + and an instanced indirect draw, one instance per slot, whose generated vertex stage looks the vertex of each + primitive corner up in the slot (`runtime/vk_exec_draw.c` `mfb_draw`, `runtime/vk_mesh_fb.c`). + - Each step reads what the one before wrote, so full barriers stand between them and every such draw ends its pass: + a village frame's 45 mesh draws are 45 passes cut, 90 to 135 dispatches and about 270 barriers more than with mesh + shaders. The buffers (`mesh_fallback_mb`, 128 MiB) are reused by every draw, so they hold the largest draw, not + a frame; a draw that emits more loses what does not fit, and the log says how much it needed. + - A program's modules and compute pipelines are made on a thread of their own at its first draw, which is skipped + until they are ready; they are not recorded for the next start, where the pipeline cache makes them quick. + Not carried: the far shadow cascades' coarser shading rate, a draw's first workgroup other than 0, and more + workgroups in one draw than one compute dispatch may have. - Pipelines: `VK_EXT_graphics_pipeline_library` where the driver has it: stage libraries compiled ahead, a fast link at a new state, an optimised pipeline replacing it from a background thread. A draw whose pipeline is not ready is - skipped when one of its pass's targets was rendered in the previous frame, and waits otherwise. Three things keep + skipped when its pass is one the game renders frame after frame: one of its targets was rendered in the last few + frames, or in eight frames or more at any time, which keeps the first frame after a loading screen from reading as + all new (`runtime/vk_target_frames.h`). A draw into a target rendered for the first time, and a full-screen draw, + wait instead, from one pool of 50 ms a presented frame (`pipe_frame_wait_ms`; `runtime/vk_exec_draw.c` + `prepare_draw_ex`, `frame_wait`); what is not ready when the pool is spent is skipped and built on a worker, so no + frame waits for pipelines much longer than that. Three things keep that short on a first visit (`runtime/vk_pipeline.c`): a pipeline whose fragment shader reads a target of its own pass is fast-linked like any other, the feedback loop flags being part of the fragment output library alone (`gpl_feedback`); the library workers also link the pipelines of skipped draws, so a burst of new materials is @@ -146,12 +177,19 @@ keeps per-core data without locks and relies on that, so the host models it (`ru is built ahead only when a run has dispatched it: a pipeline of one holds about 100 MiB of device memory whether it is used or not, also after it is destroyed, and the list has about twenty of them that the game never dispatches (`runtime/vk_pipeline.c`, "compute pipelines the boot keeps"). + The pipeline cache is two files beside the game. `pipeline-cache.bin` holds what the preparation built and what + earlier runs made; what a run compiles goes into `pipeline-cache-play.bin`, so one new pipeline in play writes a + small file and not hundreds of megabytes. A cache is written only when its data grew. The small file is merged + into the large one at a start once it reached `pipeline_cache_play_mb`, and by every preparation; the stage + libraries the library warm builds in play go to the driver's own cache alone (`runtime/vk_pipeline.c`, "the play + cache", `cache_save`). - The game's tensor-core upscaler is replaced by a decode-and-scale pass (`vk_tonemap.c`); `vk_fsr.c` runs AMD FSR 1 (EASU, RCAS) on the present when the window is larger than the picture. - HDR (`vk_hdr.c`): the game tonemaps its scene into a float target, upscales it, draws the HUD into a second float target and copies that into the 8-bit sRGB window texture it presents. With `NX2NAVI_HDR=1` the tonemap shader gets the function of `shaders/hdr_tonemap.frag` spliced in where its SDR curve clamps each channel, so the float picture - holds the HDR picture relative to the HUD's white; the game's FSR 1 pass loses its output clamp; the present reads + holds the HDR picture relative to the HUD's white (the function gets the values the curve takes, and the scene + before the game's exposure gain with that gain, which its default tone mapper anchors mid grey on); the game's FSR 1 pass loses its output clamp; the present reads the float picture in place of the window texture and `shaders/hdr_encode.comp` writes PQ for an HDR10 swapchain. `NX2NAVI_HDR=native` reports an HDR10 display to the game, which then renders and presents its own PQ picture. The menu switches between off and `1` during a run: the splice, the HDR extensions and the settings in the support diff --git a/docs/audio-input.md b/docs/audio-input.md index ef51d705..00321082 100644 --- a/docs/audio-input.md +++ b/docs/audio-input.md @@ -4,24 +4,27 @@ The runtime connects Ocarina's polling `nn::audio` input calls to SDL3's default microphone or audio interface as the operating system's default input and enable the game's microphone control. Both a hummed note and an instrument received by that input go through the game's own note recognition. -Audio capture opens when the game calls `OpenInputStream` and starts only on `StartInputStream`. The runtime does -not write recordings to disk. SDL converts the input device's format to the requested PCM format and sample rate. +At `OpenInputStream` the runtime checks that a default input exists and prepares a buffer. It opens the recording +device at `StartInputStream` and releases it at stop or close. After a stop, the game can still read or purge the +buffered frames and start capture again. Recordings stay in memory. SDL converts the input device's format to the +requested PCM format and sample rate. The capture callback uses a bounded ring: unread overflow drops the oldest complete frames instead of retaining an unlimited recording while the game is paused. Stop, purge and close are distinct operations. Purging an unopened or failed stream is safe, including the null-stream path that previously crashed in `InputStreamImpl::Purge`. This implements the non-event polling overload used by Ocarina 1.1.1. Event-based streams, per-device selection, hot-unplug recovery and packed 24-bit PCM are not implemented. Statistics return a neutral 24-byte structure. -Unsupported formats and a denied or missing recording device return an input error rather than reporting a -successfully opened stream. Input currently follows the operating system's default recording device; there is no -new runtime menu setting. +An unsupported format or missing default device returns an error at open. If the device disappears or access is +denied when capture starts, start returns an input error and the game can retry. Input follows the operating system's +default recording device; there is no new runtime menu setting. ## Validation `python tests/audio_input_check.py --toolchain C:/msys64/ucrt64` builds and runs headless checks using SDL's dummy -audio driver. They require no game files and do not open a physical microphone. They cover sample ordering across -ring wrap and overflow, frame counts, start/stop, repeated open/close, purge, unsupported formats and purge/read -after a failed open. On Linux, omit `--toolchain` and install SDL3's development package and pkg-config. +audio driver. They require no game files or physical microphone. They check that idle streams leave the device +closed, that a denied start can be retried, and that stopping one stream releases its device and preserves unread +frames. They also cover ring wrap and overflow, frame counts, repeated open/close, unsupported formats and +purge/read after a failed open. On Linux, omit `--toolchain` and install SDL3's development package and pkg-config. A separate local real-device check received mono signed PCM16 at 48 kHz, verified the 4800-frame ring remained bounded, and opened and closed the device three times. In an Ocarina 1.1.1 Windows session built from the 0.5.0 diff --git a/docs/building.md b/docs/building.md index 8237793c..d23f171b 100644 --- a/docs/building.md +++ b/docs/building.md @@ -24,7 +24,7 @@ Versions are the ones the build was verified with; newer patch releases are fine MSYS2 packages, after `pacman -Syuu` (run it twice; the first pass updates the core and exits): ```sh -pacman -S --needed --noconfirm mingw-w64-ucrt-x86_64-{clang,lld,ninja,gcc,make,pkgconf,sdl3,opus,libvpx,zstd,vulkan-devel,\ +pacman -S --needed --noconfirm mingw-w64-ucrt-x86_64-{clang,lld,ninja,gcc,make,pkgconf,sdl3,opus,libvpx,dav1d,zstd,vulkan-devel,\ vulkan-memory-allocator,vulkan-validation-layers,shaderc,spirv-tools} base-devel git unzip ``` @@ -94,6 +94,9 @@ of them. .venv\Scripts\python tools\build_game.py --version ``` + The menu's font comes into `runtime/ui/menu.cpp` with `#embed`; for a compiler without it (before clang 19, which + a Linux build with the distribution's compiler can meet) the same step writes the font's bytes as + `runtime/ui/roboto_ttf.h` (git ignores it), which `menu.cpp` then includes. The runtime's own shaders (upscaling, HDR, texture decode and the like) are in the repository as source only: GLSL and SPIR-V assembly in `runtime\shaders\`, and two small ones assembled by `tools\make_dlaa_mask.py` and `tools\make_mvobj_fs.py`. `build_game.py` compiles them into `runtime\_spv.h` (git ignores these) before it @@ -155,6 +158,28 @@ of them. version; they build at their first draw instead, another driver version builds them again, and so does deleting the file. + What this step leaves for play, and the shared pipeline list. The step translates every shader's default variant + and the shader list's variants and builds each one's stage library or compute pipeline. A whole graphics pipeline + is built ahead only at the start of a game folder that has drawn it before (`pipeline-keys.bin`); a pipeline met + for the first time is linked from its stage libraries in 2 to 6 ms, except a mesh pipeline, which has no libraries + and compiles whole (0.2 to 1.1 s, its draws left out of the picture meanwhile). `tools/pipeline_list.py merge` + folds the `pipeline-keys.bin` and `shader-answers.bin` of game folders that were played into a pipeline list; + `prepare_shaders.py` reads it from `tools\data\pipeline_list.bin` (`data\pipeline_list.bin` in a release folder, or + `--pipeline-list`), adds the shader variants it names to the seed and writes its records next to the game as + `seed-pipeline-keys.bin`, and `--prepare-shaders` builds the mesh pipelines among them into the pipeline cache and + the driver's (`runtime/vk_pipeline.c` `seed_pipelines`; `NX2NAVI_PREPARE_PIPELINES=all` builds the vertex pipelines + too). `--warm-shaders` builds them again, and `nx2navi.exe --prepare-pipelines` does that step alone. The list is + derived from game data: it is not in the repository (`tools/check_content.py` refuses it), and a kit, a launcher + release or an installer release takes one with `--pipeline-list` (`tools/make_kit.py`, `make_launcher.py`, + `make_release.py`). A list belongs to the record layout of the runtime that wrote it; another runtime says so and + builds nothing from it. `python tests\pipeline_list_test.py` checks the tool on made-up folders. + + What a game folder's shader cache holds can be checked without the game: + `python tools\validate_shader_cache.py \shader-cache` reads every translated shader from the pack and + the loose files, applies the checks the game makes when it loads one (those that fail are translated again at + their next use) and runs `spirv-val` on the rest; `--every N` samples, `--out FILE` lists the failed ones. It writes + nothing to the cache. `python tests\validate_shader_cache_test.py` checks the tool on a made-up cache. + 7. Run. The game keeps running when its window loses the focus (`assume_focus = 1` in `nx2navi.ini`, the default; the Game tab switches it). With 0 it pauses, as it does on the Switch when Home is pressed. @@ -213,12 +238,16 @@ Requirements: - Packages on Arch: ```sh - pacman -S --needed clang lld ninja make sdl3 opus libvpx zstd vulkan-headers vulkan-icd-loader \ + pacman -S --needed clang lld ninja make sdl3 opus libvpx dav1d zstd vulkan-headers vulkan-icd-loader \ vulkan-validation-layers shaderc spirv-tools dotnet-sdk uv git ``` Vulkan Memory Allocator is a single header (AUR `vulkan-memory-allocator`). Without it, `build_game.py` fetches the version the Windows release pins (3.4.0) into `toolchain/vma/` on first use and checks its hash. + The Vulkan headers must be release 363 (1.4.363, the one MSYS2 supplies on Windows) or newer: the runtime names + extensions older headers lack. Where the system's are older, `build_game.py` and `make_game.py` fetch that release + into `toolchain/vulkan-headers/` on first use, check its hash and put it ahead of the system's (`tools/vulkan_pin.py`, + `build_game.py` `vulkan_include`). The steps are the Windows ones with POSIX paths: `.venv/bin/python` in place of `.venv\Scripts\python`, and `nx2navi` in place of `nx2navi.exe`. `build_game.py` takes clang, lld and Ninja from PATH (or the ones in `/bin` with @@ -249,17 +278,33 @@ writes come back at its fence. Pages both sides write keep a base copy, so each a VRAM mirror's write-back merge marks the pages it changed, and only those are compared at the fence; a lookup that reads guest memory itself (the uniform snapshot, `vk_mem_lookup`) does not queue its pool for the copy-in. In Kokiri Forest (1.1.1, RTX 4090) that costs about 1 ms a frame (copy-in 0.5 ms, write-back 0.6 ms), and the copies hold about -5 GB. `NX2NAVI_SHADOW=1` turns it on under Windows too. The Steam Deck's RADV has `VK_EXT_external_memory_host` as +5 GB. The GPU's bytes reach guest memory in the fence's completion callback, later than an import's, so the wait +after a frame's first submission covers the write-backs there (`runtime/vk_sync.c`, "the executed timeline"): the game +rewrites what those passes wrote without a fence, and a write-back that landed after the rewrite left the GPU adding +light onto its own last output, the whole scene brighter for a frame. `NX2NAVI_SHADOW=1` turns it on under Windows too. The Steam Deck's RADV has `VK_EXT_external_memory_host` as well: the shadow copies are chosen for the measured cost above, not for a missing extension. The device address table (`runtime/vk_gpa.c`) names a pool's shadow copy as it names an import, so shaders follow guest pointers into either. A shader that reads through the table resolves nothing, so the pool it reaches is not queued for -the copy-in: a part whose pipelines declare the table is marked at its draws and dispatches, and its prologue brings -the shadow of every pool in the table up to date with the pages the CPU wrote and queues the same pages for those -pools' VRAM mirrors (`vk_memory.c` `vk_mem_gpa_sync`). That copies the written pages of every CPU-visible pool in -each such part, which the cost above does not include. What a shader stores through the table into a shadow copy does -not come back to guest memory. `--probe-vkmem` checks the read: a shader follows the table to a word of a pool that is -never bound, and must read `0x13579BDF` and, after a plain CPU write, `0x2468ACE0`. On Linux, run it for each backing: +the copy-in: a guest submission whose record binds the table (`vk_exec_draw.c` `ssbo_info`) brings the shadow of +every pool in the table up to date with the pages the CPU wrote, once, before the first part recorded after the +binding is submitted, and queues the same pages for those pools' VRAM mirrors (`vk_memory.c` `vk_mem_shadow_sync`). +That copies the written pages of every CPU-visible pool once in each such guest submission, which the cost above does +not include. What a shader stores through the table lands in the shadow copy +and in the pool's VRAM mirror, and no binding names it, so nothing notes it as a GPU write: it does not come back to +guest memory, and the next whole copy-in of its page (the CPU rewrites other words of the same records) puts guest +memory's stale bytes back over it in both copies. In the runs measured so far that copy-in always came before the +frame's stores, which does no harm. `NX2NAVI_SHADOW_TABLE_STORES=1` keeps the stores instead: the copy-ins then keep a +hash of each page they write, a page whose shadow no longer matches its hash was stored into, keeps a base copy from +then on like a page with a noted GPU write, and has its stores written back to guest memory at the fence of every +submission that uses the table. It is off by default (`runtime/vk_memory.c`, "Pages a shader stores into", says why). +`NX2NAVI_SHADOW_CHECK=1` logs every 60 frames how often a copy-in overwrote such a store and for which pools, how many +write-backs landed on pages the CPU had written since their copy-in, and what the copy-ins cost and where they went. +`--probe-vkmem` checks the sync: the shadow of a pool that is never bound must hold `0x13579BDF`, keep it through a +plain CPU write and a guest submission that does not bind the table, and hold the written `0x2468ACE0` after one that +does; and with `NX2NAVI_SHADOW_TABLE_STORES=1` the store: a GPU +write into a shadow page that nothing notes must survive the CPU's writes of that page and reach guest memory. On +Linux, run it for each backing: ```sh for shadow in 0 1; do for memory in import mirror; do @@ -278,6 +323,13 @@ Before a commit: `git config core.hooksPath .githooks` runs it before each local commit. - `build\\nx2navi.exe --selftest`: layout, dispatch table and host-function registry, without game files. +GPU page faults: `NX2NAVI_VA_REPORT=1` keeps the driver's GPU address bind/unbind reports +(VK_EXT_device_address_binding_report, `runtime/vk_vaddr.c`); `=2` also keeps the host call stack of ranges of 1 MiB +or more. After a lost device, the log names the reports whose range covered each faulting page, or the nearest ranges +when none did, and `vaddr-history.txt` beside the log holds the whole history. Stack frames are module offsets: add +the executable's load address (the link map's base) before looking them up in `ocarina.map`. Each bind and unbind +costs a callback, and `=2`'s stack walks enough to hide a timing-dependent fault. + A change to the in-game menu's look (`runtime/ui/menu_skin.cpp`, `option_rows.cpp`, `perf_panel.cpp`) can be looked at without game files: `python tools/menu_preview.py` builds the menu's own drawing code with the host's clang++ and writes the Screen tab, the full performance overlay and the boot screen to `build/menu-preview/` (`menu.png`, @@ -299,6 +351,13 @@ A change to the step Ocarina is given each frame (`runtime/frame_rate.c` `ocarin display times: a held 60 fps limit gives exactly one frame every frame, a 240 fps limit never less than a quarter frame, uneven frame times one steady step, and game time follows the clock. No game files. +A change to the mouse camera (`runtime/mouse_direct.c`, the mouse path of `runtime/input.c`, the set `mouse_direct` of +`recomp/patches-v111.txt` or `patches-v143.txt`) passes `python tests\mouse_direct_check.py --cc --deps +\include`, which builds `mouse_direct.c`, and `input.c` with `--deps`, with the rest of the runtime stubbed and +calls the camera hooks as their patch sites do, for each game version: the registers a site hands over and gets back, +the same turn for the same mouse distance at every frame rate and stick camera speed, a single count, the idle bit, the +pause after a camera reset, the capture and the mode, and scripted mouse counts. No game files. + A change to which waits a signalled event or an ended thread wakes (`runtime/kernel.c` `wake_sync_waiters`, the `WaitSynchronization` service) passes `python tests\sync_wake_check.py`, which builds `kernel.c` with the platform layer and the rest of the runtime stubbed and runs guest threads whose entries are host functions: a signal wakes the @@ -316,12 +375,92 @@ instead of timing one. No game files. A change to the button prompts (`tools/make_romfs_patches.py --prompts`, `tools/button_icons.py`) passes `.venv-py314\Scripts\python tests\romfs_prompts_test.py`, which runs the tool on a RomFS it makes itself (no game -files); a change to the settings passes `nx2navi.exe --probe-cfg`. +files); a change to the settings passes `nx2navi.exe --probe-cfg`; a change to the co-op layer (`runtime/coop*.c`, +`tools/coop_relay.py`) passes `python tests\coop_relay_test.py` and `nx2navi.exe --probe-coop` ([coop.md](coop.md)). + +A change to the action prompt's diamond of face buttons (`runtime/action_prompt.c`) or to the SARC and zstd dictionary +helpers (`runtime/sarc.c`) passes `python tests\action_prompt_check.py`. It builds them alone, with the +undefined-behaviour sanitizer, on a layout file, archives and dictionaries it makes from the format `action_prompt.c`'s +header comment describes, and checks that: + +- by label every place, cross, flip and bubble moves and no other byte, in every copy of the layout in the archive; +- a second run changes nothing, and by label then by position gives the game's file back; +- a file that is not the expected one is refused and left as it was: one value off, half laid out, one copy of four, + damaged offsets, a pane record laid over the records that lead to another field, more than 16 copies, copies that + share some of their bytes; +- the packed file names the dictionary the original named, found by its id in the pack of dictionaries. + +No game files. `--romfs ` also runs it on the game's own archive: four copies laid +out, 208 fields, the same dictionary and unpacked size, and no byte changed outside the layout's copies. A change to what the library warm logs when the driver's cache of stage libraries is cold (`runtime/vk_warm_hint.h`, `runtime/vk_pipeline.c` `lw_main`) passes `python tests\warm_hint_check.py`, which builds the header alone and checks the added text by GPU vendor and by why the cache was cold. No game files. +A change to how a run ends when the GPU device is lost (`runtime/vk_device.c` `vk_device_lost_check`, the checks of +`vk_lost` in the replay, upload and present paths, `runtime/vk_sync.c` `completion_main`) passes +`python tests\device_lost_check.py `, which runs the executable's `--probe-devlost`: with the device marked +lost no completion callback runs and the submit, upload and wait paths return at once, and four threads that report a +loss at the same moment end the process with exit code 72, one device report and one FATAL line. It needs a Vulkan +device and opens no window; the device is not really lost, so what a driver answers after a loss is not covered. +`device_lost_at = ` in `nx2navi.ini` ends a real run the same way at its n-th hand-over to the GPU queue. + +A change to the memory gate of the background pipeline builds (`runtime/vk_build_gate.h`, `runtime/vk_pipeline.c` +`gate_enter`) passes `python tests\build_gate_check.py []`, which builds the header alone and checks what it +admits and refuses and that builds under way count through their reservations. With the executable it also runs +`--probe-buildgate` (no device, no window, no build) with the settings in effect, with `build_free_mb = 0` and with a +value no machine has free. What the builders do when they are refused (`warm_builder`, `pipe_worker`, `lb_worker`, +`lw_worker`) shows in a run's log: start the game with `build_free_mb` set above the machine's free commit and read the +`vk_pipeline:` lines that name the commit headroom. + +A change to when the pipeline caches are saved in play (`runtime/vk_save_retry.h`, `runtime/vk_pipeline.c` +`autosave_once`) passes `python tests\save_retry_check.py`, which builds the header alone: a save for new content, none +without, and after a save that did not happen a bounded row of tries at the save interval. + +A change to how FSR 3.1's pipelines reach the pipeline caches (`runtime/vk_ffx.cpp` `vk_ffx_proc_addr`, +`runtime/vk_pipeline.c` `vk_pipeline_create_foreign`) passes `python tests\ffx_cache_check.py `. It runs +`--probe-ffx-cache` (one upscaling context on the device; no window, no game) twice on pipeline cache files of its own +and once with `ffx_pipe_cache = 0`: the library's pipelines must come through the runtime's creates, the second run +must compile none of them, and with the setting off none may come through. The executable needs +`amd_fidelityfx_vk.dll` beside it; without it the probe and the test skip. The graphics driver's own cache can serve +the first run too, so to see the files alone do it, run the probe from a copy of the executable under a name the +driver has not seen: its first run compiles, its second does not. + +A change to the start's memory warning (`runtime/mem_need.h`, `runtime/memory.c` `mem_start_note`) passes +`python tests\mem_need_check.py []`, which builds the header alone and checks when the game's need counts +as short. With the executable it also runs `--probe-memneed` (it prints the machine's commit and the answer and +starts nothing) with `mem_need_mb` at 0, at 1 and at a value no machine has, and reads the warning line of the last. +A change to how `pipeline-cache.bin` is read (`runtime/vk_cache_file.h`, `runtime/vk_pipeline.c` `cache_load`) passes +`python tests\pipeline_cache_file_check.py`, which builds the header alone and reads a sparse file just over 2 GB +through it: measured and read whole without a size limit, refused by its real size under one. No game files, no GPU; +about 2 GB of memory for a few seconds. + +A change to the layout of `shader-prepared.bin` (`runtime/prp_file.h`, `runtime/gfx_shader.c` +`gfx_shader_prepare_seed`, `tools/make_game.py` `prepared_from`) passes `python tests\prp_file_check.py`, which builds +the header alone, checks the parse of both versions and has `make_game.py` read the list the C side wrote. No game +files, no GPU. + +A change to where the lazy write-back is on by default (`runtime/wb_lazy_choice.h`, `runtime/vk_memory.c` +`vk_mem_lazy_decide`) passes `python tests\wb_lazy_check.py`, which builds the header alone and checks the choice and +its reason by platform, by GPU driver and by what the player set. No game files, no GPU. + +A change to what writes `nx2navi.ini` outside the game (`launcher/gameini.py`, `installer/ini.py`, `tools/make_game.py`, +`launcher/updater.py`) passes the settings-file tests of `tests\launcher_test.py` (`PlayerIniTest`, and the tests named +`..._settings_file` of `BackgroundUpdateTest` and `MakeGameTest`): a player's file with lines that are no settings of +the game comes through an update and a rebuild byte for byte. The game's own writer, the settings menu, is checked by +`--probe-cfg` with the same lines. + +A change to the mouse camera's stick deflection (`runtime/input_map.c` `input_mouse_stick`) passes +`python tests\mouse_stick_check.py`, which builds that file with the rest of the runtime stubbed and checks the +deflection at each camera speed: a slow movement is divided by the factor, a fast flick reaches full tilt. No game +files. + +A change to which render passes count as drawn frame after frame (`runtime/vk_target_frames.h`: a draw into one is +skipped while its pipeline builds, a draw into any other waits) passes `python tests\target_frames_check.py`, which +builds the header alone and replays an area change after a loading screen from a player's log: the scene, probe and +half-resolution passes are per-frame again at once, a lookup table, a volume's slices and an icon capture still wait, +and an image taken over by another texture starts without the history of the one before. No GPU, no game files. + The lifter (`recomp/`) and the CPU headers (`runtime/cpu.h`, `runtime/simd.h`) are checked against Unicorn. Every lifter change passes these, all run with `.venv`: @@ -347,6 +486,12 @@ Runtime probes, each a mode of `nx2navi.exe` (the list is at the top of `runtime part of `--probe-vkexec` translate shaders of the census below: they look for `build//shaders/jobs.json` of the exe's own version first, then of the other one. `--probe-vkmem` also checks CPU-backed texture uploads and rewrites, GPU-written texture aliases, and memory write watches. +`--probe-meshfb` (no game files) draws mesh programs of the runtime's own, with and without a task stage and with +direct and GPU-written workgroup counts, through `VK_EXT_mesh_shader` and through the mesh fallback, and compares the +pictures; on a device without mesh shaders only the fallback draws. A change to `runtime/mesh_fb.c`, +`runtime/vk_mesh_fb.c` or the fallback's part of `runtime/vk_exec_draw.c` passes it. With +`NX2NAVI_PROBE_MESHFB_DIR=` it converts the game's own task and mesh translations instead, for `spirv-val` +(the top of `runtime/mesh_fb_probe.c` says what the folder holds). A change to the texture detail (`runtime/vk_texture.c` "texture detail": `detail_skip`, `upload`, `astc_bl_regions`) passes it three times, with `NX2NAVI_TEXTURE_DETAIL` set to `full`, `reduced` and `low`: each time ASTC textures are uploaded and rewritten, and every level and layer of their images must hold the game's level it stands for. diff --git a/docs/controls.md b/docs/controls.md index a5f00305..12747f89 100644 --- a/docs/controls.md +++ b/docs/controls.md @@ -21,6 +21,22 @@ The log names the layout in effect (`input: gamepad layout ...`) and each gamepa (`input: gamepad "...": first press`); the menu shows the layout under *Automatic*. The game's prompts show the Switch letters unless *Button prompts* says otherwise (below). +The action prompt (top right) shows the four face buttons as a diamond. The game draws it in the Switch places (A right, +B bottom, X top, Y left), which `nintendo` keeps. Under `xbox`, `playstation` and `auto` the diamond follows such a +pad instead (A bottom, B right, X left, Y top), whatever *Button prompts* is. + +The game reads the diamond once at start, before a gamepad is open: + +- `auto` gets the Xbox diamond, so a Switch Pro Controller under `auto` sees A at the bottom although its A is on the + right. Pick `nintendo` for that pad. +- A change of layout shows after a restart; until then *Button prompts* says *prompts change after restart*. +- A RomFS mod that changes the action prompt keeps its own diamond. A mod that replaces the same archive for other + reasons gets the diamond moved on top of its changes. + +The log says what happened in a line that starts with `action prompt:`. How the layout is changed: +`runtime/action_prompt.c` (`DoCommand_00` in `UI/Layout2Archive/Common.Product.100.Nin_Ounce_NVN2.blarc.zs`, served +from `/action-prompt/`). + ## Button prompts `NX2NAVI_PROMPTS` (`prompts`, the *Button prompts* row on the Controls tab) picks the buttons the game's prompts show: `nintendo` (default, the game's own), `xbox`, `playstation`, `steamdeck` or `pc` (*Keyboard and mouse*). It changes three things the game draws: @@ -108,14 +124,18 @@ bind_Y = pad:north, key:mouse_l ## Mouse camera -Mouse motion (raw input) becomes right-stick deflection. Each presented frame takes the counts moved since the last frame, divides by the frame time and sets the deflection to `counts per second * NX2NAVI_MOUSE_SENS / 3000` of full, held for that frame, so the turn rate does not depend on the frame rate. This is not mouselook: the game's stick curve and dead zone still apply, so very slow movements do nothing and a fast flick saturates. The mouse deflection competes with the gamepad and arrow keys by the larger-deflection rule. +Mouse motion (raw input) becomes right-stick deflection. Each presented frame takes the counts moved since the last frame, divides by the frame time and sets the deflection to `counts per second * NX2NAVI_MOUSE_SENS / 3000` of full, held for that frame, so the turn rate does not depend on the frame rate. This is not mouselook: the game's stick curve and dead zone still apply, so very slow movements do nothing and a fast flick saturates. With a camera speed other than 1 (`NX2NAVI_STICK_SENS`) the deflection is divided by that factor before it is limited to full tilt: the turn for a given movement stays the same, and the fastest turn a flick reaches is the game's top speed with the factor in it. The mouse deflection competes with the gamepad and arrow keys by the larger-deflection rule. -`NX2NAVI_MOUSE_SENS` (0 to 10, default 1; higher turns faster, 0 turns the mouse camera and the cursor capture off). While the window is the foreground window the cursor is hidden and confined to the client area. It is released on focus loss, minimise, while F11 changes the window, during a size or move loop and while a text entry is open. Esc releases it by hand: the cursor shows, the mouse camera and mouse buttons stop, and the window can be moved, minimised or closed. A mouse click inside the client area captures it again; that click does not reach the game. Activating the window by a click on its title bar or border does not capture, so it can be dragged or closed right away; Alt+Tab or a click in the client area captures as before. `NX2NAVI_INPUT=none` disables the capture too. +`NX2NAVI_MOUSE_MODE` (`mouse_mode`, the *Mouse camera* row on the Controls tab, live) chooses that right-stick deflection (`stick`) or mouselook (`direct`, the default). In `direct` the camera's input update (`main+0x37c300`) takes the raw counts itself, after the game's stick dead zone, clamp and response curve (`recomp/patches-v111.txt`, set `mouse_direct`; `runtime/mouse_direct.c` `camera_input_oot`). The camera turns by how far the mouse moved, the same on both axes: about 0.08 degrees a count at `NX2NAVI_MOUSE_SENS` 1, at any frame rate and any `NX2NAVI_STICK_SENS`, with no dead zone and no top speed. The game's own camera sensitivity (its Options) scales the mouse as it scales the stick. A gamepad's right stick and the arrow keys still go through the game's response and add to the mouse. While the game takes no camera input (it switched camera input off, or the pause after a camera reset runs) the mouse is the right stick as above. `NX2NAVI_MOUSE_DIRECT_PATCH=0` turns the patch set off, and the mouse is the right stick whatever the mode. `NX2NAVI_MOUSE_TRACE=1` logs each camera input update (the stick, the counts taken and what they added) and, with `dlaa` on (DLAA, DLSS or FSR 3.1, which read the game's camera), the camera's direction in each frame, for measuring the turn per count. + +`NX2NAVI_MOUSE_SENS` (the *Mouse camera sensitivity* row, live; 0 to 10, default 1; higher turns faster, 0 turns the mouse camera and the cursor capture off, the row goes down to 0.05). While the window is the foreground window the cursor is hidden and confined to the client area. It is released on focus loss, minimise, while F11 changes the window, during a size or move loop and while a text entry is open. Esc releases it by hand: the cursor shows, the mouse camera and mouse buttons stop, and the window can be moved, minimised or closed. A mouse click inside the client area captures it again; that click does not reach the game. Activating the window by a click on its title bar or border does not capture, so it can be dragged or closed right away; Alt+Tab or a click in the client area captures as before. `NX2NAVI_INPUT=none` disables the capture too. `NX2NAVI_STICK_DEADZONE` (0 to 50, default 8) is the gamepad stick dead zone in percent of full deflection, the same for both sticks. It is round: a stick inside the circle reads centred, and the rest of its travel is scaled to start at 0 at the edge, so full deflection still reaches full. Raise it for a stick that drifts. The game's own dead zone applies after it. `NX2NAVI_LSTICK_DEADZONE` and `NX2NAVI_RSTICK_DEADZONE` (the *Left/Right stick dead zone* rows under *Analog sticks* on the Controls tab) set one stick each and fall back to `NX2NAVI_STICK_DEADZONE` while unset, so a worn stick can get a larger zone than the other. With a gamepad connected each row shows its stick's deflection now, before the dead zone (*stick now*): let go of the stick and set the row a few percent above the value it rests at. The stick direction bits (`StickLLeft` to `StickRDown`) are derived from the sticks at 50% deflection. With no gamepad connected the log says `input: no gamepad`. +Keys tilt a stick all the way, so on the keyboard alone Link always runs. `NX2NAVI_WALK_KEY` (`walk_key`, the *Walk key* row under *Analog sticks* on the Controls tab) names a key that, while held, scales the stick values the keys give (movement and camera keys) to `NX2NAVI_WALK_SCALE` of full (`walk_scale`, the *Walk scale* row; 0.2 to 0.9, default 0.51), so Link walks. The value is a key name of the `bind_` lines, or `none` (the default: off). The row offers Shift, Alt, Ctrl, Tab and Caps Lock and names the button a chosen key also presses: with the default bindings Shift is A, Ctrl is B and Tab is Plus, while Alt and Caps Lock are free. The gamepad's sticks and the mouse camera are not scaled. The default is just above half because half of a key's full value falls one short of the 50% the direction bits need. Both settings apply at once while the game runs. + ## Nintendo Switch 2 controllers Windows does not present the Switch 2 Pro Controller as a gamepad SDL can open (the log says `input: no gamepad`), so it needs a bridge program that wakes it and creates a virtual gamepad, for example one that emulates a DualSense: that gives buttons, rumble, gyro and accelerometer. The log then shows `input: gamepad "DualSense Wireless Controller" ... (rumble, gyro and accelerometer, ...)` and `input: motion sensors on`. Bridges that output a DualShock 4 whose gyro and accelerometer never change give buttons and rumble but no motion. Run one bridge at a time; Steam Input can also claim the controller, so close Steam if the bridge does not find it. With several virtual and real gamepads connected the game follows whichever one is pressed. diff --git a/docs/coop.md b/docs/coop.md new file mode 100644 index 00000000..bcfb05b6 --- /dev/null +++ b/docs/coop.md @@ -0,0 +1,618 @@ +# Co-op + +Each player runs their own game and save; the co-op layer connects the games of up to 8 players through a relay. The +game has no multiplayer of its own and its `nn::socket` stays offline: the layer is a host thread of the runtime +(`runtime/coop.c`) with its own UDP socket. + +What exists so far: rooms, the relay, a sealed channel for messages between the players, progress sync (below) and the +menu's Co-op tab (below), which makes, joins, accepts and leaves a room. The other players are not shown in your +world, and where your Link is never leaves your PC ("Other players in the world"). + +## What joining a room means for your save + +Read this before you join a room. + +- **Nothing from a room reaches your game until you accept it.** When you join, the menu's Co-op tab and the log name + the other players (each by the name and the key fingerprint their game signed), the room's rules and the key that + signs them; the tab asks you to accept, and the log gives the room's offer a number: `put coop_accept = 1a2b3c4d + into nx2navi.ini [coop] while the game runs`. Accept on the tab or do that. Until then your game takes nothing from + the room. You accept players by + their keys, not their names: a new player, a player whose game restarted, a removed player who comes back, or a + second player with a name you know is a new offer, and so are a key you accepted that now carries another name (it + is accepted under the name it had when you accepted it), other rules, rules signed by another key, and another + save loaded in the room; nothing more is taken until you accept that one too. A key you accepted that comes back + under its own name as another member number (the relay numbers players as they come) is no new offer; the log says + so, and it says when a member presents another key than the one it was identified by. A player in the room whose game never + says who it is keeps the room from being accepted at all. The number is random for each start of the game, so nobody + can put the right one into a file in advance. Accepting every room without asking (`NX2NAVI_COOP_ACCEPT=always`) + works only from the environment, never from `nx2navi.ini`. +- **Your game takes values only from players you accepted.** What a player you did not accept sends is not kept, not + passed on and never applied, also after that player leaves or is removed. Every message that can change your save is + signed by the player who sent it, so this holds also against someone who knows the room's secret and runs the relay, + or sends from its address on your network: they can make no message in another player's name that changes your save. + For story flags and items acceptance is passed along: a player you accepted hands on what they took from the players + *they* accepted, so a stranger someone else let in reaches you through them. Pools are not passed along: your game + counts in a pool only what you and the players you accepted brought, picked up and spent, and joins the pools only + once you accepted the room (another save loaded in it joins only once you accepted that one too). What remains with + the maker: a player uses the pools at all only once the maker's game admitted them, which it does for every player + the maker accepted; a player who left before you accepted is not counted in your pools; and while a player you + accepted counts a stranger in their pools, what they claimed when they joined a pool counts that stranger too, until + the maker removes the stranger. +- **Your save is copied first.** The moment you accept a room, the game copies your whole save (every slot) to + `coop-backup/` in the profile folder, and takes nothing from the room until the copy is made. The first copy for a + room in each start of the game is `first-` and is kept until you delete it; later copies (another save + loaded in the room, say) are ``, of which the newest eight are kept. A room the relay lost and that the + game reaches again is still accepted and copied. "Going back" below says how to restore a copy. A game that has + not saved yet has no save on the disk to copy: it takes nothing from the room until it has saved once (the log says + so), and a copy that cannot be written keeps the room closed as well. +- **What the room can change in your save** is what its rules share (progress, items, songs, quest items; small keys, + rupees and ammunition in a pool): every value is checked against your game's own table of flags before it is + stored, passed on or applied. A flag can only be set to "done", an item count only up to 999, small keys only up to + 15, a pooled counter only within its capacity. Anything else is dropped, counted in the log, and a player who sends a + few dozen of those is ignored for as long as they stay in the room. +- **What a player you let in can still do.** A player in the room plays with you: with progress shared, what they do + in their world (open a chest, beat a boss, set a story flag) happens in yours, and a player who wants to can send + such flags without playing for them. With small keys in a pool, a player you accepted can spend the keys you share: + their spends count at most up to what entered the pool (what the players brought and picked up), so they can empty a + dungeon's pool, and the keys picked up after that, but no more than the dungeon has, and a record that claims less + than nothing counts as nothing. The maker's removal of that player, also after they left, or a pool reset after they + left, gives back what they took, in every game, and each game makes its claim to the pool again as if that player + had never been in it, so keys you brought while their gains were in the pool stay yours, and a claim made while + their spends were in it does not leave the pool fuller than what the others brought. A pool reset while that player + is still in the room carries what they took into the new pools, and removing them afterwards does not give it back: + remove first, then reset (the reset's log line, the maker's hint and the Co-op tab's Reset the pools say so). Keys a + removed player's gains handed out stay as doors already opened, and in the claim of a player who saved with them and + joined the pools again with that save before the removal. With rupees or ammunition in a pool (off by default) the + same holds for them. + Flags stay set when a player is removed. None of this can be undone inside the game otherwise: go back to the copy + of your save. Invite only people you trust with your save, as you would hand them your controller. +- **Who can get in.** Only someone who knows the room's secret: 18 characters (85 bits) that the game makes when a room + is made and that the maker passes on to the others (by voice, a chat message). The relay never learns it. Someone who + sees your traffic on the network, or who runs the relay, cannot read the messages, change them, make new ones or + guess the secret from them. Someone who also knows the secret can read the room's messages, but can still make none + in a player's name: each player signs what they send with their own key. +- **Removing a player.** The room's maker can remove a player by their key's fingerprint, which the log and the Co-op + tab show beside each member (Remove on the player's row of the tab, or `coop_remove = ` in `nx2navi.ini` + while the game runs; while they are in the room or after they left): the maker's game signs the removal, every game drops that player's key and keeps it + dropped (their messages are ignored, their pool records dropped, so what they took from a pool comes back), and the + relay drops them and refuses them again (the session the maker's game listed for them at that moment, so a player + given the number since is not the one dropped). A member number in the file is not taken, since numbers pass to other + players as members come and go, and each value acts once, so a line left in the file or read again after a moment in + which the file could not be read removes nobody else. Someone who knows the secret can still come back under a new + key (everyone then gets a new offer to accept or not); to be sure, make a new room, which has a new secret. The maker + can also reset the pools (`coop_reset_pools = 1`, then 2 the next time, or 0 and then 1 again): every game joins them + again with what they held for the players in the room, which recovers a pool that a player who left had emptied, + also when the maker resets twice before the games joined again. What a game held at the reset is its claim from then + on, also while that player is at the title screen, so a key another player picks up after the reset comes on top of + it. A player who is not in the room at the reset, or whom the maker has not admitted to the pools yet, is carried + for nobody: what it brought and picked up leaves the other games' pools until it plays again in the room, when its + game joins them with what it holds. If the maker resets again before such a player's game joined, that game keeps + the larger of its two carries, so keys the others used in between can come back (more keys, never fewer). Remove a + player who emptied a pool and is still in the room first (both lines in one save of `nx2navi.ini` act + in that order). The key the maker's game signs the room's rules and + removals with is kept in the profile folder (`coop-keys/`, readable by your account only: the folder 0700, the file + 0600 on Linux; on Windows an access list of its own with your account alone), so a maker whose game restarted is still the room's maker. That file, together with the room's + secret, lets whoever has both act as the room's maker: never hand out a copy of your profile folder. A game that sees + another member present its own key says so in the log (that member stays not identified, so nobody can accept the + room while it is there), and a key file that is damaged or cannot be read is logged too. Deleting the file ends your + say over rooms you made before. + +### Who can see what + +| Who | Sees | Cannot | +|---|---|---| +| The relay's operator, and anyone on the network path | that a room exists (a random id and the locator, a value derived from the secret that does not give the secret back), the players' names, their IP addresses, when and how much they send | read, change or make any message between the players; learn the secret; change anyone's save or the room's rules (moving the relay's maker mark changes nothing for a player who accepted). It can drop, delay and send again what a player sent; a player takes one again only as "Replay" below says. | +| Someone who knows the secret and runs the relay, or sends from its address on your network | all of the above, and every message of the room | make a section, identity, pool record or set of rules in another player's name that a game acts on (each is signed by its maker); change your save other than through a player you accepted, or the rules of a player who accepted. It can also: send a member's messages again (see "Replay": within the last 64 they are refused, but four older ones in a row let it send the member's whole present session again); seal a message in a member's name with a counter far ahead, which costs a player that member's next three messages, each time it does so (one after every three of the member's keeps them out while it keeps sending); send rosters, or identities of another key for a member's session, that keep players from being identified or the room from being accepted while it keeps sending and up to 10 s after; send sections and digests in a member's name that use up what a player checks and takes from that member (128 signatures and 48 KB a second), which delays that member's own while it keeps sending; send digests in a member's name with sums of its choosing (see the sync messages); and, to a player who has not accepted the room yet, make every member's digest carry rules of a key of its own (a member does not sign its digest, only the rules in it are signed, by whoever made them): with no maker in the room, or one it controls, that player's game shows those rules and their key in the offer, so compare that key with the maker's before you accept (step 3 below). None of that changes a save, and none of it lasts longer than said once it stops | +| The other players in the room | your name, your progress (what the rules share), your messages | your IP address (the relay forwards everything), your account or profile (the id the relay knows you by is random for each start of the game and never shown to them) | +| Your log and "Copy system info" | a three-character label hashed from the room's secret (no part of the secret) and the offer's number; system info shows that `coop_room`, `coop_server`, `coop_name` and `coop_accept` are set, not their values | the secret, the relay's address (it appears only with `NX2NAVI_TRACE=coop`) | + +### Going back to your save from before a session + +1. Close the game. +2. In the profile folder, open `coop-backup` and pick the copy to go back to: `first-` is the save as it + was before you first accepted that room, `` a later acceptance (the time is UTC). +3. Delete the folder `save-tx` (it may hold a save that was being written; it would otherwise be finished over the copy + at the next start). +4. Move the folder `save/` aside (keep it until you are sure), and copy the contents of the backup folder into + a new `save/` of the same name. +5. Start the game: every slot is as it was when you accepted the room. Progress made after that, in any slot, is in the + folder you moved aside, not in the copy. + +## The menu's Co-op tab + +The menu (F1, or the pad's combo) has a Co-op tab, usable with the keyboard, the mouse and a pad. + +- **Not in a room:** your name and the relay's address (each row opens a field to type in; with a pad, A on the field + brings up the system's on-screen keyboard where it has one), Make a room, Join a room (a field for the secret, in any + case, with or without dashes, and a Paste button that takes the clipboard's text), a line that says what the layer is + doing or why it stopped (no answer from the relay, no room with that secret, refused), the rules of a room you make, + and the co-op switch. Make and Join turn co-op on when it is off. +- **In a room:** while the room waits for your answer, who is in it (a player whose game has not said who it is, or + whose session two keys present at once, is marked "not identified"; a player whose key you accepted under another + name is marked "a key you accepted as ", and that is a new offer), what its rules share, the fingerprint + of the key that signs the rules, to compare with the one the maker reads out to you by voice or chat, and Accept or + not; while any player is not identified the tab says so and why the room cannot be accepted, and Accept is greyed. + Then the players, with who made the room, how long ago each was last heard and each one's key (and the name you + accepted it as, when it now signs another); the maker sees its own key to read out, and Remove on each other + player's row, which removes by the key (a player who is not identified has no key and is removed by member number, + only while the same session still holds it). The maker also has a Pools group: every key that took more from the + pools than it brought, in the room or not, with what it took and a Remove of that key, and Reset the pools, which + says to remove such a player first. What it took can change, up or down, when the maker removes a player or a + player accepts more keys, also while that player's game is at its title screen. Then the + room's secret, hidden until you press its row, and a row that copies it to the clipboard; the rules (the room's + creator changes them, everyone else reads them; a change is a new offer for everyone); Leave the room. The status + line says when the relay lost the room and the game is getting back into it, and when the relay takes no more joins + from your network and the game tries again in a minute. +- **Nothing is accepted, removed, reset or left by accident.** Accept or not, Remove, Reset the pools and Leave each + open a window whose cursor starts on the safe button (Not now, Cancel, Stay), whenever it opens; only Right reaches + the acting button, and pressing the button that opened the window again, holding it, or a double tap lands on the + safe one. A new player or other rules while the Accept window is open replace what it shows and put the cursor back + on Not now: Accept takes only the offer you read. The window says that your whole save is copied to `coop-backup` + first, and before your first Accept in each start of the game it shows the three warnings of "Before you join a room + with strangers" below. +- **While the menu is closed** a short note at the top of the screen says when a player joined or left the room and + when the room waits for your answer. +- The name, the relay, the rules and the switch are settings (written to `nx2navi.ini` like every row); the secret is + not a setting, is not written to the log, and is shown only when you ask. + +## Running a relay + +``` +python tools/coop_relay.py [--host 0.0.0.0] [--port 24680] [--log-addrs] [--log-joins] [--max-rooms 1000] [--rooms-per-network 8] +``` + +Python 3, standard library only. A player who can reach it by UDP (forward the port on the router, open it in the +firewall) is all it takes; the others put its address into `coop_server`. The relay forwards the sealed datagrams of a +room and can read none of what the players send each other. It keeps only who is in which room, writes nothing to +disk, and loses its rooms when it stops: the room's maker makes it again under the same secret. Its log has one line +per room made, join, leave and removal, with names, member ids and a random room id (never the secret or the locator); +addresses only with `--log-addrs`; a line when a network's joins ran out (at most every 10 s); and with `--log-joins`, +where each network's joins went. + +- A room holds up to 8 players, is closed 10 minutes after the last one left (a minute, if nobody but its maker was ever + in it), and a player the relay has not heard from for 15 s is dropped (the member id is kept for a minute so that the + same game, with its rejoin token, joins again as the same member). +- The roster (who is in the room, each one's session, which one made it) goes out at a change, again 0.25 s and 0.75 s + later, and every 5 s: a datagram is lost now and then, and nothing is acknowledged. +- Limits: a source address answers a cookie challenge before the relay sends it anything larger than it sent; each + member is limited to 200 datagrams and 64 KB per second, a datagram forwarded to seven counted seven times; each + network (an IPv4 /24, an IPv6 /48) to 20 challenges a second, a join every 3 s after a burst of 20, and 8 open rooms; + each room that forwarded to someone in the last 2 s to an equal share of the forwarding (rooms that send nothing, or + send to nobody, take nothing); the relay as a whole to 5000 challenges a second and 8 MB/s of forwarding. A join + attempt costs its network one join whatever the answer, and the same attempt sent again (its answer was lost, or it + asks again for a room that is not there yet) is answered from memory without a charge while the answer is the same + refusal; the game asks for a room that is not there at most every 10 s and, while it keeps its room, waits a minute + when the relay refuses it for its network's joins instead of ending the session, so players behind one address who + wait for a room do not use up each other's joins. The relay keeps the budgets of at most 4096 networks and forgets a + budget that is full again, and checks its own challenge budget first, so a flood from spoofed addresses leaves no + state behind. A member that rejoins with its token from its own address and in its own session needs no challenge; + from another address, or with a new session (every rejoin draws one), it answers one first, so someone who saw its + CONNECT cannot take its place. The challenges for a CONNECT with a member's valid token come from that member's own + challenges (2 a second, 8 at once, kept apart for its own network and for the others), never from its packets, and + from a share set aside for rejoins: 1000 a second split equally among the open rooms for CONNECTs from other networks + than the member's, and 1000 a second split among the rooms and then among the eight member numbers of each for + CONNECTs from the member's own network (each 8 at once at least, so a member can rejoin eight times at once even on + a relay with its full 1000 rooms, and then once every 8 s). So the tokens of rooms someone made to flood with take + only those rooms' shares, and a flood of CONNECTs with a member's token, someone else's or seen on the way, from + another network neither drops the member's messages nor keeps its rejoin from its own network out of the room. What + such a flood can take is the room's share for other networks: a member that comes back from another network (a + phone that changed networks) may wait for as long as it lasts, and so may one whose own network someone sends from + with its token. A game whose roster shows + another session for it joins again, at most once + every 15 s. A session that was in the room before is refused (the last 4096 of each room are kept). A flood from many + networks can still use up the relay's 5000 challenges a second for newcomers: a relay has finite capacity, and its + operator's firewall is the place for more. +- `--host ::` listens for IPv6 as well as IPv4. The game's own socket is IPv4 and IPv6 in one; Windows may show its firewall + prompt the first time the game opens it. + +## Rooms and secrets + +A room is its secret: 18 characters of `23456789BCDFGHJKMNPRSTVWXYZ` (no vowels, no 0/1/O/I/L), typed in any case, +with or without `-` and spaces, shown `XXXXXX-XXXXXX-XXXXXX`. The game makes a new random one for each room it makes; +`coop_room` names one for `coop_auto` (tests, LAN parties). A create of a secret whose room is open on the relay is +refused (it is not a join), so nobody can be put into a room they did not mean to join. + +## Settings + +`nx2navi.ini`, section `[coop]` (`nx2navi.ini.example` has the text); the environment variable is the key with `NX2NAVI_`. + +| Key | Default | | +|---|---|---| +| `coop` | `0` | on or off, at once; off: no socket and nothing running | +| `coop_name` | empty | at most 24 bytes; empty: `Player-` and four random hex digits | +| `coop_server` | none | `host`, `host:port` or `[v6]:port`, default port 24680; with none set the layer stays idle and logs why | +| `coop_port` | `0` | local UDP port, 0 = any; read at start | +| `coop_accept` | `ask` | `ask`: nothing from a room is applied until its offer is accepted; a number (the eight hex digits the log shows, random for each start of the game): accepts that offer, set while the game runs (the file's line as it is now counts before the one read at start); `always`, from the environment only (`NX2NAVI_COOP_ACCEPT=always`; an `nx2navi.ini` line is ignored): every room is accepted (the save is still copied first) | +| `coop_auto` | `off` | `create` or `join` starts a session at launch (a join needs `coop_room`); no menu row | +| `coop_room` | empty | the room secret of `coop_auto`; no menu row | +| `coop_remove` | empty | the room's maker removes a player by its key's fingerprint (in the room or after it left; the relay drops it too while it is in the room); each value acts once; a member number is not taken from the file; the Co-op tab's Remove does the same | +| `coop_reset_pools` | empty | the room's maker resets the pools when the value changes to a new one other than `0` (1, then 2; or 0, then 1 again); the Co-op tab's Reset the pools does the same | +| `coop_drop` | `0` | test: percent of received datagrams thrown away; no menu row | +| `coop_test_set` | empty | test, environment only (`NX2NAVI_COOP_TEST_SET`): `hash=value@frame,...` sets those flags (hash in hex) at those frames of play; an `nx2navi.ini` line is ignored | +| `coop_progress` ... `coop_ammo` | see below | the rules of a room this player makes (Progress sync) | + +With `coop_auto` a room the relay lost (it restarted) is made again under the same secret by its maker, or waited for, +for as long as the session runs (asked for every 10 s; a refusal for the network's joins waits a minute); a maker who +finds it made again by someone else joins it, and the rules stay the ones its key signed. A player who leaves ends the +session. An `nx2navi.ini` someone else gave you can name a room and join it at launch (`coop_auto`, `coop_room`), but +it cannot accept the room for you: that needs the number of this start of the game, or the environment. The game reads +`coop_accept`, `coop_remove` and `coop_reset_pools` from the file as it is now once a second while it is in a room +(never out of one), as it reads the file at start (a BOM, a repeated key's later line, quotes), and skips a reading +when the file cannot be read or is empty for a moment, as while an editor saves it; values in the file at start, and +at the first reading after the start, act on nothing. + +## Progress sync + +When one player gains progress, the others' games gain it too, while they play; a player who joins later catches up +with everything the room has, and the room with what the joiner brings. Each player's own save keeps what it got: the +game saves it as its own progress. + +The game keeps its progress as flags (a database keyed by 32-bit hashes of flag names). Between two frames the runtime +reads the flags that changed, and sets the ones the room has and this game lacks through the game's own set routines, +as if the player had done it. Nothing is read or set while the game is on its title screen, loading a save or changing +scene, and not while its clock stands (the pause menu): what arrives meanwhile is set afterwards. A chest or a door +another player opened shows open the next time the area loads; an item shows in the menu the next time it opens. + +What one room merged belongs to that room and that save: leaving the room, joining another, or loading another save +forgets it. A save loaded while in a room is a new offer: nothing reaches it before you accept again, and the save is +copied again first. Once accepted, it gets the room's progress, and that holds what every save played in the room +brought, the last one's too (the others hold it); no way exists to tell one save's flags from another's in a merged +state, so the new offer and the copy are the answer. + +### What is shared + +| Category | Rule key | Modes (default first) | What | +|---|---|---|---| +| progress | `coop_progress` | `shared`, `own` | story, world and dungeon flags: events, talks, chests, doors, switches, bosses, map and compass | +| items | `coop_items` | `shared`, `own` | equipment, key items, bottles owned, wallet, bag and quiver sizes, magic meter size | +| songs | `coop_songs` | `shared`, `own` | | +| quest | `coop_quest` | `shared`, `own` | medallions, spiritual stones, the stone of agony, the gerudo card | +| keys | `coop_keys` | `pool`, `own` | small keys, per dungeon | +| rupees | `coop_rupees` | `own`, `pool` | | +| ammo | `coop_ammo` | `own`, `pool` | bombs, bombchus, arrows, deku nuts, seeds and sticks, magic beans | + +- `shared`: a flag set by anyone stays set for everyone; of a count (an item, an upgrade) the highest wins. +- `own`: not synced; switching to it stops the merge and keeps what was merged. +- `pool`: one count that every player adds to and spends from. Each player's gains and spends are counted apart (in a + record their game signs) and add up, so two players spending at once both pay; a pool that two spends at once took + below zero shows 0 and the next gain pays the debt first. A player's spends count only up to what that player gained + plus the counter's limit (999 rupees or ammunition), and never beyond what entered the pool (the highest count a + player brought, at least 0, plus every gain): nobody takes more than the pool really had, so a dungeon's key pool + loses at most the keys that dungeon has, and in a rupee pool a player who spends more than 999 rupees beyond what they + gained is not charged for the rest; a count brought below zero counts as zero, so no record turns the others' keys + into a debt. A joiner whose count is higher raises the pool to it; a game that restarts and rejoins does not add its + count again; a game that joins a pool in debt (as a drain leaves it) pays the debt with its count, so the count comes + back with the drainer's removal. A pool above a counter's capacity shows the capacity. Each game counts in its pools + only the records of the players its player accepted, and its own; it stores and passes on every admitted record, so + the games hold the same records, and games whose players accepted the same players show the same pools. A game joins + the pools once its player accepted the room and the maker's game admitted its key, which it does for each player the + maker accepted (up to 24 keys per pool reset); until then its counts stay its own. +- Small keys in the pool: a key anyone picks up goes into the dungeon's pool, a door anyone opens takes one out, and the + pickup and the door are progress, so they are gone and open for everyone. Two players who each used the last key + on a different door at the same moment open one door more than the keys paid for. +- Items, songs and quest items can be `own` only with `coop_progress = own`: in a shared world a chest one player + opened is empty for the others. With progress `own`, keys are `own` too (each world has its own doors). A room's maker + whose settings break this gets the nearest valid set, and the log says which. + +Never shared, by design or because no reliable way exists yet: + +- Where Link is, his health (the game republishes it from the player several times a second, so it cannot be set + through the flags), the magic in the meter (likewise outside the flags), the time of day (the clock runs in the + game's world manager, not in a flag), bottle contents and the equipment worn. +- Heart containers and pieces and gold skulltula tokens: most of their pickups are flags of single objects in the world + that this layer does not write, so a shared count would pay one piece or token twice; the reward flags the game names + for them stay with each player too, so everyone can collect them. +- Items the game takes away again (the trade sequence, rented masks, the knife that breaks, amiibo items): a shared + highest count would hand them back. +- Flags that the game itself resets at a scene change, a new day or a load, and counters that are not progress (puzzle + positions, minigame records, enemies defeated). + +### The room's rules + +The rules belong to the room: every game in it merges the same way. They are the settings of the player who made the +room, signed with that player's key: a game takes rules only signed by the key its player accepted (pinned at the +first acceptance in the room). Before that, a game that made the room itself takes its own; otherwise it takes the +key of the player the relay marks as the maker, but only while no other player carries rules signed by another key +(the relay's mark cannot outvote the rules the players' digests carry, and a mark the relay puts on your own name does +not make you the maker); with no maker in the room it takes the rules every member's digest carries. A member does +not sign its digest, so before you accept, someone who knows the secret and runs the relay can make every member's +digest to you carry rules of a key of its own, which your game then takes (with no maker in the room, or a maker it +controls): the offer shows the key that signs the rules, and comparing it with the maker's is what tells you (step 3 +of "Before you join a room with strangers"). When the members' rules disagree it takes +none, applies nothing, and the log and the offer say so: ask the maker which key fingerprint is theirs. No other +player's settings are used, and a member the relay marks later (after a restart, or a relay that lies) changes +nothing for a player who accepted; the offer then says that the relay names another maker. The signed rules travel +with the sync messages, so a joiner and a game that rejoins after a relay restart get them from anyone. If the maker +has left, the players keep the rules they have. The maker can change a rule during the session: switched to shared or +pool, the category merges from then on (after each player accepts the new offer); switched to own, it stops, and +nothing already merged is taken back. A maker whose game restarted keeps the room's key (from `coop-keys/` in the +profile), takes its own rules back from the others and can change them, remove players and reset the pools again. + +### Messages + +Sync rides in the room's sealed messages. Each game sends a digest (a sum per section of its state, and the rules) +every 2 s and at once to a player who joins; a section whose sum differs is sent to that player, so lost messages are +repaired and a late joiner catches up within a few seconds. A change goes out at once and again 80 and 250 ms later. +Sending is paced at 32 KB/s, under the relay's limit per member, with the players who asked for sections served in +turn (one that asks for everything all the time gets its share, not all of it), and each game takes at most 48 KB/s +from any one player. Games merge only with the same schema: this layer's version, the game's version, and the whole table of what +is shared and up to which value, so two builds that classify a flag differently do not merge. + +## The room's secret and the wire + +For a reviewer: what is derived from what, what each datagram carries and what a receiver checks. The code is +`runtime/coop_proto.c` (C) and `tools/coop_relay.py` (the relay's side, Python); `tests/coop_vectors.txt` holds byte +vectors of every message that both are checked against. + +**Library.** Monocypher 4.0.2 (`runtime/third_party/monocypher/`, two files, unmodified, BSD-2-Clause, dual-licensed +with CC0) for BLAKE2b and XChaCha20-Poly1305. It is small, has no dependencies, builds the same on Windows and Linux, +and its primitives are standard (RFC 7693, and the XChaCha20-Poly1305 construction of the IETF draft). It is used only +in `coop_proto.c`, behind four functions (`coop_room_keys`, `coop_seal`, `coop_open`, and BLAKE2b inside the first), so +another library can replace it there; the sync layer's signatures (EdDSA over Curve25519 with BLAKE2b, the library's +`crypto_eddsa`) go through `coop_sign_keypair`, `coop_sign`, `coop_sign_check` and `coop_blake2b` there too. The relay +needs no library: it uses Python's own BLAKE2b and HMAC. + +**The secret.** 18 symbols, each drawn uniformly from 27 (bytes from the operating system's random source, a byte +below 243 taken modulo 27): log2(27^18) = 85.6 bits. It is made by the client that creates the room and never sent to +the relay or written to a log; players pass it on themselves. + +**Derivation.** With `S` the 18 canonical ASCII characters as the key of BLAKE2b: + +- locator `L` = BLAKE2b-128(key `S`, "nx2navi-coop/2 room"): the relay's name for the room, and the key of the tags of + datagrams between a client and the relay. The relay and anyone who sees a CONNECT learn `L`; getting `S` from it is a + search over 2^85.6 secrets. +- message key `K` = BLAKE2b-256(key `S`, "nx2navi-coop/2 messages"): seals every message between the players. Only + holders of `S` have it. + +**The client and relay datagrams.** A 24-byte header (magic, version 2, type, the relay's room id, src, dst, length, +sequence) and an 8-byte tag, HMAC-SHA256(`L`, header[0:16] ‖ payload)[0:8]. CONNECT carries `L`, a client id (random +for each start of the game), a session (random for each join), a nonce (random for each attempt), the name, the +relay's cookie and the rejoin token. CHALLENGE, JOINED and ERROR echo the nonce and carry `L`'s tag; the client takes +only answers with its own nonce and its own `L`, so a datagram someone else sends from the relay's address neither +ends an attempt nor puts the player into another room (an untagged "protocol version" error is taken only as the +first answer of an attempt). JOINED carries a rejoin token, random per member: the relay gives a member's id (and the +maker's mark) back only to a CONNECT with it. The ROSTER lists each member's id, flags (away, maker), session and +name. KICK (maker to relay) names a member and its session. These datagrams are authenticated against outsiders who +do not know `L` only; the relay and an observer of a CONNECT can make them, which lets them disturb the session +(drop, reorder, invent members that cannot speak), not change a save. So a roster is taken only up to 2^20 ahead of +the last one's number (the relay's counter moves with its own datagrams), and after the silence time and 4 s without +a roster taken, the next one counts whatever its number, so one forged far ahead does not cut a player off; no roster +ends a session for progress sync (a session ends only when its member's identity in a later one names it, below), and +neither does a relay that says the room is gone; a roster that lists another session for this player makes it join +again at most once per 15 s, and its game keeps signing for the session it joined with. A relay or observer that keeps +sending rosters changes the roster for as long as it sends, as it can drop datagrams for as long as it likes. + +**The player message envelope** (the payload of DATA, version byte 1): + +``` +u8 envelope version (1) | u64 sender's session | u32 counter | XChaCha20-Poly1305 ciphertext of (u8 kind, message) | u8[16] tag +nonce (24 bytes) = session (8, LE) | counter (4, LE) | sender's member id (1) | 11 zero bytes +associated data = destination member id, envelope version +``` + +A session is drawn for every join and the counter starts at 1, so a nonce never repeats under `K` (two sessions +collide with probability about n²/2^65). The kind byte and the message are inside the ciphertext: a new kind of message +(a pose, say) needs only a number, and a later envelope version can change the outer fields without touching the +messages. A message is at most `COOP_MAX_MESSAGE` = 1146 bytes after its kind. + +**What a receiver checks, in order:** the sender is in the roster and is not itself, the destination is it or +everyone, the envelope's session is the one the roster lists for that sender, the counter is new within a window of +the last 64 of that session, the tag opens with `K` for that sender and destination; only then is the counter recorded +and the message delivered. A counter older than the window is refused, unless it opens and is the fourth of that +sender's messages in a row below the window, each later than the one before: then the window starts again from it and +it is delivered. `K` is the whole room's, so whoever knows the secret can seal one message in a member's name with a +counter far ahead, which leaves that member's later messages below the window; the member's next four start it again, +and the first three of them are lost. That is per forged message: one sent again after every three of the member's +keeps that member's messages from a player for as long as it keeps sending. + +**Replay.** A message recorded before a player joined again carries the old session, which the roster no longer +lists: refused. Within a session the window refuses only what it still remembers: a message sent again within the +last 64 it took is refused, and an older one alone is refused too. But four older ones in a row, each later than the +one before, start the window again (that is how it recovers from a counter far ahead), and from then on the window +has forgotten what it took: anyone who recorded a member's messages of its present session (the relay too, without +the secret) can have every one of them delivered again, in order. Someone who knows the secret can also seal a +recorded message again under a new counter. So the envelope does not make a message arrive once; a layer for which a +repeat matters checks a counter of its own. A sync section carries its sender's own counter inside its signature for +that: a section is taken once, and only within the last 64 of its sender's session; a digest taken again repeats what +it said (until its sender's next one, 2 s later). A relay that lists an old session in a forged roster could replay +that session's messages to a player whose game never saw the session end; they are messages the sender really signed, +and sync messages only raise values, so this brings nothing new into a save. + +**The sync messages (version 4).** `runtime/coop_state.c` has the byte layout. Each game makes a signing key for each +room and start of the game (EdDSA, from a random value of the start and the room's secret, so nothing ties a player +across rooms; the maker's from 32 random bytes kept in the profile for that room, mixed with the secret, so that it +outlives a restart) and sends in every DIGEST its identity: the key, its name, the session it held in the room before +this one (0 none) and a signature over the room's context (BLAKE2b-128 keyed with the secret), its member id, the +session it joined with and that session before. A game takes values only from a member whose identity checks out; an +identity belongs to one session, a session a member's later identity names as the one before is never taken again +(the latest 1024 of each key the player accepted are kept apart, where no other member's churn removes them; the +others share the last 65536), and a key another member holds is refused, so an identity cannot be copied to another +member or slot; the relay also refuses a session that was in the room before. An identity of another key for a +session that is identified already (only one of them is the member's) makes the game take that member as neither +while both are presented; once one of them has not been presented for 10 s, the other takes the place. Only the key's +holder ends its sessions +that way: a forged roster, a relay that says the room is gone, or a replayed message or identity ends none. A game +announces its identity at once when its session changes. A name is checked as signed and shown cleaned (control and +reordering characters replaced). Every SECTION (a push of a change or an answer to a digest) ends with its sender's +counter (8 bytes) and its signature (64 bytes) over "nx2navi-coop/4 section", the room's context, the sender's +member id and session and the section's bytes, checked against the identified key before anything of the section is +stored, applied or passed on: 72 bytes and one signature per section whatever it carries, about 35 µs to sign and +100 µs to check one (measured on the runtime's -O2 build of Monocypher on an x64 desktop). Flags are taken only from a +member whose key the player accepted. The DIGEST also carries the +maker's charter: the rules, the keys admitted to the pools (8-byte key ids), the last 16 keys removed and the pools' +epoch, with an epoch the maker raises at each change (saturating at 2^32−1), signed by the maker's key; each game +keeps every removal it saw in the room. A pool record (one per contributor and pool) carries the contributor's key, +the pools' epoch, a sequence number, its base, gains and spends, and its signature; a game keeps the record with the +highest sequence of each key (its own too: a room that comes back hands it its own newest record) and stores only +records of admitted keys of the current pools' epoch, checking the signature before it stores or passes one on; its +pools count only the records of keys its player accepted, and its own. A game remembers (in memory) its last 8 joins +of each pool in the epoch, each with what it joined with and the records it saw then; its base is the highest of +their claims, each made as if the game had counted then the keys it counts now, and made again whenever that changes +(a removal, or its player accepting more). An older join keeps the claim it had when the ninth was made, so after +nine saves loaded in one pools' epoch (a game over and continue counts) a removal leaves that claim as it was until +that save is loaded again. A reset carries this game's own claim as it would be with only the players the reset +admits, and the game signs it at once as its record in the new epoch (a game the reset does not admit claims it when +it joins). A digest's sums are not signed: a forged one can make a game send its sections or join a pool before it +heard every record, as dropping messages can. + +**Rules and the maker.** A game takes a charter signed by the key its player accepted; before any acceptance, its own +for a room this session made; else by the key of the member the relay marks as the maker while no identified member +carries a charter of another key; else, with no maker in the room, by the one key every identified member's charter +carries (each member's first digest is waited for, up to 5 s, so the quickest does not win). A charter of the same key +counts only with a later epoch. + +**Per-member limits in each game.** Every value is checked against the local table before it is stored, passed on or +applied; at most 48 KB/s is taken from one member; 32 refused flags, or pool records whose contributor's signature +fails, in sections that member signed, and the member is ignored while it stays. Nothing that fails inside a digest +counts against the member it names (an identity, a charter in the maker's name), and neither does a section whose +signature fails: anyone with the secret can send either in its name. A pool record this game cannot count is dropped +without counting against its sender, since an honest member may hold a newer charter for a moment. A signature check +that failed is not made again for the same signature, key and signed bytes (a changed copy of a genuine message fails +on its own and leaves the genuine one to be checked), and each member gets at most 128 signature checks a second (256 +at once), sections' included; +the register index is keyed (SipHash-2-4 with a random key of the process); a pool stores at most 24 records (the +admitted keys), a record's base, gains and spends are at most 2^20 either way, and nobody but a record's key holder +can make or change it. Without the system's random source (no client id, session, nonce or key a stranger cannot +guess) co-op stays off. + +## Before you join a room with strangers + +1. **Keep a save you can go back to.** Join only with a save you are ready to restore from + `coop-backup/first-`. Anyone you accept can set story flags in your save, and so can anyone a player you + accepted let in. A player in your pools can empty a dungeon's small keys while they play; the maker's removal of + that player, or a pool reset after they were removed or left, gives back what they took, but no removal takes a + flag back, and a reset while they are still in the room keeps their drain: remove first, then reset. +2. **Your acceptance is yours, the room is not.** A player you did not accept reaches neither your flags nor, by + themselves, your pools, also when they know the secret and run the relay. But the players you accept pass on the + flags of the players they accepted, a player you accepted who counts a stranger in their pools claims against a + pool with that stranger in it until the maker removes them, and the maker alone decides who may use the pools at + all. If anyone you do not know is in the room, even one you declined, do not accept: leave, and ask the maker for a + new room (a new secret) for the people you know. +3. **Check the keys, and keep yours to yourself.** Before you accept, compare the fingerprint of the key that signs + the room's rules with the maker's, and each player's with that player's, by voice or chat: a name is what a member + says it is, and someone who knows the secret and runs the relay can hold back a player's own identity and show its + own key under that player's name and member number until that player's arrives. Never start the game with + `NX2NAVI_COOP_ACCEPT=always`, + or with a script or `nx2navi.ini` someone hands you. Never hand out a copy of your profile folder: its `coop-keys` + folder makes whoever has it, with a room's secret, the maker of that room (your game logs a member that presents its + key). + +What nothing can prevent: everyone who knows the secret can join and read the room; a member or the relay can disturb +it (leave messages out, delay them, send one again as "Replay" says, flood within its limits, keep the rules from +being agreed, change the offer so that nothing is applied until you accept again, keep the room unaccepted by never +saying who it is, send rosters or identities that keep a player unidentified for as long as it keeps sending, or seal +messages with a counter far ahead, each of which costs a player three of a member's messages); and the relay sees who plays +with whom and when, with names and addresses. None of that changes a save. + +## Other players in the world + +Not in this build. The protocol has a message for it (POS in `runtime/coop_proto.h`: the area, a position, a facing +and what Link's animation slots play), and its codec and its counter against replayed poses are in the build and +checked by `--probe-coop`, but nothing sends one and nothing draws another player: a POS that arrives is dropped. So +no position leaves your PC, whatever the settings. + +## In the log + +State changes only: `coop: connecting to the relay`, `the relay answered in N ms`, `room XXX… created`, `joined room +XXX… as member N`, ` (member N) joined the room` and `left the room`, `relay lost; rejoining`, `left room ()`. +A cause that repeats (a message that does not open, a replay, no server) logs once per 30 s; a counters line follows +every minute in a room. Peer addresses are never logged; the relay's only with `NX2NAVI_TRACE=coop`, which also adds a +line per datagram. + +Progress sync: `coop: sync: playing a save: N progress flags, ...` when a save is being played (and `... nothing is read +or written until a save is played` when it stops), `a room to accept; in the room: ...; rules: ...` followed by `put +coop_accept = into nx2navi.ini [coop]` (or, while a member is not identified, `N member(s) in the room are +not identified`; when the members carry rules of different keys, a line that says so), `room accepted`, `the save +as it was before this room is in `, `the key this game signs the room's rules with is kept in ` (the +maker), `the room's rules: progress shared, ...`, `took N values from the room (progress a, items b)` at most every +5 s, `N values from the room were refused`, `member N sent values this game does not take; nothing more is taken from +it`, for the maker `key K (member N, name | not in the room) took N keys ... from the pools beyond what it brought; +coop_remove = K removes it`, `key K removed`, `coop_remove = N in nx2navi.ini names a member number` (not taken), `the +pools are reset`, `member N presents this game's own key`, `member N presents another key than the one it was identified +by in its session`, `member N (name, key K) presents a key you accepted as member M | under the name ...: under this +name it is a new offer`, and `the room's key file ... is damaged | cannot be read`. +`NX2NAVI_TRACE=coop` adds `sent`, +`received` and `applied` lines by category, hash and value. With `coop = 0` nothing of this is logged and the game's +frames do no more than check the setting. + +## The interface for the layers above + +`runtime/coop.h`: `coop_send(kind, bytes, n)` and `coop_send_to(member, ...)` send a sealed message to the others (it is +a datagram: it may be lost, arrive out of order or, recorded, arrive again: see "Replay"), `coop_on_message(kind, fn, user)` receives +them on the coop thread, `coop_on_view(fn, user)` reports the state and the roster (with each member's maker mark and +whether its messages opened), `coop_view_get(&view)` copies them, `coop_command(COOP_CMD_CREATE | COOP_CMD_JOIN | +COOP_CMD_LEAVE, secret)` drives the room, `coop_remove_member(id)` is the maker's removal (progress sync signs it +through `coop_on_remove`). `runtime/coop_offer.h` holds the menu's calls, none of which waits for the sync engine (what +they read is a copy the coop thread publishes at each step, what they ask it carries out at its next step): +`coop_game_offer(&offer)` and `coop_game_accept(number)` show a room and accept it (`CoopOffer` in +`runtime/coop_state.h`: each member's signed name, key fingerprint, whether it is identified or removed, how many +members never identified (the room cannot be accepted while there are any), whether the members' rules disagree, the +rules and the key that signs them, whether another save is played and whether the copy is made), +`coop_game_reset_pools()` is the maker's pool reset, `coop_game_remove_key(fingerprint)` the maker's removal of a key +(also of a player who left; a member in the room with that key is removed at the relay too), and +`coop_game_contributors()` lists the pools' contributors with what each took beyond what it brought, per pool and in +the room or not (a player who used keys others found is among them). `CoopView.made` is this session's own creation of +the room, `CoopView.name` the player's own name. The wire format is `runtime/coop_proto.h`. Progress sync uses +`coop_on_tick(fn, user)` for its timers. + +## Checks + +- `python tests/coop_relay_test.py`: the relay (rooms, rejoin with the token, timeouts, limits per member, per network + and in all, removal by the maker, bad tags, a stolen client id, challenge and room floods, fan-out, garbage from a + member, the log without secrets, a join attempt asked again without a charge, two players behind one address who + wait ten minutes for a room, a rejoin during a challenge flood, rooms that send to nobody, a rejoin while the members + of four other rooms flood with their tokens, and a rejoin on a relay with its full 1000 rooms while someone floods + with every token of the room and a member of it with its own) on a fake clock and over + UDP, and the codec against the vectors. With `NX2NAVI_EXE=/ocarina` it also runs the probe against a relay it + starts (with `--log-joins`, whose log a failure shows), with and without 30 % loss, and restarts that relay in the + middle. +- `ocarina --probe-coop`: the sockets, the codec and its cryptography (known answers, a sealed message that does not + open when changed or sent by another), a fuzz of every parser, the POS message's counter (a pose sent again, one + recorded 35000 poses earlier, another session in the same member number, one forged far ahead), which members count + as shown (only those accepted and identified), and two sessions in + one process that make and join a + room, exchange messages, take garbage and forgeries from a hostile relay (a changed message, one it sealed itself, + a replay after a rejoin, lies while a player connects), lose the relay and find each other again, and in which the + maker removes a player. Needs no window, GPU or game files. It runs its own small relay; + `NX2NAVI_COOP_RELAY=host:port` uses a real one, `NX2NAVI_COOP_DROP=30` drops that share of what the sessions + receive, `NX2NAVI_COOP_VECTORS=tests/coop_vectors.txt` checks the byte vectors. Its sync part runs the merge engine + between fake games on a fake network: merging, late joiners, loss, the rules and pools, nothing carried from one room + or save to the next, a hostile member (refused values, pool records it did not sign or that nobody admitted, its own + records against a pool, removal), identities (a removed player back, a copied identity, a second name, the accepted + list), the offer's number, rules that wait for acceptance, another save in the room, the maker's pinned key, an + honest base above the limit, fair answers, the third review's cases: flags only from accepted keys (through + another member, after a declined member left or was removed, from a member that never identified), a key drain with + the maker's game restarted and the absent drainer removed, a pool reset, an identity replayed after 64 sessions or a + room the relay lost, the relay's maker mark against the members' rules, signed names, failed signatures, a game's own + pool record after the room came back, and a removal 17 removals ago; and the fourth review's: a record with the + lowest base, pools that follow the player's own acceptance, two resets in a row, a forged roster's sessions, what a + contributor took per pool, an accepted key's ended session after 65600 others; and the fifth review's: sections in + another member's name made with the secret alone (and a flood of them), a member's session after a forged roster + with a replayed message, a roster without it, a relay that says the room is gone, and a replayed identity of a + session the game never saw end, claims made again after a removal (keys brought while a removed player's gains + counted, a claim made while its spends counted, honest games that agree, a game at its title screen), another save + that joins only once accepted; and the sixth review's: digests in a member's name whose charter does not check out, + a changed copy of a member's digest and of the maker's charter sent first, another key's identity for a member's + session sent first, and a reset's carry with a player who comes after it and with a removal in the same charter; + and the seventh review's: a key the player accepted in another member's place under that member's name, and a relay + restart that hands the players other numbers; + and a randomised run (a few seeds by default; `NX2NAVI_COOP_ADVERSARY=first:count` runs those seeds alone, + `NX2NAVI_COOP_ADVERSARY_TRACE=1` prints its events and the engines' lines) of hostile members who hold the secret, + admitted or not, and of an attacker with the secret and no accepted key who forges senders and rosters, replays + messages and identities, sends changed copies of digests and sections and identities of its own key in a member's + place, against invariants of flags, acceptance, identification, ignored members, the maker's charter and a ledger + of the honest players' joins, carries, pickups and uses. The session part adds rosters forged + far and a little ahead, rosters that list another session again and again, a message in a member's name sealed with + the room's key 2^31 − 1 ahead, a refusal for the network's joins, and a + room that is not there. `ocarina --probe-fs` checks that the first copy + of a save outlasts the rotation. +- `python tests/coop_page_check.py`: the menu's Co-op tab without the game, driven with the keyboard's and the pad's + events: typing a name, a relay and a secret (Q and E are letters there, not tab keys), Make, Join with a wrong secret + and a pasted one, the offer accepted and declined, the maker's key to compare, the three warnings before the first + Accept only, a player not identified (Accept greyed, removed by member number only while the same session holds + it), a key accepted under another name (said in the offer, the row and the Accept window), Remove by key, a pool + contributor's key removed, Reset the pools, Leave, the relay's join limit and a lost room, + the maker's rules and the others' read-only ones; Accept, Remove, Reset and Leave never act on a second press, a held + button or a double tap, and a new offer under an open Accept window puts the cursor back on Not now. It then runs + again with a deliberate fault (each such window opens with the cursor moved onto its acting button) and passes only + when that run fails. Needs a C++ compiler only. diff --git a/docs/installer.md b/docs/installer.md index 7587c906..fe0d8f1e 100644 --- a/docs/installer.md +++ b/docs/installer.md @@ -148,7 +148,8 @@ llvm/ llvm-mingw, x86_64-only subset (Apache-2.0 with LLVM excep runtime/ libnx2navirt.a, libnx2navirt-v2.a and the headers the generated code and modules.c/romfs.c/patches.c include bin/ nx2navi_xlate.exe, hactool.exe, SDL3.dll, libopus-0.dll, ninja.exe -data/ shader_list.tsv (MIT, THIRD_PARTY_NOTICES.md); pgo-.profdata + .json, the execution profile an +data/ shader_list.tsv (MIT, THIRD_PARTY_NOTICES.md); pipeline_list.bin when the release was made with + one (building.md, step 6); pgo-.profdata + .json, the execution profile an update's code and the runtime libraries compile with (building.md, "Profile-guided build") THIRD_PARTY_NOTICES.md nx2navi.ini.example, VERSION the default ini; the release string (the repository's VERSION plus the commit) diff --git a/docs/launcher.md b/docs/launcher.md index 5899b20d..4c0ab9df 100644 --- a/docs/launcher.md +++ b/docs/launcher.md @@ -14,7 +14,7 @@ it. The code is `launcher/`, the release is made by `tools/make_launcher.py`, an drive, and proposes `\game` as the install folder (or `X:\Games\NX2navi` on the drive with the most free space when that drive has less than 40 GB). Both rows can be changed. 3. Selects **Begin Installation**. The launcher downloads the build tools (about 170 MB, once), checks the dump, - unpacks it, translates and compiles the game: 10 to 25 minutes. It keeps the PC awake meanwhile. + unpacks it, translates and compiles the game: 20 to 45 minutes. It keeps the PC awake meanwhile. 4. Selects **Play**. The launcher hides while the game runs and comes back when it exits. From then on the launcher looks for a new version when it opens and every hour while it runs, also while it is @@ -136,11 +136,17 @@ A path the Windows ANSI code page cannot hold breaks the MSYS2 tools, so the too complete. No MSYS2 shell or pacman runs. Then zbic: the wheel for the bundled Python from PyPI, checked against PyPI's sha256, into `pydeps/`. 2. **Inspect Your Game** to **Compile**: `tools/make_game.py --nup --out --msys --events`, - whose `@@` progress lines drive the rows (check, exefs, romfs, lift, compile). How it keeps the build short: + whose `@@` progress lines drive the rows (check, exefs, romfs, lift, compile). Before the first long step it + looks at what can be known to fail later: the disk space of every step that will run (the RomFS image and 1 GiB, + 2 GiB for the build cache, 4 GiB for the prepared shaders; `check_space` names each part and how much is + missing), and that the build tools compile and link an empty program (`probe_toolchain`). How it keeps the build + short: - The RomFS image (26 GB, mostly disk work) is packed beside the lift and the compile (processor work), so a first build takes about as long as the longer of the two. Only `romfs.c`, which includes the RomFS index's `romfs_config.h`, waits for the image. - - Every logical processor compiles, the largest files first, so no big file starts last and runs on alone. + - Every logical processor compiles, the largest files first, so no big file starts last and runs on alone; fewer + compiles run when memory is short, as many as 80 % of the free memory holds at 768 MiB each (`make_game.py` + `default_jobs`). - The lifted code compiles with MSYS2 CLANG64's clang when the toolchain has it: the same LLVM release as UCRT64's, built with profile-guided optimisation, about a fifth faster on this code and writing the same objects (it reads UCRT64's headers; `make_game.py` `fast_clang` checks that both report the same version and target). @@ -159,14 +165,20 @@ A path the Windows ANSI code page cannot hold breaks the MSYS2 tools, so the too and writes the Xbox, PlayStation, Steam Deck and keyboard and mouse prompts into `romfs-patches-*` beside the game (about 30 s), which the game's Controls > Button prompts loads. The keyboard and mouse prompts show the keys of `nx2navi.ini`'s `bind_` lines, so Rebuild the Game after rebinding keys draws them again; the step's key names - all it reads (the RomFS, the art, the tools, those lines), so it runs again only when one changed or a folder is - gone, and runs no other step again. Without art the row is not shown and the game keeps its own prompts. + all it reads (the RomFS, the art, those lines) and the version of the tools (`make_game.py` `PROMPT_TOOLS`, changed + by hand when a change to them changes what they write: an edit of a script alone does not draw the prompts + again), so it runs again only when one changed or a folder is gone, and runs no other step again. Without art + the row is not shown and the game keeps its own prompts. 5. **Check the Game Files**: make_game.py's last step runs `tools/romfs_check.py`, once for each copy of the game data - (about 4 minutes, in worker threads, never while the game runs). It decompresses every file, writes + (about 4 minutes on players' PCs up to 0.7.1, in worker threads, never while the game runs; its key holds the + check's version, `SCAN_TOOL`, in the same way). It decompresses every file, writes `romfs-check.json` beside the game, and for each damaged texture puts a stand-in, another texture of the same kind under the damaged one's name, in `mods/Damaged file stand-ins`, so the game can load what needs it. A damaged file of any other kind is only reported: only a clean dump restores it. In play the game logs a file it keeps opening - and cannot load (runtime/romfs.c `open_note`). + and cannot load (runtime/romfs.c `open_note`). The launcher shows what the check found (`jobs.Job.note_scan`): + the count in the step's row ("4 Flagged, 3 Stand-Ins"), and after a job in which the check ran a sentence on the + home screen and in `launcher.log`. The four files the check flags on every copy of the game (`jobs.SCAN_EXPECTED`) + are told as that, with nothing for the player to do; other files are counted and `romfs-check.json` named. 6. The game's Cetra Display is decoded for the window. ## Updating @@ -180,6 +192,10 @@ directly. Every address is https (plain http only to this PC), a redirect to htt sent on when a redirect leaves the host it was meant for (`launcher/net.py`). A manifest that does not give a file's size and sha256 is refused. +GitHub allows an address 60 such requests an hour. The Updates row and F5 therefore start no check within a minute +of the last one (`FORCED_CHECK_PAUSE`), and a check GitHub refuses says when the allowance is whole again, from the +answer's `X-RateLimit-Reset` (`feed.retry_text`). A failed check is one line in `launcher.log`. + ### In the background The player never waits for a download and play is never interrupted. A check that finds a newer release (the check @@ -251,18 +267,33 @@ The stub swaps `python.next` in while no Python runs, then starts the new versio objects of 0.5.0 and earlier); Rebuild the Game compiles it for this processor's (`--retune`), and runs the compile step for that even when nothing else changed (`retune_due`). 6. **Swap In the New Build**: lld links `ocarina.exe.new`, which replaces `ocarina.exe` only once it is complete. A - failed rebuild leaves the old build playable; Rebuild the Game tries again. + failed rebuild leaves the old build playable; Rebuild the Game tries again. A rebuild that lifted again and then + stopped has no finished compile on record (`build.built_version` is empty), but the old exe and the unpacked game + files are there: the launcher still counts the game as installed (`build.installed`), opens on home, where + Rebuild the Game reads "Not Finished", and never asks for the dump again. Begin Installation into a folder whose + game files are already unpacked builds on from them as well (`jobs.InstallJob.args`). 7. **Prepare the Shaders** is skipped once shaders were prepared before (`shader-prepared.bin`): the game keeps using them and translates them again with the new translator in the background (`NX2NAVI_SHADER_CARRY`). With - `shader_carry = 0`, or nothing prepared yet, the step prepares them all as at the install. + `shader_carry = 0`, or nothing prepared yet, the step prepares them all as at the install. So it does when the + list was prepared from another shader seed than the one this kit writes: `shader-prepared.bin` carries the digests + of the two seed files and the translator identity (`runtime/prp_file.h`), the step writes the seed first + (`prepare_shaders.py --no-run`, seconds) and compares (`make_game.py` `seed_changed`); a list from before it + recorded its seed is prepared again once. Another translator alone does not prepare again. The step still builds + the prepared shaders into the graphics driver's cache again (`make_game.py` `warm_driver_cache`): seconds while + the driver has them, 20 minutes on a player's PC when the update changed what they are built with. Its bar + follows that count from 0 to 100 %, and the Updates row says an update takes from a few minutes to half an hour + or more (`launcher/ui/app.py` `UPDATE_TAKES`). 8. **Draw the Button Prompts**, with button art in the new version: only when the art, the prompt tools or the key bindings changed, or a prompt folder is missing (a first version with art draws them all). 9. Every version but the current and the previous one is deleted, except a staged release newer than the current one. When the new version fails to start (exit code 86 from `start.pyw`, or any error within six seconds), the stub sets -`current.txt` back to `previous.txt`'s version and starts it with `--rolled-back`. The game is never rebuilt while it -runs. Keep Build Cache off deletes the lifted C and the objects (about 5 GB) after each build but keeps +`current.txt` back to `previous.txt`'s version and starts it with `--rolled-back`. `start.pyw` writes the failure to +`data/logs/crash.log` and shows it in a message box only when there is no version to go back to, when Steam started +it, or when the six seconds are over (`quiet_exit`): a box holds the exit code back until it is closed, and the +broken version then stayed the current one. The game is never rebuilt while it +runs. Keep Build Cache off deletes the lifted C and the objects (about 1.5 GB) after each build but keeps `build-cache/state.json`, so updates still rebuild without the dump (compiling everything). ## Sharing a save @@ -273,7 +304,9 @@ save. Saves (home, under Game Folder; `launcher/saves.py`) and the Saves rows of **Export.** Export Save writes `NX2navi-save-_