Files
NX2navi/docs/architecture.md
chrg6 f9f0505ed1 Build a large compute shader ahead only when a run has dispatched it, and release the shaders of pipelines the boot does not keep.
The 2 GiB of device memory a filled cache cost was not the thousands of compute pipelines but twenty of them: the compute shaders of 0.9 to 2.0 million SPIR-V words, the game's tensor-core upscaler programs, which nothing dispatches. A pipeline of one holds about 100 MiB of device memory from the moment it exists, and the driver keeps that memory when the pipeline is destroyed, so keeping only the recently dispatched pipelines did not help: the boot pass still created the twenty from pipeline-cache.bin at every start. Measured with --probe-prewarm on a copy of an installed copy's caches (RTX 5090, NVIDIA 621.01): the pass over all 4,066 compute shaders took the device memory from 386 to 2,398 MiB and the process's commit up by 2.5 GB; the same pass before the twenty were in the cache left the device memory at 386 MiB, and all 4,046 other pipelines kept at once cost 2 MiB.

A compute shader over NX2NAVI_LIB_PREBUILD_BIG is now built ahead, from the caches or by the background builder, only when the usage record says a run dispatched it. None of the twenty is among the 138 shaders eleven runs dispatched. Should the game dispatch one for the first time, that dispatch compiles it once and later boots build it ahead.

The boot also reads the shader of a pipeline it does not keep as a copy and releases it after the build, instead of leaving 3,900 shaders loaded (240 MB of commit); a first dispatch then reads its shader from the disk, 0.04 to 0.10 ms in the probe.

With both, the same pass on the same caches leaves the device memory at 386 MiB and raises the commit by 47 MB; 256 first dispatches after it took 0.13 ms on average, 1.8 ms at most, all read from the cache file. With compute_keep = all, which builds everything as before, the pass ends at 2,528 MiB. Not yet run in the game.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
2026-11-10 04:53:00 -05:00

154 lines
13 KiB
Markdown

# Architecture
How the Switch 2 build of *Ocarina of Time* (game version 1.1.1) becomes a native Windows x86-64 program. Code taken
from other projects, with its license, is listed in [THIRD_PARTY_NOTICES.md](../THIRD_PARTY_NOTICES.md).
## Pipeline
### 1. Input
- The ExeFS and RomFS of the user's own dump. Everything extracted or generated stays under `build/`, `generated/` or
the user's own folders, never in the repository (`tools/check_content.py`).
### 2. CPU: lift ARM64 to C
- Modules: `main`, `sdk` and the `subsdk*` modules. `rtld` is dropped; the host links the modules.
- A hand-written decoder (`recomp/lifter.py`) and NEON/FP lowering (`recomp/simd_c.py`, `runtime/simd.h`) emit one C
function per guest function, direct calls for `BL` and an address-keyed table for indirect branches.
- The generator runs in parallel processes, with bounded memory per worker.
- Jump tables are resolved by a symbolic pass of our own (`recomp/jumptables.py`).
- `LDXP`/`STXP` (128-bit exclusive pairs) are supported.
- NZCV and the six most used general registers of each function live in C locals instead of the `Cpu`
(`recomp/flags.py`, `recomp/regs.py`): registers are stored back where they changed, before calls, SVCs and
exits, and reloaded after them. A call reloads only X0-X18 and X30, as AAPCS64 has the callee preserve X19-X29
and SP; `gen.py --no-callee-saved-trust` reloads those too.
- Memory: guest address equals host address, all below 2^39 (IPC encodes 39-bit addresses). The heap, stacks and the
alias region are reserved with `MEM_WRITE_WATCH`, so the graphics back end can ask which pages the CPU wrote since
the last upload (`runtime/memory.c`).
- Indirect branches go through `rt_dispatch` (`runtime/dispatch.c`), which looks the target up in the address table
and tail-calls it.
- Testing: a differential harness checks every lifted instruction class against Unicorn (test-only, never linked into
the game).
### 3. Host
- The SDK boundary is at the `nn::*` function level: threads and synchronisation, IPC, memory, fs/RomFS, time,
account, applet, hid, audio renderer and effects run as host code. Only `audren:u` and `sm:` are real IPC services.
- Window, keyboard and mouse: Win32 (`gfx_window_win.c`, `input_win.c`). Gamepads and audio output: SDL3 (every
connected gamepad is open; the game reads the one pressed last, `input.c`). Voice: libopus. Movies: a host VP9
decoder over libvpx replaces the SDK's `movie::Decoder` (`runtime/ov_movie.c`).
- Settings and menu: every key with its default is in one table (`cfg.c`), read from `nx2navi.ini` and `NX2NAVI_*`
variables and written back when the in-game menu changes it. The menu and the performance overlay are Dear ImGui,
drawn into the swapchain image (`runtime/ui/`); their text is in `ui_text.c`.
- OS calls the host makes go through `runtime/platform/` (`platform.h`, `win32.c`).
#### Threads and cores
Every guest thread is a host thread. The game assumes Horizon's scheduler: three application cores, a thread runs
only on a core in its affinity mask, and a higher-priority thread takes a core from a lower-priority one. The game
keeps per-core data without locks and relies on that, so the host models it (`runtime/kernel.c`):
- Three virtual cores. A guest thread runs guest code only while it holds a core; the others wait in a
priority-ordered list.
- Preemption. When a waiting thread has a better priority than a holder on a core it may use, exactly one holder is
flagged. The holder checks the flag at its next SVC and at every indirect call (`rt_dispatch`), checks again under
the kernel lock that a better thread still waits, and only then hands its core over.
- Asynchronous preemption (on unless `NX2NAVI_ASYNC_PREEMPT=0`): a waiter that has spun 250 us suspends the holder
and, if its host rip is in lifted code at host depth 0, moves it to `kern_ap_stub`, which saves the volatile
registers and gives the core up there. A holder of a guest mutex counts at the priority of its best waiter, and one
inside an SDK spin lock is not preempted.
- Host work gives the core back. Queue submits, presents, GPU waits, shader translation, `nn::fs` calls and NVN memory
pool setup run without a core (`NVN_BLOCKING`, `kern_core_away`).
- Spin waits. Loops that only another thread can end send their back-edges through `rt_spin_gate`, which pauses the
core once per pass and hands it to a waiter after 50 us of polling (`NX2NAVI_SPIN`, `NX2NAVI_SPIN_HANDOFF_US`).
### 4. Graphics
- NVN 2 front end (`nvn_api_*.c`, `nvn_obj.h`, texture layout and deswizzle, the Switch 2 GOB layout). The game
records command buffers through it; nothing reaches the GPU until the game submits.
- Vulkan 1.3 back end. At `QueueSubmitCommands` the recorded NVN commands are replayed into Vulkan command buffers on
the submitting thread (`vk_exec*.c`); a recorder thread makes the `vkCmd*` calls from a ring of packets
(`vk_rec.c`).
- Memory pools are imported as host memory (`VK_EXT_external_memory_host`). On a discrete GPU, pools bound as buffers
are mirrored in device-local memory and the pages the CPU wrote (write watch) plus the ranges the game flushes are
uploaded before a replay (`vk_memory.c`); without the mirrors the GPU reads them over PCIe and Kokiri Forest runs at
7 fps. GPU-rendered textures are written back when the CPU reads them.
- Uniform snapshot. The game rewrites per-object uniform blocks soon after it submits the frame that reads them; at
the start of a submission's replay every uniform range it binds from CPU-written pools is copied, and the draws bind
the copy (`vk_usnap.c`).
- Driver data. The NVN driver keeps a per-stage constant bank (c0). The back end fills it as the driver does: storage
and uniform tables, push constants and, for NVN 2 compute, the dispatch's group counts in bytes 0-0xb.
- Storage buffers the shaders reach through pointer tables in memory are bound at the address the table holds
(`GfxShaderRes.ptr`, `vk_exec_draw.c ptr_addr`).
- Bindless textures: the texture and sampler pools are descriptor arrays kept in step with the game's pool writes
(`vk_exec_draw.c pool_sync`); slots that resolve alike share one lookup.
- Shaders: Ampere (SM86) code is lowered to Maxwell (`tools/xlate/AmpereLowering.cs`) and translated to SPIR-V by the
pinned shader translator (`tools/vendor/ryujinx`, 1.3.2) with our patches (`tools/xlate/patches/`), built with .NET 10 NativeAOT as
`nx2navi_xlate.exe` and run as separate processes. Translations are cached on disk; shaders and pipelines seen in
play are prepared at the next boot. The game waits for it (`runtime/boot.c` `boot_wait`): about half a second
when warm; after a GPU or driver change, or a translator change with nothing to carry (below), a "Preparing
shaders" screen shows the progress (`ui/menu.cpp`
`menu_boot_frame`). With the graphics pipeline library the boot builds recorded pipelines in record order for at
most 20 s after the shaders are ready and leaves the rest to the pipeline workers below normal priority; a draw
that meets one before it is built gets a fast-linked pipeline (`vk_pipeline.c` `PREWARM_PIPE_MS`).
`NX2NAVI_PREWARM_FULL=1`, and drivers without the library, wait for every pipeline. `NX2NAVI_PREWARM_WAIT_MS` caps
the whole wait, after which the rest finishes in the background.
- Translator updates: every cache key names the translator, so a new one has no translations. The cache carries the
previous translator's (`NX2NAVI_SHADER_CARRY`, `runtime/gfx_shader.c` "Carry"): `shader-cache/identities.txt`
lists the translators it holds translations of, and a shader the new translator has not translated yet uses the
previous one's for the whole session, so neither the start nor play waits for a translation the update caused.
After the boot prewarm a background pass on its own translator process at idle priority, which waits while the game
translates, translates every stored program again for the next start, then deletes the old translations (a pruned
copy of `shader-cache.pack` replaces the pack at the next start). A program the new translator refuses keeps its
old translation. `--prepare-shaders` still translates everything with the current translator.
- Shader disk reads in play: a draw's shader that is in the disk cache but not in memory is read on the render thread
within a budget of 1/8 of the wall time (2 ms at once), and past it by three loader threads while its draws are
skipped as for a translation (`runtime/gfx_shader.c` `load_budget`). Opening a loose file is what costs (5.6 ms a
pair the first time on Windows), so an update that carries the shaders over packs the cache once it holds 1,000
loose translations (`tools/make_game.py` `PACK_LOOSE_MIN`).
- Texture pool streaming: the bindless pool's refresh before each draw creates at most `pool_create_budget` entries,
and once a frame's refreshes have taken `pool_create_ms` (6 ms) none more until the next frame; the slots left keep
their stand-in, and the frame's later refreshes skip them (`runtime/vk_exec_draw.c` `pool_refill`). An area load
spreads over several frames instead of holding one for 200-400 ms.
- Mesh and task shaders run as `VK_EXT_mesh_shader`; indirect mesh draws read NVN's `{count, first}` record through a
ring of Vulkan `{x, y, z}` records filled on the GPU.
- Pipelines: `VK_EXT_graphics_pipeline_library` where the driver has it: stage libraries compiled ahead, a fast link
at a new state, an optimised pipeline replacing it from a background thread. A draw whose pipeline is not ready is
skipped when one of its pass's targets was rendered in the previous frame, and waits otherwise. Compute pipelines
are compiled outside the pipeline lock, and one compile serves every thread that needs it. The boot builds the
pipeline of every compute shader play recorded or the shader preparation listed, but keeps only those of the shaders
dispatched most recently (`compute-used.bin`, `compute_keep`): the others go into the pipeline cache and are
destroyed, and their first dispatch creates them from it. A compute shader of more than half a million SPIR-V words
is built ahead only when a run has dispatched it: a pipeline of one holds about 100 MiB of device memory whether it
is used or not, also after it is destroyed, and the list has about twenty of them that the game never dispatches
(`runtime/vk_pipeline.c`, "compute pipelines the boot keeps").
- The game's tensor-core upscaler is replaced by a decode-and-scale pass (`vk_tonemap.c`); `vk_fsr.c` runs AMD FSR 1
(EASU, RCAS) on the present when the window is larger than the picture.
- HDR (`vk_hdr.c`): the game tonemaps its scene into a float target, upscales it, draws the HUD into a second float
target and copies that into the 8-bit sRGB window texture it presents. With `NX2NAVI_HDR=1` the tonemap shader gets
the function of `shaders/hdr_tonemap.frag` spliced in where its SDR curve clamps each channel, so the float picture
holds the HDR picture relative to the HUD's white; the game's FSR 1 pass loses its output clamp; the present reads
the float picture in place of the window texture and `shaders/hdr_encode.comp` writes PQ for an HDR10 swapchain.
`NX2NAVI_HDR=native` reports an HDR10 display to the game, which then renders and presents its own PQ picture.
The menu switches between off and `1` during a run: the splice, the HDR extensions and the settings in the support
buffer are there from the start whatever is set (`vk_hdr_armed`), the spliced tonemap returns the game's SDR result
while the swapchain is SDR, and a change of the setting makes the swapchain again in the other format
(`gfx_present.c` `window_settings_live`). Only `native` waits for a restart, as the game asks about the display
once. `NX2NAVI_HDR_LIVE=0` leaves the HDR path out of a run that starts with HDR off.
- ASTC textures are uploaded as they are where the device samples ASTC, and decoded by a compute shader everywhere
else (`vk_astc.c`); under 20 GiB of video memory the decoder encodes them to BC3.
- Occlusion queries never block the CPU; a result that is not ready counts as visible.
- Allocation: Vulkan Memory Allocator. Debugging: Vulkan validation layers, per-pass frame dumps (`NX2NAVI_DUMP`,
`vk_dump.c`), a sampling profiler (`NX2NAVI_PROFILE`, `tools/prof_report.py`) and a flight recorder
(`NX2NAVI_FLIGHT`). RenderDoc cannot capture, because it hides `VK_EXT_external_memory_host` from the application.
Maxwell behaviour the back end has to match: [maxwell.md](maxwell.md).
### 5. Toolchain
- Generated C: MSYS2 UCRT64 Clang + LLD. The generated code uses GNU extensions (`__int128`, `musttail`, vector
types) that `cl.exe` cannot compile.
- Host code: the same Clang, C11.
- Builds write a Ninja file and run MSYS2 Ninja. Every object is hashed before linking, because a faulty RAM module
once flipped bits in stored objects.