Add the recompiler, Windows runtime, tools and docs

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Valiantsin DzerakhandClaude Opus 5.5 committed 2026-10-23 22:27:54 +03:00
1 parent 3d73290520
commit 19c9b648d1
558 files changed
+119174 -10

No files matched your search

+116
View File
@@ -0,0 +1,116 @@
# Agent playbook: running, measuring and debugging the game
Read this before you run the game, take a frame dump or measure performance. This page holds the conventions; the
`--help` of each tool holds its options.
## Work in a private runtime copy
Fork, build, hand back and clean up with the `private-build` skill (`.claude/skills/private-build/SKILL.md`).
The pipeline cache, `pipeline-keys.bin`, `shader-cache`, `shader-programs.bin` and `shader-answers.bin` live next to
each `totk.exe`, so a fork starts cold: seed it by copying `build/v121`'s five before timing anything. A fork seeded
from an older build stalls on pipeline and shader builds, and its slow frames say nothing about the change. (Until 2026-10-22 every fork wrote into
`build/v121`'s caches, and forks broke each other's runs.)
## Running
Run a build into gameplay with the `run-game` skill (`.claude/skills/run-game/SKILL.md`): `tools/run_game.py`, the save
backups and their scenes, input scripts. `build/profile` is the user's real profile: never write it. Other agents run
the game at the same time: stop only a `totk.exe` you started, by PID; `taskkill /IM totk.exe` closes every instance.
## Measuring
Timings are only comparable on a quiet machine. Pass `--quiet` to take the machine-wide lock `build/.gpu-run.lock`
(held until the game exits, freed by the OS if the caller dies, holder pid and build in the file), then wait until no
other `totk.exe` or `ninja.exe` runs. The log's first and last lines record the count either way.
- `--env TOTK_TRACE=perf,sched`, then `python tools/perf_summary.py <log> <lo> <hi>`: fps, max frame and the
render-thread buckets per 60 frames. Per-thread run, core, host, lock and addr shares come per 120 presents.
- `TOTK_PROFILE=1 TOTK_PROFILE_FRAMES=lo-hi`: sampling profiler (`runtime/prof_win.c`). Resolve `exe+0x...` RVAs
with the build's `totk.map`.
- `tools/regress.py <build> --base build/v121-m4 [--routes fight,rock,island,field] [--repeat 3] [--cold] [--validation]
[--out dir]`: runs the routes through `run_game.py --quiet`, scores logs and `TOTK_SHOTS` frames
(`tools/regress_score.py`, tested by `tests/regress_score_test.py`) and prints median and worst per metric. Run the candidate alone and judge it against
the targets: max fps, no slow frames (`perf: slow frame`), no black or flat frames, no new validation errors.
`--base` (a diff with `ok`, `better`, `worse`) only when a question needs a side-by-side; do not rerun a base build
by habit. Glitches are found by looking at the shots and dumps, not by the diff. `--cold` empties only the
pipeline cache. Each route writes `<out>/<build>/<route>-worst.png` (the 6 worst frames) and `route_failed` marks a
run that ended in game over, crashed or stopped early: its numbers do not count. One run takes 2 to 4 minutes.
- Baselines (Ryzen 9 7900X, RX 9070, 1600x900, 60 fps patches and real-time step on, 2026-10-23):
- field: 59.4 fps mean, 60 median, replay 9.5 ms per frame;
- `fight.txt`: 59.1 fps mean, 60 median, replay 13.6 ms, 0 CPU-side slow frames; the slow frames left are
pipeline and shader-translation waits.
- `--validation` runs work in the world (1800 frames checked). The layer prints each message kind 10 times, so it
gives no totals; the known messages left are in the backlog correctness queue, item 8.
## Frame dumps
`TOTK_DUMP=<frame> TOTK_DUMP_DIR=build/captures/<name>` writes per-pass PNGs, `passes.txt` and `images.txt`
(`runtime/vk_dump.c`). `passes.txt` lists bound textures with swizzles, storage buffers with their c0 slots, and
copies and clears. `TOTK_DUMP_BUF=addr:size[:off:stride:w:h]` dumps a guest buffer.
- A draw's argument lines come before its pass header.
- Pass numbers shift between runs. Find a pass by its draw count instead: the g-buffer pass has about 1990 draws.
RenderDoc cannot capture: the driver hides `VK_EXT_external_memory_host`.
## Other GPUs
The RX 9070 is the only GPU here; the build also has to run on NVIDIA and older AMD (Vega, wave64 only). New Vulkan code
queries the feature, extension, format or limit it uses and keeps a working path or a logged fallback when it is
missing (`vk_pipeline.c` provoking vertex and subgroup size pinning are examples). Never hard-code what this GPU
reports: alignments, subgroup size, depth formats, `maxPushDescriptors`.
## Checks before handing back
`totk.exe --probe-kernel`, `--probe-vkexec`, `--probe-nvn-tex` and `--probe-shader` run from the build directory and
must pass. CPU-header changes also need `tests\diff\simd.py`, `lift.py` and `func.py` (AGENTS.md).
`tools\build_game.py` hashes every object against `obj/objects.sha256` before it links and recompiles a mismatch (the
faulty RAM flipped bits in stored objects once, `build/BOOTCRASH.md`). The line `objects verified: N, recompiled after
a hash mismatch: M` should show M of 0; a nonzero M means rerun the probes. A fork checks the shared objects against
the main build's manifest, so build `build/v121` first.
## Bug classes already fixed
Check these classes before you re-investigate a symptom that looks like one of them.
- A colour target outside the fragment shader's output map must keep its texel, as on Maxwell: write mask 0 from
`vk_pipeline.c` `target_wmask`. AMD wrote undefined values there (lime silhouettes in grass); zero-filling it
instead wiped the half-res depth (sky rectangles).
- The CPU copies GPU-rendered textures between pools with memcpy (grass tile maps): `nvn_api_core.c` `ov_memcpy`
writes them back first. Other CPU reads of GPU output are not covered yet. A write-back skips a texture whose
storage the CPU rewrote after the GPU render (`vk_texture.c` `write_back`); writing it anyway put stale grass maps
into the far terrain for a second (texture flicker on a hit).
- A one-shot draw (a target not rendered in the previous frame) waits for its shader and pipeline instead of being
skipped: `vk_exec_draw.c` `prepare_draw`. Skipping left the cloud and fog volumes empty for the session.
- Storage buffers bound by Ryujinx first-use order instead of the NVN c0 slot: `vk_exec_draw.c` `ssbo_slot`. It showed
as tile rectangles.
- 3D colour targets rejected: `vk_exec.c` `resolve_target`. The grading LUT was never written, so the dialog
background and the loading map were black.
- Primitive restart ignored: `vk_exec_draw.c` `restart_for`. It showed as streaks on cliffs.
- The slot-follow path picked the newest texture at shared storage: `vk_texture.c` `vk_texture_by_id` now prefers
`same_but_swizzle`. It showed as a streaky map screen.
## Lessons from other ports
Before you form a hypothesis about a symptom, follow "Before you investigate a symptom" in
[research/port-lessons.md](research/port-lessons.md): evidence first, then a search of the lessons and the upstream
notes. `refs/nxnative/docs/agents/05-debugging.md` has recipes for intermittent glitches, racy crashes and memory growth.
## Context budget
Read output through a filter; the full text stays on disk.
- Game logs run to megabytes: `grep` the lines you need, `tail -20` for the end, `perf_summary.py ... | grep SUMMARY`
for timings.
- Generated C (`generated/v121`) runs to hundreds of thousands of lines per file: `grep -n` the function, then
`sed -n` its range.
- Look at screenshots downscaled: paste several into one 1280x720 grid with PIL and read the grid.
- Long-running commands go to the background with their output in a file; read the file's last lines when it ends.
- Research notes (`docs/research/`) run to 40 KB each: `grep -n` the symptom or the subsystem, then read that
section.
- Read each screenshot once; write what it shows into the notes instead of opening it again.
- Keep notes in `build/v121-<tag>/NOTES.md` from the first finding, so a handoff costs one write.
After about 40 tool calls (a call costs about 2.4k tokens of context), write `build/v121-<tag>/HANDOFF.md` (under 80 lines) and stop. Include:
findings with file paths, what is ruled out, the leading hypothesis, the exact next step, and the temporary debug edits
(file:line). A fresh agent continues from it.
+103
View File
@@ -0,0 +1,103 @@
# Architecture
How the Switch build of *Tears of the Kingdom* becomes a native Windows x86-64 program. Each choice below cites the research note it rests on: [lasrecomp.md](research/lasrecomp.md), [macnativegames.md](research/macnativegames.md), [prior-art.md](research/prior-art.md).
## Starting points
Two MIT projects cover different halves of the problem:
| | LAS Recomp | MacNativeGames |
|---|---|---|
| Game | *Link's Awakening* | *Tears of the Kingdom* 1.0.0–1.4.3 |
| CPU | ARM64 lifted to C, runs on x86-64 | Original ARM64 code runs directly on Apple silicon |
| OS boundary | IPC services and SVCs | ~163 `nn::*` SDK functions replaced by symbol, 38 SVCs |
| Graphics | Own NVN layer on Vulkan, own Maxwell translator | NVN front end + Metal 4 back end, Ryujinx translator |
| Useful to us | Lifter, NEON-to-C lowering, Windows memory layer, tests | Everything TotK-specific: host behaviour, NVN front end, version tables, patches, shader list |
MacNativeGames cannot run on x86-64 as is: its CPU path executes ARM64 code natively. LAS Recomp's host only covers what *Link's Awakening* calls. The port takes the CPU half from LAS Recomp and the game half from MacNativeGames, and writes the parts neither has: a lifter that scales to TotK, and a Vulkan back end for the NVN front end.
## Pipeline
### 1. Input
- Base 1.0.0 (`0100F2C0115B6000`) and one cumulative update (`0100F2C0115B6800`), NSP/XCI/NSZ, plus the user's `prod.keys`.
- ExeFS and RomFS extraction: MacNativeGames' Python extractor (Python 3.14 for `compression.zstd`, `.venv-py314`).
- Update merging: hactool at `1d64a83`, with MacNativeGames' BKTR patches (`toolchain/hactool`).
- Verification: MacNativeGames' `expected-v*.json` hashes of ExeFS, RomFS and fonts.
- Primary version: 1.2.1, the update most players have. MacNativeGames supports it with the same build path as the others. 1.0.0, 1.1.2 and 1.2.1 share `sdk`, `subsdk0` and `rtld` byte for byte, so the lifted SDK modules and the host's SDK boundary serve all three; only `main` differs. 1.4.3 replaced all three modules (new SDK 20.5.22, RELR relocations, audio renderer REV15) and is a separate, later target.
- Windows driver: `tools/extract.py` runs the vendored extractors (`tools/vendor/macnativegames/`) and identifies the update by the SHA-256 of its `main`. hactool has no Darwin `funopen` here, so the base Program NCA is copied out of the NSP before the BKTR merge (about 17 GB of temporary space).
### 2. CPU: lift ARM64 to C
- Modules: `main`, `sdk`, `subsdk0`. `rtld` is dropped and linking is done by the host, as MacNativeGames does.
- Base: LAS Recomp's hand-written decoder (`lifter.py`) and NEON/FP lowering (`simd_c.py`, `simd.h`), MIT. Output: one C function per guest function, direct calls for `BL`, an address-keyed table for indirect branches.
- Rewritten for TotK scale (see lasrecomp.md, "Scaling risks"):
- generator runs in parallel processes, with bounded memory per worker;
- jump tables resolved by our own symbolic pass instead of Unicorn, which keeps GPL code out of the shipped generator;
- `LDXP`/`STXP` (128-bit exclusive pairs) supported;
- no 64 MB limit on `main`; `subsdk*` loaded;
- guest registers kept in C locals where liveness allows, instead of memory.
- Coverage oracle: MacNativeGames' NSO rewriter lists every site where game code touches the OS (SVCs, TLS reads, counter reads, `x18`, exclusive windows, jump tables): 68,968 sites in 1.4.3 `main`; 1.2.1 counts are in [totk-v121-inventory.md](research/totk-v121-inventory.md). The lifter must handle every one.
- 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: LAS Recomp's differential harness, every lifted instruction class checked against Unicorn (test-only, never linked into the game).
### 3. Host
- Portable C from MacNativeGames: threads and synchronisation, IPC, memory services, fs/RomFS, time, account, applet, audio renderer and effects. The Apple pieces (mach VM, CommonCrypto, AudioToolbox, GameController) are replaced with Win32 and SDL3.
- SDK boundary at the `nn::*` function level, matching MacNativeGames. Only `audren:u` and `sm:` are real IPC services.
- Window, input, controllers and audio output: SDL3. Voice: libopus (BSD). Movies: the SDK's `movie::Decoder` is replaced by a host VP9 decoder over libvpx (BSD, static; `runtime/ov_movie.c`), because FFmpeg from MSYS2 is a GPL build.
- OS calls the host makes go through `runtime/platform/` (`platform.h`, `win32.c`), so a Linux or macOS host adds one file instead of touching the rest. `tools/check_platform.py` keeps Win32 calls out of the other files.
#### Threads and cores
Every guest thread is a host thread. TotK 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`: two loads when nobody waits), checks again under the kernel lock that a better thread still waits, and only then hands its core over. The indirect-call check comes from SavageWindRecomp's BotW port; checking only at SVCs left a better thread waiting up to 26 ms.
- Host work gives the core back. Queue submits, presents, GPU waits and shader translation run without a core (`NVN_BLOCKING`, `kern_core_away`), so a thread blocked in the driver does not hold up guest threads.
- `TOTK_FREE_CORES=1` turns the gate off, for experiments.
Other ports and what they changed about scheduling: [port-lessons.md](research/port-lessons.md), rows S1-S6.
### 4. Graphics
- NVN front end from MacNativeGames (`nvn_api_*.c`, `nvn_obj.h`, texture layout and deswizzle). The game records command buffers through it; nothing reaches the GPU until the game submits.
- Vulkan 1.3 back end in place of MacNativeGames' Metal one. At `QueueSubmitCommands` the recorded NVN commands are replayed into Vulkan command buffers (`vk_exec*.c`).
- Memory pools. Apple's unified memory let MacNativeGames use the game's pools zero-copy. On a discrete GPU the back end uploads the pages the CPU wrote (write watch, above) before a replay, and writes GPU-rendered textures back when the CPU reads them (`vk_texture.c`).
- Driver data. The NVN driver keeps a per-stage constant bank (c0) that shaders read for things like point size, dispatch size and base instance. The back end fills it the way the driver does.
- Shaders: the Ryujinx translator 1.3.2 with MacNativeGames' patches and ours (`tools/xlate/patches/`), built with .NET 10 NativeAOT as `totk_xlate.exe` and run as a separate process. Its SPIR-V goes to Vulkan directly. Translated shaders are cached on disk.
- Pipelines: `VK_EXT_graphics_pipeline_library` where the driver has it. Shader stages are compiled ahead into libraries; a draw that meets a new state links them at once (fast link), and an optimised pipeline replaces the linked one when a background thread finishes it. Pipeline keys seen in play are saved and built at boot. Without the extension, a missing pipeline is built on a worker and the draw waits or is skipped.
- Occlusion queries never block the CPU; a result that is not ready counts as visible.
- ASTC textures are decoded on the CPU when the GPU has no ASTC support (`tex_astc*.c`).
- Allocation: Vulkan Memory Allocator. Debugging: Vulkan validation layers, per-pass frame dumps (`TOTK_DUMP`, `vk_dump.c`) and a flight recorder (`TOTK_FLIGHT`). RenderDoc cannot capture, because the driver hides `VK_EXT_external_memory_host` from it.
Maxwell behaviour the back end has to match, and the TotK bugs other ports fixed: [maxwell.md](research/maxwell.md).
Why Vulkan rather than D3D12 or wgpu:
- The translator emits SPIR-V, which Vulkan consumes as is. D3D12 would add a SPIR-V to DXIL step; wgpu would add SPIR-V to WGSL through Naga and drop features the game uses (bindless textures, some atomics).
- LAS Recomp's Vulkan back end is a working reference on Windows.
- The same back end runs on Linux.
### 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: `tools/build_game.py` writes a Ninja file and runs MSYS2 Ninja. Every object is hashed before linking, because a faulty RAM module once flipped bits in stored objects.
- Analysis: Ghidra with the Switch loader, Capstone, `llvm-objdump`.
- Later, for players: build the game code on their machine with a bundled `zig cc`, as LAS Recomp does, so no recompiled code is ever distributed.
## Milestones
| | Goal | Done when | Status |
|---|---|---|---|
| M0 | Toolchain and repository | Every tool in the toolchain docs passes its verify command | Done |
| M1 | Input | The user's dump extracts and matches `expected-v1.0.0.json` and `expected-v1.2.1.json`; sizes and function counts of `main`, `sdk`, `subsdk0` are recorded | Done |
| M2 | Lifter at scale | All three modules lift to C, compile and link into one exe; differential tests pass | Done |
| M3 | Host boots | The exe reaches the first NVN call with threads, memory and RomFS working | Done |
| M4 | Playable | Vulkan back end draws the title screen and the world; input and audio work | Done |
| M5 | Renderer foundation | Fewer stutters and visual glitches, a render thread with room for 60 fps | In progress |
| M6 | Release shape | Build-on-player-machine packaging, Linux, 60 fps | |
Open problems, in the order they are worked on: [backlog.md](backlog.md).
+188
View File
@@ -0,0 +1,188 @@
# Backlog: the plan and the proposed fixes
Priorities: no artifacts and no crashes first, then 60+ fps without dips, then other GPUs and platforms. Each item
names its evidence; Maxwell item numbers refer to [research/maxwell.md](research/maxwell.md). Remove an item when it is
merged or dropped.
## Plan (agreed 2026-10-23)
Work the stages in order. At most three agents at once, at most two of them running the game. Done 2026-10-23 and
removed: validation-layer crash (`build/archive/v121-val`), frame-time summary in the default log
(`build/archive/v121-fts`), shader prebuild (`build/archive/v121-sl`), 1.4.3 recon (`build/v143-recon`), agent docs
and README, settings file `totk.ini` (`runtime/cfg.c`, `--probe-cfg`; a new variable needs a row in `known[]`;
`build/archive/v121-ini`), portable folder (`tools/package_build.py`, README build step 7; `build/archive/v121-port`),
freezes on new pipelines in fights (cold fight 53.9 to 59.7 fps mean, frames over 50 ms 10 to 0;
`TOTK_GPL_DRAW_BUILD=0` turns it off; `build/archive/v121-pfh`).
**Stage 1: before the tester weekend**
1. User play test of the prepared build: F11, menus, movies, rumble and gyro still to check. First report
(2026-10-23): flying smooth, short freezes in fights with monsters.
5a. Fight hitches, the user's main complaint. In a warm fight (`fight.txt`, frames 1500+) the game runs 58.3 fps mean,
52.9% of frames over 16.7 ms, 6.3% over 20 ms; frames over 20 ms are 87% replay (19 ms) with no pipeline or
shader waits. The user's play added 0 shader translations and 29 full pipelines.
1. Uneven frames: replay off the critical path. Translate command buffers at `EndRecording` or on a queued replay
thread, so `QueueSubmitCommands` only queues; `TOTK_REPLAY_ASYNC=0` restores the synchronous path. Merge with
the new path off by default if the play test leaves any doubt. Code and probes done in `build/v121-rq`
(0 validation errors); no valid timings yet (its runs fell in the 21:00 file-cache corruption). Next: rebase on
runtime/, measure `fight.txt` warm with `--quiet`.
2. Streaming: the slow loading frames are first texture uploads (ASTC, 367 ms at frame 219 of `fight.txt`).
Measure where the time goes, then decode on the GPU or ahead of use.
6. Lantern texture bug: waiting for the user's description or a cropped shot.
7a. Keyboard and mouse: the PC layout and mouse camera agreed with the user (details below). Sonnet.
**Stage 2: tester weekend (2026-10-24/25)**
8. Runs on other GPUs and CPUs (NVIDIA, Vega 7, weaker CPUs, [tester-guide.md](tester-guide.md)). One table: GPU,
driver, CPU, game version, fps in field and fight, hitches, errors and crashes, with a log per machine (the
`[host] frametime:` lines give the causes). Check whether NVIDIA and older AMD drivers cache pipeline libraries
like the RX 9070 does (the drawing thread builds them for a waiting draw, 0.77 ms average here); the AMD driver keys
that cache by exe path, so each copied folder runs `totk.exe --prepare-shaders` once.
**Stage 3: release next week**
9. Fix what stops play on the tested machines; the rest goes into this file.
10. Commit with the user's approval, GitHub repository, push.
11. Reddit: a post with the repo link (r/decomps, News flair), or the held preview post if the moderators approve it.
**Stage 4: after release, speed and stability**
13. GPU memory over long sessions (details below); 6-8 GB cards are the risk.
16. The correctness queue below, in its order.
**Stage 5: platforms and launcher** (each gets a written design first, agreed with the user)
17. Platform layer: no Win32 outside `runtime/platform/` (`tools/check_platform.py`: 1195 uses in 41 files; FAIL in
`motion_fusion.c`, `movie_probe.c`, `ov_movie.c`, `swkbd_win.c`, `vk_exec_draw.c`).
18. Linux: `runtime/platform/linux.c`, as SavageWindRecomp splits windows, linux and macos files.
19. Steam Deck: RADV offers Vulkan 1.3 and `VK_EXT_external_memory_host`; 4 Zen 2 cores, so expect 30-40 fps.
20. Launcher (details below).
**Later**
21. Button remapping.
22. Game version 1.4.3. Paused 2026-10-23 by the user. Recon in `build/v143-recon` (extracted and verified in
`build/extracted/v143`; copies to continue from in `build/v143-port`). The generator runs unchanged; estimate one
day to the title, two to three to play at 60 fps. Steps:
1. `stg` no-op lift, DT_RELR in `recomp/nso.py` and `runtime/loader.c` (decoder in
`build/v143-recon/recomp/nso.py`), symbol count from DT_GNU_HASH for sdk/subsdk0.
2. Jump tables: 26 disagreements and 83 unresolved sites to 0 unexplained, v121 still at 0.
3. Tools take a version instead of `v121`; re-measure `loader.c:518-526` and `boot.c:22-24`; new boot anchors
(`boot.c:19-20`).
4. RELRO (`nn::ro::ProtectRelro`) and the new SDK imports; run to the title.
5. `recomp/patches-v143.txt` from MNG `game_patches_v143.c` (fps60, bounce, cloth; real time rewritten for the
`sys+0x1da` coefficient); player position for `frame_rate.c:89`; `make_romfs_patches.py --version`
(`Common.Product.140`).
6. Audio REV15 is mostly in place (`audren.c`, `audio_mixer.c`): fix the REV11 self-test; check override
signatures (biquad, font decode); render differences in play.
23. Community ExeFS patches.
24. Frame rates above 60 and VRR.
## Waiting for a play test
- 60 fps at real-time speed (2026-10-23): MacNativeGames' controller patch, real-time frame step, hair and cloth clock
and trampoline fix as generator patches (`recomp/patches-v121.txt`, switches `TOTK_FPS60`, `TOTK_REALTIME`,
`TOTK_CLOTH_REALTIME`, `TOTK_HIGHFPS_FIX`); the pacer ignores the game's interval while the step is real-time.
- Phantom objects and the flat far field (one frame of a rock or log in place of pillars, or a surface filling the
sky), 2026-10-23. The game's producer rewrites its per-object uniform blocks 14-24 ms after the submit that reads
them, with no fence; NVN starts the GPU within microseconds, our replay takes longer. A guard in `nvn_api_core.c`
holds the producer until the newest submit has completed. Item 5a.1 must keep that guarantee.
## Correctness queue
1. Shader census for the open graphics lessons ([port-lessons.md](research/port-lessons.md) G3, G6), offline with no
game run: how many TotK shaders fetch from buffer textures and how many clears use a partial mask.
2. Image aliasing over GPU-only pool memory (Maxwell 2.3 / check 7, yuzu PR 10418 "areas black for a frame on camera
changes"): count distinct texture keys per address per frame; flight recorder counts new aliases.
3. Fire on grass deals no damage, grass does not burn (`build/archive/v121-fire2/HANDOFF.md`): the CPU reads GPU-written data in
GPU-only pools that we never write back (Maxwell 4.1). Recheck after the occlusion merge first.
4. `VK_KHR_index_type_uint8` (check 9): drops the CPU widening of 130-170 byte-index draws per frame.
5. Texture gather rounding on AMD (Maxwell 2.10): yuzu's sub-pixel offset at `ImageGather` fixed BotW shadow edges.
6. Horizon scheduling fidelity beyond the phantom work (port-lessons S1, S3, S5, S6): wake a better-priority thread on
the signaller's core at SVC return, pin ideal-core -2 and main threads to core 0. Count each case with
`TOTK_TRACE=svc,sched` first; fight.txt fps must not drop.
7. Line width 4.5 (check 14): dynamic `wideLines`.
8. VUID-vkCmdDispatch-None-06479 (check 20): a D32 copy of the 4x4 R32F placeholder sampled with depth compare.
Still reported with in-world validation (2026-10-23), together with a fragment write to Location 0 with no
colour attachment.
12. `vk_memory.c` `defer()` (unverified, `build/archive/v121-val/NOTES.md`): an object destroyed while frame F is
recorded is stamped with F-1 and may be freed before F's commands that use it are submitted.
9. Masked clears (Maxwell 1.3 / check 3): fix written and parked in `build/archive/v121-clr`; merge if the census finds a
partial-mask clear.
10. GPU timestamps (port-lessons T1): find whether dynamic resolution reads the report difference before writing real
GPU times per report.
11. MacNativeGames since our pin `b75be8c` (245 commits, fetched): kernel sync `dab728a` (S6), NVN texture sizes
`3c482a7`, CPU reads of small render targets `8a29e0a` (item 3), border colour `29dd997`. Add lessons, move the
pin and fix the `refs/MacNativeGames` line citations in `docs/`.
## Details for later items
- Keyboard and mouse (plan item 7a, agreed 2026-10-23). Today the keyboard map is `input_win.c:34-36` (camera on
I J K L, attack on F) and there is no mouse input at all.
- Layout:
| Switch | Action in the world | Keys |
|---|---|---|
| left stick | move | W A S D |
| right stick | camera | mouse; arrow keys as a second source |
| Y | attack | left mouse button |
| ZL | shield, lock on | right mouse button, also Z |
| ZR | bow | F, also X |
| X | jump | Space |
| B | run, cancel | Left Shift |
| A | interact, pick up | E |
| L | abilities | Q |
| R | throw weapon | R |
| left stick click | crouch | Left Ctrl |
| right stick click | | C |
| D-pad | | 1 2 3 4 |
| Plus | inventory | Tab |
| Minus | map | M |
Esc stays free for the in-game menu. Z and X duplicate ZL and ZR so menu pages turn with two neighbouring keys;
menu tabs (L, R) are Q and R. The mouse wheel stays unbound: L and R are abilities and weapon throw in the world.
- Before coding, check in the game what L/R, ZL/ZR, X/Y, the D-pad and the right stick click do in the inventory
and in the world, and correct the action column.
- Mouse camera: raw mouse deltas per frame become right-stick deflection, with sensitivity
(`TOTK_MOUSE_SENS`) and the larger-deflection rule against the gamepad. The cursor is hidden and confined to the
client area while the window is focused and released on focus loss and while F11 changes the window. Not true
mouselook: the game's stick curve and dead zone still apply.
- Update [controls.md](controls.md). Remapping goes into `totk.ini` (plan item 21).
- In-game menu (Dear ImGui over our Vulkan output, as SavageWindRecomp `runtime/ui/menu.mm`). Opens with F1/Esc or
Minus+Plus. While it is open, the game gets no input. Pages:
- fullscreen and window size;
- performance overlay on F10 (fps, or a frame-time graph with the wait breakdown of `TOTK_TRACE=perf`);
- volume;
- async shader builds;
- quit.
Settings live in `totk.ini`. Leave room for later pages: upscaler, frame-rate choices, remapping,
and the software keyboard moved onto SavageWindRecomp's `osk.mm`.
- Launcher (plan item 20): one exe for Windows and Linux, SDL3 and Dear ImGui (SavageWindRecomp
`runtime/ui/launcher.mm`, `tools/fetch_zig.sh`).
- The player picks the base game (XCI or NSP), the 1.2.1 update and keys. The launcher checks the version,
extracts, generates and compiles the game code with a bundled compiler (Zig, `zig cc`) and an embedded Python or
a native generator, then prepares the shaders. About 4 minutes on 12 cores, longer on a Steam Deck.
- Configuration screen: Play, Settings, Game files, Quit. Settings that need a restart go there.
- It is the recovery path when a setting stops the boot.
- The package ships no game code.
- GPU memory over long sessions (port-lessons P3): never measured. MacNativeGames' TotK reached its 5000 MB GPU
budget after 2 h 43 min (their issue #72) and grew from 4.5 to 6.25 GiB resident; their dead-serial hash sets
reached ~1 GiB after 3 h. Our textures are destroyed when their pool range goes or a new texture takes the address
(`vk_texture.c` `entry_of`, `vk_texture_range_gone`), pools at Finalize, Vulkan objects deferred. Started in
`build/archive/v121-mem` (paused 2026-10-23): a memory line every 1800 frames (VMA heaps, textures, pools, pipelines) and
a list of growing containers; then a 2-3 h session.
- Attachment feedback loops (`build/archive/v121-fb/HANDOFF.md`, Maxwell 1.9 / check 10): 425-667 draws per frame sample
G-buffer targets of the open pass, all at the fragment's own pixel. A spec violation with no visible symptom tied to
it; the v1 fix lost grass (image recreation). Parked until a captured glitch points here.
- Render passes ended by uniform updates and clear-only work (port-lessons P2).
- Map tour (the user's idea): teleport Link across the map by writing position, time of day and weather in guest
memory, to fill the caches on a first run and to serve as an automatic test (crashes, validation, fps per region).
- Community ExeFS patches (`.ips`, `.pchtxt` for 1.2.1): apply them through the generator's patch table
(`recomp/patches.py`); RomFS mods already load (`romfs.c`, `TOTK_ROMFS_MODS`). Code-module mods (exlaunch
`subsdk9`) need porting one by one.
- Faster save loading, asynchronous texture write-back. With 60 fps, keep menus, chests and cutscenes at 30 as
SavageWindRecomp does (`runtime/hle/framepace.c`; [prior-art.md](research/prior-art.md) section E). A trimmed
pipeline key (SavageWindRecomp).
- Maxwell sources not read yet (maxwell.md section 8).
+34
View File
@@ -0,0 +1,34 @@
# Controls
Input comes from the first SDL3 gamepad and the keyboard, merged into one Switch controller (`runtime/input_win.c`). Buttons are ORed; each stick takes the source with the larger deflection. Keys count only while the game window is in the foreground. `TOTK_INPUT=none` disables both (automated runs). `TOTK_*` settings can also be set in `totk.ini` next to `totk.exe` (`input = none`, `motion = 0`, `rumble = 0`); the environment overrides the file.
| Switch | Gamepad (by position) | Keyboard |
|---|---|---|
| Left stick | left stick | W A S D |
| Right stick | right stick | I J K L |
| D-pad | D-pad | Arrow keys |
| A | east | E |
| B | south | Left Shift |
| X | north | Space |
| Y | west | F |
| L / R | shoulders | Tab / R |
| ZL / ZR | triggers (over 50%) | Q / Z |
| Left / right stick click | stick clicks | C / V |
| Plus / Minus | Start / Back | Enter / Backspace |
The stick direction bits (`StickLLeft` to `StickRDown`) are derived from the sticks at 50% deflection. A gamepad plugged in later is picked up within one second; with none connected the log says `input: no gamepad`.
## Scripted input
`TOTK_INPUT_SCRIPT=<file>` replays presses by presented-frame number (`gfx_counters.frames`). It is ORed with real input and still applies under `TOTK_INPUT=none`. One event per line, `#` starts a comment:
```
<frame> <button> [hold_frames] # A B X Y L R ZL ZR PLUS MINUS LEFT UP RIGHT DOWN LCLICK RCLICK; hold defaults to 4
<frame> LSTICK|RSTICK <x> <y> [hold_frames] # -32767..32767, up is +y
```
Each event logs once (`input: script frame N: A`). `tools/input/load_save.txt` loads the first save from the title screen.
## RenderDoc capture (blocked)
`TOTK_RDOC=<frame>[,...]` (`runtime/rdoc_win.c`; `TOTK_RDOC_DIR`, `TOTK_RDOC_DLL`) loads RenderDoc before `vkCreateInstance`. RenderDoc hides `VK_EXT_external_memory_host`, which the back end requires for guest pool imports (`runtime/vk_memory.c`), so device creation fails under it. A capture needs a copy-based pool fallback first.
+447
View File
@@ -0,0 +1,447 @@
# LASRecomp study (reference for the TotK port)
Source: `refs/LASRecomp`, commit `da35b83` (2026-10-19, single squashed commit), version `beta_4`
(`runtime/ui/launcher.mm:88`). Paths below are relative to `refs/LASRecomp`.
TL;DR: a clean, small static recompiler (~2.8k lines of Python), a runtime that recompiles on the player's
machine, and an NVN-at-API-level HLE renderer for Vulkan. The CPU pipeline and the Windows platform layer can be
reused with targeted fixes. The kernel, services, NVN HLE, Maxwell shader translator and Vulkan backend cover only
what Link's Awakening calls, so for TotK they need large extensions or replacement.
## 0. Size
| Area | Lines | Reuse for TotK |
|---|---|---|
| Recompiler (`tools/gen.py lifter.py simd_c.py nso.py analyze.py sym.py`) | 2,779 | yes, with fixes |
| Recompiler tests (`tools/test_lift.py test_simd.py` + harnesses) | 865 | yes |
| Runtime core (cpu/dispatch/kernel/ipc/loader/simd/platform/main/paths/settings/romfs/gamelib/gamebuild) | 6,338 | mostly |
| Services (`runtime/services/*.c`) | 2,452 | partly |
| Generic HLE (input, bindings, movie, nvn_boot, pl, swkbd, vi, heaps, framepace) | 2,024 | partly |
| NVN core (`runtime/nvn/objects.c cmdbuf.c tegra.c formats.c astc.c output_scale.c` + headers) | 2,319 | base only |
| Maxwell translator (`runtime/nvn/maxwell/`) | 2,268 | base only |
| Vulkan backend (`runtime/nvn/vulkan/`) | 6,019 | base only |
| Metal backend (`runtime/nvn/*.m`) | 3,892 | no (Windows target) |
| LA-specific: `tools/patches.py`, `warp_table.py` | 958 | no |
| LA-specific HLE (`runtime/hle/{chamber,digs,doorjump,escape,flags_ext,hookshot,keysanity,miniboss,mirror,pets,pot_glow,qol,rescue,shopsanity,souls,warp,widescreen}.c`, `runtime/rando.c`) | 4,593 | no |
| `runtime/nvn/texpatch.c` (LA button-prompt texture edits) | 1,043 | no |
| UI (`runtime/ui/*`, launcher + randomizer UI + overlays) | 6,479 | launcher concept only |
| Randomizer tools (`tools/rando/*.py`) | 8,489 | no |
## 1. CPU pipeline
### Loading
- `tools/nso.py:12-41`: NSO0 header, 3 segments LZ4-decompressed (`lz4.block`), flat image, MOD0 → dynamic section,
dynsym via `DT_HASH` nchain, RELA + JMPREL relocations.
- Runtime loader `runtime/loader.c`: its own LZ4 decoder (`:17-38`), loads into the guest window at fixed bases,
applies `R_RELATIVE/ABS64/GLOB_DAT/JUMP_SLOT` (`:143-173`). Imports resolve in this order: host HLE implementation
by symbol name, then a guest export, then an "unimplemented" stub at a fake address (`:131-141`).
- Only two modules: `main` @ `0x7000000000`, `sdk` @ `0x7004000000` (`runtime/loader.c:177`, `runtime/rt.h:73-74`,
also hard-coded in `Makefile:191-192`, `runtime/gamebuild.c:304`, `tools/sym.py:15`). `rtld` and `subsdk*` are
ignored. rtld's job (module init order, `nn::init::Start` arguments) is done by the host (`runtime/main.c:16-36`).
**The main image (text, rodata, data and bss) must fit in 64 MB**, or `SDK_BASE` has to move.
### Decoding
- **Capstone is not used by the lifter.** `tools/lifter.py` is a hand-written AArch64 decoder (op0 split at
`:180-194`). Capstone is used only in `analyze.py` (instruction census), `sym.py` (disassembly for debugging) and the
tests.
- Unsupported encodings raise `Unsupported` and become `rt_udf(c, pc)` traps in the output (`tools/gen.py:60-69`), so a
build never fails on an unknown instruction; it crashes at run time if the instruction executes.
- Gaps that matter for TotK:
- Exclusive pair `LDXP/STXP/LDAXP/STLXP` (`o1=1`) raises Unsupported (`lifter.py:391-392`). 128-bit lock-free code
(tagged pointers) will trap.
- Register-offset atomics (LSE) are not supported (`lifter.py:445-446`). That is fine: the Switch's Cortex-A57 is
ARMv8.0.
- `simd_c.py:1-6`: ARMv8.0 + Crypto + CRC32 only. FP16 arithmetic, RDM, dot product, FCMA and JSCVT are rejected
(not present on A57).
### Function, CFG and jump-table discovery (`tools/gen.py`)
- Seeds (`boundaries`, `:71-83`): `.eh_frame_hdr` table (`analyze.py:28-46`), exported FUNC symbols, and targets of
`R_AARCH64_RELATIVE` relocations that land in `.text` (vtables, callbacks).
- More seeds (`:519-546`): every `BL` target, `ADR` targets, and `ADRP`+`ADD` pairs within 8 instructions.
- Fixpoint (`:547-561`): a function is the contiguous range `[start, next_start)`. `scan()` (`:298-328`) collects
branches. A branch target outside the range becomes a new start. Repeat until no new starts appear. Results are
cached per `(start, end)`.
- Jump tables (`:98-277`): **Unicorn** single-steps the code between the bounds check (`cmp #N; b.hi/b.ls`) and the
`br`, once for each index `0..N-1` (at most 4096). It first replays the `ADRP/ADR/ADD` instructions from the
function entry so the table base is known.
- Unresolved computed `br`: `tables[a]='all'` (`:319-322`).
- Any function with a table gets a label on every instruction and an `L_dispatch` switch over all of its instruction
addresses (`:378-382`, `:459-463`). This is the fallback when emulation missed cases.
- Indirect `br` from a load (tail call through a pointer) → `rt_dispatch`.
### Emitted C
One C function per guest function, `void f_<addr>(Cpu *c)`. Templates are in `gen.py:355-466` and `lifter.py`.
Representative shape, assembled from those templates:
```c
#include "cpu.h"
#include "simd.h" /* --simd=c (x86 hosts) */
void f_7000123460(Cpu *c);
void f_7000123400(Cpu *c) {
FN_ENTER(0x7000123400ull); /* profiler hook, one predictable branch */
{ uint64_t ea = c->sp - 32; ST64(ea, c->x[29]); ST64(ea + 8, c->x[30]); c->sp = ea; } /* stp pre-index */
c->x[29] = (uint64_t)(c->sp + 0x0ull); /* mov x29, sp */
(void)(subs64(c, c->x[0], 0x10ull)); /* cmp x0, #16 (flags into c->nzcv) */
if (COND_HI(c)) { goto L_7000123440; }
c->x[30] = 0x7000123418ull; f_7000123460(c); /* bl: direct host call */
c->pc = c->x[8]; c->x[30] = 0x7000123420ull; rt_dispatch(c); /* blr x8 */
SV_FOP_S(FOP_ADD, 1, 0, VREG(vf32, 1), VREG(vf32, 2), (vf32){}); /* fadd v0.4s, v1.4s, v2.4s (simd_c.py:437-469) */
switch (c->x[9]) { case 0x7000123430ull: goto L_7000123430; /*...*/ default: break; }
c->pc = c->x[9]; goto L_dispatch; /* br x9 through a resolved jump table */
L_7000123440:;
{ uint64_t ea = c->sp; uint64_t a = LD64(ea), b = LD64(ea + 8); c->sp = ea + 32;
c->x[29] = (uint64_t)(a); c->x[30] = (uint64_t)(b); } /* ldp post-index */
return; /* ret */
L_dispatch:
switch (c->pc) { /* every instruction address of this function */ default: break; }
__attribute__((musttail)) return rt_dispatch(c);
}
```
- `b` to another function: `__attribute__((musttail)) return f_X(c);` (`gen.py:370-376`).
- `ret` is a plain C `return;`. The model assumes strict call/return discipline: `x30` is never checked. Guest
setjmp/longjmp, fibers, or code that changes LR before `ret` would break. LA needs none of these (no handling exists
in the runtime).
- Patch hooks:
- `PATCHES[addr]` replaces single instructions (`gen.py:408-412`, `tools/patches.py`).
- `RANDO_CODE` emits seed-selected instruction variants (`gen.py:397-407`).
- Output is chunked at ≤1500 functions or ~1.5 MB of C per file. A function with >100 KB of C gets its own file.
Unchanged chunks are not rewritten, so `make` stays incremental (`gen.py:480-490`, `:499-501`, `:577-608`).
- `<mod>_table.c` holds sorted `fn_addrs[]` and `fn_ptrs[]` (`gen.py:613-625`).
### Indirect calls and branches (`runtime/dispatch.c`)
- `rt_dispatch` (`:160-164`):
1. Per-thread direct-mapped cache, 4096 entries keyed by `pc>>2`.
2. On a miss, `dispatch_slow` (`:134-157`): HLE fake-address range, then a linear scan of overrides, then a binary
search of the two sorted tables (`:115-128`).
3. Always `musttail`, so chains of indirect jumps don't grow the host stack.
- HLE functions live at fake addresses `HLE_BASE + 16*i`, at most 4096 of them (`:14-57`).
- Unknown address: `FATAL`.
- `main` → `sdk` calls go through PLT/GOT slots (relocated function pointers), so every SDK call from the game is an
indirect dispatch.
### FP/SIMD
- On arm64 hosts: raw `.inst` passthrough in inline asm, V regs loaded from and stored to `Cpu` around each batch of up
to 24 instructions (`lifter.py:680-728`).
- On x86 (Windows): `--simd=c` (`gen.py:503-504`). `simd_c.py` decodes each encoding at lift time into calls to
`always_inline` helpers in `runtime/simd.h` and `simd_fp.h` with constant fields, so clang folds the switches.
- Semantics follow the ARM pseudocode (`simd.h:1-8`): NaN propagation order, FPCR.DN/FZ/RMode, saturating FP→int,
fused FMA, ARM estimate tables. Not modelled: FPSR cumulative bits and QC, trap enables.
- Requires x86-64-v3 (AVX2, FMA, BMI2). Checked at startup in `runtime/platform/windows.c:143-149`.
- FPCR/FPSR live in `Cpu` (`cpu.h:17-18`). All V regs live in `c->v[32]` in memory (`cpu.h:20`).
- Tested by differential fuzzing against Unicorn. `tools/test_simd.py` enumerates the whole FP/SIMD encoding space;
`tools/test_lift.py` covers the integer path one instruction at a time.
### Exclusive monitor and atomics (`runtime/cpu.h:73-97`)
- `ldxN` records `(addr, value)` in `Cpu`. `stxN` does a CAS against the recorded value: ABA-tolerant, standard
practice.
- `LDAR/STLR` → `__atomic` acquire/release.
- `CLREX` → `excl_addr = ~0` (`lifter.py:325-326`).
- `DMB/DSB` → `__atomic_thread_fence(SEQ_CST)` (`lifter.py:327`).
- `DC ZVA` → 64-byte `memset` (`:330-331`). Other cache maintenance is a no-op.
### System registers, TLS, timing
- `TPIDRRO_EL0` = `c->tpidrro`, a per-thread 0x200-byte TLR in `TLS_BASE` (`runtime/kernel.c:201-221`).
- `TPIDR_EL0` is user-writable (`lifter.py:337, 351`). musl TLS is handled by the guest SDK itself.
- `CNTFRQ` = 19.2 MHz. `CNTVCT/CNTPCT` → `rt_ticks()`.
- `DCZID` = 4. `CTR_EL0` = `0x8444c004` (`lifter.py:335-346`).
### Memory model (`runtime/rt.h:68-84`, `runtime/platform/windows.c:13-82`)
- **Identity mapping: guest address == host address.** `LD64(a)` is `*(u64u*)(uintptr_t)a` (`cpu.h:53-71`). There is
no base register and no offset.
- Window `0x70_0000_0000 .. 0x73_2000_0000` (12.5 GB):
- modules
- `HLE_BASE 0x7080000000`
- `TLS_BASE 0x7090000000`
- `HLE_HEAP 0x7092000000` (224 MB)
- `ALIAS 0x7100000000` (4 GB)
- `STACK 0x7200000000` (1 GB, `kernel.h:7-8`)
- `HEAP 0x7240000000` (3.25 GB max)
- Windows: the window is reserved by `VirtualAlloc(MEM_RESERVE | MEM_WRITE_WATCH)` in a priority-101 constructor
(`runtime/main.c:37-52`). If the range is taken, the process re-executes itself, up to 20 times.
- Regions are committed on map, and a vectored exception handler lazily commits 64 KB on the first stray access
(`windows.c:21-38`).
- `MEM_WRITE_WATCH` feeds the Vulkan vertex/index cache (`windows.c:40-63`).
- `svcMapMemory` copies the data instead of aliasing it (`kernel.c:580-589`).
- No page protection emulation, no MMIO.
### Stack and threads
- Guest stack: in guest memory (`c->sp`).
- Host stack: every guest `BL` is a host C call, so guest recursion runs on the host stack. Each guest thread gets a
256 MB host stack (`kernel.c:226`), reserved rather than committed on Windows (README credit #107).
- One guest thread = one pthread (winpthreads on Windows), started by `thread_main` (`kernel.c:187-199`).
- Priorities are stored, core masks are ignored (`kernel.c:642`). There is no scheduler.
- One global `g_klock` guards all kernel state. Each thread has its own cond var.
- In-place reboot: `longjmp` to `thread_main` at safe points (`kernel.c:173-185`).
## 2. Runtime / HLE
### Kernel (`runtime/kernel.c`, 868 lines)
| SVC | Behaviour |
|---|---|
| 0x01 | SetHeapSize |
| 0x02, 0x03 | No-op OK |
| 0x04, 0x05 | Map/Unmap by copy |
| 0x06 | QueryMemory |
| 0x07 | ExitProcess |
| 0x08–0x10 | Threads |
| 0x11–0x17 | Events, shared memory, transfer memory |
| 0x18, 0x19 | WaitSynchronization, Cancel |
| 0x1A–0x1D | ArbitrateLock/Unlock, CondVar |
| 0x1E | GetSystemTick |
| 0x1F | ConnectToNamedPort (only `sm:`) |
| 0x21, 0x22 | SendSyncRequest (with user buffer) |
| 0x24–0x27 | |
| 0x29 | GetInfo (fixed values) |
| 0x2C, 0x2D | Map/UnmapPhysicalMemory |
| 0x34, 0x35 | WaitForAddress, SignalToAddress |
| 0x45 | CreateEvent |
| anything else | `FATAL` (`:785`) |
- Handle table: 4096 handles (`kernel.c:30`).
### IPC (`runtime/ipc.c`, 246 lines, plus `ipc.h`)
- HIPC/CMIF parsing and serialization.
- Services register through a linker-section table, `SERVICE("name", handler)`. On PE/COFF it uses the
`.svc$a/$m/$z` trick (`ipc.c:8-17`).
- An unknown service gets a logging stub that returns OK with 0x40 zero bytes (`ipc.c:19-24, 34-41`).
- Implemented services:
| Service | Notes |
|---|---|
| `sm:` | |
| `acc:u0` | |
| `appletOE` | no applets (`swkbd.c` HLEs the keyboard) |
| `apm` | |
| `lm` | |
| `audren:u` | CPU mixer modelled on Ryujinx's AudioRenderer: PCM16/ADPCM, resampling, sub-mixes → SDL3 audio stream. Effects and splitters not implemented (`audio.c:14-18, 875`) |
| `audout:u` | |
| `fsp-srv` | RomFS as a raw image plus overlays; save data and SD card mapped to host dirs. `romfs_build.c` builds RomFS images |
| `hid`, `hid:sys` | shared memory filled from SDL3 keyboard/gamepad (`runtime/hle/input.c`, `bindings.c`) |
| `set`, `set:sys` | |
| `pctl*` | |
| `aoc:u` | |
| `time:u/a/s` | |
### Function-level HLE
`HLE_FUNC("mangled", fn)` binds guest imports by name (`runtime/hle.h:150-166`):
- `vi`/`nv` display init (`hle/vi.c`)
- `nn::pl` shared fonts
- `movie::` (nnMedia) on FFmpeg (`hle/movie.c`, 796 lines)
- swkbd
- heap wrappers
- `nvnBootstrapLoader` / `nvnDeviceGetProcAddress` (`hle/nvn_boot.c`)
`hle_override(addr, fn)` replaces functions by address, but only on the dispatch path (indirect calls).
`runtime/hle/hle_symbols.txt` is empty.
### Recompile on the player's machine (`runtime/gamebuild.c`, `runtime/gamelib.c`)
- The release contains no game code.
- On first run, the start screen does three things:
1. Runs the PyInstaller-frozen `gen.py` (`tools/lasgen.spec`).
2. Compiles the chunks with bundled `zig cc` as they appear. Jobs = `min(cores, RAM_GB-2)`
(`runtime/ui/launcher.mm:283-285`): budget about 1 GB RAM per compile job.
3. Links `lasgame.dll` with `zig lld-link`.
- The DLL exports only `lasgame_tables()` (`tools/gamelib_entry.c`).
- It calls back into the exe through an import library. The exe is linked with `--export-all-symbols --out-implib`
(`Makefile:104-106`).
- `GAMELIB_ID` (a hash of the generator, the headers and the flags) forces a rebuild when they change
(`Makefile:111-114`).
- The UI says the build takes "a few minutes" for LA (`launcher.mm:282`).
## 3. Graphics
### NVN on Windows
- NVN is HLE'd at the **API level**, not the GPU command level. Every `nvn*` proc address resolves to a host stub
(`hle/nvn_boot.c`). About 495 `NVN(...)` entry points exist (`objects.c` 371, `cmdbuf.c` 124).
- Command buffers are recorded as `CmdRec` records into guest command memory (`cmdbuf.c:1-3`), then executed by the
Vulkan backend (`runtime/nvn/vulkan/exec.c`, 3.8k lines).
- Vulkan 1.3 is required (dynamic rendering: `VkPipelineRenderingCreateInfo`, `exec.c:1513`). Allocation uses VMA.
- Missing NVN entry points silently `return 0` (`dispatch.c:69-75`).
### Shaders
- Own Maxwell SM5.x decoder in `runtime/nvn/maxwell/translate.c` (2.2k lines). Pipeline: emit MSL, token-rewrite to
GLSL 4.60, compile with shaderc (runtime, Apache-2.0) to SPIR-V (`translate.c:1-12`, `shader.h:1-27`).
- Branches become a `switch(pc)` state machine with explicit SSY/PBK/PCNT stacks.
- Handled opcodes: BAR BFE BFI BRA BRK BRX CONT CSETP EXIT F2F F2I FADD FADD32I FCMP FFMA FFMA32I FLO FMNMX FMUL
FMUL32I FSET FSETP FSWZADD I2F I2I IADD IADD3 IADD32I ICMP IMNMX IMUL IMUL32I IPA ISCADD ISCADD32I ISET ISETP KIL
LD(attr) LDC LDG/STG LDL/STL LOP LOP3 LOP32I MOV MOV32I MUFU P2R PBK PCNT POPC PRMT PSET PSETP R2P S2R SEL SHF SHFL
SHL SHR SSY ST(attr) SYNC TEX TEXS TLDS TXQ XMAD.
- **Missing** (`fail()` at `translate.c:1624`):
- shared memory LDS/STS
- atomics ATOM/ATOMS/RED
- surface load/store SULD/SUST
- TLD, TLD4 (gather), TXD, TMML
- VOTE
- double precision
- CSET
- bindless TEX.B (`translate.c:760`)
- Graphics pipelines are VS+FS only (`stageCount = 2`, `exec.c:1516`, also `:1092, :3269, :3330`), plus compute. No geometry or tessellation.
- Pipeline caching:
- SPIR-V disk cache `cache/spirv/<hash>.spv` (`vulkan/shaders.c:20-54`).
- `VkPipelineCache` saved to `cache/vk_pipelines.bin` (`vulkan/device.c:217-248`).
- One translator thread plus N pipeline worker threads (`exec.c:566-640`). Draws are skipped until their pipeline is
ready (`exec.c:2685`), so new areas show pop-in.
### Textures
- Tegra block-linear deswizzle on the CPU (`runtime/nvn/tegra.c`).
- BCn formats map natively (`vulkan/textures.c:92-104`).
- **ASTC is decoded on the CPU to RGBA8** (`runtime/nvn/astc.c`, LDR 2D only, bit-exact with astcenc;
`vulkan/textures.c:299-308, 548-555`).
### Other
- Resolution scaling, SMAA and FSR1 options (`output_scale.c`, `smaa_data.c`).
- Write-watch vertex cache (`exec.c:2048-2150`).
## 4. Windows toolchain
### Dev build
- MSYS2 UCRT64 (`tools/setup_windows.ps1`): clang, lld, make, SDL3, FFmpeg, vulkan-devel, shaderc, spirv-tools, VMA,
validation layers, nasm.
- Python 3.12 from python.org, with venv `tools/venv` (capstone, unicorn, lz4).
- Build commands: `make gen` then `make -j` (`docs/BUILD-windows.md`).
### Flags (`Makefile`)
| What | Flags |
|---|---|
| Generated code | `clang -O1 -fno-strict-aliasing -Wno-return-type -Wno-unused-label -fvisibility=hidden -Iruntime -D_FILE_OFFSET_BITS=64 -march=x86-64-v3` (`:39, :91-92`) |
| Runtime | `-O2 -g -fno-strict-aliasing -Wall ...` (`:117`) |
| Exe link | `clang++ -fuse-ld=lld -Wl,--stack,16777216 ... -lvulkan-1 -lshaderc_shared -Wl,--export-all-symbols -Wl,--out-implib` (`:93-95, :104`) |
| Game DLL link | `clang -shared -fuse-ld=lld build/lasrecomp.dll.a` (`:105`) |
### Player build
- zig 0.17.0 `zig cc` with `-mcpu=x86_64_v3`, linked with `zig lld-link @rt/link.rsp`.
- The zig runtime is prebuilt and the bundle slimmed by `tools/zig_slim.sh`; the exe is fetched by
`tools/fetch_zig.sh`.
- The `lasgen.exe` PyInstaller bootloader needs Control Flow Guard cleared, because Unicorn longjmps out of its JIT
(`tools/pe_no_cfg.py`).
### No MSVC dependence
- Target is the mingw-w64 / UCRT ABI.
- The generated C needs GNU/Clang extensions: `__int128`, `vector_size`, `__builtin_shufflevector/convertvector`,
`musttail`, statement expressions, inline asm on arm64. So `cl.exe` cannot compile it; clang-cl would need checking.
### Unknown figures
- Generated file count, C size and compile time are not recorded in the repo.
- Chunking bounds them at 1.5 MB per file. LA main `.text` is about 16.5–23 MB (code patch at `0x7001071220`, rodata
literal at `0x70016afba4`, `tools/patches.py`). That is roughly 4–6 M instructions, so LA is not "small".
- Measure TotK with `python tools/nso.py <exefs>/main` before estimating.
## 5. Game-specific vs generic
- LA-specific, around 22k lines in total:
- `tools/patches.py` (687 lines, 60 hard-coded `0x70…` addresses: widescreen, warp, rando hooks)
- `tools/warp_table.py`, `tools/rando/*` (8.5k)
- `runtime/hle/*` LA files (4.6k), `runtime/rando.c`
- `runtime/nvn/texpatch.c` (1k)
- most of `runtime/ui/*` (6.5k)
- `third_party/LAS-Randomizer`
- hard-coded addresses in `runtime/nvn/cmdbuf.c`, `runtime/hle/movie.c`, `runtime/fnprof.c`
(`grep -l 'main+0x\|0x70[0-9a-f]{8}' runtime`)
- Generic, around 18k lines: recompiler, cpu/dispatch/loader/kernel/ipc, services, platform layer, NVN core, Maxwell
translator, Vulkan backend, ASTC, tegra, generic HLE.
- About 45% of the non-third-party code is LA-only. Of the generic part, the CPU side is reusable almost as-is, while
the GPU/kernel/service side holds only what LA calls.
## 6. Scaling risks for TotK (concrete)
1. **Python generator memory and time.**
- `Module.cache` keeps one `Insn` object (with C strings) per instruction (`gen.py:60-69`), and `scanned` keeps
label sets per function. At 10M+ instructions that is several GB of RAM. Lifting is single-process pure Python.
- Fix: stream functions, drop caches after emission, parallelize lifting across processes (functions are
independent once boundaries are fixed).
2. **Jump-table emulation cost.** Each table index replays address materialization from the function entry
(`gen.py:159-161, 257-264`), so cost is O(entries × function length) per table, through Unicorn single-steps from
Python. Large switch-heavy functions (state machines, AI scripts, Havok) will be slow.
3. **"All labels" fallback** (`gen.py:378-382, 459-463`). Any function with a jump table gets a label on every
instruction and a switch over all of them. Clang -O1 compile time and RAM grow badly, and register promotion dies.
This drives the ~1 GB per compile job budget. Needs a precise table resolver (data-flow on index register and table
base, no emulation) so the fallback is the exception.
4. **Codegen quality.**
- Guest regs live in `Cpu` in memory. `LD/ST` use `may_alias` types plus `-fno-strict-aliasing` (`cpu.h:53-71`,
`Makefile:39`), so clang must assume every guest store can clobber `c->x[]`/`c->v[]` and reload them.
- SIMD helpers carry NaN/FZ checks per op.
- Built at `-O1`.
- Fine for LA at 60 fps; TotK is CPU-bound on Switch.
- Options: cache guest regs in C locals with explicit spill at calls and dispatch; put `Cpu` behind
`restrict`/noalias; FPCR-specialized fast paths.
5. **Fixed layout.** `SDK_BASE = MAIN_BASE + 64 MB` (`rt.h:73-74`, `Makefile`, `gamebuild.c:304`), only 2 modules
(`loader.c:177`), `g_modules[4]`. Make it data-driven (N modules, bases computed from sizes).
6. **Dispatch.**
- 4096-entry per-thread direct-mapped cache; binary search on a miss; linear `overrides` scan on every slow path
(`dispatch.c:145-146`).
- TotK's virtual-heavy code and many threads will miss more.
- Better: a perfect hash or a dense table indexed by `(addr - text_lo) >> 2` (4 bytes × text/4 ≈ text-size
memory).
7. **Missing ISA.** `LDXP/STXP` (`lifter.py:391-392`) trap at run time. Add them via `cmpxchg16b` (x86-64-v3 has it).
Also log a census of `Unsupported` per build (`gen.py:66`).
8. **Call model.** `ret` = C return; guest `BL` = host call. Guest setjmp/longjmp, `nn::os` fibers, or exception
unwinding would break. Audit TotK's SDK imports for `setjmp`, `longjmp`, `__cxa_throw`, `nn::os::Fiber`.
9. **Kernel.**
- One global lock; no scheduler; core masks ignored.
- Unimplemented SVCs are FATAL. The SVC list is LA-scoped: no MapProcessMemory, CreateCodeMemory,
SetThreadActivity, GetThreadContext, etc.
- Handle cap 4096.
- TotK has many worker threads (job system); expect contention on `g_klock`.
10. **GPU.**
- Translator lacks shared memory, atomics, image load/store, gathers, TXD/TMML, bindless and VOTE, and has no
geometry/tess stages. TotK compute and deferred passes will hit these.
- NVN coverage is only what LA calls, and missing calls silently return 0.
- CPU ASTC decode plus RGBA8 upload is 4× VRAM and a large CPU cost on a heavily ASTC game. Use a GPU compute
ASTC decoder.
- Draw skipping on pipeline misses means visible pop-in.
11. **Audio.** No effects or splitters (`audio.c:875`), so TotK reverb/delay will be missing.
12. **Toolchain cost.** Chunk compile at ~1 GB per job. 64-job cap. Single lld link of one DLL. Expect link RAM and
time to scale with object size; consider splitting the game DLL or using LTO-free thin archives.
## 7. Licensing
| Component | License | Where | Impact |
|---|---|---|---|
| LASRecomp code | MIT (`LICENSE`, © 2026 Peiikai) | all of `tools/`, `runtime/` | Reusable with attribution |
| Capstone 5.0.9 | BSD-3 | analyze/sym/tests only | Fine |
| Unicorn 2.1.4 | **GPL-2.0** (Python bindings BSD) | `gen.py` jump tables, tests | Build-time helper only (separate process). Shipping a frozen generator that bundles Unicorn makes that helper a GPL distribution. Replacing it with an own resolver removes the issue |
| Keystone 0.9.2 | **GPL-2.0** | `tools/rando/collect_patches.py` only | Not needed for TotK |
| oead / evfl | **GPL-2.0+** | randomizer only | Not needed |
| LAS-Randomizer | MIT | randomizer | Not needed |
| python-lz4 / LZ4 | BSD | nso.py | Fine |
| Dear ImGui, VMA, SMAA, AMD FSR1 | MIT | UI, renderer | Fine |
| SDL3 | zlib | window/input/audio | Fine |
| FFmpeg 9.0.2 | LGPL-2.1+ (release built LGPL-only, `tools/build_deps_windows.sh`) | movies | Dynamic link only |
| shaderc | Apache-2.0 | GLSL→SPIR-V | Fine |
| zig 0.17.0 / LLVM | MIT / Apache-2.0 w/ LLVM exception | player-side compiler | Fine |
| PyInstaller | GPL-2.0+ w/ bootloader exception | freezing helpers | Fine |
| GCC runtime, winpthreads | GPL-3 w/ runtime exception, MIT/BSD | Windows DLLs | Fine |
| Baloo 2 font | OFL-1.1 | start screen | Fine |
| Ryujinx (audio design reference, `audio.c:14-18`) | MIT | design only | Fine |
envytools docs were used for the shader translator. For the TotK shader work, the Ryujinx shader translator (MIT, C#)
is a license-compatible reference. yuzu's `shader_recompiler` is GPL-2.0+, so code cannot be copied from it into an MIT
codebase.
## 8. Recommendation for the TotK port
### Reuse with fixes
- `nso.py`
- `lifter.py` (add LDXP/STXP)
- `simd_c.py` + `simd.h` + `simd_fp.h` (tested; add fast paths later)
- `cpu.h`, `dispatch.c` (replace the lookup structure), `loader.c` (N modules)
- `platform/windows.c` (reserve + lazy commit + write watch is directly applicable)
- `ipc.c` framework, `services/fs.c` + `romfs_build.c`, `services/time.c`, `hid_set.c`, `hle/input.c`
- `nvn/tegra.c`, `nvn/astc.c` (as the reference/CPU fallback)
- Test harnesses `test_lift.py`, `test_simd.py`, `test_translate.*`, `test_astc.*`
- The recompile-on-user-machine distribution model (`gamebuild.c`, `zig_slim.sh`)
### Rewrite or replace
- `gen.py` driver: scalable, parallel, streaming, precise jump tables without Unicorn
- Register caching in codegen
- Kernel scheduler and locking
- Most of the NVN HLE and Vulkan backend
- Maxwell translator: needs a full SM5.x IR with compute/atomics/images/bindless/gathers
- GPU ASTC
- Audio effects
### Drop
- `patches.py` contents, rando, LA HLE, LA UI, Metal backend
+587
View File
@@ -0,0 +1,587 @@
# MacNativeGames / d2r-mobile / nxnative: research notes
Scope: what the three reference ports do, what transfers to an x86-64 Windows port of TotK, what is Apple-only.
Checkouts (read-only, HEAD at time of study, 2026-10-20):
| Repo | Path | HEAD |
|---|---|---|
| MacNativeGames | `refs/MacNativeGames` | `b75be8c` |
| d2r-mobile | `refs/d2r-mobile` | `53e7c5b` (MacNativeGames copied its generic parts from `9f0c257`) |
| nxnative | `refs/nxnative` | `a35e964` |
All paths below are relative to `refs/MacNativeGames` unless prefixed.
## 0. Architecture in one paragraph
Not an emulator and not a recompiler. The game's three ARM64 NSOs (`main`, `sdk`, `subsdk0`; `rtld` is dropped and the
host links) are rewritten offline so they can run natively on Apple ARM64 (`games/totk/third_party/d2r/patch_nso.py`).
A C host maps them at original relative layout, resolves imports itself, and replaces Horizon at two levels:
(a) kernel SVCs via a "gate" trampoline, (b) whole `nn::*` SDK functions overridden by mangled name at relocation time.
NVN is replaced entirely: `nvnBootstrapLoader` is overridden, all 523 NVN entry points route to a host implementation
that records commands into game memory and replays them on Metal 4. Shaders: Maxwell code -> Ryujinx translator ->
SPIR-V -> SPIRV-Cross -> MSL -> Metal, cached on disk, partially pre-built at app build time.
Consequence for us: the CPU side of their work (rewriter, gate) is ARM64-host-only and useless on x86-64 as code, but it
is an exact, verified census of every place game code touches the OS. Everything above the CPU boundary (SVC
semantics, `nn::*` overrides, NVN command model, shader pipeline, TotK patches, data formats) is reusable knowledge, and
much of it is plain C.
## 1. Build pipeline: XCI/NSP + prod.keys -> app
Entry: `build_app.py` (1028 lines). Steps documented at `build_app.py:1-30` and `docs/how-it-works.md:73-125`.
### 1.1 Inputs
- Base game 1.0.0 only (`0100F2C0115B6000`), XCI or NSP. NSZ/XCZ base unsupported. Personalized tickets unsupported.
- Optional cumulative update NSP/NSZ via `--update`: 1.1.2 (v262144), 1.2.1 (v393216), 1.4.3 (v720896). No intermediate
update needed. DLC and combined packages unsupported (`README.md:66-67, 204`).
- `prod.keys`. NSP needs `--firmware <dir of .nca>` or `--shared-fonts <dir>` (NSP has no system fonts; XCI reads its
update partition) (`README.md:67, 100`).
- Python deps (`games/totk/requirements.txt`): `cryptography==50.0.2`, `lz4==4.4.5`, `capstone==5.0.9`, `nsz==5.0.0`.
Python 3.14 is required because the build uses stdlib `compression.zstd` (`requirements.txt:1`,
`scripts/locate_shaders.py:24`).
### 1.2 Code (step 1, `build_app.py:384-426`)
1. Container detection by header: XCI = HFS0 secure partition, NSP = PFS0 (`docs/how-it-works.md:75`).
2. `games/totk/scripts/extract_exefs.py`: own pure-Python reader, no hactool. NCA3, key-area or common-ticket AES-CTR,
hierarchical SHA-256 PFS0. Title key from ticket decrypted with titlekek from `prod.keys`, in memory only
(`extract_exefs.py:1-5, 93-146`). Ticket signature type `0x10004` is little-endian `04 00 01 00`
(`docs/how-it-works.md:132`).
3. ExeFS hashes compared to `expected-<ver>.json`. A different `main.npdm` is accepted if its ACID signature verifies
against Nintendo's public ACID modulus (`build_app.py:57-70, 146-171`).
4. `scripts/prepare_modules.py` -> ELF inventory; `third_party/d2r/patch_nso.py <nso> <out> <name>` for sdk, subsdk0,
main with `DM_RULESET=native DM_PRIVATE_GATES=0`; output hash must equal `rewritten_sha256` (`build_app.py:410-418`).
5. `scripts/prepare_runtime.py` binds the C loader to the verified images: emits `build/runtime_tables.h` (symbols,
relocations incl. RELR, gates) (`scripts/prepare_runtime.py:1-25`).
### 1.3 Data (step 2, `build_app.py:429-470`, `573-597`)
- Base RomFS: `scripts/extract_romfs.py`, decrypts the 17 GB RomFS into one flat `romfs.bin` + `index.json`, verified
through all six IVFC levels, then whole-image SHA-256 compared (`build_app.py:433-441`).
- Update merge (BKTR): hactool, pinned `https://github.com/SciresM/hactool.git` @ `1d64a83450e025622f3468c28fc4164dad2c5ef6`
(`build_app.py:44`). `build_hactool()` patches the fetched source before `make CC=clang` (`build_app.py:473-570`):
1. `MNG_TITLE_KEYS` env: private title-key file for both tickets, mode 0600, deleted after merge.
2. `MNG_BASE_RANGE_OFFSET/SIZE`: funopen-backed bounded view of the base NCA inside the original XCI/NSP, avoiding a
second 17 GB copy (Darwin `funopen`; Windows needs another mechanism or a temp copy).
3. Two BKTR layout checks relaxed: newer updates leave sector-aligned padding after the subsection table
(`build_app.py:542-565`).
Output via `--sectionN` (not `--romfs`, which does not export the BKTR section) (`docs/how-it-works.md:119`).
Driver: `scripts/extract_update_romfs.py`.
- Update version is chosen by exact ExeFS hashes, not file name; BKTR section marker identifies an update NCA
(`docs/how-it-works.md:117`).
- Shared fonts: `scripts/extract_shared_fonts.py`. Six BFTTF from system data titles starting `0100000000000811`;
BFTTF = big-endian words XORed with `key = word0 ^ 0x7f9a0218`, word1 = size (`extract_shared_fonts.py:19-28, 122-128`).
Other firmware fonts accepted if structurally valid.
- RomFS overlays from the player's files (manifest: path, size, sha256 overlay, sha256 original):
- `scripts/make_romfs_patches.py`: quick-menu capture timing (`UI/LayoutArchive/Common.Product.100.Nin_NX_NVN.blarc.zs`
anim keys moved to frame 0) and 1.0.0 game-over retry (`Event/EventFlow/DmF_SY_GameOver.bfevfl.zs`) (header lines 1-25).
- `scripts/make_output_res_overlay.py`: HeapDef for 2560x1440 (see section 6.3).
### 1.4 Shaders and packaging (steps 3-4)
- SPIRV-Cross @ `aa217aeb6c9f0ace7a0ab233b28807edf45eb165`, compiled from 11 sources with plain clang, no CMake
(`build_app.py:49-54, 600-612`).
- Prebuilt `games/totk/prebuilt/macos-arm64/totk_xlate` checked against `totk_xlate.sha256` (`build_app.py:615-630`).
- `scripts/prepare_shader_seed.py` extracts every shader from the verified RomFS + main module, translates default-bind
variants plus every `V` row from `assets/shader_list.tsv`; refuses to ship fewer than 8,000 (`docs/first-launch-shaders.md`).
1.4.3: 8,290 unique shaders, 24,871 runtime files, ~334 MiB seed.
- Optional: `metal` compiles MSL -> `.metallib` per source hash (`build_app.py:674`); `tools/warm_metal_cache.m`.
- Runtime binary built per version (`games/totk/Makefile:71-72, 341, 351, 361`: `-DTOTK_GAME_V112/V121/V143`), bundled,
codesigned, `--check` run.
### 1.5 Verification hashes (`games/totk/assets/expected-v*.json`)
| | 1.0.0 | 1.1.2 | 1.2.1 | 1.4.3 |
|---|---|---|---|---|
| `main` sha256 | `faf81f8a…a3eaab` | `f04fbebd…08d1ac` | `e5aa8d48…efcb6` | `e84a90d5…2dc9e` |
| `sdk` | `91573d44…4eea` | same | same | `1d187f29…e4ad` |
| `subsdk0` | `9d04c989…3f99` | same | same | `767c35bc…79b1` |
| `rtld` | `28317605…a44d` | same | same | `49308064…2817` |
| RomFS size | 17,069,139,640 | 17,051,988,992 | 17,052,047,360 | 17,052,625,232 |
| RomFS sha256 | `4751542f…dafcf` | `d98fde08…c43` | `c2beb1c2…7c11` | `797e66f2…19e9b` |
Full hashes in the JSON files. Fonts identical across versions. Base card image 17,536,620,544 bytes, program NCA
`9d827368992a2faafa9062aa5458b7ec.nca` (`expected-v1.0.0.json`). 1.0.0-1.2.1 share sdk/subsdk0/rtld; 1.4.3 replaced
all three (new SDK, RELR relocs, GNU-hash-only SDK modules) (`docs/how-it-works.md:125`). nxnative records 1.4.3 build IDs:
`main=277178b7dba1b6d4949a84778d4abc58 subsdk0=f39f4c431234c72eb520cfdd1001bbcf sdk=574284b40c06cf1821a44857939083be`,
SDK 20.5.22 (`refs/nxnative/dm/games/0100F2C0115B6000/game.tsv`).
These hashes are directly reusable for our own input validation.
## 2. NSO rewriter: every place game code touches the OS
File: `games/totk/third_party/d2r/patch_nso.py` (1036 lines, Python + capstone), plus `call_window.py`, `relr.py`.
Verification: `structck.py` (structural, independent llvm-objdump recount), `equiv.py` (Unicorn per-site differential
with mutation negative controls).
### 2.1 Why
Apple's kernel clobbers `x18` (platform register) and owns `tpidr_el0`; Horizon's TLR (`tpidrro_el0`), SVCs and the
system counter have no Darwin counterpart (`patch_nso.py:12-22`). iOS forbids writable code, so the rewrite is static and
never patched at runtime; thread-slot indices come from a read-only "key page" (`patch_nso.py:21, 245-248`).
### 2.2 What is rewritten (linear scan of `.text`, `patch_nso.py:609-619`)
| Instruction | Encoding mask | Replacement |
|---|---|---|
| `svc #n` | `w & 0xFFE0001F == 0xD4000001` | host gate, `arg = imm16` |
| `mrs xN, tpidr_el0` | `0xD53BD040` | load thread slot `KTLS` |
| `msr tpidr_el0, xN` | `0xD51BD040` | store `KTLS` |
| `mrs xN, tpidrro_el0` | `0xD53BD060` | load `KTLR` (Horizon ThreadLocalRegion ptr) |
| `mrs xN, cntpct_el0` | `0xD53BE020` | host gate (timer) |
| `mrs xN, cntvct_el0` | `0xD53BE040` | host gate (timer) |
| any `x18`/`w18` operand | capstone regex | load/modify/store slot `K18` via scratch regs |
`x18` handling variants: plain (`site_plain`, 331-341), conditional branch on x18 (`site_cond`, 343-358), `adr/adrp x18`
(`site_pcrel`, 360-369), `br x18` jump tables with landing pads (`site_br`, 371-391; 1.4.3 adds signed 32-bit offset
tables at five sites, `SIGNED_TABLES` 631-637 keyed by build ID `277178b7…`), `blr x18` call windows (`call_window.py`,
1.0.0 `main+0x9c9858`), LDXR/STXR exclusive windows containing x18 copied whole into the patch area so no stores land
inside the reservation (`find_windows`/`site_window`, 457-582). Function bounds from `.eh_frame_hdr` (584-605).
Local TotK fixes vs upstream: jump-table look-back 8 -> 32 instructions for `main+0x590574` (1.0.0)
(`third_party/d2r/README.md`, `patch_nso.py:649`); exclusive window fallthrough exit fix for `main+0x72afdc`,
`main+0x7aa630` (`patch_nso.py:560-562`).
Not rewritten in code but handled at runtime: `mrs CTR_EL0` and `dc civac` trap on Darwin and are emulated in the
SIGILL handler, SDK only (`games/totk/runtime/loader.c:370-374`).
The `CUTS`, `OBS`, `PARAMS` tables in the copied rewriter are D2R-only (keyed by D2R build ID `db0507f3…`,
`patch_nso.py:54-167, 916-928`); TotK uses none of them. TotK game patches live in the runtime (section 6).
### 2.3 Counts (OS touch-points)
- 1.2.1 main: 31,475 rewrite sites; sdk: 100 SVC/timer gates (`docs/v1.2.1-port.md`). sdk has 33 `cntpct` sites,
14 with destination x19..x23 (`runtime/gate.S` comment at the x0..x29 restore).
- 1.1.2: 55,018 site checks across modules (`docs/how-it-works.md:130`). 1.4.3: 68,968 semantic sites, 554,281
relocations applied at load (`docs/v1.4.3-port.md:20-21`).
- Game `main` itself makes almost no SVCs; the SVCs live in `sdk`. `main` touches the OS mostly through `x18`
(compiler uses it as a general register), TLS (`tpidr_el0`) and imported `nn::*` / `nvn*` functions.
### 2.4 Implication for an x86-64 recompiler
- `x18` is an ordinary GPR in Nintendo's ABI: a recompiler must model it as a normal register; no special handling.
- `tpidr_el0` (user TLS, written by the game) and `tpidrro_el0` (TLR, read-only) need per-guest-thread storage; TLR
layout: host allocates 0x200 bytes TLR, 8 KiB TLS, and stores a dummy pointer at TLR+0x1F8 (`loader.c:277-290`).
IPC message buffer is in the TLR (first 0x100 bytes, `runtime/ipc.c:16`).
- `cntpct_el0`/`cntvct_el0` must return 19.2 MHz ticks: host computes `ns * 12 / 625` (`loader.c:299-300`).
- Exclusive load/store pairs (LDXR/STXR, LDAXR/STLXR) appear in both game and SDK; a recompiler must lower them to
host CAS or equivalent with matching semantics.
- Jump tables via `br x18` with byte/halfword/signed-32 offsets exist; static recompilation must recover them
(the rewriter's recovery logic and the 1.4.3 table list are a ready reference).
- The SVC list in section 3.2 is the complete kernel surface actually used.
## 3. Horizon host
Files: `games/totk/runtime/` (9,856 lines total). Generic parts adapted from d2r-mobile `dm/host`.
### 3.1 Entry and gate
- `runtime/gate.S` (124 lines, ARM64 asm): switches to the per-thread host stack, saves x0-x30, q0-q31, NZCV, FPSR, FPCR
into an 800-byte frame, calls `runtime_dispatch(return_pc, regs)`, restores (x18 skipped).
- `runtime_dispatch` (`loader.c:296-304`): finds the gate by return address in `<module>.gates.tsv`; timer gates write
19.2 MHz ticks to the target register; SVC gates call `runtime_svc` (`services.c:304`).
- Host functions handed to guest code run on the thread's host stack (`runtime/hle_stack.c`, `hle_stack.S`, 4096 thunks).
### 3.2 SVCs implemented (complete list)
`runtime/services.c:304-382`, `runtime/threads.c:1-20, 354-560`, `runtime/ipc.c:169-210`. Unknown SVC = fatal.
| SVC | Name | Where | Notes |
|---|---|---|---|
| 0x01 | SetHeapSize | services.c:369 | 2 MiB granularity, cap 4 GiB; 1.4.3 sets ~2.2 GiB in nninitStartup |
| 0x02 | SetMemoryPermission | services.c:315 -> loader.c:66 | RELRO on module data, 4 KiB logical on 16 KiB host pages |
| 0x03 | SetMemoryAttribute | loader.c:91 | only the RELRO lock (mask=attr=16) |
| 0x04/0x05 | MapMemory/UnmapMemory | services.c:131 | stack moves; copy + protect source |
| 0x06 | QueryMemory | services.c:343 | synthesizes MemoryInfo for heap, alias, stack, modules |
| 0x08-0x0A | Create/Start/ExitThread | threads.c:354-378 | |
| 0x0B | SleepThread | threads.c:379 | 0/-1/-2 = yields |
| 0x0C/0x0D | Get/SetThreadPriority | threads.c:409-410 | prio 28..59 |
| 0x0E/0x0F | Get/SetThreadCoreMask | threads.c:411-418 | bookkeeping |
| 0x10 | GetCurrentProcessorNumber | threads.c:419 | virtual core |
| 0x11/0x12/0x17 | SignalEvent/ClearEvent/ResetSignal | threads.c:506 | |
| 0x15 | CreateTransferMemory | ipc.c:202 | |
| 0x16 | CloseHandle | threads.c:549 | |
| 0x18 | WaitSynchronization | threads.c:522 | |
| 0x19 | CancelSynchronization | threads.c:542 | |
| 0x1A/0x1B | ArbitrateLock/Unlock | threads.c:422-430 | tag = owner handle, bit 0x40000000 = waiters |
| 0x1C/0x1D | WaitProcessWideKeyAtomic/SignalProcessWideKey | threads.c:431-469 | condvars |
| 0x1F | ConnectToNamedPort | ipc.c:188 | only `sm:` |
| 0x21/0x22 | SendSyncRequest(+WithUserBuffer) | ipc.c:193 | in-process CMIF/HIPC/TIPC server |
| 0x25 | GetThreadId | threads.c:420 | |
| 0x26 | Break | services.c:377 | |
| 0x27 | OutputDebugString | services.c:378 | |
| 0x29 | GetInfo | services.c:317-338 | ids 0-8,10-18,20-23,28; 18 = program id `0x0100f2c0115b6000` |
| 0x2C/0x2D | MapPhysicalMemory/Unmap | services.c:339, 159-191 | alias region, 4 KiB page bitmap; LimitReached `0x10801` on pool exhaustion |
| 0x34/0x35 | WaitForAddress/SignalToAddress | threads.c:470-500 | |
| 0x45 | CreateEvent | threads.c:501 | |
Semantics follow Atmosphère mesosphère (KConditionVariable, KAddressArbiter, KSynchronization) (`threads.c:12`).
### 3.3 Services
Only one real IPC service is served in-process: `audren:u` (`runtime/audio_renderer.c:343`), plus `sm:` itself.
Everything else is replaced at the `nn::*` function level by mangled-name override during relocation
(`loader.c:209-228`: `runtime_observer` for JUMP_SLOT, then `runtime_override`, wrapped to run on the host stack).
~163 distinct symbols across:
| Area | File | Count | Examples |
|---|---|---|---|
| oe/aoc/pctl/err/diag/fs init | `services.c:289-302` | 24 | GetDesiredLanguage, GetOperationMode, GetPerformanceMode, aoc list = empty |
| fs | `fs_host.c`, `romfs.c` | 31+2 | MountRom, MountSaveData, MountCacheStorage, file/dir ops; saves = host dir |
| hid | `input.c`, `hid_feedback.c` | 16+13 | GetNpadStates (FullKey/Handheld/JoyDual/...), six-axis, vibration |
| applet/oe/nfp/err | `applet_host.c` | 31 | notification messages, launch params, nfp (amiibo) stubs |
| time | `time_host.c` | 13 | clocks, ToCalendarTime, ClockSnapshot (0xD0 layout) |
| codec | `opus_codec.c` | 7 | HardwareOpusDecoder -> libopus |
| movie | `movie_host.c` | vtable | `movie::Decoder` (subsdk0 = NintendoSDK_movie) -> libvpx VP9 |
| pl | `shared_font.c` | 3 | shared font address/size/state |
| swkbd | `swkbd_host.c` | 7 | ShowKeyboard -> host text entry |
| account | `account.c` | 6 | preselected user, nickname |
| vi | `frontend.m` | 5 | OpenDefaultDisplay, CreateLayer, GetNativeWindow, vsync event |
| os | `threads.c`, `services.c` | few | CreateSystemEvent, AllocateAddressRegion (observed) |
| nvn | `hle_nvn.c` | 523 | via `nvnBootstrapLoader` |
Startup: host calls the game's own `nn::init::Start(main_thread_handle, 0, rtld_cb, module_inits, module_finis)` in sdk
(`loader.c:470-477`); DT_INIT for each module is run from the callback (`loader.c:458-462`). nnMain return PC is a
version-table checkpoint.
TotK-specific vs generic: thread/sync/IPC/gate/stack code is generic (adapted from D2R). Memory layout constants,
`nn::*` override list (driven by what TotK `main` imports), audio REV11/REV15 renderer, movie decoder, fonts, swkbd hook
by PLT/GOT address are TotK-shaped. Roughly half of `runtime/` is game-agnostic Horizon emulation.
### 3.4 Threading model
- One guest thread = one host pthread running on the guest stack the SDK allocated (`threads.c:4-14`).
- All waits under one global mutex `G`, one condvar per thread; correctness first.
- Virtual cores: TotK keys per-core allocators/job queues by `GetCurrentProcessorNumber` without locks, so guest threads
must hold one of 3 virtual application cores while running guest code; core released only where Horizon would switch
(waits, sleep, yield, exit, blocking host calls). `TOTK_FREE_CORES=1` disables (`threads.c:120-150`). **Critical
correctness constraint for any port.**
- Guest threads run at `QOS_CLASS_USER_INTERACTIVE` (`threads.c:235`).
### 3.5 Memory layout
`runtime/services.c:18-123`, `docs/how-it-works.md:27-32`.
- All guest memory must be below 2^39: the SDK encodes IPC buffer addresses in 39 bits (HIPC descriptor bits 36..38).
- macOS 26: alias region fixed at `0x70_0000_0000`, size 64 GiB (real Horizon 39-bit size). Stack region 256 MiB, heap
region below it; 6 GiB low reservation searched from `0x3_0000_0000`.
- Fallback (macOS 27/iOS): one hole for stack+heap+alias, alias shrunk in 4 GiB steps down to 8 GiB; game uses < 3 GiB.
- Application pool reported: `0xCD500000` (~3.2 GiB, retail) + extra for 2K heaps (`services.c:60-63`).
- System resource 32 MiB; NPDM declares 24 MB system resource, so the game uses the alias region via MapPhysicalMemory
(`refs/nxnative/dm/games/0100F2C0115B6000/game.tsv`).
- Module images: page-aligned, main gets one extra writable page after its image for patch data (`loader.c:182-185`).
- Host page size 16 KiB asserted (`loader.c:489`); Windows has 4 KiB pages / 64 KiB allocation granularity, which makes
guest-exact 4 KiB permission tracking easier than on macOS.
### 3.6 TLS
Per thread: 8 KiB TLS block (`tpidr_el0` target), 0x200-byte TLR (`tpidrro_el0` target), dummy pointer at TLR+0x1F8,
256 KiB sigaltstack (`loader.c:269-290`). Slot storage = Darwin pthread keys read through `tpidrro_el0 + key*8`.
## 4. NVN layer (NVN on Metal)
Location: `games/totk/third_party/d2r_gfx/gfx/nvn/` and `gfx/tex/`. Mapping reference:
`refs/d2r-mobile/dm/gfx/nvn_metal_mapping.md` (78 lines, good one-page spec).
### 4.1 Files and size
| File | Lines | Role | Backend |
|---|---|---|---|
| `hle_nvn.c` | 2,727 | API front: 258 `NVN(...)` implementations, object semantics, command recording | agnostic C (uses mach for VM, pthread) |
| `totk_nvn_ext.c` | 275 | NVN 55 extras (debug labels, deferred binds, timestamps) | agnostic |
| `nvn_obj.h` | 203 | in-place object layouts + command record format | agnostic |
| `include/nvn.h` | 1,756 | NVN types/structs | agnostic |
| `nvn_protos.h`, `names.txt` | 577, 523 | prototypes, 523 entry names | agnostic |
| `nvn_thunks.S`, `nvn_entry.S` | 6,813, 79 | generated ARM64 counting thunks per entry | ARM64 asm, regenerate |
| `nvn_tex.c`/`.h` | 164 | texture layout sizes (deko3d-derived, zlib) | agnostic |
| `nvn_dirty.c` | 253 | write-protect dirty-page tracking of pool memory | OS VM API (mprotect/mach) |
| `totk_vpool.c` | 121 | virtual memory pools via `mach_vm_remap` | OS VM API |
| `nvn_hmap.h`, `nvn_pool_index.h`, `totk_serial_set.h`, `nvn_cube_group.h`, `nvn_pso_skey.h` ... | ~1,000 | containers, pool index, PSO state keys | agnostic |
| `nvn_mtl.m` | 13,696 | replay of command streams onto Metal 4, PSO cache, render passes, present | Metal / ObjC |
| `totk_mfx.m`, `totk_mfx_up.m` | 621 | MetalFX upscale + frame interpolation | Apple-only |
| `totk_shader_rt.m` | 279 | runtime shader translation client, cache, variants | Foundation + spawn |
| `nvn_refl.m` | 108 | reflection JSON -> bindings | Foundation |
| `fps_overlay.c`, `totk_sysload.c` | 428 | HUD via CoreText, IOKit load | Apple-only |
| `gfx/tex/nvn_deswizzle.c`, `nvn_bcdec.c`, `nvn_bc1astc.c` | ~270 | block-linear deswizzle, BC decode, BC1->ASTC | agnostic |
| `gfx/tex/nvn_deswizzle_gpu.m`, `nvn_bctc.metal`, `nvn_fmt_mtl.c` | ~980 | GPU deswizzle, BC transcode shaders, NVN->MTLPixelFormat | Metal |
Totals: `gfx/nvn` 29,295 lines (incl. 6,813 generated asm); Metal-specific ~15,000; backend-agnostic C ~6,000.
### 4.2 Model
`hle_nvn.c:1-20`, `nvn_metal_mapping.md`:
- `main` imports only `nvnBootstrapLoader`; host overrides it; the NVN driver in sdk never runs. All 523 names resolve to
counting thunks; unimplemented = fatal (`hle_nvn.c:54-66`). TotK requires NVN API 55, minor >= 15
(`hle_nvn.c:153`, check at `main+0xe9d614`). Device integer queries return Tegra X1 values (`hle_nvn.c:150-165`).
- GPU address = CPU address. Memory pools are game memory wrapped as zero-copy MTLBuffers (16 KiB-rounded,
overlapping allowed). Buffer address -> (MTLBuffer, offset) via interval table.
- Commands recorded into the game-provided command memory in `nvn_obj.h` format; replayed at `QueueSubmitCommands`.
CPU-visible side effects (event writes, counters, sync) happen after GPU completion.
- Sync object = submit fence value; `SyncWait` returns after the GPU reaches it (MTLSharedEvent).
- Textures: block-linear, deswizzled on upload; CPU writes detected by write-protect dirty tracking and re-uploaded.
TotK streams textures by CPU write + `nvnMemoryPoolFlushMappedRange` (`nxnative game.tsv: tex_flush_upload`).
- Window: game-owned swapchain textures presented by a present thread with `WindowSetCrop`.
- Shader bindings: driver constant buffers c0 (SSBO table) and c2 (texture/sampler handles) are filled by the replay
layer. TotK offsets: combined texture handles c2+0x20 (32 slots x 8 B), separate textures c2+0x168, samplers
c2+0x568, images c2+0x120; c0 SSBO tables vs=0x110 ps=0x510, compute c0 0x200 (group counts) / 0x210 (UBO table),
vertex point-size limit c0+0x610 (`tools/totk_xlate/Service.cs:26-37`); nxnative lists cs SSBO base 0x310 (`game.tsv`).
- Conditional rendering in GPU order (`nvn_mtl.m:1679`), occlusion queries via visibility buffer (`nvn_mtl.m:724`),
layered passes (`nvn_mtl.m:7252`), store-action lookahead (`nvn_mtl.m:3786-3830`), PSO prediction on submit thread
(`docs/pipeline-prediction-stalls.md`).
- `nvn_mtl.m` still contains D2R-only paths (shop drag image `8662`, 3D brightening `9948`, world freeze `10380`,
power-save `10426`): dead weight for TotK.
### 4.3 Retarget to Vulkan or D3D12
Reusable as-is or with small edits: `hle_nvn.c`, `nvn_obj.h`, `nvn.h`, `nvn_protos.h`, `names.txt`, `nvn_tex.c`,
`gfx/tex/*.c`, PSO state key logic, pool index, serial set, the c0/c2 slot conventions, reflection format.
Replace: `nvn_mtl.m` (13.7k lines of ObjC/Metal 4), MetalFX, CoreText overlay, `nvn_dirty.c`/`totk_vpool.c` VM calls
(`VirtualProtect` + vectored exception handler, `MapViewOfFile3`/placeholders for remap), the ARM64 thunk asm
(x86-64 or plain C function table).
Vulkan is the natural target: SPIR-V from the Ryujinx translator feeds it directly (drop SPIRV-Cross and MSL rewriting),
Ryujinx's own Vulkan backend is a working reference for Maxwell-on-Vulkan state mapping, and features Metal lacked
(quads via index emulation, depth clamp, geometry stages, subgroup ops in vertex stage, border colors) are mostly native.
Zero-copy "GPU address = CPU address" maps to `VK_EXT_external_memory_host` or to explicit buffer mirroring with dirty
tracking; on discrete GPUs (no unified memory) the pool-as-buffer model needs staging, which is the biggest design change.
D3D12 would need SPIR-V -> DXIL (spirv-cross HLSL or dxil-spirv); more work, no benefit.
Estimate: a Vulkan replay layer of similar scope to `nvn_mtl.m` (10-15k lines), reusing the front end unchanged.
## 5. Shader path
### 5.1 Translator
- `vendor/ryujinx`: Ryujinx 1.3.2 `Ryujinx.Graphics.Shader`, `Ryujinx.Common`, `Spv.Generator`, unmodified in-tree
(`vendor/ryujinx/README.md`).
- `games/totk/tools/totk_xlate/`: `Program.cs` (215, IGpuAccessor answering texture/attr/output types from a job file,
c1 constant segment needed for BRX jump tables), `Service.cs` (468, `--service` line protocol: JSON request ->
SPIR-V -> spirv-cross MSL + reflection JSON), `VertexCounterLowering.cs` (61).
- `publish_native.sh`: copies vendor/ryujinx, applies patches, `dotnet publish -r osx-arm64 -p:PublishAot=true`.
For Windows: `-r win-x64`. .NET SDK 10.0.401 used (`prebuilt/macos-arm64/README.md`).
- Patches (`tools/totk_xlate/patches/`), all to Ryujinx shader optimizer, all real correctness bugs, all relevant to any
SPIR-V consumer:
1. `0001-keep-call-arguments-in-variables`: don't propagate expressions into Call args (SPIR-V passes args by pointer).
2. `0002-keep-live-call-sources-when-removing-dead-node`: DCE must not strip sources of side-effecting ops (TotK
sun-visibility kernel `c7830fac` lost its atomicMin).
3. `0003-keep-side-effect-assignments-in-the-ast-optimizer`: unused-result atomics (Maxwell RED, ATOM to RZ) kept.
4. `0004-no-else-if-flattening`: else-if flattening gave shared merge blocks; SPIRV-Cross then dropped the trailing
else (fragment shader `1870878a` lost loops with atomic max + discard; 12 variants lost atomics, 83 changed discards).
Note: 0004 is a SPIRV-Cross interaction; check whether the Vulkan path needs it (probably harmless to keep).
- Exact-hash lowerings: visibility-counter vertex shader uses subgroup ballot + atomic; lowered to one atomic add per
passing invocation, restricted to code SHA-256 `EABE9FDD…24AD` (1.1.2/1.2.1) and `F5F4D231…1FF7B` (1.4.3)
(`VertexCounterLowering.cs:1-20`). Needed on Metal only because vertex-stage subgroup builtins were unavailable through
SPIRV-Cross; Vulkan supports subgroup ops in vertex shaders, so likely not needed.
- MSL post-processing in Service.cs: depth textures sampled as plain textures rewritten to `depth2d` etc.
(`Service.cs:39-46, 118+`), FP64 detection (`Service.cs:47`). Metal-only.
- Window origin upper-left, depth 0..1 (game sets via `nvnDeviceSetWindowOriginMode`/`SetDepthMode`); some shaders use
`NEAR_IS_MINUS_W` (`totk_shader_rt.m:29`).
### 5.2 Shader identity and extraction
- Key = SHA-256(first 0x880 bytes of NVN control section + code) (`totk_shader_rt.m:1`, `nvn_mtl.m:4962-4963`).
Control sections are 0x880 or 0x88c bytes; only 0x880 is hashed. Graphics code has a 0x30-byte NVN header
(+ 0x50-byte SPH inside code per Program.cs) (`scripts/locate_shaders.py`).
- Variant = shader + translator "answers" (texture slot types, image formats, attr/output component types); variants
reused only if answers match current bind state.
- Sources (`scripts/prepare_shader_seed.py:75-210`, `docs/first-launch-shaders.md` step 1):
- BNSH files (`BNSH` magic, `grsc` at +96) inside `Shader/*.bfsha.zs` (BFSHA; `material.bfsha` holds most),
`Effect/*.esetb`, UI layouts.
- agl `.sharcb` (`BAHS` magic) in `Lib/agl`, `Shader/ApplicationPackage`, `Lib/Terrain`, `Lib/gsys`: records
`<u64 code offset, u32 control size, i32 control offset>`; controls may be shared. Missing these = magenta title.
- BNSH embedded in `main`.
- RomFS `.zs` = zstd with dictionaries from `Pack/ZsDic.pack.zs` (SARC of dicts); SARC nesting up to 4 deep.
- Counts: 1.0.0 9,360; 1.1.2 8,286; 1.4.3 8,290 unique shaders, 0 offline translation failures.
### 5.3 Shared shader list and pipeline cache
- `games/totk/assets/shader_list.tsv`: 41,414 `V` (shader key + deps JSON), 1,557 `S` (libraries to warm), 63 `C`
(compute pipelines), 4,737 `R` (render pipelines, hex-encoded key), `L` locator rows (`docs/shader-list.md`).
Identifiers only, no game data. `t` flag = title screen set (1,445 rows across versions), `m` = background warm.
The `V` rows (shader hash + bind state) are backend-agnostic and directly reusable to pre-translate SPIR-V for Vulkan.
`R` rows encode Metal-pipeline-specific state keys and are not portable.
- Runtime cache: `~/Library/Application Support/MacNativeGames/TOTK/shader-cache`; missing variants appended to
`shader-list-contribution.txt`.
- First-compile stalls (100-900 ms) remain the main perf issue; long sessions showed footprint growth 4.5 -> 6.25 GiB
(`docs/v1.4.3-port.md:55-72`).
## 6. TotK-specific knowledge (CPU-approach independent)
### 6.1 Version address table (`games/totk/runtime/game_version.h`)
Keys are 1.0.0 main offsets; values per version. Generated by `scripts/map_version_sites.py` (instruction-window search
ignoring PC-relative fields; data via ADRP+LDR users; functions via callers) (`docs/v1.2.1-port.md`, "补丁地址").
| Role | 1.0.0 | 1.1.2 | 1.2.1 | 1.4.3 |
|---|---|---|---|---|
| present-interval controller clamp (fps60) | 0x8f6c60.. | 0x8f66e4.. | 0x8f273c.. | 0x2db204.. (`game_patches_v143.c:16-22`) |
| frame-step producer (realtime) | 0x7a83f4.. | 0x7f7a38.. | 0x7ede7c.. | 0x2daa54, 0x3e5658 (`game_patches_v143.c:74-75`) |
| global ratio | 0x8f68b8.. | 0x8f633c.. | 0x8f2394.. | in 0x2daa54 block |
| scene render size store | 0xc630bc | 0xcdd3e8 | 0xcc3f68 | 0x585e48 |
| output size getter call | 0xc630a4 | 0xcdd3d0 | 0xcc3f50 | 0x3dcb28 (display cfg +0x10/+0x508) |
| swapchain size const | 0xe996ac | 0xea7efc | 0xe7aa3c | 0xbdb578 |
| nnMain return checkpoint | 0xe995c4 | 0xea7e14 | 0xe7a954 | 0xbdb48c |
| forceSetMatrix | 0x69a18c | 0x70376c | 0x6ba86c | 0x45ce70 |
| scene slot (data) | 0x4663f08 | 0x4725058 | 0x4728538 | 0x3add238 |
| stale-ref crash site | 0x15ecb0c | 0x1627f10 | 0x1622bf0 | 0x1bd01c4 |
| ShowKeyboard PLT / GOT | 0x2aa4fa0 / 0x453f648 | 0x2b16100 / 0x46129e0 | 0x2b18000 / 0x4615d78 | 0x2bb79f0 / 0x398b348 |
| frame controller return | 0x8f6cbc | 0x8f6740 | 0x8f2798 | 0x2db2ec |
| actor name/pos/rot offsets | 0x210/0x2ac/0x2b8 | 0x218/0x2b4/0x2c0 | same | same |
| ultrawide camera/viewport | - | - | 0xcb4b10, 0x12521cc, 0x19b36f0, 0x1ecdf68 | 0x628c74, 0xb43460, 0x1ff04f4, 0x253fbb0 |
Exact original/replacement words per site: `game_patches.c:27-35, 121-126, 169-173, 298-304`;
`game_patches_v143.c:16-22, 74-75, 193-194, 260-263`. Every patch verifies original words before writing.
### 6.2 Frame timing (the 30 -> 60 fps unlock)
- Adaptive present-interval controller `main+0x8f6bec` (1.0.0), called once per frame from `main+0x8f68b4`, converts
measured frame work time (system object +0x118) into 60 Hz ticks clamped to [min, max]; result goes to
`nvnWindowSetPresentInterval` and to the variable frame-rate step `main+0x7a83e4` (ratio = interval*0.5, frame time =
interval/60). Shipping min = 2 (30 fps). Patch lowers min to 1 (7 instructions) (`game_patches.c:13-35`).
- Real-time step: replace the producer with two floats read from a data page (ratio = dt*30, dt seconds), updated each
present from a 5-sample moving average of present intervals, clamped to [1/120, 1/15] s (`game_patches.c:42-154`).
- 1.4.3: FrameRateMgr has two call sites fed from `0x3e5658` with a 0.5/1.0 coefficient selected by `sys+0x1da` bit 0;
replace the nominal 60/FPS value before the multiply, not the callee entry (`docs/v1.4.3-port.md:48`).
- nxnative alternative for 1.4.3 (`refs/nxnative/dm/tools/patch_nso.py:1037-1168`): interval picker `main+0x2db174`,
int fps at timing +0x50 read at `main+0x2daa54` and `main+0x3e562c`, float fps at +0x24; host chooses whole-vsync
steps; FPSLocker-derived fixes: D-pad menu fade `main+0x1fbc80`, swapchain argument `main+0xbe14a8` = 1, movie start/end
30 fps cap at `main+0x2b36100`/`main+0x2b33918`, view render scale at `main+0xd5c24`.
- Side effects of high fps: game-over "Retry" hung on 1.0.0 because `DmF_SY_GameOver` waits one frame after pausing;
fixed by RomFS overlay. 1.1.2+ use `DmF_SY_GameOver.110` (EventWaitUpdate), unaffected
(`scripts/make_romfs_patches.py` header). Quick-menu capture background black at 60 fps; fixed by moving bflan
visibility keys to frame 0.
- `TOTK_PCHTXT` loader accepts community emulator pchtxt patches (by `@nsobid`) (`game_patches.c:387-423`).
### 6.3 Resolution
- Scene render size from parameter tree (`main+0xc6325c`: handheld 1280x720, docked 1600x900), stored in renderer
+0xcc4/+0xcc8 (`game_patches.c:156-168`). 1.4.3 actual scene RT is 1600x896.
- Output/swapchain 1920x1080 constant before "NvInitializeGraphics" (`main+0xe996ac`); canvas from graphics params
(+0x38 output, +0x30 scene) (`game_patches.c:207-235`). 1.4.3: display config object +0x10 canvas, +0x508 crop,
+0x528 scale, pending bit 21 of +8 (`game_patches_v143.c:144-148`).
- Runtime mode switch path: post `nn::oe` message 30 (operation mode changed) + set renderer +0xca4 bit 0x200 ->
`main+0x1185310` handler relayouts (`game_patches.c:222-230`).
- 2560x1440 needs bigger heaps: `System/HeapSize/Product.Nin_NX_NVN.HeapDef.byml.zs`: `DynamicTextureAllocatorMem`
113,664 KiB (parent `Graphics` 201,728 KiB); scale by pixel ratio, grow Graphics and the app pool by the same amount
(+89,088 KiB at 1440p) (`scripts/make_output_res_overlay.py`, `game_patches.c:271-284`).
- UI canvas width cap, 19:9 aspect constants (D2R; not TotK). TotK ultrawide: patch every producer of the projection
aspect ratio (sead camera +0xb0), DefaultAspect 1.777778 in rodata only copied at camera creation
(`runtime/aspect_patch.h:1-13`).
- Final upscale shader hashes: EASU `a3a570eb…` (old), `ac58fc18…` (1.4.3, multiplies by 1/3.5 then 3.5, R11G11B10F)
(`docs/v1.4.3-port.md:39`).
### 6.4 Game data and engine facts
- Engine: sead / agl / gsys, NintendoWare G3d2 / Ui2d / Vfx2, Havok; `main` imports `nn::ro` (NRO loading)
(`refs/nxnative/dm/games/0100F2C0115B6000/game.tsv`). subsdk0 = NintendoSDK_movie (Android MediaCodec over NvMM).
- Heaps: `sead::ExpHeap` use list at +0xc8, heap self ptr +0x28, size +0x30 (`loader.c:394-419`).
- Movies: 28 WebM in `Event/Movie`, VP9 profile 0, 1920x1080, 30 fps, video only; NVDEC path aborts without a host
decoder; `movie::Decoder` 17 vtable methods, output format 4 = NV12; pacing by PTS required at >30 fps
(`runtime/movie_host.c:1-24`). Identical across 1.0.0-1.2.1.
- Audio: `audren:u` REV11 (Q14 biquads) and REV15 (1.4.3: 0x188-byte voice input, float biquads, 0xa8 splitter
destination) (`docs/v1.4.3-port.md:26`); effects (delay, reverb, compressor) ported from Ryujinx.Audio. Voice streams
are Opus via `nn::codec::HardwareOpusDecoder` with 8-byte big-endian header {payload size, final range}
(`runtime/opus_codec.c:1-5`). 1.4.3 English voice: 280,723 packets.
- Streamed audio bug: `content://Sound/Resource/Stream/Dm_OP_0001.bwav` has a double separator after the mount name;
path parser must skip repeated `/` (`docs/audio-troubleshooting.md`, `runtime/romfs_path.h`).
- Save format (1.1.2/1.2.1): 2,307,656 bytes, header `0x47E0F4`; 54 files in a profile (`docs/v1.2.1-port.md`).
- Language codes the game accepts via `GetDesiredLanguage`: ja, de, fr, es, it, nl, ru, ko, zh-Hans, pt (pt-BR on 1.4.3),
en-US (`services.c:246-272`).
- RomFS file counts: 1.1.2 304,471; 1.2.1 304,473; 1.4.3 304,243.
### 6.5 Known pitfalls (from docs and loader)
1. Virtual cores: per-core lock-free data in the game; must emulate 3 application cores (section 3.4).
2. 39-bit guest address limit for IPC (section 3.5).
3. MapPhysicalMemory must map only unmapped pages and leave mapped ones intact; TotK heaps grow by remapping overlapping
ranges. Pool exhaustion must return LimitReached (132 -> `0x10801`), not `0xd401` (abort) (`services.c:164-174`).
4. Texture auto block height: NVN truncates `height_in_blocks*1.5/8`; deko3d rounds up; wrong at boundaries (shrine warp
pad 160x160 BC3-sRGB shows black) (`docs/how-it-works.md:47-55`).
5. D16 load-clear vs fragment depth rounding differ (0.5 -> 32767 vs 32768); Ultrahand/Recall classification grid
(`docs/how-it-works.md:57-63`). Check on Vulkan too.
6. Aliased memory (virtual pools remapping physical pools, two pools on same CPU memory) needs alias-aware barriers
(`docs/how-it-works.md:67-71`).
7. Crash workarounds in game code: stale optional target reference at `GAME_ADDR(0x15ecb0c)` (object+0x6b0) after long
play (#57); tagged invalid reference `0xffff0000ffffffff` during save load (`loader.c:313-369`). A recompiler must
reproduce or patch these.
8. TotK reserves only 16 bytes for `NVNtextureView` on its stack (`main+0x823398`), host objects must fit NVN's reserved
sizes (`nvn_obj.h` FITS asserts).
9. Shader translator optimizer bugs (section 5.1).
10. Long-session metadata growth (dead-serial hash sets ~1 GiB after 3 h) (`docs/serial-history.md`).
11. Mods: RomFS-only overlay via manifest; ExeFS/IPS not supported (`README.md:200`).
## 7. Apple-only vs portable
| Component | Files | Status |
|---|---|---|
| NSO rewriter, gate, thread_enter, hle_stack asm, NVN thunks | `third_party/d2r/*.py`, `runtime/*.S`, `nvn_thunks.S` | ARM64-host-only. Useless for x86-64 execution; valuable as OS-touch census and verification method |
| Loader | `runtime/loader.c` | logic portable (reloc kinds 1027/257/1025/1026, RELR, symbol override); mmap/mach/CommonCrypto/signals Apple/POSIX |
| Kernel emulation | `runtime/threads.c`, `ipc.c`, `services.c` | portable C over pthreads + mach_vm; Windows needs VirtualAlloc2 placeholders, SRWLock/CondVar or winpthreads |
| `nn::*` overrides | `fs_host.c`, `romfs.c`, `time_host.c`, `account.c`, `applet_host.c`, `opus_codec.c`, `movie_host.c`, `shared_font.c`, `swkbd_host.c`, `hid_feedback.c`, `input.c`, `audio_renderer.c`, `audio_effects.c`, `audio_reverb.c` | portable C (libopus, libvpx); CommonCrypto SHA-256 to replace |
| Audio output | `audio_mixer.c` | AudioToolbox; replace with WASAPI/XAudio2/SDL |
| Input, haptics, motion | `gamepad.m`, `gamepad_feedback.m` | GameController/CoreHaptics/IOKit; replace with SDL3/XInput |
| Window, front end | `frontend.m`, `app/launcher.m`, `frontend_ios.m` | AppKit/UIKit |
| Graphics replay | `nvn_mtl.m`, `nvn_refl.m`, `totk_shader_rt.m`, `gfx/tex/*.m`, `.metal` | Metal 4 |
| Upscale / interpolation | `totk_mfx*.m` | MetalFX; replace with FSR/DLSS/XeSS or drop |
| HUD | `fps_overlay.c`, `totk_sysload.c` | CoreText/IOKit |
| Shader translator | `vendor/ryujinx`, `tools/totk_xlate` | portable C#; NativeAOT for win-x64 works |
| Build | `build_app.py`, `scripts/*.py` | mostly portable Python; Apple bits: `xcrun`, codesign, lsregister, APFS clone, `funopen` hactool hook |
## 8. Toolchain
- macOS 26+ on Apple silicon (Metal 4), Xcode command-line tools (`xcrun clang`, C11, `-fobjc-arc`).
- Homebrew: `opus`, `libvpx` (linked statically from `/opt/homebrew/opt/*/lib/*.a`), `python@3.14`.
- Python 3.14 (stdlib `compression.zstd`), venv with `cryptography`, `lz4`, `capstone`, `nsz`; dev: `unicorn==2.1.4`,
`Pillow`, `brotli` (`requirements-dev.txt`).
- .NET 10 SDK (10.0.401) only to rebuild `totk_xlate` (NativeAOT).
- Fetched at build: hactool @ `1d64a83`, SPIRV-Cross @ `aa217ae`.
- Optional: Xcode Metal toolchain for offline `.metallib`; iOS: Xcode 26, xcodegen, cmake, ninja.
- Single-instance "game slot" lock for all GPU tests (`runtime/game_slot.c`).
## 9. Licenses
From `THIRD_PARTY_NOTICES.md` and LICENSE files:
| Code | License |
|---|---|
| MacNativeGames (repo) | MIT (`LICENSE`) |
| `third_party/d2r` (rewriter, verification), `third_party/d2r_gfx` (NVN on Metal), `tools/totk_xlate` | MIT (d2r-mobile) |
| `nvn_tex.c` texture layout sizes | zlib (deko3d) |
| bcdec 0.985 | MIT or public domain |
| `vendor/ryujinx` (Shader, Common, Spv.Generator 1.3.2) | MIT |
| audio effects/mixer ported from Ryujinx.Audio | MIT (`third_party/licenses/Ryujinx-Audio.txt`) |
| SPIRV-Cross | Apache-2.0 |
| hactool (+ bundled mbedTLS) | ISC (+ Apache-2.0) |
| libopus, libvpx | BSD-3-Clause |
| d2r-mobile | MIT |
| nxnative | MIT (`refs/nxnative/LICENSE`); bundles libvpx, stb_vorbis, libdeflate, Vulkan headers, NVIDIA FLIP with their own licenses |
The TotK-Ultrawide community mod is GPL; MacNativeGames states none of its code is used (`runtime/aspect_patch.h:6`).
Everything we would reuse (host C, NVN front end, translator patches, addresses, hashes) is MIT/zlib/Apache: compatible
with any license we choose.
## 10. nxnative and d2r-mobile notes
- d2r-mobile `dm/host` is the generic origin (loader, `hle_svc.c`, `hle_thread.c`, `hle_table.c` for libc passthrough,
`HLE`/`HLE_FORCE` registration with mandatory reasons, `UNIMPL` named stubs). Offline shader route: everything
pre-translated to metallib, no runtime translation. `dm/gfx/nvn_metal_mapping.md` is the best concise NVN spec.
- nxnative generalizes to 14 games with per-game profiles (`dm/games/<title id>/game.tsv`), including TotK 1.4.3 and BotW
1.9.0 (shares sdk/subsdk0 build with TotK per its comment), Vulkan-on-Metal path for Hades (`dm/gfx/vk/hle_vk.m`),
LibHac-based `dm/tools/nx_extract` (.NET) for NSP + update layering. Its TotK profile has memory numbers
(`mem_alias 0x98000000`, heap `0x86000000`, app pool `0xCD500000`) and NVN constant-buffer bases. One-script packaging:
`scripts/build_ipa_from_nsp.py` (1,229 lines).
## 11. Takeaways for the Windows x86-64 port
1. The CPU strategy must change (no native ARM64), but the rewriter's site census (`sites.tsv`, `gates.tsv` per module)
is a precise list of every SVC, timer read, TLS access and x18 use; reuse `patch_nso.py`'s scanner as an analysis
tool for the recompiler front end.
2. The host boundary is mostly at `nn::*` function level, not IPC: a recompiler can link recompiled `main` against host
implementations of ~163 `nn::*` symbols plus 523 NVN entries, and either recompile `sdk` (for os/thread/heap code
that uses the 38 SVCs in section 3.2) or HLE more of it.
3. Port as C: `threads.c`, `ipc.c`, `services.c` memory logic, `fs_host.c`, `romfs.c`, `time_host.c`, audio renderer
and effects, opus, movie, fonts, swkbd, `hle_nvn.c` + `nvn_obj.h` + texture code.
4. Write a Vulkan replay to replace `nvn_mtl.m`; keep Ryujinx translator + the four patches, emit SPIR-V directly.
5. Reuse version hashes, address table, fps/realtime/resolution patch semantics, RomFS overlays, HeapDef math, shader
extraction formats and the shared shader list `V` rows.
+229
View File
@@ -0,0 +1,229 @@
# Maxwell / NVN behaviour a port must reproduce
Reference for diagnosing graphics bugs. Each item: what Maxwell (GM20B, 3D class `B197`, compute `B1C0`) and NVN do,
what Vulkan / AMD (RDNA4, our GPU0) do instead, how emulators and ports handle it, and the source. Items are ordered by
how likely they are to cause visible artifacts. "Ours:" marks what our runtime does (grep-level look, see the last
section). Licensing: yuzu/suyu are GPL, cited for behaviour only.
Source shorthands:
- **OGD**: NVIDIA open-gpu-doc `classes/3d/clb197.h`, `classes/compute/clb1c0.h` (MIT-style),
<https://github.com/NVIDIA/open-gpu-doc/tree/master/classes>. Offsets below are method offsets in `clb197.h`.
- **G80TEX**: Mesa nouveau `src/gallium/drivers/nouveau/nv50/g80_texture.xml.h` (MIT),
<https://gitlab.freedesktop.org/mesa/mesa/-/blob/main/src/gallium/drivers/nouveau/nv50/g80_texture.xml.h>.
- **RYU-SU**: Ryujinx `Ryujinx.Graphics.Gpu/Engine/Threed/StateUpdater.cs` (MIT), mirror at 1.1.1137:
<https://git.dawidpotocki.com/mirror/ryujinx/plain/src/Ryujinx.Graphics.Gpu/Engine/Threed/StateUpdater.cs?h=1.1.1137>.
- **RYU-SH**: Ryujinx shader translator vendored at `refs/MacNativeGames/vendor/ryujinx/src/Ryujinx.Graphics.Shader/`
(Ryujinx 1.3.2, MIT). Paths below are relative to it.
- **NXN**: `refs/nxnative/docs/agents/04-graphics.md` (MIT).
- **MNG**: `refs/MacNativeGames` (MIT).
- **DK3D**: `refs/deko3d` @ `373bfd43d8b2d805fa2eb7d406dbb823032df958` (zlib, fincs), the homebrew Maxwell driver for Switch. Written
against the hardware, not the NVN API: what it programs is what the GPU needs. Paths relative to `source/`. `.def` files give
methods as word indices (`engine_3d.def`); byte offset = index x 4, so `0x5A1` = OGD `0x1684`. No conditional rendering, no
provoking-vertex conversion, no 8-bit indices in it.
- **YZ-2305 / YZ-2306**: yuzu progress reports May / June 2023,
<https://yuzu-mirror.github.io/entry/yuzu-progress-report-may-2023/>,
<https://yuzu-mirror.github.io/entry/yuzu-progress-report-jun-2023/> (behaviour only).
- **VKSPEC**: Vulkan 1.4 specification, <https://registry.khronos.org/vulkan/specs/latest/html/vkspec.html>;
**GLSL450**: SPIR-V GLSL.std.450 extended instructions, <https://registry.khronos.org/SPIR-V/specs/unified1/GLSL.std.450.html>.
## 1. Render targets
| # | Maxwell / NVN | Vulkan / AMD | Emulators / ports | Source |
|---|---|---|---|---|
| 1.1 | **Colour target the fragment shader does not write keeps its old texel**, even with blending enabled. | Undefined value written/blended. | NXN: zero write mask and no blend for unwritten outputs (`reflection colors`). Already fixed here. | NXN:122; MNG `games/totk/tests/metal_semantics/probe.m:5` |
| 1.2 | **Unwritten vertex outputs read as (0, 0, 0, 1)** in the next stage, including the unwritten components of a partly written output (VS writes xyz, FS divides by w). | FS input with no VS output: interface mismatch, value undefined; an unwritten component of a written output is undefined (AMD: whatever the register holds, often 0). | Ryujinx initialises exactly the components the next stage reads, but only when stages are linked (`Translation/Translator.cs:212-227`, `NextInputAttributesComponents`); position starts (0,0,0,1) (`:259`). NXN Link's Awakening: sun shadow lookups divided by w = 0, scene dim, no shadows. Ours: missing outputs padded with **zero**, partial outputs not initialised (section 7, check 2). | NXN:84, NXN:151 |
| 1.3 | **Clears honour the scissor and the clear's own channel / stencil write mask**, and may come between draws inside a pass. `SET_CLEAR_SURFACE_CONTROL` (0x10f8) has `RESPECT_STENCIL_MASK`, `USE_CLEAR_RECT`, `USE_SCISSOR0`, `USE_VIEWPORT_CLIP0`. | `vkCmdClearAttachments` takes a rect but **ignores the colour write mask**; load-op clears are whole-attachment. | NXN/MNG draw a triangle with the clear's mask (`clear_color_tri`, `clear_ds_tri`); TotK uses mid-pass, partial-mask and partial-scissor clears (NXN:174). yuzu: "red dot" was clears hitting the wrong RT index (YZ-2305, PR 10243). Hardware recipe (DK3D): `CLEAR_BUFFERS` (`0x674` = 0x19d0) carries the colour channel mask (bits 2-5), depth (0), stencil (1), target id (6-9) and layer (10-20) in one word; `ClearBufferFlags` (`0x43E` = 0x10f8) is set once to `StencilMask | Scissor` (`maxwell/gpu_3d_base.cpp:69`), so every clear is cut by scissor 0 and its stencil bits by the stencil front write mask register, and DK3D's colour clear does not program `ColorWriteMask` (`0x680`). A stencil clear writes `StencilFrontMask` (`0x4E7`) and `ClearStencil` (`0x368`) just before the clear and restores the shadowed state after (`gpu_3d_base.cpp:497-510`). Multisample raster is switched off around a colour clear (`:459, :465`). Arrays: an MME macro repeats the clear for every layer (`maxwell/clear_buffers.mme:5-22`). No pass concept: clears sit between draws. Ours: masked colour and stencil clears are **skipped** (check 3). | OGD 0x10f8; NXN:81, NXN:174; DK3D `maxwell/gpu_3d_base.cpp:444-512`, `engine_3d.def:305, 644` |
| 1.4 | **Conditional rendering** (`SET_RENDER_ENABLE_A..C` 0x1550-0x1558, NVN `SetRenderEnableConditional`) compares two 64-bit counters at `addr` and `addr+16` on the GPU, in command order. TotK wraps nearly every clear in it. A `TIMESTAMP` report writes 0 to the counter field. | `VK_EXT_conditional_rendering` tests one 32-bit word against zero. | NXN: honouring it fixed the black 3D scene (light-volume depth never cleared). deko3d has no conditional rendering at all (no `SET_RENDER_ENABLE` in `engine_3d.def`), so it cannot settle the compare rule. Ours: evaluated on the CPU at record time; a report from an unfinished submission counts as 0 (check 5). | OGD; NXN:173 |
| 1.5 | **Depth mode** is runtime state: `nvnDeviceSetDepthMode` near = -w (GL, NVN default) or 0. Register `SET_VIEWPORT_Z_CLIP` (0x0d7c) `NEGATIVE_W_TO_POSITIVE_W` / `ZERO_TO_POSITIVE_W`. | Vulkan clips z < 0 unless `VK_EXT_depth_clip_control` `negativeOneToOne`. | Ryujinx infers the mode from the viewport transform, falling back to the register (`GetDepthMode`, RYU-SU). NXN: wrong mode either clips everything (black window) or puts all depth in 0.5..1 (DOF blurs the screen). Ours: `negativeOneToOne` from NVN state. DK3D programs both halves: `SetDepthMode` (`0x35F` = 0xd7c) selects the pre-transform clip range, and the viewport transform maps z to [near, far] itself: scale z = `0.5 * (far - near)` and offset z = `0.5 * (near + far)` for -1..1, scale `far - near` and offset `near` for 0..1 (`maxwell/gpu_3d_base.cpp:143-147, 336-343`). Same maths as Vulkan `negativeOneToOne`. | OGD 0x0d7c; NXN:55-64, NXN:150; DK3D `maxwell/gpu_3d_base.cpp:136-147, 321-362` |
| 1.6 | **Depth clamp / clip**: `SET_VIEWPORT_CLIP_CONTROL` (0x193c) has separate `PIXEL_MIN_Z`/`PIXEL_MAX_Z` CLIP or CLAMP and geometry-clip modes. | `depthClampEnable` also disables z clipping (unless `VK_EXT_depth_clip_enable`). RADV had a dynamic depth clamp driver bug causing TotK vertex explosions. | Ryujinx: clamp = `!(clip & DepthClampDisabled)` (RYU-SU `UpdateDepthClampState`). yuzu disabled dynamic depth clamp on affected RADV (YZ-2305, PR 10262). DK3D has one switch, `depthClampEnable`, and writes `VIEW_VOLUME_CLIP_CONTROL` (`0x64F` = 0x193c) with `0x101A` when on and `0x181D` when off (default at setup is `0x181D`); it labels the bits "todo: figure out what this actually does". Bits 3-4 (`DepthClampNear/Far`) are set in both values, bits 0-2 and 11 differ. There is no separate depth-clip toggle. The viewport near/far registers (`Viewport` array words 2-3) carry the clamp range and are swapped when far < near (`:349-350`). Vulkan clamp to [min, max] of the viewport depth matches. | OGD 0x193c; DK3D `maxwell/gpu_3d_state.cpp:42`, `gpu_3d_base.cpp:135-139, 349-350`, `engine_3d.def:621` |
| 1.7 | **Depth formats**: D24S8 is native; D24 quantises to 2^-24 everywhere in 0..1. Polygon offset units are in D24 steps for D24 targets; `SET_DEPTH_BIAS_CONTROL` (0x1110) `DEPTH_FORMAT_DEPENDENT`. | RX 9070 has no D24S8 attachment; D32F has finer steps near 0 and a per-primitive exponent-based r. EQUAL / LEQUAL tests between a pre-pass and a later pass, and decal biases, behave differently. | yuzu rescales depth-bias units when D24 is emulated as D32F; Ryujinx passes `units / 2` (register is twice the API value) (RYU-SU `UpdateDepthBiasState`). MNG: D16 load-clear 0.5 → 32767 vs fragment 0.5 → 32768 made Ultrahand/Recall classification tiles visible. Ours: D24S8 → D32_SFLOAT_S8, bias not rescaled (check 4). DK3D writes `PolygonOffsetUnits` (`0x56F` = 0x15bc) as `constantFactor * 2.0f`, clamp to `0x61F`, factor to `0x55B` (`maxwell/gpu_3d_state.cpp:148-157`), confirming the x2 register. | OGD 0x1110, 0x15bc, 0x156c; MNG `docs/how-it-works.md:57-61`; DK3D `maxwell/gpu_3d_state.cpp:154` |
| 1.8 | **Position invariance**: identical position math gives identical depth across programs (pre-pass then EQUAL / LEQUAL). | Only for outputs declared `Invariant`. | Ryujinx decorates position `Invariant` (`CodeGen/Spirv/Declarations.cs:571`) and marks float ops `NoContraction` unless `QueryHostReducedPrecision` (`CodeGen/Spirv/Instructions.cs:2047`). NXN: Odyssey ground z-fought without it; LA's foliage drawn with depth EQUAL vanished when the pre-pass failed. Ours: translator default (all NoContraction). | NXN:85, NXN:147 |
| 1.9 | **Sampling a texture that is also a bound render target**: Maxwell's texture cache is not coherent with ROP writes; NVN requires `nvnCommandBufferBarrier(INVALIDATE_TEXTURE)` between writing and sampling (methods `INVALIDATE_TEXTURE_DATA_CACHE` 0x1338, `..._NO_WFI` 0x1288). Reading a different level/layer, or read-only depth while testing, is fine. | Same image as attachment and sampled in one pass is a feedback loop: undefined unless `VK_EXT_attachment_feedback_loop_layout`; on AMD DCC/HTILE-compressed data is not readable by the sampler without decompression. | yuzu: pixelated Ultrahand glow fixed with barriers on attachment feedback loops (YZ-2305, PR 10402). BotW black textures on GCN worked around with `AMD_DEBUG=nohyperz` (HTILE off) (<https://git.openpunk.com/OpenPunk/yuzu/wiki/commit/bd401539420182cbbf8bc638b042536a7e690c3f>). Ours: an NVN barrier ends the pass and inserts a full memory barrier; no detection of a sampled texture that is a current attachment (check 10). DK3D barrier recipe (`maxwell/gpu_base.cpp:49-115`): the ordering part and the cache part are separate. Ordering: Tiles = `TiledCacheBarrier` (`0x3DF`), Fragments = `FragmentBarrier` (`0x378`), Primitives = `WaitForIdle` (`0x44`), Full = gpfifo `SetReference` + new gpfifo entry with `NoPrefetch`, so later command and indirect-parameter fetch happens after everything finished. Tiles and Fragments need an implicit WFI before a cache invalidate. Caches (each opt-in): texture data `InvalidateTextureDataCache` (`0x3DD`, WFI) or `..NoWfi` (`0x4A2`); shader `InvalidateShaderCaches` (`0x369`: instruction, global data, constant); descriptors `InvalidateTextureHeaderCacheNoWfi` (`0x50A`) + `InvalidateSamplerCacheNoWfi` (`0x509`); zcull `0x4B2`; L2 gpfifo `MemOpB` `L2FlushDirty` + `L2SysmemInvalidate`. The texture-cache invalidate is its own flag; ordering alone does not refresh it. Every queue flush ends with image + shader + descriptor + L2 invalidation "to ensure the visibility of CPU updates between flushes" (`:28-47`): CPU writes into textures and descriptors reach the GPU at the next submit boundary, not mid-submit (2.2). | OGD; DK3D `maxwell/gpu_base.cpp:28-115` |
| 1.10 | **Duplicate attachments**: the same texture bound at two colour slots with write mask 0 on one does not interfere (ROP writes only enabled channels). | Tile-based or compressed attachments may store the unwritten copy over the written one. | NXN BotW G-buffer (c1 = c2, c3 = c4): leaves the duplicate slot unattached (`rt_dup_slot`). | NXN:130 |
| 1.11 | **Per-target write masks**: `RtColorMask[i]`, or entry 0 for all when `RtColorMaskShared`. `SET_SINGLE_CT_WRITE_CONTROL` (0x0f90). A colour target with format 0 is disabled. | Per-attachment `colorWriteMask`. | RYU-SU `UpdateRtColorMask`, `IsRtEnabled` ("Colors are disabled by writing 0 to the format"). | OGD 0x0f90 |
| 1.12 | **sRGB render target views**: NVN encodes on write when the view format is sRGB over a linear texture. Maxwell also has a global `SET_SRGB_WRITE` (0x15b8). | Format of the attachment view decides; needs `MUTABLE_FORMAT`. | NXN Mario: attaching the base texture stored linear values, picture darker. Ours: RT views take the view format (`view_format`). | OGD 0x15b8; NXN:69 |
| 1.13 | **Compressed and 3D targets**: agl's GPU BC4 encoder renders blocks through an `RGBA16UI` view, one plane of a 32×32×32 BC4 3D texture per pass. NVN renders a 3D texture slice by slice. | Needs `BLOCK_TEXEL_VIEW_COMPATIBLE` + `EXTENDED_USAGE`, `2D_ARRAY_COMPATIBLE`. | NXN shadow textures (`bcrt_attach`). yuzu: wrong block depth on 3D slices gave Gloom textures on terrain (YZ-2305, PR 10433). Already fixed here. | NXN:132, NXN:176 |
| 1.14 | **Draw with no render target** (fragment shader only writes an SSBO, 1×1 viewport) runs normally. | Needs an attachment-less pass with explicit render area. | NXN `bare_dims`: cave ambient light came back. Ours: area of viewport 0 (`vk_exec.c:229`). | NXN:177 |
| 1.15 | **Window origin**: NVN default lower-left (GL); TotK switches to upper-left. Y flip and scissor flip follow. | Vulkan upper-left; negative viewport height to flip. | Ryujinx flips scissor against screen height when Y-negate is on (RYU-SU `UpdateScissorState`). | NXN:145 |
| 1.16 | **Multiple viewports / scissors** (16), selected by `ViewportIndex` output. | Needs `multiViewport` and `shaderOutputViewportIndex`. | Ours: one viewport, one scissor; differing scissors logged (`nvn_api_cmd.c:499-508`). | OGD 0x192c |
| 1.17 | **Fragment output saturation** per target: `SET_PS_SATURATE` (0x13a8) clamps output n to 0..1 or -1..1 in fixed function. NVN does not expose it (GLSLC emits `.SAT` in code). | None. | Not emulated by Ryujinx; listed so a clamp difference is not chased in the wrong place. | OGD 0x13a8 |
| 1.18 | **New memory reads as zero** (fresh pool pages); feedback effects never clear their state texture. | New image content undefined. | NXN `tex_zero_fill`. | NXN:80 |
| 1.19 | **MSAA**: `nvnCommandBufferDownsample` resolves; depth-stencil downsamples are copies the game does itself. | `vkCmdResolveImage` colour only; integer formats pick one sample. | NXN LA: stencil lost in the half-size depth copy, no AO. | NXN:148 |
## 2. Textures and samplers
| # | Maxwell / NVN | Vulkan / AMD | Emulators / ports | Source |
|---|---|---|---|---|
| 2.1 | **Automatic block height**: NVN truncates `height_in_blocks * 1.5 / 8` before picking the GOB power of two (deko3d rounds up). Wrong H reads padding: 160×160 BC3 warp pad half black. Allocation size is the same, so size checks do not catch it. Mip levels shrink the block height while the level fits in half of it. | Opaque optimal tiling. | MNG fixed (40 SDK-measured cases, `games/totk/tests/texture_auto_layout/probe.c`). Ours: truncating form already (`runtime/nvn_tex.c:149`). DK3D reads: height in block rows (rounded up), x 1.5, then `(h + 7) / 8` rounded up, then the largest power of two <= that, capped at 16 GOBs (`dk_image.cpp:444-447`, `pickTileSize` `:13-20`); 3D uses `depth + depth / 2` directly as the GOB count (`:451-454`); video images are fixed at 2 GOBs (`:438`). Per level, the shift drops while `unit << (shift - 1) >= level dimension` with unit 8 rows / 1 slice (`adjustTileSize` `:23-37`, used at `:89-91`), width tile is always 0. Array layers are padded to the block shrunk to the full height / depth (`alignLayerSize` `:57-72`). Every one of these matches `nvn_tex.c:60-66, 115-125, 149-150` except the rounding. | MNG `docs/how-it-works.md:47-53`; DK3D `dk_image.cpp:13-37, 57-72, 80-103, 436-455` |
| 2.2 | **Textures filled by the CPU with no NVN flush** (TotK terrain: two 121-layer ASTC 8×8 arrays, 42 MB each; BC4 material textures read back with `ReadTexels` and copied into a 5120×5120 roughness atlas). The CPU and GPU share memory, so no flush is needed on the Switch. | Host images are copies; must detect CPU writes. | NXN write-protects texture pages (`tex_dirty_upload`); zero ASTC decodes magenta, zero BC black. yuzu: small CPU writes into GPU-used pages not invalidated gave slow rain/snow particles and teleport particle corruption (YZ-2306, PR 10942). Ours: `GetWriteWatch` generations (`vk_memory.c:349-380`). | NXN:174-175 |
| 2.3 | **Same storage, new texture object every frame** (transient targets, deferred handles). Same storage with a different descriptor reinterprets the same block-linear bytes. | Two `VkImage`s over one allocation with optimal tiling do not share a defined layout (AMD tiling and DCC metadata are per image); a new image starts `UNDEFINED`. | NXN shares host textures by `(pool, offset, description)`; MNG keeps a "live texture at address" redirect. yuzu: whole areas black for a frame on camera changes from texture-cache alias/overlap ordering (YZ-2305, PR 10418). Ours: GPU-only pool textures are `VkImage`s bound onto pool memory (check 7). | NXN:70; MNG `docs/how-it-works.md:67-71` |
| 2.4 | **Deferred texture handles** (`BindTexturesDeferred`): the GPU reads the handle from memory when the command runs; BotW records command blocks once and writes handles later. | n/a | NXN BotW: handles copied at record time were zero, 3D scene black. | NXN:129 |
| 2.5 | **Border colours**: any RGBA (TSC words 4-7, plus sRGB border fields). TotK/BotW grass interaction map clamps to (0.5, 0.5, 0.5, 0.5), its "untouched" value. | Three fixed colours unless `VK_EXT_custom_border_color` (+ `customBorderColorWithoutFormat`); integer formats need `INT_CUSTOM`. | MNG emulates in the shader; with transparent black, grass away from the player lay flat and showed no cut (MNG issue #49). Ours: custom border when supported, else transparent black (check 11). | G80TEX; MNG `games/totk/third_party/d2r_gfx/gfx/nvn/nvn_mtl.m:5041-5045` |
| 2.6 | **sRGB decode** is a TIC bit (`G80_TIC_2_SRGB_CONVERSION`) separate from the format; TSC has its own `SRGB_CONVERSION` (word 0 bit 13). NVN exposes sRGB as formats. | Format decides. | NVN-level translation by format is enough. | G80TEX:197, :377 |
| 2.7 | **Swizzles** per texture and per view (`TextureBuilderSetSwizzle`, `TextureViewSetSwizzle`); BotW layout captures rebuild a texture on the same storage with (1, 1, 1, R) or alpha 1. Default per-format mapping R8 → (R, 0, 0, 1). | `VkComponentMapping` on the view. | NXN: font atlas white boxes, HUD dark boxes without it. Ours: mapped (`vk_exec_draw.c:328`). | NXN:68, NXN:140 |
| 2.8 | **Sample dimension comes from the instruction**: a non-array sample of an array texture reads layer 0; 1,512 BotW shaders sample a cube as a cube array. | View type must match the declared type. | NXN: 2D array bound as 2D gave one pale colour (washed-out scene); cubes created as 6-layer arrays with cube / cube-array views. Ours: views per resource type (`get_view`). | NXN:121, NXN:131 |
| 2.9 | **LOD**: TSC min/max LOD clamp, LOD bias, `TWO_D_NO_MIPMAP` texture type, a min filter without mips stays on the base level; TIC carries its own max anisotropy and aniso quality fields. | `minLod`/`maxLod`, `mipLodBias` limited by `maxSamplerLodBias`. | yuzu: anisotropy heuristics for mods forcing trilinear (YZ-2306, PR 10744). Ours: non-mip filter → `maxLod = minLod + 0.25`, bias clamped (`vk_texture.c:1008-1013`). | G80TEX |
| 2.10 | **Texture gather rounding**: Maxwell sub-texel precision differs from AMD/Intel; edge texels picked by TLD4 differ by one. | Implementation-defined `subTexelPrecisionBits`. | yuzu adds a sub-pixel offset to gathers on non-NVIDIA hosts: fixed BotW shadow artifacts at object edges ("shader_recompiler: Add subpixel offset for correct rounding at ImageGather", <https://git.openpunk.com/OpenPunk/yuzu/src/commit/780240e6979b198e7bd10feaad5399b8b4b63762>, title only). | — |
| 2.11 | **Gather offsets**: `TLD4.PTP` takes four per-texel offsets, possibly from registers. | `ConstOffsets` must be constant. | Ours: `QueryHostSupportsNonConstantTextureOffset() => false` makes Ryujinx emulate register offsets (`tools/xlate/Program.cs:96-99`). | RYU-SH `Translation/Optimizations` (TexturePass) |
| 2.12 | **Depth compare** (`TSC` depth compare + `TIC_4_DEPTH_TEXTURE`), min/max reduction filtering. | `compareEnable`; reduction mode needs `samplerFilterMinmax` and is not allowed with compare. | Ours: reduction dropped when compare is on (`vk_texture.c:1037`). | G80TEX |
| 2.13 | **ASTC / BC**: native ASTC; zero ASTC block = error colour on hosts. | RX 9070 lacks ASTC: CPU decode to RGBA8. yuzu offered ASTC recompression to BC1/BC3 for low VRAM (YZ-2305, PR 10398). | Ours: `tex_astc.c`. | `runtime/tex_astc.c` |
| 2.14 | **Linear CPU-written textures** (`FLAGS_LINEAR`, small ramps, glyph caches): CPU writes visible to the GPU directly. | Must re-upload or use linear images over host memory. | NXN Mario: sky black without its 64×1 RGBA16F ramps. | NXN:75 |
## 3. Shader math
| # | Maxwell | Vulkan / AMD | Emulators / ports | Source |
|---|---|---|---|---|
| 3.1 | **FMNMX and `.SAT` with NaN return the other operand / 0** (IEEE minNum). Games rely on this to stop NaN spreading (one NaN pixel blown up by bloom or temporal passes flickers or fills the screen). | `GLSL.std.450 FMin/FMax/FClamp`: result undefined when an operand is NaN (NMin/NMax are the NaN-dropping forms). AMD hardware min/max usually drops NaN; the compiler may still assume no NaN. | Ryujinx emits FMin/FMax/FClamp (`CodeGen/Spirv/Instructions.cs:336, 956, 972`; saturate = FClamp 0..1, `Instructions/InstEmitAluHelper.cs:419-423`). NXN translated shaders use `isnan` selects; MNG measured Metal min/max/saturate drop NaN (`probe.m:1-4`). | GLSL450; NXN:86 |
| 3.2 | **FMZ multiply mode** (`FMUL/FFMA/...` field `Fmz`, `.FMZ`): 0 × anything = 0, including Inf/NaN (DX9 rule). | IEEE: 0 × Inf = NaN. | Ryujinx decodes `Fmz` (`Decoders/InstDecoders.cs:306-309, 1901`) but no emitter reads it. Ours: same. Census needed (check 13). | RYU-SH |
| 3.3 | **Denormals**: per-instruction `.FTZ`. | AMD flushes fp32 denormals by default; `VK_KHR_shader_float_controls` sets it per shader. | Ryujinx ignores `.FTZ`. Low risk. | RYU-SH (no `Ftz` use in `Instructions/`) |
| 3.4 | **Warp size 32**: `SHFL`, `VOTE`, `S2R LANEID`, ballots are 32-bit. | AMD RDNA runs wave32 or wave64 per shader (the driver chooses; RADV fragment default wave64); `VK_EXT_subgroup_size_control` `requiredSubgroupSize = 32` fixes it. | Ryujinx adapts lane masks to `QueryHostSubgroupSize()` (default 32, `IGpuAccessor.cs:218`; `Instructions/InstEmitWarp.cs:72, 106`, `InstEmitMove.cs:175-185`). Ours: not overridden, no required size (check 6). | <https://docs.mesa3d.org/envvars.html> (`RADV_PERFTEST=pswave32`) |
| 3.5 | **Discard (`KIL`)** keeps the quad's derivatives valid (demote semantics). | `OpKill` terminates; later derivatives in the quad undefined. | Ryujinx emits `OpKill` (`CodeGen/Spirv/Instructions.cs:508`). | — |
| 3.6 | **Implicit-LOD sampling in divergent control flow** works on Maxwell (TEX unit uses quad neighbours). | Undefined in non-uniform control flow; AMD whole-quad mode usually works. | — | VKSPEC (derivatives) |
| 3.7 | **Integer division** does not exist (compiled to `XMAD`/`IMAD` sequences); MUFU.RCP(0) = +Inf, LG2(0) = -Inf. | Same IEEE edge cases through `1/x`, `Log2`. | Low risk. | — |
| 3.8 | **FP64** in some TotK cutscene shaders. | No FP64 on some hosts. | yuzu FP64 → FP32 (YZ-2306, PR 10693); ours: `softfloat64` job flag (`tools/xlate/Program.cs:101`). | — |
| 3.9 | **Integer vertex inputs read as raw bits** (bone indices `R8UI`). | Float-declared inputs convert integers. | NXN Mario: stretched characters; re-translated with `uint` inputs. Ours: attribute types passed to `QueryGraphicsState` (`Program.cs:86-88`). | NXN:76 |
## 4. Memory model
| # | Maxwell / Tegra | Vulkan / AMD discrete | Emulators / ports | Source |
|---|---|---|---|---|
| 4.1 | **One memory**: the CPU reads GPU-written buffers and textures after a fence; the GPU sees CPU writes after `FlushMappedRange` or, in practice, immediately (TotK skips flushes). Block-linear layout is defined, so a buffer copy into texture storage is a texture upload. | Images live in VRAM with private tiling; buffer bytes copied into image memory are not texels. | yuzu PR 10942 (small CPU writes); MNG alias visibility barriers for copies through two buffers over one allocation. Ours: GPU-written ranges of CPU-visible pools marked at fence completion; GPU-only pools nothing (check 8). | MNG `docs/how-it-works.md:67-71` |
| 4.2 | **Counter reports** (`ReportCounter`, `SET_REPORT_SEMAPHORE_A..D` 0x1b00): `{counter, timestamp}`; TIMESTAMP puts 0 in the counter; SAMPLES_PASSED counts visible samples; ZCULL stats. | Occlusion queries are separate objects; results copied to a buffer. | NXN TotK: timestamp counter 0 matters for conditional clears. Ours: every report writes `{0, time}`; occlusion counts are always 0 (check 5). DK3D writes `SET_REPORT_SEMAPHORE_OFFSET` (`0x6C0` = 0x1b00) with payload `0` and `OPERATION=Counter`, `STRUCTURE_SIZE=FourWords` (`dk_variable.cpp:193-240`): TIMESTAMP = unit `Crop`, counter `Payload`, written when the ROP has retired every earlier draw; SAMPLES_PASSED = unit `Crop`, counter `0x15`; ZCULL stats = four one-word reports at +0, +4, +8, +12. TIMESTAMP_TOP is not a 3D report: a gpfifo `Semaphore` release of 16 bytes with `ReleaseWfiDisable`, written when the command processor reaches it, without waiting for earlier work (`:246-253`). So `TIMESTAMP - TIMESTAMP_TOP` around a span is its GPU duration. Layout: two 64-bit words, counter then timestamp (`Primer.md:578`). Each report is followed by a tiled-cache flush (`:256`). `ResetCounter` (`0x54C` = 0x1530) zeroes SAMPLES_PASSED; it is the reset for the timestamp types too (`:282-300`). Unit: `dkTimestampToNs(ts) = ts * 625 / 384`, i.e. **614.4 MHz** GPU ticks (1.63 ns), not the 19.2 MHz system tick (`include/deko3d.h:1367-1373`) (check 21). | OGD 0x1b00; NXN:173; DK3D `dk_variable.cpp:183-300`, `include/deko3d.h:1367` |
| 4.3 | **Semaphores / events** written by the GPU in order; CPU polls them. | Writes on a completion thread after the fence. | Ours: `vk_completion_add`, submit order. | — |
| 4.4 | **Inline uniform updates** (`UpdateUniformBuffer`) happen in command order between draws; reading the buffer at record time gives the last value. | Must snapshot. | NXN: snapshotted at encode time; Mario's wave sim diverged when two writes reordered. | NXN:71, NXN:79, NXN:82 |
| 4.5 | **GPU-written index buffers** (8-bit indices written earlier in the same submission). | No `uint8` index type without `VK_EXT_index_type_uint8`; CPU widening reads stale bytes. | NXN widens on the GPU (`wide_run`). Ours: CPU widening at record time; device-local byte indices skipped (check 9). | NXN:175 |
| 4.6 | **Compute shared memory**: 48 KiB per block on GM20B. | AMD 64 KiB. | Ours: `QueryComputeSharedMemorySize` from job (`Program.cs:82`). | OGD `clb1c0.h` |
| 4.7 | **Virtual memory pools** map physical pool pages; the same bytes reachable at two GPU addresses. | Two `VkBuffer`s over one allocation need alias-aware barriers. | MNG `MTL4VisibilityOptionResourceAlias`. | MNG `docs/how-it-works.md:67-71` |
| 4.8 | **Command list calls**: a `CallCommands` / `CallList` is not a GPU subroutine. DK3D `dkCmdBufCallList` stores a `Call` control entry (`dk_cmdbuf.cpp:327-338`); `dkQueueSubmitCommands` walks the entries on the CPU and recurses into the called list at submit (`dk_queue.cpp:287-296`), emitting gpfifo entries that point at the command words, which the GPU fetches later (prefetch can be switched off per entry, `:176`). So list structure is fixed at submit, command words are read when fetched. | n/a | Ours: `OP_CALL` is walked at replay, `CallCommands` inlines the recording at record time (`nvn_api_cmd.c:399-404`, `vk_exec.c:571-574`). Equivalent for control flow; deferred bind handles are the data read late (2.4). | DK3D `dk_cmdbuf.cpp:327`, `dk_queue.cpp:280-298` |
## 5. Fixed function
| # | Maxwell / NVN | Vulkan / AMD | Emulators / ports | Source |
|---|---|---|---|---|
| 5.1 | **Provoking vertex: last** (GL convention, NVN default; `SET_PROVOKING_VERTEX` 0x1684, NVN 55 `SetProvokingVertexMode`). Flat-interpolated outputs (instance/particle ids, material indices, flat normals) come from the last vertex. | **First vertex** unless `VK_EXT_provoking_vertex` with `provokingVertexMode = LAST_VERTEX`. | Ours: extension queried (`vk_device.c:205`) but no pipeline sets last-vertex mode (check 1). DK3D: `ProvokingVertexLast` (`0x5A1`) is set to 1 at queue setup and per rasterizer state from `DkProvokingVertex` (`maxwell/gpu_3d_base.cpp:76`, `gpu_3d_state.cpp:67`); `DkRasterizerState` defaults to Last (`include/deko3d.h:823`). Confirms last as the hardware-side default. | OGD 0x1684; `runtime/nvn_ext.c:396-400`; DK3D `include/deko3d.h:794-823` |
| 5.2 | **Primitive restart**: any index value, compared against the raw index for any index size; can apply to lists (`SET_DA_PRIMITIVE_RESTART_TOPOLOGY_CHANGE`) and to non-indexed draws (`..._VERTEX_ARRAY` 0x0de8). | Restart only at all-ones of the index type; lists need `primitiveTopologyListRestart`. | Ryujinx enables it for draw-arrays only on GL (RYU-SU comment). NXN: TotK terrain strips use 0xffff. Ours: non-all-ones restart not replayed, logged. DK3D: `PrimitiveRestartEnable` (`0x591` = 0x1644) + `PrimitiveRestartIndex` (`0x592` = 0x1648), index written only when enabled; any value; `PrimitiveRestartWithDrawArrays` (`0x37A` = 0x0de8) is forced 0 at setup (`maxwell/gpu_3d_ibo.cpp:21-30`, `gpu_3d_base.cpp:73`). Nothing on lists vs strips beyond that. | OGD 0x1644, 0x1648; DK3D `maxwell/gpu_3d_ibo.cpp:21-30` |
| 5.3 | **Point size**: `SET_POINT_SIZE` (0x1518) when the shader does not write it; GLSLC clamps a written size to a driver constant. | Point size must be written by the shader. | Ryujinx writes the `PointSize` from graphics state at VS start (`Translation/EmitterContext.cs:84-88`); ours passes 1.0 (`Program.cs:92`) and logs `SetPointSize` (`nvn_ext.c:371-373`). | NXN:41 |
| 5.4 | **Line width**, smooth lines (`SET_LINE_WIDTH_FLOAT` 0x13b0, `SET_ANTI_ALIASED_LINE`). | `wideLines`, `VK_EXT_line_rasterization`. | Ours: 1 px, logged. | OGD |
| 5.5 | **Polygon offset units** are twice the API value in the register; NVN API takes GL units. | `depthBiasConstantFactor` in format-dependent r. | Ryujinx `units / 2f` from the register (RYU-SU). Ours takes NVN API units (right) but D32F instead of D24 (1.7). DK3D `constantFactor * 2.0f` (1.7). | OGD 0x15bc, 0x187c; DK3D `maxwell/gpu_3d_state.cpp:154` |
| 5.6 | **Dual-source blending**: SRC1 factors read the shader's second output. | Needs fragment output `Location 0, Index 1`. | Ryujinx declares `Index` only when `DualSourceBlendEnable` (`Translation/Translator.cs:196`, `CodeGen/Spirv/Declarations.cs:608-617`). Ours: SRC1 factors mapped (`vk_pipeline.c:253-256`) but the translator is always given `false` (`Program.cs:92`) (check 12). | — |
| 5.7 | **Alpha-to-coverage** with dither (`SET_ALPHA_TO_COVERAGE_DITHER_CONTROL` 0x12e0), alpha test (fixed function on Maxwell). | A2C without dither; no alpha test. | Ryujinx emulates alpha test and A2C dither in the shader from graphics state; ours passes `AlphaTestOp.Always`, A2C false to the translator (`Program.cs:91-93`). | OGD 0x12e0, 0x16b4 |
| 5.8 | **Logic ops** on colour targets. | `logicOp` feature; ignored on float targets. | Ours: in the pipeline key. | OGD 0x19c4 |
| 5.9 | **Vertex formats**: `*SCALED` 8/16-bit, RGB10A2 SNORM/SCALED, 3-component formats, 32-bit scaled. | No 32-bit SCALED; 3-component formats often unsupported. | Ours: 32-bit scaled read as integers (logged), 3-component widened (`vk_pipeline.c:382-413`). | — |
| 5.10 | **Transform feedback**, rasterizer discard. | `VK_EXT_transform_feedback`. | Ours: rasterizer discard without XFB = no draw (`nvn_api_cmd.c:530`). | OGD 0x0744 |
| 5.11 | **Depth bounds, sample mask, conservative raster**. | Optional features. | Ours: ignored, logged (`nvn_ext.c:377-394`). | OGD 0x0fa4 |
| 5.12 | **Blend factors on targets without alpha** (RGBX emulated as RGBA). | Destination alpha reads the stored value. | Ryujinx replaces DST_ALPHA factors on no-alpha targets (`FilterBlendFactor`, RYU-SU). | RYU-SU |
## 6. Known BotW / TotK issues in other projects
| Game | Symptom | Cause | Fix / link |
|---|---|---|---|
| TotK | 3D scene black | conditional clears ignored | NXN:173 |
| TotK | cave magenta / black | CPU-filled ASTC/BC with no flush never uploaded | NXN:174 |
| TotK | stone blocks unlit by torches | roughness atlas built from `ReadTexels` of never-uploaded BC4 | NXN:175 |
| TotK | BC4 3D texture draws lost | compressed render target | NXN:176 |
| TotK | missing ambient light, bloom halo | draw with no render target skipped | NXN:177 |
| TotK | warp pad half black | block height rounding | MNG `docs/how-it-works.md:49-53` |
| TotK | coloured squares with Ultrahand / Recall | D16 clear vs fragment rounding with depth EQUAL | MNG `docs/how-it-works.md:57-61` |
| TotK/BotW | grass flat away from Link, no cut | custom border colour (0.5) | MNG `nvn_mtl.m:5041-5045` |
| TotK | cloud flicker, missing geometry in the Depths | shader recompiler bugs | YZ-2305 PR 10234 |
| TotK | red dot on screen | clear targeted the wrong RT index | YZ-2305 PR 10243 |
| TotK | scrambled Link/terrain at 2× | buffer-cache clears during sync | YZ-2305 PR 10249 |
| TotK | vertex explosions (RADV) | driver dynamic depth clamp bug | YZ-2305 PR 10262 |
| TotK | pixelated Ultrahand glow | attachment feedback loop without barriers | YZ-2305 PR 10402 |
| TotK | areas black for a frame on camera changes | texture-cache alias/overlap order | YZ-2305 PR 10418 |
| TotK | Gloom textures on terrain | block-depth adjustment on 3D slices | YZ-2305 PR 10433 |
| TotK | terrain gaps at distance (Depths) | one-character shader recompiler error | YZ-2305 PR 10459 |
| TotK | mangled textures on RDNA3 | not found (AMD test case) | YZ-2305 |
| BotW/TotK | slow rain/snow, particle corruption on teleport | small CPU writes into GPU-used pages not invalidated | YZ-2306 PR 10942 |
| TotK | AO broken above 1008p mods | rescale thresholds | YZ-2306 PR 10675 |
| TotK | "detective mode" Link on AMD | AMD EDS3 colour-blend driver regression | YZ-2306 PR 10946 |
| BotW | shadow artifacts at object edges (AMD) | gather rounding | yuzu commit 780240e (2.10) |
| BotW | black textures on GCN | HTILE (depth compression) | `AMD_DEBUG=nohyperz` wiki (1.9) |
| BotW | 3D scene black | deferred texture handles | NXN:129 |
| BotW | albedo scattered squares | duplicate colour attachments | NXN:130 |
| BotW | HUD dark boxes, black stamina wheel | capture texture swizzle rebuild | NXN:140 |
## 7. Checks for our runtime
Grep-level look on 2026-10-22; "saw" is what the grep and short reads showed, not a test result.
1. **Provoking vertex.** *Stale as of 2026-10-23: `vk_pipeline.c:223, 1324-1328, 1438` enable `provokingVertexLast` and chain
LAST_VERTEX; re-check, then mark fixed.* Earlier look: `grep -n provokingVertex runtime/vk_pipeline.c` → no hits; `vk_device.c:205` only queries
`VK_EXT_provoking_vertex`. Vulkan draws flat outputs from the first vertex, NVN from the last. Fix: enable the feature
and chain `VkPipelineRasterizationProvokingVertexStateCreateInfoEXT{LAST_VERTEX}` in the pipeline create. **Mismatch.**
2. **Unwritten vertex outputs.** `spirv_add_outputs` (`vk_pipeline.c:551-554`, `:946`) adds **zero**-initialised outputs
for FS inputs the VS lacks; Maxwell gives (0, 0, 0, 1). Partly written outputs get nothing: our translator never links
stages (`grep SetNextStage tools/xlate/Program.cs` → none), so Ryujinx's `InitializeVertexOutputs` initialises no
user output. **Mismatch**: w = 0 breaks perspective divides (NXN:151 shadows).
3. **Masked clears.** `vk_exec.c:418-421` skips colour clears with a partial channel mask; `clear_ds` skips stencil
clears with a partial mask (`W_STENCIL_MASK`). TotK issues such clears (NXN:174). Check the log for
`colour clear with channel mask` and `stencil clear with mask`. DK3D (1.3) confirms what the replay must do: colour clear = scissor 0 + channel mask, stencil clear = `value & mask` merged under the front write mask; so a draw with `colorWriteMask` / `stencilWriteMask` set to the clear mask is the exact equivalent. **Missing.**
4. **D24 → D32F.** `vk_formats.c:43` maps D24S8 to `D32_SFLOAT_S8_UINT`; `vk_exec_draw.c:710` passes NVN units
unscaled. Depth EQUAL passes and decal offsets can z-fight. Look at: per-pass depth-test op histogram, EQUAL passes
against D24 targets. **N/A for TotK**: a census of the field and fight saves (2026-10-22) saw depth targets
0x34 (DEPTH32F) and 0x32 (DEPTH16) only; biased draws (units -5 and 1, factor -0.5 and -0.2) are on DEPTH32F.
5. **Counters and conditional rendering.** `vk_exec_xfer.c:11-18, 83-88`: every report writes `{0, time}`;
SAMPLES_PASSED is always 0; a condition is read on the CPU at record time and an unfinished report reads 0. Grep the
NVN log for counter types other than TIMESTAMP; any occlusion-driven visibility (flares, culling) is off. **Fixed 2026-10-22**:
SAMPLES_PASSED counts come from Vulkan occlusion queries between RESET and REPORT (`vk_exec_xfer.c`, ~4 queries
per frame in the field, ~21 in a fight); the game's CPU reads them (guest f_70010c3298) to cull objects.
6. **Subgroup size.** `grep -n -i subgroup runtime/vk_*.c tools/xlate/Program.cs` → none. Translator assumes 32;
RDNA4 may run fragment shaders in wave64. Fix: `VkPipelineShaderStageRequiredSubgroupSizeCreateInfo{32}` for
modules using `GroupNonUniform*` (or `QueryHostSubgroupSize` = actual size). **Risk.**
7. **Images aliased onto GPU-only pool memory.** `vk_texture.c:263-270` binds each `VkImage` into its pool allocation;
textures are keyed by address plus descriptor, and each new image starts `UNDEFINED` (`:310`). Two descriptors over the
same storage, or bytes written through a buffer, do not see each other's data on AMD. Check: count distinct keys per
address per frame. **Risk** (yuzu PR 10418 class).
8. **GPU writes into CPU-visible pools.** `note_gpu_write` (`vk_exec_xfer.c:65-71`) stamps pages when the fence
completes, so a texture sampled later in the same submission keeps its old upload; GPU-only pools are skipped.
MNG saw at most one buffer copy per frame in TotK, so low priority. **Risk.**
9. **Index buffers.** `vk_exec_draw.c:888-897`: byte indices widened on the CPU at record time, skipped in
device-local memory; `:865-876` non-all-ones restart index logged and dropped. Census (2026-10-22): 130-170 byte-index draws/frame widened on the
CPU, 0 device-local, 0 non-all-ones restarts. **OK**; `VK_KHR_index_type_uint8` (supported) would drop the CPU cost.
10. **Feedback loops.** `grep -n -i feedback runtime/vk_exec*.c` → none. NVN barriers end the pass (`vk_exec.c:316-327`),
but a draw that samples a currently attached image without an NVN barrier is not detected. Census (2026-10-22):
425/frame (field) to 667 (fight), G-buffer material/decal shaders sampling the 1600x900 targets of the open pass.
**Mismatch**: needs `VK_EXT_attachment_feedback_loop_layout` (supported). Shader keys: build/archive/v121-chk/NOTES.md.
Confirmed 2026-10-23 (`build/archive/v121-sq/SQUARES.md`): the terrain G-buffer pass reads its own albedo, normal and R32F
targets at the fragment's pixel; on the RX 9070 the reads return stale data as ~16x14 px dark rectangles on the
ground, and the sage spirit next to Link is not drawn. Ending the pass behind a barrier before such a draw fixes
both.
11. **Border colours.** `vk_texture.c:1025-1035`: custom colour only with `customBorderColorWithoutFormat`, else transparent
black; integer formats use the float path. Confirm the RX 9070 reports the feature (grass map needs 0.5).
**OK if supported.**
12. **Dual-source blend.** `vk_pipeline.c:253-256` maps SRC1 factors; `Program.cs:92` always passes
`dualSourceBlendEnable = false`, so no `Index 1` output exists. Log pipelines with SRC1 factors. **Mismatch if used.**
13. **FMZ / NaN.** Count `FMUL/FFMA/FMUL32I/FFMA32I` words with the `Fmz` field set (`Decoders/InstDecoders.cs:1901`
bit positions) in `build/v121/shaders/`; FMin/FMax/FClamp NaN results are undefined (3.1). Census (2026-10-22):
FMZ in 1 instruction of 12397 shaders, FTZ in 12241 shaders, FMNMX in 7457. The translator emits GLSL.std.450
FMin/FMax (Ryujinx `GenerateMinimum`), not NMin/NMax. **FMZ: no fix needed. FMNMX: OK** (RX 9070 test: FMin/FMax(NaN, 1) = 1 both orders, FClamp(NaN, 0, 1) = 0).
14. **Point size / line width.** `nvn_ext.c:367-373` log non-default values; the translator writes `PointSize = 1`.
Census: `SetLineWidth 4.5` ~1/frame (2 line draws into a 144x144 R8 target), `SetPointSize 5` ~14/frame; 4 point
VS rely on it. **Mismatch, minor.**
15. **Block height.** `nvn_tex.c:149` truncates like NVN (2.1). DK3D rounds up (`dk_image.cpp:446`); every other step matches. **OK.**
16. **Depth mode and clamp.** `vk_pipeline.c:978-983` (`negativeOneToOne` from `nvn_depth_minus_w`, `depthClampEnable`
from NVN state). DK3D agrees on the z maths (1.5) and the clamp switch (1.6). **OK.**
17. **Depth bias argument order.** `vk_exec_draw.c:710` (units, clamp, factor); DK3D takes the same three and doubles units for the register (1.7). **OK.**
18. **Sampler LOD.** `vk_texture.c:1008-1013`. **OK.**
19. **Viewport / scissor arrays.** Single viewport (`vk_exec_draw.c:700-702`), extra scissors logged. Census: 0 differing. **OK.**
20. **Depth-compare sampling in compute** (VUID-vkCmdDispatch-None-06479): one compute shader samples a 4x4 R32F
CPU-written placeholder through an R32_SFLOAT view with compare on, ~1/frame. Needs a D32 copy. **Minor.**
21. **Report timestamps: unit and instant.** `write_counter` (`vk_exec_xfer.c:88-91`) writes host `ns * 12 / 625` (19.2 MHz
ticks) at fence completion for every report; `nvnDeviceGetTimestampInNanoseconds` converts back with the same factor
(`nvn_ext.c:52-56`). DK3D: GPU ticks convert at 625/384 ns (614.4 MHz), TIMESTAMP is written when the ROP has retired
the earlier work, TIMESTAMP_TOP when the command processor reaches it (4.2). Two consequences for port-lessons T1:
(a) if the 1.2.1 consumer scales raw report ticks with its own constant rather than the NVN conversion call, our
19.2 MHz unit is 32x off from the hardware's; find that consumer before fixing the unit; (b) the delta needs
`vkCmdWriteTimestamp2` with `TOP_OF_PIPE` for TIMESTAMP_TOP and `BOTTOM_OF_PIPE` for TIMESTAMP, per submission
segment, converted to whichever unit (a) shows. **Mismatch (instant); unit unverified.**
## 8. Sources not read yet (TODO)
- Mesa NVK (`src/nouveau/vulkan`, MIT): how it maps Vulkan provoking vertex, depth clip, restart, feedback loops onto B197.
- envytools rnndb `graph/gf100_3d.xml`, `tsc.xml`, `tic.xml` (MIT): field-level TIC/TSC meanings (LOD snap, trilinear opt).
- Ryujinx `Ryujinx.Graphics.Gpu/Image/TextureCache.cs`, `Texture.cs` (MIT): alias/overlap rules, depth texture swizzle.
- Ryujinx TotK/BotW PRs and issues (GitHub repo gone; mirrors blocked or 404 on 2026-10-22).
- yuzu progress reports 2023-08 to 2024-02 and suyu/sudachi trackers (behaviour only).
- switchbrew wiki NVN and GPU pages.
+123
View File
@@ -0,0 +1,123 @@
# Port lessons: symptoms other ports already solved
Each lesson maps a player-visible symptom to the cause another port found, and records whether our runtime has the fix.
Sources: nxnative (MIT, `refs/nxnative` at `d5b380b`, 2026-10-22; `docs/agents/03-bringup.md`, `04-graphics.md`,
`05-debugging.md`, `docs/development.md`, the TotK profile `dm/games/0100F2C0115B6000/game.tsv`) and MacNativeGames
([macnativegames.md](macnativegames.md)). nxnative runs TotK 1.4.3, so its `main+` addresses do not carry over to 1.2.1.
Maxwell semantics live in [maxwell.md](maxwell.md); a lesson that is also a Maxwell check names its number (`mx N` =
maxwell.md section 7 check N). Our side was checked by reading the code on 2026-10-22 and updated 2026-10-23; `file:line` refers to that state.
Status: **open** (missing or partial), **unknown** (not checked), **done**, **parked**.
## Before you investigate a symptom
1. Get the evidence first: the user's screenshot or recording, or a flight-recorder dump
([agent-playbook.md](../agent-playbook.md), "Frame dumps"). A guess without a captured frame costs a game run each.
2. Search the lessons for the symptom words: this file, maxwell.md sections 6-7, then the upstream notes:
`grep -rniE 'black|flicker' docs/research refs/nxnative/docs refs/MacNativeGames/docs`. Words that match well are
what the player sees (black, magenta, flicker, slow motion, missing, stale, streaks) and the object (sky, grass,
shadow, fog, HUD).
3. A **done** match: confirm our fix still holds before deriving anything new. An **open** match is the first
hypothesis.
4. Read the code the hypothesis depends on before any game run: the guest functions in Ghidra or `generated/v121`,
our runtime path. A hypothesis the code already rules out costs no run (2026-10-23: ten agent runs went to
scheduler and lock theories that one Ghidra read of the game's double-buffer protocol would have narrowed).
5. Then falsify what is left with the cheapest switch, dump or trace before writing a fix. A fix that changes timing
or scheduling also needs the slow-frame count of the same route next to the run without it.
## Keeping the lessons current
Upstream changes daily. `git -C refs/<name> fetch origin`, then `git log --format='%h %s' <pin>..origin/HEAD` lists the
new commits and `git diff <pin> origin/HEAD -- docs` their notes. Add lessons here, then move the pin in
`tools/fetch_refs.sh`. nxnative rewrote its history on 2026-10-22; when a pinned hash is gone, find it by commit subject.
## Open: timing and frame pacing
| id | symptom | cause and their fix | our status | next step |
|---|---|---|---|---|
| T1 | GPU-bound scenes run in slow motion; dynamic resolution never drops | The Zelda engine's GPU time is the `TIMESTAMP` report at the end of the frame minus `TIMESTAMP_TOP` at its start, read after the frame fence; the interval controller and dynamic resolution use it. One time per submission made it 0-6 ticks (BotW). Fix: each report gets the GPU start or end of its command segment (`gpu_timestamps segment`, `DM_NVN_GPU_TS`; 04-graphics.md) | open: every report gets the host time at fence completion (`vk_exec_xfer.c:90-94, 259-276`), so the difference is microseconds. Counter word 0 is right (conditional clears need it). 1.2.1's interval controller does not read it: `[x1+0x118]` (`0x8f26c8`) is `GetSystemTick` minus the frame start (`f_70008f24bc`); dynamic resolution not checked | find a reader of the report difference; then `vkCmdWriteTimestamp` (top of pipe for `TIMESTAMP_TOP`) converted to 19.2 MHz ticks with calibrated timestamps |
| T2 | frame-rate counter wanders 50-60 | the vsync event and the window acquire each kept a 60 Hz clock and drifted apart; both follow one display tick now (03-bringup.md) | open: `gfx_window.c:92-104` and `nvn_api_obj.c:640-680` run separate clocks | derive acquire slots from the vsync thread's tick |
| T3 | a 30 Hz thread runs at 27 Hz, slow cutscenes | host sleep overshoot; `sleep_precise` | unknown: high-resolution waitable timer (`kernel.c:685-697`), overshoot not measured | measure `SleepThread` at 1, 5, 16 and 33 ms |
## Open: thread scheduling
Horizon runs a better-priority thread at once and pins some threads to one core; a host runs them all in parallel.
A one-step ordering difference between two engine threads can show as one frame with inconsistent data.
| id | symptom | cause and their fix | our status | next step |
|---|---|---|---|---|
| S1 | state read one step early; use-after-free between threads | a woken better-priority thread pinned to the signaller's core runs before the signaller's next instruction (`dm_yield_to_core_peers`, `core_preempt`; 03-bringup.md) | open: the preempt flag is honoured at the holder's next SVC (same design as MacNativeGames `threads.c:120-151`). Tried 2026-10-23 (`build/archive/v121-preempt/NOTES.md`): a check at every host call made phantom rocks rarer (0/10 to 4/6 clean runs) but added 50-75 ms CPU-side hitches, so it was reverted; a nxnative-style waker handoff did not help | none until a symptom is traced to it alone |
| S2 | per-core data races, different thread order | `CreateThread` with ideal core -2 and the main thread get the default core and a mask of that core only; `SetThreadCoreMask` -2 means core 0 / mask 1 | open: mask 7 for negative cores and the main thread (`kernel.c:646, 777`); `SetThreadCoreMask` -2 keeps the old ideal core (`kernel.c:879-890`) | count -2 creations with `TOTK_TRACE=svc`, then pin |
| S3 | worker threads burn cores, late frames | 843 SVC-free spin loops in TotK `main`; nxnative's rewriter makes them poll 2 ms, then sleep | open: a lifted spin loop keeps its virtual core with no preemption point (`kernel.c:363-371`) | measure core-wait while a holder spins (sched trace `preempt` latency) |
| S4 | rare hang or lost wake | `SignalToAddress` type 2, count <= 0 with waiters: Ryujinx, yuzu and nxnative set `value - 2` | done: `kernel.c:1017` writes `value - 1` and the count > 0 branch writes `nw <= count ? value - 1 : value`, both as mesosphere master `kern_k_address_arbiter.cpp`; 1.2.1 calls type 2 only with count 1, and `value - 2` did not change the phantom rocks (2026-10-23, `build/archive/v121-lock/NOTES.md`) | none |
| S5 | the main thread holds a core a worker needs | yield types 0 / -1 / -2 differ on Horizon; TotK's render-graph wait is a poll plus yield | unknown: all three hand the core only to an equal or better waiter (`kernel.c:835-846`) | trace which yield type 1.2.1's frame-end poll uses |
| S6 | lost or extra wakes | MacNativeGames `dab728a`: `SignalToAddress` wake-all, `SystemEvent` rebinding, targeted wakes | unknown | read the commit, compare with `kernel.c` |
## Open: graphics
| id | symptom | cause and their fix | our status | next step |
|---|---|---|---|---|
| G3 | light or decal lists, particle data read 0 | buffer textures read by 1D integer fetches; bound as 2D rows | open: buffer textures bind a zero view (`vk_exec_draw.c:657-659`) | census; Vulkan texel buffer views need no 2D trick |
| G4 | textures read as the dummy | bindless handles stored in the game's own uniform buffers (`tex_ubo`) | not in 1.2.1: 0 of 75k descriptors take a handle from cbuf >= 3 and no startup shader has a `_B` texture op (`build/g4/G4.md`, 2026-10-22); only c2 handles are mapped (`tools/xlate/Program.cs:49-54`) | if a later version needs it: nxnative `ubo_read` (`dm/gfx/nvn/nvn_mtl.m:4199-4215`) |
| G5 | garbage in feedback effects | new GPU textures start at zero | open: depth starts cleared, GPU-only colour images start undefined (`vk_texture.c:307-308`; mx 7) | clear new GPU-only colour images |
| G6 | 50x50 black tiles, masks not cleared | clears with a partial channel or stencil mask | parked: fix in `build/archive/v121-clr` (mx 3, backlog) | merge if the census shows partial-mask clears |
| G7 | garbage geometry on title or load screens | 8-bit indices written by a copy in the same submission read stale by CPU widening | open: CPU widening at record time (`vk_exec_draw.c:888-897`; mx 9) | `VK_KHR_index_type_uint8` (backlog) |
| G8 | cave stone blocks get no torch light | `ReadTexels` of a CPU-filled BC4 atlas returned the never-uploaded copy | open: ported, not checked on the 5120x5120 atlas | dump the cave save |
| G9 | scattered squares in albedo | G-buffer attaches one texture at two slots | unknown | validation on a G-buffer frame |
| G10 | stale 32x32 blocks where pre-pass and G-buffer disagree | identical position math must give identical depth (invariance) | unknown | grep a dumped VS SPIR-V for `Invariant` |
| G11 | characters stretched into streaks | integer vertex inputs vs the format's type | unknown | count `VUID-vkCmdDraw-Input-08734` |
| G12 | one flat ambient colour | a 1-layer 2D array sampled as 2D | unknown | read view creation in `vk_exec_draw.c:290-300` |
| G13 | magenta streamed textures | sparse textures use a 64 KB tile layout | unknown | look for virtual pools in the NVN log |
| G14 | upside-down UI text | lower-left window origin | unknown: origin recorded (`nvn_api_core.c:220-223`) | grep the NVN log for the origin |
| G15 | magenta 16x16 blocks | same-pass feedback sampling | parked (mx 10, backlog "Later") | only if a captured glitch points here |
## Open: performance
| id | symptom | cause and their fix | our status | next step |
|---|---|---|---|---|
| P2 | low fps outdoors | inline uniform updates and clear-only passes end render passes; deferring them cut TotK's attachment traffic from 1,100 to 700 MB a frame (`DM_NVN_UB_PARTIAL`, `DM_NVN_LAZY_CLEAR`, `cb_extent.tsv`) | unknown: `vkCmdUpdateBuffer` is illegal inside a pass, so ours likely end one (`vk_exec_draw.c:933-946`) | count passes per frame and those ended by an update in a `TOTK_DUMP` |
| P3 | out-of-memory after minutes | dead textures re-entered tables | unknown | log VMA bytes and live images every 1000 frames |
## Open: debugging tools
| id | lesson | our status |
|---|---|---|
| D1 | Per-shader highlight, depth override and skip (`DM_NVN_HILITE`, `DEPTHOVR`) split "rejected by depth" from "never drawn" and bisect a glitch to one shader | open: `TOTK_DUMP` has none |
| D2 | First-use texture info with the count of non-zero guest bytes (`TEXINFO`, `TEXRAW`, `ZBLOCK`) shows a texture the CPU filled but we did not upload | open: dump lines carry address, mirror state and upload count only |
| D3 | Crash reports with a stack scan and the words at `*xN` | open: vectored handler (`main.c:118-160`) |
## Done
Confirm the fix still holds before re-deriving any of these.
- Speed follows the present interval at 60 fps (T4): MacNativeGames' controller patch and real-time frame step as
generator patches (`recomp/patches-v121.txt`, `runtime/frame_rate.c`); the pacer ignores the game's interval while
the step is real-time (`nvn_api_obj.c` `present_period`).
- Driver constant bank c0 (G2, fog that never parts, flicker in tile rows): a c0 bank per stage with the dispatch
size at 0x200, point size at 0x610 and base instance at 0x644, `vk_exec_draw.c:602-618`.
- GPU idle while the replay records (P1): the replay is submitted in parts between passes every `TOTK_SPLIT_DRAWS`
(64) draws, only the last part signals, `vk_exec.c:564-575`.
- Unwritten vertex outputs read (0,0,0,1) (no sun shadows in Link's Awakening): translator patch
`tools/xlate/patches/0006-initialise-unlinked-vertex-outputs.patch` (mx 2).
- Conditional clears on counter words; a timestamp report writes 0 in the counter word: `vk_exec_xfer.c:90-94, 278-301`.
- CPU-filled textures without a flush (magenta cave walls): write-watched pool mirrors, `vk_texture.c:124-139`. The same
path covers BotW's sky (tables memcpy'd into a CPU-cached pool, flushed, sampled from a zero texture: brown sky).
- Deferred texture binds read at execution (3D scene black): `nvn_api_cmd.c:621-660`.
- `nvnTextureCompare` compares the channel mapping (HUD prompt boxes, black stamina wheel): `nvn_api_obj.c:231-234`.
- BC textures drawn through an RGBA16UI view (BC4 encoder): block-texel-view-compatible images, `vk_texture.c:190, 255`.
- Fragment draws with no render target: `vk_exec.c:229`. Output types from attachment formats: `vk_pipeline.c:500`.
- Block-height rounding: `nvn_tex.c:149` (mx 15). Depth mode: `vk_pipeline.c:978-983` (mx 16).
- Cubes sampled as cube arrays, 1D textures, swizzles, sRGB views, scaled copies, targets outside the output map keep
texels: see the playbook's "Bug classes already fixed".
- `GetCommandMemoryUsed` follows the driver's sizes and resets at `AddCommandMemory`: `nvn_api_cmd.c:321-347`. The game
sizes model heaps from it, so a larger host record crashes world loads.
- `nvnQueueFinish` waits for the GPU only: `nvn_api_core.c:516-519`.
- Yield back-off: none (`kernel.c:835-846`); one that starts before 2 ms of yields drops TotK to 20 fps.
- Condition-variable waiters wake in arrival order within a priority: `kernel.c:184-191`.
- The guest clock never freezes: `main.c:106-115`. Focus message 15 only under focus modes 1 and 2: `gfx_window.c:178-180`.
- Alias region and heap: `memory.c:27-30`. Adr-relative jump tables: `recomp/jumptables.py`.
- Scripted and recorded input by frame: `TOTK_INPUT_SCRIPT`, `TOTK_INPUT_RECORD`.
Not applicable to us: Metal and iOS limits (big-stack entry points, TBDR store order, encoder order, display-link rates,
efficiency cores), the NSO rewriter's retry blocks, `DT_RELR` (SDK 20 only), GC-title thread contexts, audio renderer
take-over (we serve `audren:u`).
+254
View File
@@ -0,0 +1,254 @@
# Prior art: Switch static recompilation and native ports (as of 2026-10-20)
Scope: prior art for porting TotK (0100F2C0115B6000, ARM64 NSO) to native Windows x86-64 by static recompilation.
Labels: **[confirmed]** = seen in a primary source (post JSON, repo, code). **[reported]** = press or secondary source only.
**[inference]** = my reading of the evidence.
## A. Another TotK PC port (announced 2026-10-15)
- **[reported]** A native PC build of TotK was shown on X on 2026-10-15: 32-59 fps on an RTX 4060 Ti, Vulkan, "worked
on for a couple of days". No game version, toolchain or source was published, and the screenshots were later
removed after a copyright report. Press: https://wccftech.com/zelda-tears-of-the-kingdom-unofficial-native-pc-port-sluggish-notrexed-release-2-4-weeks/
- **[inference]** The figures fit a static ARM64-to-C recompilation with an NVN layer on a portable graphics API. There
is nothing to reuse.
## B. Other projects
### Switch → native, static recompilation (closest prior art)
| Project | URL | Status | Lang / license | Relevance |
|---|---|---|---|---|
| **OpenSmash-Ultimate (ssbu-recomp)** | https://github.com/Denkishi/ssbu-recomp | Active (pushed 2026-10-20), 254 stars. SSBU 13.0.4/13.0.5 → **Windows x64**. Boots, plays full matches at 59-60 fps | C + Python tools, **GPL-3.0** | **Closest blueprint for our target.** Lifter `tools/lifter/recomp.py`: AArch64 → C, one C function per guest function, checked against Unicorn on 32,043 instruction cases. clang → game DLL plus one DLL per script module. Runtime: about 1,100 `nn*` entry points, threads, C++ exceptions through lifted code. NVN → Vulkan/GL (`nvn_vk*.c`). `mx_translate.c`: Maxwell shader → GLSL → SPIR-V. Pipelines prebuilt in background threads. Deterministic mode with a per-frame state hash. GPL: read for ideas; copying code makes our project GPL. |
| **LAS Recomp** | https://github.com/peiikai/LASRecomp (local: `refs/LASRecomp`) | Beta release, 1.37k stars. Link's Awakening v1.0.0 → Windows x64 (Vulkan), macOS (Metal), Linux | C runtime + Python lifter, **MIT** (own code) | **Most reusable code (MIT).** "Made almost exclusively with Claude Code." `tools/lifter.py` (728 lines): AArch64 → C; integer, memory and control flow in C; FP/SIMD lowered to C on x86 hosts by `simd_c.py` (1,156 lines, with `runtime/simd.h`). `gen.py`: whole-NSO generation; functions from `.eh_frame`; Unicorn for analysis; `--chunk`. `tools/test_lift.py` and `test_simd.py`. Runtime: `kernel.c`, `ipc.c`, `services/` (acc, am, audio, fs, hid, time), `nvn/` with a Maxwell translator, Vulkan backend (GLSL via shaderc), ASTC decode. Windows: guest window at `0x70_0000_0000` reserved with `VirtualAlloc`, committed on demand through a vectored exception handler. Toolchain: MSYS2 UCRT64 clang/lld; zig for building on the player's PC. Dev tooling worth copying: `perf_sweep.py` (warp to each room, per-room fps table), `shot.sh`, `frames.sh`, `explore_input.sh`, `fnprof.c`. |
| **SavageWindRecomp** | https://github.com/Revivedx/SavageWindRecomp (local: `refs/SavageWindRecomp`) | Alpha 2 (2026-10-21). Breath of the Wild **1.8.2** to Windows x64 and Linux, Vulkan. Great Plateau at 60 fps; nobody has played past it | C runtime + Python lifter, **MIT** (`LICENSE:1-4`: Revivedx, plus Peiikai for LAS Recomp) | LAS Recomp fork for the engine TotK descends from (sead, ksys, agl; NVN 55.15). Kernel core gate, NVN command recording, submission queue, frame pacing and Vulkan backend were reworked for BOTW; its dated bring-up log is the useful part. Findings: section E. |
| **suyu v0.0.4 "Recompiler mode"** | https://github.com/suyu-emu/suyu-v0.0.4 | Archived after the final release (Sep 2026). No published perf data; users report crashes | C++, **GPL-2.0+** | `src/core/recompiler/arm64_to_c.h` (4.5k lines, header-only): "AArch64 → portable C, N64Recomp-style, GuestContext. Every instruction translates or emits a runtime fallback." Bundled with the Eden/yuzu HLE plus GPU. Useful as a second AArch64→C reference and for its fallback design. Weakest of the three. Coverage: https://xenospectrum.com/en/suyu-static-recompiler-performance-evidence/ |
| **bgyss/SwitchRecomp** | https://github.com/bgyss/SwitchRecomp (local: `refs/SwitchRecomp`) | Specs plus scaffolding. Last push 2026-03, 88 stars | Rust; Cargo says MIT OR Apache-2.0 but the repo has no LICENSE file | See section C. Documentation value only. |
| Mario Kart 8 DX recomp | listed at https://allrecomps.com | "Limited race tests", Windows, no release | ? | Watch only. |
### Switch → Apple native ARM64 execution (no CPU translation; HLE and graphics are reusable)
These do not recompile. They patch the instructions macOS/iOS cannot run (x18, TPIDRRO, `svc`, counter registers) and
run the guest code directly. For an x86 port, the relevant parts are the **Horizon HLE host, the NVN reimplementation,
TotK-specific data and the bring-up playbooks**.
| Project | URL | Notes |
|---|---|---|
| **MacNativeGames** (TotK) | https://github.com/ly05010419/MacNativeGames (local: `refs/MacNativeGames`) | **MIT**, 2.06k stars, active. TotK **1.0.0, 1.1.2, 1.2.1, 1.4.3** on Apple silicon and iOS. Reported about 90 fps on M4 after shader warm-up. NVN → Metal 4 with dirty-page tracking. Shaders: Ryujinx `Ryujinx.Graphics.Shader` (patched, NativeAOT `totk_xlate`) → SPIR-V → SPIRV-Cross → MSL. Shared shader list: 26,832 variants. `docs/how-it-works.md` documents guest memory below 2^39 (IPC buffer addresses use 39 bits), the alias region, NVN block-height rounding (deko3d's heuristic is wrong at some sizes), TotK frame-pacing and 60 fps patches, and per-version expected hashes. **Best TotK-specific reference for HLE and NVN behaviour.** Press: https://www.notebookcheck.net/Zelda-Tears-of-the-Kingdom-Mac-port-runs-at-90-fps-topping-Switch-2-and-PC-rival.1427448.0.html |
| **nxnative** | https://github.com/seedds/nxnative (local: `refs/nxnative`) | **MIT**. 39 game profiles on 2026-10-22 (about 10 new a day), TotK 1.4.3 and BotW at 60 fps. `docs/agents/01..05` is an agent playbook for porting a new Switch title: extract, survey (SDK/NVN version, SVC and import census), bring-up failure catalogue, NVN graphics, debugging; `docs/development.md` has per-game findings. **Best source for project skills and symptom lessons**; what applies to us is in [port-lessons.md](port-lessons.md). The history was rewritten on 2026-10-22. |
| d2r-mobile | https://github.com/jhaizhou-ops/d2r-mobile (local: `refs/d2r-mobile`) | MIT. Origin of the NSO rewriter, Horizon host and NVN-on-Metal design. |
| totk-mobile | https://github.com/OJZen/totk-mobile | Apache-2.0, 73 stars. TotK 1.4.3 only, follows the d2r-mobile design. |
### Decompilation
| Project | URL | Notes |
|---|---|---|
| zeldaret/botw | https://github.com/zeldaret/botw | BotW 1.5.0 decomp, C++, no license file, active (2026-10-19), progress at https://botw.link/progress. Not near 100% (about 40 MB executable). Useful for TotK: shared EPD engine (sead, ksys, agl), so class layouts and names carry over to some extent. Matching decomp is not a viable route for TotK. |
### Design references from other consoles
| Project | URL | Notes |
|---|---|---|
| N64Recomp | https://github.com/N64Recomp/N64Recomp | MIT, 8.3k stars. Canonical "instruction → C over a context struct" model; the suyu engine copies it. |
| XenonRecomp / XenosRecomp | https://github.com/hedge-dev/XenonRecomp , https://github.com/hedge-dev/XenosRecomp | MIT. PPC → C++ recompiler plus Xenos shader → HLSL. Patterns: function-table dispatch for indirect calls, jump-table detection config, mid-asm hooks. UnleashedRecomp (GPL-3.0) is the full-game example. |
| ReXGlue SDK | https://github.com/rexglue/rexglue-sdk | 1.1k stars, active 2026-10. X360 recomp runtime built on a Xenia-derived runtime. Model for "one SDK, many titles". |
| Mario Kart Wiicompiled | https://www.dsogaming.com/news/unofficial-pc-port-of-mario-kart-wii-coming-in-august-2026/ | Wii (PPC) static recomp, AI-assisted, beta 2026-08. |
### Emulators (HLE and GPU references; most are under DMCA pressure)
| Project | URL | Notes |
|---|---|---|
| Ryujinx / Ryubing | GitHub `Ryubing/Ryujinx` returns 404; `ryujinx-mirror` was blocked by DMCA on 2025-03-14. Ryubing's own Git host (not verified) | MIT C#. `Ryujinx.Graphics.Shader` (Maxwell → SPIR-V/GLSL) is the shader translator MacNativeGames and nxnative ship. HLE services are a semantics reference. Reported to be in maintenance mode in 2026. |
| Eden | https://git.eden-emu.dev/eden-emu/eden | yuzu descendant, GPL. Reported as the most active fork; suyu 0.0.4 is based on it. Hit by DMCA in Feb 2026 ([reported]). |
| Citron, Sudachi | (off GitHub) | Citron is alive off GitHub; Sudachi is mostly dead ([reported], low-quality sources such as https://tech-insider.org/eden-vs-ryubing-best-switch-emulator-2026/). |
| dynarmic | https://github.com/lioncash/dynarmic (archived 2024), forks https://github.com/azahar-emu/dynarmic and in-tree in Eden | 0BSD. A64 decoder tables and IR are a semantics reference for the lifter (flags, FP/SIMD corner cases). |
| oaknut | https://github.com/merryhime/oaknut | MIT, archived 2024. AArch64 emitter/encoder, not a decoder. Low relevance. |
### Generic lifters
| Project | URL | Notes |
|---|---|---|
| remill | https://github.com/lifting-bits/remill | Apache-2.0, active 2026-08. AArch64 → LLVM IR. Per-instruction semantics as C++ functions. Candidate for an LLVM-IR route or as a semantics oracle. Its AArch64 SIMD coverage is incomplete (from memory, not checked against the current tree). |
| mcsema | https://github.com/lifting-bits/mcsema | AGPL-3.0, archived 2022. Do not use. |
| RetDec | https://github.com/avast/retdec | MIT, LLVM decompiler. Analysis aid only. |
| Unicorn | https://www.unicorn-engine.org | Differential-test oracle; LASRecomp and ssbu-recomp both use it. |
### What the field converged on (all three working Switch recomps)
1. AArch64 → **C** (not LLVM IR). One C function per guest function, chunked source files, compiled by clang.
2. Function discovery from `.eh_frame`, `bl` targets and relocations. Indirect calls go through a dispatch table
keyed by guest address.
3. Guest memory at its original addresses, reserved up front (`0x70_0000_0000` window). Addresses must stay below 2^39.
4. Per-instruction differential testing against Unicorn.
5. HLE of `nn::` services and SVCs in the host runtime, not kernel emulation.
6. NVN reimplemented at the API level. Maxwell shaders translated at load time (own translator or Ryujinx's).
Pipelines prewarmed.
7. Dev loop: scripted input, warp sweeps, per-scene fps tables, frame dumps, function profiler.
## C. refs/SwitchRecomp assessment
Layout: `specs/` (35 draft specs SPEC-000..270), `docs/` (35 notes and schemas), `crates/` (8 crates, about 15.9k lines
of Rust including tests), `skills/` (7 Codex skills), `scripts/` (capture, ffmpeg, Ghidra export, AWS). There is one
commit in the local clone, dated 2026-02-17.
### Crates: usable? No.
Not compiled here: `cargo` is not installed and installing it was out of scope. Dependencies are pure Rust (clap,
serde, toml, sha2, lz4_flex, thiserror), so it would most likely build and its tests would pass, but nothing in it does
real work.
- `recomp-isa`: a toy interpreter covering 12 ops (`MovImm`, `Add`, `Sub`, `Cmp`, shifts, `Ldr/StrImm`, `Ret`) with
registers in a `BTreeMap`.
- `recomp-pipeline/src/homebrew/lift.rs` (1.2k lines): decodes about 15 integer encoding classes (movz/movk, adr,
add/sub imm/reg, logical reg, ldr/str unsigned imm, b, bl, b.cond, cbz/cbnz, tbz/tbnz, br, ret, nop). It has no
LDP/STP, pre/post-index, FP/SIMD, exclusives or atomics, system registers or `svc` lowering. That covers a negligible
fraction of a real game's .text.
- Emitter (`output.rs`) writes a Rust crate with **per-function local registers** (`let mut x0: i64 = 0`) and a
`match block_label` string dispatch. Registers do not cross calls, so the output is semantically wrong for real ABI
code and slow.
- `recomp-gfx`: `CommandStream` + `GraphicsBackend` trait + `StubBackend` + FNV checksum. No NVN or Maxwell.
- `recomp-services`: a name → closure registry with allow-list and stub behaviours. No IPC or CMIF.
- `recomp-runtime`: flat memory regions, `mem_load/store_*`, syscall log, noop and panic.
- XCI intake shells out to hactool/hactoolnet. Fixtures are fake (`main.nso` is 5 bytes).
- Verdict: do not depend on it. LASRecomp (MIT) is a far better code base to learn from or borrow.
### Specs and docs: limited value
- Process and validation specs (provenance, A/V validation, run manifests, automation loop, agent pipeline security)
are coherent but generic and were written before any real title booted.
- `docs/llm-assisted-decompilation-long-tail.md` summarizes https://blog.chrislewis.au/the-long-tail-of-llm-assisted-decompilation/
(similarity-guided retrieval, lanes for gfx/math, hook-enforced guardrails, parallel worktrees). Worth reading if we
run an agent loop over functions.
- `docs/LEGAL-POLICY.md` and the provenance idea (sha256 of user inputs, inputs kept separate from outputs) are worth
copying in spirit.
### Skills: adapt one, rewrite the rest from better sources
| Skill | Content | Verdict |
|---|---|---|
| static-recomp-av-compare | SKILL.md + 3 real Python scripts (565 lines): ffmpeg normalize/align, SSIM, PSNR, optional VMAF, EBU R128 loudness, batch manifest, threshold check | **Adapt.** The only skill with working code. Port it to a Claude Code skill for "emulator reference capture vs our build" comparisons. Check the license first (no LICENSE file in the repo). |
| static-recomp-input-replay | Checklist | Concept is needed; the content is generic. Write our own around a frame-indexed input trace fed to both Ryujinx/Eden and our runtime. |
| static-recomp-regression-triage | Checklist mapping symptoms → loader / ISA / services / GPU / audio | Rewrite using nxnative `docs/agents/03-bringup.md` and `05-debugging.md`, which are concrete failure catalogues. |
| static-recomp-perf-profile | Checklist | Rewrite around a LASRecomp `perf_sweep.py`-style warp sweep plus a function profiler. |
| static-recomp-reference-capture | Checklist | Fold into av-compare. |
| static-recomp-scope-plan, static-recomp-batch-harness | Multi-title catalogue planning | Skip. We have one title. |
Better skill sources: nxnative `docs/agents/` (extract → survey → bring-up → graphics → debugging), LASRecomp
`tools/` (test_lift, test_simd, perf_sweep, shot, frames, explore_input), and ssbu-recomp's Unicorn differential tests
and deterministic state-hash mode.
## Takeaways for this project
1. The other TotK PC port (section A): no code, and its screenshots were taken down. Proof of feasibility, not a dependency.
Its stack (MSVC link + wgpu) is plausible but unconfirmed.
2. Base the lifter design on LASRecomp (MIT, AArch64→C, SIMD→C for x86) and validate it the way ssbu-recomp does
(Unicorn differential tests). Read suyu's `arm64_to_c.h` for its fallback strategy.
3. Base HLE and NVN behaviour for TotK on MacNativeGames (MIT): per-version hashes, memory layout constraints, NVN
texture layout fixes, frame-pacing patches, shader-variant list.
4. Shaders: Ryujinx `Ryujinx.Graphics.Shader` (MIT) → SPIR-V is the proven route. LASRecomp and ssbu-recomp wrote
their own Maxwell → GLSL translators.
5. SwitchRecomp: reuse the av-compare scripts and the legal/provenance policy only.
## D. Performance techniques in other Switch recomps (2026-10-21)
Clones read at `build/research/` (ignored): HWDER (https://github.com/sonsegajp/HWDER, MIT), B2recomp
(https://github.com/K0NL/B2recomp, GPL-3.0; its runtime is a copy of ssbu-recomp), SuperMarioWonderRecomp
(https://github.com/BelmanteGu/SuperMarioWonderRecomp, MIT), ssbu-recomp (GPL-3.0). GPL code: read only.
1. FPCR: all four ignore it and run FP on host SSE in the default mode. HWDER stores FPCR and never applies it
(`tools/recomp/a64.py:371,394`); B2recomp and ssbu drop FPCR writes (`lifter/recomp.py:269-271`,
`tools/lifter/recomp.py:287-290`); Wonder documents FPCR as "not honoured" (`docs/RECOMP.md:31,71`). None handles
a game that sets FZ, as TotK does. Exactness work they keep: NaN sign, FRECPE/FRSQRTE (B2recomp `runtime/fpexact.h`).
2. Cores: HWDER and Wonder run guest threads free, one host thread each, no preemption model; GetCurrentProcessorNumber
returns the ideal core or the lowest mask bit (HWDER `svc.cpp:157-170`, Wonder `runtime/src/kernel.cpp:528-538`).
ssbu and B2recomp have an opt-in 3-core pinning model, shipped off because it costs frame rate
(`os_threads.c:143-156`). TotK crashes without our core gate (`TOTK_FREE_CORES=1`), so the gate stays.
3. Waits: ssbu sleeps with a high-resolution waitable timer (`os_threads.c:104-122`); Wonder removed its yield nap
(it cost the main thread about 18%, `kernel.cpp:81-96`).
4. Codegen: HWDER clang-cl /O2 /arch:AVX2 -mfma, one dense dispatch table per module with a musttail call
(`core.cpp:26-58,131-138`); Wonder -O2 with `-ffp-contract=off`; B2recomp `-ffp-contract=off`, `optnone` on
functions over 5000 statements, and a register-caching pass measured at no gain under -O2 (`regcache.py:1-30`);
ssbu stays at -O1 because huge lifted functions take over an hour at -O2 (`tools/lifter/build.py:55-68`). No LTO
or PGO anywhere.
5. Pipelines: HWDER compiles on worker threads and skips the draw until ready (`vk_renderer.cpp:1391-1430`); ssbu
waits by default, but its workers precompile predicted keys and replay `pipes.bin` plus a VkPipelineCache at start
(`nvn_vk_draw.c:4037-4062`); B2recomp prewarms from a saved list (`nvn_vk_m4.c:1702-1759`); Wonder's canonical
pipeline key removed 18% of compiles (`docs/nvn/android-perf/PIPELINES-1810.md:15-20`).
6. GPU to CPU data: ssbu copies idle compute buffers on the GPU into host memory and merges them into guest memory when
the submit completes, avoiding 19-20 ms reads of write-combined memory (`nvn_vk_draw.c:1940-1960`); Wonder splits
the submit after the last dispatch (`runtime/src/nvn/nvn_frames.cpp:11-19`).
7. Textures: ASTC on the CPU everywhere (Wonder multi-threaded, `runtime/src/nvn/nvn_astc.cpp`); HWDER detects dirty
textures by content hash with a 48 MB per-epoch budget (`texture_cache.cpp:322-334`).
8. Pacing: HWDER mailbox present plus its own 60 Hz limiter, swap interval 2 paced two slots ahead
(`display.cpp:160-163,317-334`); Wonder prefers MAILBOX; B2recomp patches 60-120 fps at lift time from a census of
frame-rate sites (`lifter/fps_ticks.txt`).
## E. SavageWindRecomp findings (2026-10-23, `refs/SavageWindRecomp` @ `575ad88`)
MIT (`LICENSE:1-4`), pinned in `tools/fetch_refs.sh`. 430 files, 8 commits, one week old. Its notes (`docs/SAVAGE-WIND.md`, Spanish, 904 lines, cited
as `SW.md:line` = first line of the entry) are a dated log of BOTW 1.8.2 bring-up fixes. Most are bugs TotK 1.2.1 hits too. Paths are relative to
`refs/SavageWindRecomp/`. BOTW addresses do not carry over to TotK; the mechanisms do.
| Area | Theirs | Ours | Differs |
|---|---|---|---|
| Cores | 4 tokens, ticket queue per core (`runtime/kernel.c:96-235`); mask used only if single-bit (`kernel.c:867-880`) | 3 cores, mask-aware grant, preempt flag (`runtime/kernel.c:230-360`) | Yes |
| Preemption points | SVCs plus every indirect call (`runtime/dispatch.c:167`) | SVCs only (`runtime/svc.c:140`) | Yes |
| Exclusive monitor | Value CAS (`runtime/cpu.h:73-97`); pairs unsupported (`tools/lifter.py:391-392`) | Same macro plus 128-bit pair (`runtime/cpu.h:73-118`) | No (ours is a superset) |
| Call/CopyCommands | Record `CMD_CALL`, executed recursively at submit (`runtime/nvn/cmdbuf.c:687-688`, `runtime/nvn/vulkan/exec.c:4689-4695`) | Inlined at record time (`runtime/nvn_api_cmd.c:395-410`) | Yes |
| UpdateUniformBuffer | Applied at execution into guest memory, skipped if bytes equal (`exec.c:4863-4871`) | Recorded, written at replay (`nvn_api_cmd.c:430-441`) | Partly |
| Submit | Host queue thread, part-wise GPU submit (`runtime/nvn/objects.c:157-170`, `exec.c:1015-1017`) | Replay on the submitting thread (`runtime/nvn_api_core.c:520-530`) | Yes |
| Frame pacing | Patches VFR and the vsync wait (`tools/patches.py:186-223`) | none yet | Yes |
### a. Threads
- Core gate like ours: a token per core, best priority then ticket order (`kernel.c:96-165`). Reason given: BOTW shares a sead heap without a lock between threads pinned to one core (`kernel.c:97-103`).
- Four tokens, indexed `core & 3` (`kernel.c:150`); a multi-bit affinity mask is not honoured, only a single-bit mask or the ideal core (`kernel.c:876`). `-1`/`-2` land on core 0 (`kernel.c:388`).
Ours takes any free allowed core and keeps the ideal core for -2/-3, closer to Horizon.
- Preemption at indirect calls: `rt_dispatch` compares `g_core_best_wait[core]` with the running priority and yields (`dispatch.c:167`, `kernel.c:120-130, 220-229`).
Reason: a prio-48 job thread ran about 5 ms of guest code without a syscall once a second while a prio-44 worker on the same core, which the main thread waited for, sat waiting (a frame 10 ms longer each second) (`SW.md:540`).
Measured p99 frame time 23.6-24.8 ms without, 17.4-20.6 ms with (`SW.md:553`). Ours preempts only at SVCs (`runtime/kernel.c:354-362`, `runtime/svc.c:140`).
- Host work releases the core: the submit and present path calls `kernel_host_work_begin/end` (`kernel.c:196-205`, `runtime/nvn/objects.c:132, 245-249, 292-294`). Reason: the translation took about 10 ms a frame on the core token (`SW.md:295`).
- Yield and `SleepThread(0)`: release then reacquire, so same-priority waiters go first (`kernel.c:231-236, 838`). `SignalProcessWideKey` and `ArbitrateUnlock` yield after unlocking, not before (`kernel.c:735-741`, `SW.md:256`).
- `svcWaitProcessWideKeyAtomic`: releasing the mutex before marking the condvar hung half the runs (`SW.md:224`); a timed-out wait returns without the mutex, and a timeout racing a wake does not count as expired (`SW.md:253`). Same family as port-lessons S6.
### b. Exclusive monitor
- Value CAS on the address recorded by LDXR, identical to ours (`runtime/cpu.h:73-97`). No ABA protection on either side. Nothing to adopt.
### c. NVN command buffers
- The game sees command memory accounted at an estimated NVN cost per command, `cmd_cost` (`cmdbuf.c:15-28`); records live in host "shadow" blocks keyed by guest memory.
Reason: BOTW records each display list once to measure it, then allocates exactly that from a heap sized by the ResourceSizeTable for real NVN (`SW.md:201`).
- A list dies only when a recording writes over its guest memory (`shadow_claim`), not when the game adds an overlapping window. The old rule lost the deferred-lighting material lists, so no light was composed (`SW.md:233`). Dead blocks are reused three frames later (`cmdbuf.c:25-26`).
- Textures in records are resolved at record time (`nvn_texture_host`, `cmdbuf.c:442-455`). The exposure chain (192x192 down to 3x3) re-inits one `NVNtexture` per step inside a command buffer; resolved at execution, every step drew into the last (`SW.md:242`).
- One Vulkan image per (memory, shape): `NVNtexture` objects on the same memory and shape share an image (copies, finalized originals still in the pool, re-created render targets) (`SW.md:220, 245`; `runtime/nvn/vulkan/textures.c`).
- `NVNsampler` objects are copied by value and the copy is registered after the original is finalized. Descriptions are shared per configuration and never freed; otherwise the Shrine corridor texture clamped instead of repeating (`SW.md:261`).
- Draws resolve at execution on the queue thread. UBO ranges are copied at the draw, shared per list, and `UpdateUniformBuffer` (about 450 a frame into about 40 ranges) invalidates only the copies over its range; identical rewrites (about 1 in 5) are skipped (`exec.c:471-503, 2415-2430, 4863-4871`; `SW.md:535, 565`).
- `BindTexturesDeferred` was a no-op and dropped the lighting composite's textures; the other `Bind*Deferred` entry points are still unimplemented there (`SW.md:240, 278`).
### d. Engine special cases
- Few guest patches: 17 in `tools/patches.py:209-223`, 15 for their own options screen. The two for us: the sead vsync wait `0x7000d811fc` (`patches.py:186-203`) and the `ksys::VFR::updateInterval` ratio load `0x70014092f4` (`patches.py:206-210`).
TotK equivalents are in macnativegames.md (present-interval controller, lines 438-446).
- Frame pacing (`runtime/hle/framepace.c`, `runtime/framepace.h`, `SW.md:430`): presents on a fixed grid; the game's clock is told the real frame length through `rt_vfr_update` (ratio = seconds x 30, at most 3 % change per frame, at most 1/20 s per step, debt paid back over later frames) (`SW.md:454`);
integer interval with hysteresis (1 above 43 fps, 2 below 35, 3 below 23); menus, events and movies pinned to 30 fps (`SW.md:443`); controller hold counters stepped by real time.
Havok, stamina, time of day and animation all read the ratio; a ratio that alternated made Link's camera judder.
- Dynamic resolution: BOTW picks 1600x900 or 1280x720 from GPU time in `ReportCounter`; their translation time dropped the open world to 720p. Fix: every counter in a frame gets the same timestamp (`exec.c:4890-4902`, `SW.md:414`).
- Render-thread layout: the main thread records about 30 of 62 lists per frame, two workers the rest; the sead render thread (`0x7000d81100`) submits one list a frame and presents (`SW.md:503`).
- FPCR.FZ is set at thread start (`0x7000b4de30`, `0x70000c4e3c`). Software flushing cost about 40 % of main-thread time; they mirror FZ into MXCSR (`runtime/simd.h:53-58, 239`; `SW.md:516`). Ours already mirrors it (`runtime/cpu.h:21`).
- Depth clamp: BOTW enables it for the three sun-shadow cascades and the sun query. Ignored, geometry nearer than a cascade's near plane was clipped; tree shadows appeared, were cut and moved with the camera (`SW.md:593`). Ours records and applies it (`runtime/nvn_api_cmd.c:528`, `runtime/vk_pipeline.c:242`).
`SAMPLES_PASSED` returns 0 and `SetRenderEnableConditional`/`SetRasterizerDiscard` are no-ops (`SW.md:593`).
- Same-pass feedback: the terrain fragment shader ORs bits into the G-buffer's own pixel, about 240 draws a frame. Copying the 1600x900 target before each draw cost 8.5 of 16 ms GPU. They use `VK_EXT_attachment_feedback_loop_layout` plus `VK_KHR_dynamic_rendering_local_read` with an in-pass barrier: copies 8.5 to 0.4 ms (`SW.md:325`).
Ours parks this (`docs/backlog.md:51-54`); TotK has 425-667 such draws.
- Submit in parts: a pass boundary about every 300 draws (`exec.c:1015-1017`, `SW.md:302`), except after a shader storing to guest memory (about 10 dispatches a frame). Ranges those storage buffers can write are tracked; a UBO inside them is read in place from the imported heap, and any other CPU copy of that memory waits for the GPU (`SW.md:524`). Holding the rest of the list caused device-lost in 1 of 7 loads when copying half-written data.
- Present on its own thread with a second queue; NVIDIA `vkQueuePresentKHR` blocked on the GPU for 13-18 ms in one frame of five (`runtime/nvn/vulkan/device.c:563-593`, `SW.md:306`).
- Shaders and pipelines: translation cached in memory and on disk (`cache/xlate/`, `SW.md:309`); `vk_pipelines.bin` with a GPU/driver/translator header plus `vk_pipelines.list`, replayed by worker threads at start-up, first world frame waits for it (`SW.md:337`, `device.c:310-384`).
Scripted walk, render-thread compile time 5898/865/362/449 ms to 16/1/32 ms, frames over 40 ms 56/51/9/11 to 24/4/5. The pipeline key held colour formats and blend bytes of unused targets, giving about 1,500 pipelines where about 870 were needed (`SW.md:364`).
- Synchronous shader compile by default: a draw skipped while its pipeline builds is lost for good if the game draws it once (save thumbnail) (`SW.md:657`).
- Targets are not cleared per frame (BOTW keeps data in them between frames); new images start at zero (`SW.md:409`).
### e. Known glitches
Issue list (`gh issue list -R Revivedx/SavageWindRecomp --state all`, 23 issues, 2 closed, none with a technical fix thread for graphics):
- #16 trees "vertex explosions" at some distances or angles, 4K, no upscaler. Open; a collaborator replies "almost fixed". No cause stated. Closest match to one-frame popping.
- #20 distant LODs not rendering fully. Open, no analysis. #26 and #5 "texture errors" and "graphic errors" (RX 570 and unknown GPU). Open, logs requested.
- #23 ROG Ally: 114-700 ms frames on transitions and shader generation, up to 250,000 draws reported per frame, VRAM use 0.4-1.4 GB. Open. Matches their own note that a first-use pipeline costs 40-100 ms (`SW.md:386`).
- #31 30 fps in menus, chests, cutscenes: by design (`framepace.h:15-17`). #30 asks to precompile all shaders; the pipeline list is their answer.
- Crashes with a stated cause: #2 voice banks swapped in are larger than the ResourceSizeTable entry, so a later heap allocation fails; #6 `movie.c` vtable slot 2 is a stub, crash at the first tower cutscene.
Fixed in `SW.md` and relevant to TotK: stretched texture from sampler copies (`SW.md:261`), blocky image from re-created render targets (`SW.md:220`), black cube arrays (`SW.md:248`), moving tree shadows from depth clamp (`SW.md:593`), missing lighting from dead command lists (`SW.md:233`).
Still open in their log: a differently tinted rectangle top-left from half-resolution fog passes (`SW.md:271`), a 32x32x32 BC4 3D texture sampled as 2D returning black (`SW.md:276`), an ambient palette that fades interior to exterior over 60 s (`SW.md:606`).
Nothing in the issues or the log describes objects teleporting for a frame, or a wrong-LOD mesh, with a cause.
### f. Linux platform layer
- `runtime/platform.h` is the split: `plat_reserve_guest`, `plat_commit`, `plat_reset_guest`, `plat_protect`, `plat_now_ns`, `plat_sleep_until_ns`, spawn, symbols, crash handler (`platform.h:16-65`). Implementations: `runtime/platform/{windows,linux,macos}.c`, with `win_compat.h` and `linux_compat.h` filling POSIX gaps.
- Memory: Linux maps the whole guest window once, `MAP_PRIVATE|MAP_ANONYMOUS|MAP_NORESERVE|MAP_FIXED_NOREPLACE` (`platform/linux.c:29-33`). Windows reserves with `VirtualAlloc` and commits in chunks from a vectored handler (`platform/windows.c:20-27, 71-76`).
- Write watching is a debug tool: page `PAGE_NOACCESS` plus single-step (`windows.c:30-58`, `runtime/kernel.c:1150-1160`). The renderer does not track dirty pages; it copies guest memory when the draw runs.
- Threads are pthreads on both (winpthreads on mingw). Timers: `clock_nanosleep(TIMER_ABSTIME)` on Linux (`linux.c:54-60`); a high-resolution waitable timer plus `timeBeginPeriod(1)` on Windows (`windows.c:108-125, 205`).
- Linux needs a 4 KB or 16 KB page kernel (`docs/linux.md`).
### What to adopt, ranked by expected effect on glitches and stutter
1. Preemption at indirect calls in `rt_dispatch`, plus the host-work core release. Small change, removes a periodic 5-10 ms frame spike they measured (p99 23.6-24.8 to 17.4-20.6 ms). Needs TotK confirmation with our sched trace.
2. Persistent pipeline list pre-warmed at start-up, with a key that holds only the used targets. Removes the 40-100 ms first-use hitches that read as stutter (frames over 40 ms 56 to 5 on their walk).
3. Host submission queue with part-wise GPU submit (about 300 draws) and the guest-memory-write tracking for storing shaders. Their p99 went 38-43 ms to 29-34 ms with queue, MXCSR FZ and range tracking together (`SW.md:550-552`).
Next: feedback-loop layout instead of target copies, one image per (memory, shape), UBO copy sharing with per-range invalidation, equal-timestamp counters for dynamic resolution.
+102
View File
@@ -0,0 +1,102 @@
# TotK 1.2.1 module inventory
Numbers measured on a retail 1.0.0 base plus the 1.2.1 update (`v393216`), extracted with `tools/extract.py` on 2026-10-20. Counts only; no game data.
## Input verification
| | Result |
|---|---|
| Base ExeFS (`main`, `sdk`, `subsdk0`, `rtld`) | match `expected-v1.0.0.json` |
| Base RomFS | 17,069,139,640 bytes, 304,207 files, SHA-256 matches; 1,041,818 level-5 IVFC blocks verified |
| 1.2.1 ExeFS including `main.npdm` | match `expected-v1.2.1.json`; ACID signature verifies |
| 1.2.1 RomFS (BKTR merge) | 17,052,047,360 bytes, 304,473 files, SHA-256 matches |
| MacNativeGames rewrite of `main`, `sdk`, `subsdk0` | output hashes equal `rewritten_sha256` in `expected-v1.2.1.json` |
The tested base dump's `main.npdm` differs from the reference only in bytes `0x80-0x27F` (ACID signature and ACID public key), so its ACID signature no longer verifies. A repacking tool that re-signs the NCA header does this. Code and RomFS are unaffected.
Timing on the development machine (NVMe): ExeFS under 1 s each, base RomFS 40 s, update merge with NCA copies 1 min 50 s.
## Modules
`image` is the loaded size (all segments plus `.bss`, page aligned).
| Module | image | `.text` | `.rodata` | `.data` | `.bss` | relocations | imports | exports |
|---|---|---|---|---|---|---|---|---|
| `main` | 74,625,024 | 45,193,808 | 23,658,396 | 5,006,256 | 765,008 | 510,904 | 675 | 29 |
| `sdk` | 14,520,320 | 6,161,120 | 7,150,872 | 429,712 | 774,512 | 35,032 | 13 | 27,747 |
| `subsdk0` | 6,983,680 | 3,424,448 | 2,202,004 | 199,416 | 1,152,264 | 19,397 | 667 | 10,954 |
`main` exceeds LAS Recomp's 64 MB module limit (see [lasrecomp.md](lasrecomp.md), "Scaling risks").
## Functions and instructions
LAS Recomp `tools/analyze.py --census` (seeds: `.eh_frame_hdr`, exported FUNC symbols, `R_AARCH64_RELATIVE` targets in `.text`, `BL` targets; each start is credited to the first source that finds it).
| Module | functions | eh | sym | ptr | bl | instructions | undecodable words | mnemonics | time |
|---|---|---|---|---|---|---|---|---|---|
| `main` | 247,495 | 246,909 | 0 | 3 | 583 | 11,298,063 | 389 | 259 | 15 s |
| `sdk` | 38,305 | 31,238 | 36 | 8 | 7,023 | 1,539,998 | 282 | 362 | 3 s |
| `subsdk0` | 13,690 | 10,061 | 15 | 2 | 3,612 | 855,798 | 314 | 178 | 1 s |
| total | 299,490 | | | | | 13,693,859 | | | |
About 2.5-3 times *Link's Awakening* (4-6 M instructions). `main` has unwind info for nearly every function, so `.eh_frame_hdr` alone gives a near-complete function list.
Instructions the lifter must cover, by module:
- Exclusive pairs (`LDXP`, `STXP`, `LDAXP`, `STLXP`): `sdk` only (26 / 38 / 50 / 63). `main` has none.
- LSE atomics (`CAS*`, `CASP*`, `SWP*`, `LDADD*`, `LDCLR*`, `LDEOR*`, `LDSET*`): `sdk` only, 1-2 of each variant, likely behind a CPU feature check.
- Crypto: `sdk` uses AES (`AESE`, `AESD`, `AESMC`, `AESIMC`), SHA-1 and SHA-256 instructions. CRC32: `main` 7,710, mostly `CRC32B`.
- Exclusive single (`LDXR`/`STXR`): `main` 15,821 / 16,308; acquire/release forms in all three.
- System: `SVC` 60 (`sdk`), `MRS` 865 / `MSR` 53 (`main`), `MRS` 181 / `MSR` 13 (`sdk`).
- Indirect branches: `BLR` 105,284 and `BR` 26,426 in `main`.
- SIMD: `FMLA` 24,520, `TBL` 2,327, `LD1`-`LD4`/`ST1`-`ST4` in `main`.
## Lifter coverage
`tests/diff/lift.py --coverage` lifts every distinct word of `.text` (`recomp/lifter.py`, portable FP/SIMD lowering). Every word is lifted except those that become an `rt_udf` trap:
| Module | distinct words | trapped words (distinct) | of which `UDF` | undecodable data (capstone `?`) | other |
|---|---|---|---|---|---|
| `main` | 1,393,284 | 28,266 (10) | 27,873 | 389 | 4: the module header at `main+0x0`-`0x20`, which capstone decodes as SVE |
| `sdk` | 313,813 | 22,494 (9) | 22,212 | 282 | 0 |
| `subsdk0` | 233,022 | 5,858 (8) | 5,545 | 313 | 0 |
Upstream LAS Recomp rejects 277 `sdk` words: the exclusive pairs and the LSE atomics. Both were added (`excl_pair`, `cas`, `casp`, `atomic` in the lifter; `ldxp128`/`stxp128` and `atomic_[su]{max,min}N` in `runtime/cpu.h`).
Differential test results (2026-10-20, seed 1):
| Test | Encodings | Cases | Failing |
|---|---|---|---|
| `lift.py` (all opcode signatures of the three modules, then random words; 20,000 per module) | 60,000 | 239,948 | 0 |
| `simd.py` (1,048,640 FP/SIMD encodings: lifter and Unicorn accept the same 270,299) | 20,000 | 159,976 | 0 |
| `atomic.py` (exclusive sequences, LSE, CAS, CASP; every variant) | 198 | 12,672 | 0 |
Unicorn 2.1.4 (QEMU 5.0) compares `LDSMAX`/`LDSMIN` on bytes, halfwords and words as unsigned. `atomic.py` checks those against a Python model of the ARM pseudocode instead. The game does not use them.
## Jump tables
`tests/jumptables_check.py` runs `recomp/jumptables.py` on every `br` and compares it with LAS Recomp's Unicorn method. Functions are `[seed, next seed)` over the module's seeds plus `BL` targets (2026-10-20, `.venv`, 36 s wall for all three modules):
| Module | `br` | computed | resolved | entries | oracle resolved | agree | oracle wrong | computed, unresolved | PLT stubs (not computed) |
|---|---|---|---|---|---|---|---|---|---|
| `main` | 26,426 | 2,242 | 2,219 | 16,657 | 1,771 | 1,758 | 12 + 1 | 22 | 642 |
| `sdk` | 11,457 | 707 | 694 | 5,330 | 586 | 585 | 0 | 12 (+1 only the oracle resolves) | 8,933 |
| `subsdk0` | 4,465 | 339 | 339 | 2,529 | 312 | 312 | 0 | 0 | 3,925 |
- "Oracle wrong" carries independent evidence: the table base the oracle replays is not the constant every reaching definition gives (8 sites; the register is reused for other values, e.g. `x3` at `main+0x7c6fa8`), or the table index comes from a register or stack slot the oracle does not set (5 sites, e.g. `and w9, w1, #3` at `main+0x3d358`, a stack reload at `main+0xce2af4`).
- Every hoisted table base (482 in `main`, 86 in `sdk`, 30 in `subsdk0`) is confirmed by a capstone reaching-definitions pass.
- Left unresolved, by pattern: index `(x & 7) - 1` with no check (an unreachable default; 17 sites in `main`, one templated function family), index from an argument, a field or a stack slot without a visible check (`main+0x832f0`, `+0xcd7b40`, `+0xce2f38`, `+0x1386f24`, `sdk+0x10ec9c`, `+0x10f7e4`, `+0x10fd90`, `+0x11f2f0`), index from a bit insert of an unknown 32-bit value (`main+0x17d61c`), pointer difference in the `memchr`-style tails (`sdk+0xff1d0` and five more), a 64-bit index reloaded from the stack and compared as 32-bit (`sdk+0x32a518`, `sdk+0x591a4`), and a thunk that jumps to the next function through a constant (`sdk+0x56f4f4`).
## OS touch-points (MacNativeGames `patch_nso.py`, `DM_RULESET=native`)
Site kinds from `sites.tsv` (`x18` = platform register uses, `W` = exclusive windows, `J` = jump tables, `C` = call window):
| Module | x18 | tpidr_r | tpidrro_r | tpidr_w | cntpct | svc | W | J | C |
|---|---|---|---|---|---|---|---|---|---|
| `main` | 30,577 | 813 | | | | | 84 | 19 | 1 |
| `sdk` | 12,731 | 2 | 123 | 3 | 40 | 60 | 5 | 6 | |
| `subsdk0` | 10,201 | | | | | | | 2 | |
Rewriter statistics for `main`: 29,716 plain, 610 conditional, 232 PC-relative, 19 `br`, 813 TLS reads, 84 exclusive windows, 1 call window; 31,475 slot references. Runtime: `main` 77 s, `sdk` 12 s, `subsdk0` 7 s.
`patch_nso.py` prints Chinese text at the end of the `main` run; on a non-UTF-8 Windows console run it with `python -X utf8`.
+72
View File
@@ -0,0 +1,72 @@
# Tester guide: running TotK Recomp on your GPU
This guide is for testing the build on a GPU other than the developer's (AMD RX 9070). You build it from source with
your own copy of the game and your own console keys. Nothing from the game is in this repository, and nothing you build
from it may be shared.
## What you need
- Windows 10 or later, an x86-64 CPU with AVX2, about 60 GB free.
- A GPU with Vulkan 1.3 and `VK_EXT_external_memory_host`, with a current driver.
- *Tears of the Kingdom* base game (1.0.0) and the 1.2.1 update, dumped from your own Switch as NSP or XCI.
- `prod.keys` dumped from your own Switch. Never send it to anyone, and never paste it into a log or an issue.
## Build
1. Install the toolchain: [toolchain-windows.md](toolchain-windows.md) and
[toolchain-msys2-python.md](toolchain-msys2-python.md).
2. Follow steps 1-5 of "Building from source" in the [README](../README.md): Python environments, `config.local.toml`
with your own paths, extraction, the shader translator, then lifting and linking. The result is
`build\v121\totk.exe`.
3. Check the build without the game: `build\v121\totk.exe --selftest` must print a pass.
4. To run the build on another of your machines, `.venv\Scripts\python tools\package_build.py` writes
`build\v121-portable` (about 2.4 GB). Copy it over; it needs no MSYS2, Python or .NET. The 16 GB RomFS is not in it:
copy `build\extracted\v121\romfs\romfs.bin` into `romfs\` there, or run the packager with `--with-romfs`.
Then run `totk.exe --prepare-shaders` once in the copied folder (about a minute): the driver caches pipeline
libraries per exe path, and without it the first fights stutter.
The folder holds game code: for your own machines only.
## Run and collect the log
The log goes to stderr. Run from `cmd.exe` in the repository root, so the log lands in a file:
```bat
set TOTK_VK_VALIDATION=1
build\v121\totk.exe 2> totk-log.txt
```
`TOTK_VK_VALIDATION=1` turns on the Vulkan validation layer (it comes with the Vulkan SDK). It makes the game slower;
do one run with it and one without (`set TOTK_VK_VALIDATION=`).
Keep the window in the foreground: an unfocused window stalls the game. The first launch spends minutes on shaders.
Play into the open field (load a save, walk around for a minute, fight something if you can), then close the window.
## Choosing the GPU
A laptop with an iGPU and a discrete GPU, or two cards, lists every GPU at the top of the log (`vk: gpu 0: ...`).
- `set TOTK_GPU_NAME=Radeon` picks the first usable GPU whose name contains that text (case does not matter).
- `set TOTK_GPU_INDEX=1` picks GPU 1 from that list.
The line `vk: using gpu N: <name>` says which one ran.
## What to send back
1. `totk-log.txt` from each run. It contains no keys and no game files. The lines that matter most start with
`vk caps:` (GPU, driver, features and the fallbacks taken), `vk: gpu`, `validation` and `gfx_shader:`.
2. GPU model, driver version, CPU, RAM, and whether it is a laptop.
3. What you saw: how far it got (menu, loading, field), roughly how smooth it ran, and screenshots of anything wrong
(black or missing areas, flickering, wrong colours, missing grass). Win+Shift+S is fine.
4. If it crashed or hung: the last 50 lines of the log and what you were doing.
## Switches for the developer's questions
Only set these when asked; each forces a fallback the build picks by itself on GPUs that need it.
| Variable | Effect |
|---|---|
| `TOTK_VK_NO_FLOAT64=1` | Translate shaders without 64-bit floats |
| `TOTK_VK_SSBO_ALIGN=64` | Treat storage buffers as needing 64-byte alignment |
| `TOTK_VK_SUBGROUP_PIN=0` | Do not pin shaders to 32 lanes; tell the translator the GPU's own subgroup size |
Each switch makes the first launch translate every shader again.
+104
View File
@@ -0,0 +1,104 @@
# Toolchain: MSYS2 UCRT64, Python, Switch content tools
Set up 2026-10-20. Package set follows `refs/LASRecomp/tools/setup_windows.ps1` plus cmake, ninja, gcc, git, unzip.
`setup_windows.ps1` itself was not run.
## MSYS2 UCRT64 (`C:\msys64`)
Update: `C:\msys64\usr\bin\bash.exe -lc "pacman -Syuu --noconfirm"` (twice: first pass updates the core and exits).
Install:
pacman -S --needed --noconfirm make mingw-w64-ucrt-x86_64-{clang,lld,sdl3,ffmpeg,vulkan-devel,shaderc,spirv-tools,
pkgconf,gdb,vulkan-memory-allocator,vulkan-validation-layers,nasm,cmake,ninja,gcc,make} base-devel git unzip zip p7zip
| Package | Version |
|---|---|
| clang / lld | 23.1.3 |
| gcc | 16.2.0 |
| make (msys) / mingw32-make | 4.4.1 |
| sdl3 | 3.4.18 |
| ffmpeg | 9.0.2 (MSYS2 build is GPLv3; LASRecomp ships an LGPL build via `tools/build_deps_windows.sh`) |
| vulkan-devel group (headers, loader, utility libs, spirv-headers, spirv-tools, validation layers) | 1.4.363 |
| shaderc (glslc) | 2026.4 |
| vulkan-memory-allocator | 3.4.0, header at `/ucrt64/include/vma/vk_mem_alloc.h` |
| pkgconf | 3.0.9 |
| cmake / ninja | 4.4.4 / 1.13.2 |
| nasm / gdb | 3.02 / 18.1 |
| git / unzip / zip / p7zip | 2.56.0 / 6.0 / 3.0 / 17.06 |
Use from Git Bash: `export PATH="/c/msys64/ucrt64/bin:/c/msys64/usr/bin:$PATH"`. Built exes need
`C:\msys64\ucrt64\bin` on PATH at run time (SDL3, FFmpeg, Vulkan, shaderc DLLs).
Verify:
clang --version; ld.lld --version
pkgconf --modversion sdl3 vulkan libavcodec
glslc --version; ffmpeg -version; spirv-val --version
### Vulkan back end of M4
# all part of the install line above plus spirv-cross and glslang; --needed makes this a check
pacman -S --needed mingw-w64-ucrt-x86_64-{vulkan-devel,vulkan-memory-allocator,vulkan-validation-layers,shaderc,spirv-tools,spirv-cross,glslang}
Verify:
pkgconf --modversion vulkan # 1.4.363
spirv-val --version; spirv-dis --version
ls /ucrt64/include/vma/vk_mem_alloc.h /ucrt64/lib/libvulkan-1.dll.a
vulkaninfo --summary # Vulkan SDK; lists the discrete GPU, Vulkan 1.3 or newer
`tools/build_game.py` links `-lvulkan-1 -luser32 -lgdi32 -ldwmapi` and adds `/ucrt64/include/vma` to the runtime include
path (`#include "vk_mem_alloc.h"`). At run time `vulkan-1.dll` comes from `System32`.
## Python
uv 0.13.3 at `%USERPROFILE%\.local\bin\uv.exe` (standalone installer, not winget).
| venv | Python | Purpose | Pins |
|---|---|---|---|
| `.venv` | 3.12.15 (uv-managed) | lifter / generator (capstone, unicorn, lz4, keystone, lief, pyelftools), oead 1.3.0, evfl, quicktex, PyYAML, Pillow, numpy, cryptography, nsz, zstandard, pyinstaller | `tools/requirements.txt` |
| `.venv-py314` | 3.14.7 (system) | MacNativeGames TotK scripts: they use stdlib `compression.zstd` (3.14+) | `tools/requirements-py314.txt` |
Version pins taken from LASRecomp `Makefile` (capstone 5.0.9, unicorn 2.1.4, lz4 4.4.5, pyinstaller 6.22.3) and
`refs/MacNativeGames/games/totk/requirements*.txt` (cryptography 50.0.2, nsz 5.0.0, Pillow 12.3.0, brotli 1.2.0).
`capstone.__version__` reports `5.0.7` although the installed wheel is 5.0.9; the wheel's metadata is right.
Recreate:
uv venv --python 3.12 .venv
uv pip install --python .venv/Scripts/python.exe -r tools/requirements.txt
uv venv --python 3.14 .venv-py314
uv pip install --python .venv-py314/Scripts/python.exe -r tools/requirements-py314.txt
Verify:
.venv\Scripts\python -c "import capstone, unicorn, lz4; print(capstone.__version__, unicorn.__version__)"
.venv\Scripts\python -c "import capstone; md=capstone.Cs(capstone.CS_ARCH_ARM64, capstone.CS_MODE_ARM); print([i.mnemonic for i in md.disasm(bytes.fromhex('1f2003d5'),0)])"
# -> ['nop']
.venv-py314\Scripts\python -c "import compression.zstd, capstone, unicorn, lz4, cryptography, nsz"
## Switch content tools (`toolchain\`)
| Tool | Path | Status |
|---|---|---|
| hactool 1.4.0 @ `1d64a83450e025622f3468c28fc4164dad2c5ef6` (the MacNativeGames pin) | `toolchain\hactool\hactool.exe` | built, static, depends only on system DLLs |
| hactoolnet | - | not installed: `github.com/Thealexbarney/LibHac` returns 404 (repo, releases and assets gone) |
hactool source: `toolchain\src\hactool` (git checkout of the pinned commit). Build: UCRT64 gcc, `config.mk` =
`CC=gcc EXEEXT=.exe CFLAGS=-O2 ... LDFLAGS=... -static`, `make -j8`.
Applied the portable part of MacNativeGames `build_app.py:build_hactool()` (diff in
`toolchain\hactool\portable-patches.diff`):
1. `MNG_TITLE_KEYS` env var selects the title-key file.
2. BKTR: allow 0x200-aligned padding after the subsection table (`nca.c`).
3. BKTR: accept the subsection total-size layout of newer cumulative updates (`nca.c`).
Not applied: the `MNG_BASE_RANGE_OFFSET/SIZE` base-file hook. It uses `funopen` (BSD/macOS only); on Windows the
base NCA must be extracted to a file first.
Verify: `toolchain\hactool\hactool.exe` prints `hactool (c) SciresM.` and usage.
Keys: hactool reads `-k <prod.keys>`, else `$HOME\.switch\prod.keys` (falls back to `%USERPROFILE%` when `HOME` is
unset; MSYS shells set `HOME`, so pass `-k` explicitly). Use your own keys; no keys are in this repo.
+51
View File
@@ -0,0 +1,51 @@
# Windows toolchain
Native Windows tools, installed with winget unless noted. MSYS2 packages and Python environments are in [toolchain-msys2-python.md](toolchain-msys2-python.md).
Versions are the ones verified on 2026-10-20. Newer patch releases are fine unless the row says otherwise.
| Tool | Version | Install | Verify |
|---|---|---|---|
| Visual Studio Build Tools 2026 (C++ workload, Windows SDK, VC.Llvm.Clang) | MSVC 19.51, SDK 10.0.26100 | `Microsoft.VisualStudio.BuildTools` with `--add Microsoft.VisualStudio.Workload.VCTools --includeRecommended --add Microsoft.VisualStudio.Component.VC.Llvm.Clang` | `cmd /c "call <VS>\VC\Auxiliary\Build\vcvars64.bat && cl"` |
| LLVM | 23.1.3 | `LLVM.LLVM` | `clang --version`, `lld-link --version`, `llvm-objdump --version` |
| CMake | 4.4.4 | `Kitware.CMake` | `cmake --version` |
| Ninja | 1.13.2 | `Ninja-build.Ninja` | `ninja --version` |
| Vulkan SDK | 1.4.363.0 | `KhronosGroup.VulkanSDK` | `glslc --version`, `spirv-cross --revision`, `vulkaninfo --summary` |
| .NET SDK | 10.0.402 | `Microsoft.DotNet.SDK.10` | `dotnet --list-sdks` |
| Rust | 1.99.1, target `x86_64-pc-windows-msvc` | `Rustlang.Rustup`, then `rustup default stable` | `rustc --version` |
| Zig | 0.17.0 | `zig.zig` | `zig version` |
| JDK | Temurin 21.0.12 | `EclipseAdoptium.Temurin.21.JDK` (sets `JAVA_HOME`) | `java -version` |
| Ghidra | 12.1.2 (pinned: SwitchLoader targets it; REA accepts 12.1.x) | Release zip from github.com/NationalSecurityAgency/ghidra into `toolchain/ghidra/` | `toolchain\ghidra\ghidra_12.1.2_PUBLIC\support\analyzeHeadless.bat` |
| Ghidra SwitchLoader | 1.6.1-c600d05 for Ghidra 12.1.2 | Release zip from github.com/Adubbz/Ghidra-Switch-Loader, extracted into `<ghidra>\Ghidra\Extensions\SwitchLoader` | Ghidra lists "Nintendo Switch Binary" as a loader |
| RenderDoc | 1.46 (`e4bd23b`) | Signed MSI from renderdoc.org, unpacked without installing: `msiexec /a <msi> /qn TARGETDIR=<tmp>`, then move `<tmp>\PFiles\RenderDoc\*` to `toolchain/renderdoc/` (drop `System`/`System64`, the VC++ runtime Windows already has). For Vulkan captures, once, as administrator: `renderdoccmd vulkanlayer --register --system` | `renderdoccmd version`; `renderdoccmd vulkanlayer --explain` reports the layer registered |
| REA | rea-agents 6.7.0 | Skill in the repo (`skills-lock.json`); MCP server registered per clone, see [AGENTS.md](../AGENTS.md) | `claude mcp get rea`; `npx -y rea-agents@6.7.0 doctor --json` shows the Ghidra provider available |
## PATH
The User PATH needs these, appended:
- `C:\Program Files (x86)\Microsoft Visual Studio\Installer`: `vswhere.exe`. Without it .NET NativeAOT publish fails at the link step (MSB3073).
- `C:\Program Files\LLVM\bin`: the LLVM installer does not add it.
A 32-bit winlibs MinGW on PATH can shadow `ninja`. Builds call Ninja from `C:\msys64\ucrt64\bin` by full path.
## Smoke tests
- **NativeAOT** (needed for the Ryujinx shader translator): `dotnet new console` then `dotnet publish -c Release -r win-x64 -p:PublishAot=true` produces a native exe that runs.
- **Generated-C dialect**: a C file using `__attribute__((musttail))`, `unsigned __int128` and `vector_size` types builds with MSYS2 UCRT64 `clang -O1 -fno-strict-aliasing -march=x86-64-v3 -fuse-ld=lld` and runs.
- **GPU**: `vulkaninfo --summary` lists the discrete GPU with Vulkan 1.3 or newer.
## Building the game code
`tools/build_game.py` compiles `generated/<version>/` (written by `recomp/gen.py`) and links it with the runtime into `build/<version>/totk.exe`:
```powershell
.venv\Scripts\python tools\build_game.py # generated/v121 -> build/v121/totk.exe
.venv\Scripts\python tools\build_game.py --modules subsdk0 # one module; --compile-only skips the link
build\v121\totk.exe --selftest # layout, guest window, dispatch table
```
- It writes `build/<version>/build.ninja` and runs `C:\msys64\ucrt64\bin\ninja.exe` with `C:\msys64\ucrt64\bin` first on `PATH`. Unchanged chunks are not recompiled.
- Compile jobs default to the smaller of the CPU count and a 50 GiB memory budget (80% of RAM on smaller machines) at `JOB_MEM` per job. `--jobs N` overrides it.
- Each phase prints its wall time and the peak committed memory of one process and of all processes together, then the exe's section sizes.
- 1.2.1 on 24 threads / 64 GB (2026-10-20): 351 files, 900 MB of C; clean compile 190 s at 24 jobs, under 600 MiB per job and 3.7 GiB all jobs together; link 1 s, 820 MiB working set; `totk.exe` 316 MB with 276 MiB of `.text`, well inside the 2 GiB reach of RIP-relative code.