mirror of
https://github.com/tangerineturtle1/NX2navi.git
synced 2026-11-16 09:39:58 -04:00
The route reaches Kakariko Village, Hyrule Field by day and night, the Market, Death Mountain Trail and the graveyard edge from the available saves, every pause subscreen, and a save, return to the title and reload in one process; Kokiri Forest, a dungeon and a boss are not reachable. The ledger gains a confirmed crash on loading the test install's Kokiri Forest save and a confirmed UBSan report in the menu's grain texture; ASan cannot start because its shadow covers the guest's fixed windows, and TSan has no Windows target. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
1925 lines
140 KiB
Markdown
1925 lines
140 KiB
Markdown
# 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.
|
||
- Phases 3 to 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
|
||
|
||
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** `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** `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** `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** `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** `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** `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** `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** `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** `ipc.c` `ipc_svc` 0x21/0x22. The session is used without a reference while `CloseHandle` may free it.
|
||
Domain fields are unlocked.
|
||
- **L-10** 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** 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** `kernel.c` `thread_main`. A thread created but never started (or closed first) waits forever, keeping its
|
||
stack reservation.
|
||
- **L-13** `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** `menu_assets.c` `dicts_load`. Lazy dictionary load without a lock, from the "menu-art" thread and the
|
||
present thread.
|
||
- **L-15** `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** 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** `frame_rate.c` `frame_limit_live`. It is reached from three threads without a lock, and can call
|
||
`rt_patch_switch` concurrently.
|
||
- **L-18** `cfg.c` `raw_get`. `getenv` races with `cfg_setenv` → `_putenv_s` while the game runs
|
||
(`gfx_present.c` ~90).
|
||
- **L-19** 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** `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** `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** `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** `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** 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** Leaked kernel objects per call:
|
||
- `audio_mixer.c` change events (beyond 16);
|
||
- `ipc.c` domain sub-objects;
|
||
- `net_offline.c` spare events.
|
||
- **L-26** `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** `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** `memory.c` `lzs`. Lazy write-back segments grow without a cap, and every fault and arm scans them linearly.
|
||
- **L-29** `vk_usnap.c`. `U.wr` grows without pruning when `NX2NAVI_UBO_SNAPSHOT=0`. The arena free list is never
|
||
trimmed.
|
||
- **L-30** `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** `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** `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** `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** 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** `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** `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** `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** 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** `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** `vk_sync.c` completion queue. It is FIFO, not ordered by fence, so one late callback holds back the frees
|
||
behind it.
|
||
- **L-41** `prof_win.c` sampler. Time-critical, suspending every thread each 1 ms. Phase 2 must not compare profiled
|
||
runs with unprofiled ones.
|
||
- **L-43** `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** 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** 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** `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** 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** 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
|
||
|
||
Empty. Phase 3 fills it.
|
||
|
||
| Field | Meaning |
|
||
|---|---|
|
||
| ID | `F-<pass>-<n>`, 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) / guest code; the host cause is not traced | 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 | Load the test install's slot 1 (`E:\NX2navi-060b\game\profile\save\<user>\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` and `probe_d1_all` | confirmed: 3 of 3, including `ocarina_all.exe` (no Phase 2 code). It is the only Kokiri Forest save available. Not tried in the user's own install | Phase 3: trace what the guest reads at +0x150 and whether a host service (save, caption, `fs_host.c`) left it null | Unknown until traced; may touch the save format (ask the user first) | — | — |
|
||
| 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 | — | — |
|
||
|
||
---
|
||
|
||
## 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 | not started |
|
||
| 2 Threading and races | not started |
|
||
| 3 Memory and VRAM budget | not started |
|
||
| 4 Shader stutter and hitching | not started |
|
||
| 5 Rendering correctness | not started |
|
||
| 6 UI | not started |
|
||
| 7 Performance | not started |
|
||
| 8 Edge cases | not started |
|
||
|
||
---
|
||
|
||
## 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 `@<ms> MARK <name>` 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: '<name>' 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 <t> rom <path>` 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) -> <path>` (`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: <area> loads (frame, world)`; `scene: <areas> 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 `<tick> MARK <name>` or `@<ms> MARK <name>`; `segment: '<name>' 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: <areas> 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, <group>: 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_<name>.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\<user>`) and
|
||
from the test install's profile (`E:\NX2navi-060b\game\profile\save\<user>`):
|
||
- `u0`-`u5` and `d0`-`d5` are the whole folder with slot *k* copied into slot 0.
|
||
- `one_u<k>` and `one_d<k>` 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 `<tag>\`.
|
||
|
||
**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_<slot>`, 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_<name>.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).
|