Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
11 KiB
Architecture
How the Switch build of Tears of the Kingdom becomes a native Windows x86-64 program. The upstream projects it builds on are listed under Credits in the README.
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'sprod.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*.jsonhashes 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,subsdk0andrtldbyte for byte, so the lifted SDK modules and the host's SDK boundary serve all three; onlymaindiffers. 1.4.3 replaced all three modules (new SDK 20.5.22, RELR relocations, audio renderer REV15) and is a second target on the same build path:--version v143,recomp/patches-v143.txt. - Windows driver:
tools/extract.pyruns the vendored extractors (tools/vendor/macnativegames/) and identifies the update by the SHA-256 of itsmain. hactool has no Darwinfunopenhere, 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.rtldis 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 forBL, an address-keyed table for indirect branches. - Rewritten for TotK scale:
- 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; - NZCV and the six most used general registers of each function kept in C locals instead of the
Cpu(recomp/flags.py,recomp/regs.py): registers are stored back where they changed, before calls, SVCs and exits, and reloaded after them. A call reloads only X0-X18 and X30, as AAPCS64 has the callee preserve X19-X29 and SP;gen.py --no-callee-saved-trustreloads those too.
- 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.3main. 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. Onlyaudren:uandsm:are real IPC services. - Window, input, controllers and audio output: SDL3. Voice: libopus (BSD). Movies: the SDK's
movie::Decoderis 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. The split is not finished:tools/check_platform.pylists the Win32 uses left in 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. - Asynchronous preemption (from MacNativeGames 8bf0893, on unless
TOTK_ASYNC_PREEMPT=0). Game code can run for milliseconds with neither (TOTK_CORE_DIAG=1measures it): a waiter that has spun 250 us suspends the holder and, if its host rip is in lifted code at host depth 0 (not inside a host call or SVC), moves it tokern_ap_stub, which saves the volatile registers and gives the core up there. A holder of a guest mutex counts at the priority of its best waiter, and one inside an SDK spin lock (TLR+0x100disable_count) is not preempted: its interrupt flag is set and the switch happens at SVC 0x36.TOTK_ASYNC_PREEMPT=2keeps those two without interrupting. The interruption is Win32 (SuspendThread, SetThreadContext); another host needs a signal handler there, as MacNativeGames has. - 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=1turns the gate off, for experiments.
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
QueueSubmitCommandsthe 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. The back end imports the pools as host memory (
VK_EXT_external_memory_host). On a discrete GPU, pools bound as buffers are mirrored in device-local memory and the pages the CPU wrote (write watch, above) are uploaded before a replay; idle pool regions are made read-only so the write-watch queries skip them (vk_memory.c). GPU-rendered textures are written back when the CPU reads them: on a pool invalidate, on a CPU copy, and for small targets once the CPU waits for a fence (vk_texture.c). - Replay thread.
TOTK_REPLAY_ASYNC=1moves the replay off the submitting thread onto a queue at most one frame behind the game; reads of GPU results wait for the newest writer instead of draining the queue (vk_backend.c). It is off by default because no timing has shown a gain yet. - 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 astotk_xlate.exeand run as a separate process. Its SPIR-V goes to Vulkan directly. Translated shaders are cached on disk. - Pipelines:
VK_EXT_graphics_pipeline_librarywhere 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. A draw whose pipeline is not ready is skipped when one of its pass's targets was rendered in the previous frame, and waits otherwise, so one-shot passes are never lost; a full-screen draw is skipped as well rather than waiting (TOTK_PIPE_SKIP); the stage libraries a waiting draw needs are built on idle workers in parallel (TOTK_PIPE_WAIT). Without the extension, a missing pipeline is built on a worker and the draw waits or is skipped by the same rule. - Occlusion queries never block the CPU; a result that is not ready counts as visible.
- ASTC textures are uploaded as they are where the device reports
textureCompressionASTC_LDR, and decoded by a compute shader everywhere else (vk_astc.c,TOTK_ASTC). The CPU decoder (tex_astc*.c) is the fallback and the test oracle. - Draw state. A draw whose program, bound state and textures repeat reuses the previous draw's shaders and skips rebuilding its descriptor sets; descriptor sets are written through update templates (
vk_exec_draw.c,vk_pipeline.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 it hidesVK_EXT_external_memory_hostfrom the application.
Maxwell behaviour the back end has to match, and the TotK bugs other ports fixed: 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) thatcl.execannot compile. - Host code: the same Clang, C11.
- Builds:
tools/build_game.pywrites 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. - Players: the installer (installer.md) builds the game code on the player's machine with a bundled llvm-mingw, so no recompiled code is ever distributed.