Check the 1.1.0 patch contracts and document their coverage

This commit is contained in:
shenjack committed 2026-11-09 08:39:10 +08:00
1 parent 6966cee0d4
commit 89364414ea
4 files changed
+199 -3

No files matched your search

+4 -2
View File
@@ -10,8 +10,8 @@ Code copied or adapted from another project is listed here with its source, the
| MacNativeGames TotK host runtime: dynamic linking, identity check, module permissions, guest memory and SVCs, threads, IPC, audio renderer, system services, RomFS and save storage, boot sequence, the NVN proc name list | https://github.com/ly05010419/MacNativeGames @ `b75be8cfa704df3701e86130c8ced268e79d6b11` (`games/totk/runtime/`, `games/totk/scripts/prepare_runtime.py`), Copyright (c) 2026 MacNativeGames contributors | MIT | `runtime/loader.c`, `runtime/memory.c`; `runtime/kernel.c`, `runtime/svc.c`, `runtime/ipc.c`, `runtime/ipc.h`, `runtime/audren.c`, `runtime/audren.h`, `runtime/audio_mixer.c`, `runtime/audio_effects.c`, `runtime/audio_effects.h`, `runtime/audio_reverb.c`, `runtime/audio_reverb.h` (SDL3 output replaces CoreAudio), `runtime/ov_system.c` (also `shared_font.c`: the BFTTF layout behind nn::pl), `runtime/ov_input.c` (also `hid_feedback.c`: vibration and six-axis handles and calls), `runtime/motion_fusion.c` (six-axis fusion of `motion_fusion.c`), `runtime/ov_media.c` (hardware Opus decoder over libopus), `runtime/swkbd_win.c` (`swkbd_host.c`: ShowKeyboardArg offsets, UTF-8/UTF-16 conversion, disabled-key filter, result codes; Win32 window replaces the macOS text bar), `runtime/ov_gfx.c`, `runtime/romfs.c`, `runtime/romfs_path.h`, `runtime/fs_host.c`, `runtime/fs.h`, `runtime/boot.c`; `runtime/gfx_window.c`; `tools/gen_nvn_procs.py`, `runtime/nvn_procs.inc` (`NVN/names.txt` and the `NVN_EXTRA` names of `totk_nvn_ext.c`) |
| MacNativeGames TotK frame-rate patches: 60 fps present-interval controller, real-time frame step and its present sampling, hair and cloth clock, trampoline slow-motion check (instruction words and 1.2.1 sites), player position chain; quick-menu capture background RomFS overlay | https://github.com/ly05010419/MacNativeGames @ `ebe621de99bfc48f3c42f2d2aa73e04fbcc6eae2` (`games/totk/runtime/game_patches.c`, `game_version.h`, `world_survey.c`, `games/totk/scripts/make_romfs_patches.py`), Copyright (c) 2026 MacNativeGames contributors | MIT | `runtime/frame_rate.c`, `recomp/patches-v121.txt`, `tools/make_romfs_patches.py` |
| MacNativeGames TotK 1.4.3 fade fix: the four distance / LOD and pre-actor fade sites, their instruction words and the floor of the fade step at 1 | https://github.com/ly05010419/MacNativeGames @ `3e9e7f67fdfdd3404134dcfa0f24969a9425a33f` (`games/totk/runtime/game_patches_v143.c` patch_fade_increment), Copyright (c) 2026 MacNativeGames contributors | MIT | `recomp/patches-v143.txt` (set fade; the floor without flags, clz >> 5, as in pull request #78) |
| MacNativeGames TotK 1.2.1 cursor and aim steps: the map cursor, vertical Ultrahand aim and vertical gyro aim sites, their instruction words and the step scaled by the frame ratio | https://github.com/ly05010419/MacNativeGames @ `363a6eb50434387f7d623349934bcf1e910be48f` (`games/totk/runtime/game_patches.c` patch_cursor_speed), Copyright (c) 2026 MacNativeGames contributors | MIT | `recomp/patches-v121.txt` (set cursor) |
| MacNativeGames TotK aspect ratio: the camera and viewport sites that hand the perspective projection its aspect ratio, and the UI layout edits for a canvas wider than 16:9 | https://github.com/ly05010419/MacNativeGames @ `933b6a0d1438de160208a0a13eb5e8d7a2cb8094` (`games/totk/runtime/aspect_patch.h`, `aspect_math.h`, `game_patches_v143.c`, `games/totk/scripts/ultrawide_layout.py`), Copyright (c) 2026 MacNativeGames contributors | MIT | `recomp/patches-v143.txt` (set aspect), `tools/ultrawide_layout.py`, `tools/make_romfs_patches.py` (--aspect) |
| MacNativeGames TotK 1.2.1 cursor and aim steps: the map cursor, vertical Ultrahand aim and vertical gyro aim sites, their instruction words and the step scaled by the frame ratio | https://github.com/ly05010419/MacNativeGames @ `363a6eb50434387f7d623349934bcf1e910be48f` (`games/totk/runtime/game_patches.c` patch_cursor_speed), Copyright (c) 2026 MacNativeGames contributors | MIT | `recomp/patches-v121.txt`, `recomp/patches-v110.txt` (set cursor) |
| MacNativeGames TotK aspect ratio: the camera and viewport sites that hand the perspective projection its aspect ratio, and the UI layout edits for a canvas wider than 16:9 | https://github.com/ly05010419/MacNativeGames @ `933b6a0d1438de160208a0a13eb5e8d7a2cb8094` (`games/totk/runtime/aspect_patch.h`, `aspect_math.h`, `game_patches_v143.c`, `games/totk/scripts/ultrawide_layout.py`), Copyright (c) 2026 MacNativeGames contributors | MIT | `recomp/patches-v110.txt`, `recomp/patches-v143.txt` (set aspect), `tools/ultrawide_layout.py`, `tools/make_romfs_patches.py` (--aspect) |
| MacNativeGames TotK button icons: the Xbox controller's shoulder buttons, triggers, Menu, View and d-pad drawn with letters from the game's own text fonts, the .bfotf key, the button guide's images and their block-linear layout, the resource size table raised for the archives that grew | https://github.com/ly05010419/MacNativeGames @ `933b6a0d1438de160208a0a13eb5e8d7a2cb8094` (`games/totk/scripts/make_button_icons.py`), Copyright (c) 2026 MacNativeGames contributors | MIT | `tools/button_icons.py`, `tools/make_romfs_patches.py` (--prompts) |
| RenoDX TotK mod (game mod by souperman9, tonemapper by Musa, RenoDX framework by ShortFuse, RenoVK fork by Ritsu): the approach of the HDR tonemap (the game's 1 - e^-x curve kept below a pivot and continued along its tangent above it, the saturation grade applied to the colour scaled into 0..1) and the observation that the passes after the tonemap keep values above 1. No code copied; the shader is our own | https://github.com/clshortfuse/renodx @ `b6f87272ad1bfdc0e6444910a93606815944a085` (`src/games/totk/tonemap.slang`, `addon.cpp`), Copyright (c) 2025 Carlos Lopez Jr. | MIT | `runtime/shaders/hdr_tonemap.frag`, `runtime/vk_hdr.c` |
| TOTK-Ultrawide, the community mod for emulators: the list of UI panes the ultrawide layout edits and the distances they move (data only, no code copied; the edit code is our own, and MacNativeGames' `ultrawide_layout.py` in the row above already carries the same values). The mod's repository URL and licence version are not recorded in this repository | TOTK-Ultrawide (community mod; URL not recorded here) | GPL (version not recorded here) | `tools/ultrawide_layout.py` (`KEEP_ROOT`, `edits`, `anim_edits`) |
@@ -42,6 +42,8 @@ Code copied or adapted from another project is listed here with its source, the
| Zstandard 1.5.7 (MSYS2 `mingw-w64-ucrt-x86_64-zstd`), static link | https://github.com/facebook/zstd, Copyright (c) Meta Platforms, Inc. and affiliates | BSD-3-Clause | `runtime/resolution.c` (the HeapDef table), `runtime/ov_zstd.c` (the game's zstd frames decoded on the host) |
| musl `fma.c`, `fmaf.c` and `scalbn.c`, adapted into one file for the x86-64-v2 build | https://github.com/kraj/musl @ `5a56ad13e1e0790c06122978aad2a14d6b9efc1a` (mirror of https://git.musl-libc.org/cgit/musl), Copyright (c) 2005-2020 Rich Felker and contributors | MIT | `runtime/fma.c` (the correctly rounded fma/fmaf the FP lowering needs on CPUs without FMA3) |
| MacNativeGames texture pool offset fix: widen the 32-bit texture storage and packaged-data offsets unsigned | https://github.com/ly05010419/MacNativeGames @ `ca311e2d` (`games/totk/runtime/game_patches.c` patch_pool_offset), Copyright (c) 2026 MacNativeGames contributors | MIT | `recomp/patches-v110.txt` (set pooloff; sites located again in 1.1.0) |
## Compiler runtime in a source build
A build with the MSYS2 UCRT64 toolchain of `docs/building.md` links these into `totk.exe`. The installer release builds with llvm-mingw instead (its row below).
+41
View File
@@ -0,0 +1,41 @@
# Game 1.1.0 patch coverage
The built-in table is [recomp/patches-v110.txt](../recomp/patches-v110.txt). These sites were located in the local 1.1.0 main and checked against its original instruction words, rather than applying a version-wide address shift. The generator rejects a different word or an invalid spin back-edge.
## Added coverage
| Set | Sites added | Runtime control |
| --- | ---: | --- |
| realtime | 1 | Equipment-switch cooldown: step every positive remainder, including values below FLT_EPSILON. Follows the existing real-time clock switch. |
| cursor | 3 | Scale map panning, vertical ability aim and vertical gyro aim by the 30 Hz ratio; follows `TOTK_HIGHFPS_FIX`. |
| aspect | 4 | The two camera and two viewport projections read page +56. The resolution code enables it for non-16:9 output. |
| fov | 2 | The two camera projections multiply their vertical angle by page +60. The field-of-view setting is live; 100 leaves the original path. |
| pooloff | 2 | Widen texture-pool offsets unsigned, covering 2..4 GiB without changing offsets below 2 GiB. Enabled by default; `TOTK_POOL_OFFSET_PATCH=0` retains the original path. |
| shadow | 1 | The sun shadow map takes its fixed size from page +92 before rounding. The shadow-resolution setting enables it; `shadow_res=game` leaves the game's sizing. |
| cascade | 4 | Read the four sun shadow cascade defaults from page +64..76. Shadow range 100 leaves the original constructor. |
The table has 12 sets and 50 instruction sites in total. Its existing 889 spin back-edges are unchanged. The new sets use the existing runtime page and settings; no new setting, allocator or renderer path is introduced.
The camera sites were cross-checked by normalized instruction-window matching from the local 1.0.0 main. The viewport routine has two matching copies: both are patched. Other sites were checked through their data flow: the equipment timer and its gate, the map clock, the ability clock, the NVN texture storage/package calls, the shadow size publication and the cascade parameter constructor. FOV's s8 is overwritten by the next original instruction; x10 is saved. The cursor sites use the same scratch registers as their 1.2.1 counterparts.
## Deliberately separate
- Direct mouse: 1.1.0 continues to use stick emulation. Porting the complete camera hook set also needs the runtime layout and load-site table; matching an individual store or one camera mode is not sufficient. No partial set is enabled here.
- Fade: the four 1.4.3 sites are not presumed to exist in 1.1.0. An equivalent zero-increment path has not been established.
- Native Zstandard: the existing host bridge calls back to hard-coded 1.4.3 decoder entry points on fallback. Adding only the BL patches to 1.1.0 would be incorrect.
- Live DLSS scene sizing and game-menu mouse input retain their existing version restrictions. They are not patch-table parity work.
## Validation
Run with Python's numpy, lz4, capstone and unicorn dependencies and a runtime-supported Clang:
```sh
# CC selects the Clang used by the differential harness.
python tests/patches_v110_check.py
python tests/patches_v110_check.py --cflags=-march=x86-64-v2
python tests/patches_v110_check.py --exefs <local ExeFS directory>
```
Without ExeFS, the test uses synthetic memory and the patch table only. It compares the complete integer/SIMD register state, SP and NZCV of the lifted C and Unicorn for all 17 additions, on and off, at 30/60/120 Hz, including pool offsets immediately below and above 2 GiB and at the end of the 32-bit range. Windows test mappings respect its 64 KiB allocation granularity. With ExeFS it additionally validates every original word and spin target. Extracted images and generated C are local build artifacts, never repository content.
These checks establish instruction and code-generation contracts. World-scene visual acceptance, texture packs allocating a pool above 2 GiB, physical gyro and comparisons of shadow quality still require gameplay checks.
+153
View File
@@ -0,0 +1,153 @@
"""Check the v110 patch contracts without game data; optionally check every site and spin against local ExeFS.
python tests/patches_v110_check.py --exefs <local ExeFS> [--cflags=-march=x86-64-v2]
Uses the differential harness, Clang (CC) and Unicorn. Extracted bytes and generated C stay in build/.
"""
import argparse
import math
import struct
import sys
import tempfile
from pathlib import Path
ROOT = Path(__file__).resolve().parents[1]
sys.path.insert(0, str(ROOT / 'tests' / 'diff'))
from common import BUF, BUF_SIZE, Emu, build_harness, diff_state, run_harness
import patches
from lifter import Lifter
from layout import layout
from module import Module
# Set, offset, target register, result kind. The patch file owns the instruction words.
SITES = [
('realtime', 0xa20518, 1, 'zero'),
('cursor', 0xf31e80, 0, 'map'),
('cursor', 0x1d55f24, 12, 'aim'),
('cursor', 0x1d556a4, 3, 'gyro'),
*[('aspect', a, 0, 'aspect') for a in (0xcdbf30, 0x1261a64, 0x19c2260, 0x1ed8fa4)],
*[('fov', a, 0, 'fov') for a in (0xcdbef8, 0x1261a2c)],
('pooloff', 0x9b93a8, 2, 'offset'), ('pooloff', 0x9b93c4, 1, 'source'),
('shadow', 0xd0760c, 11, 'shadow'),
*[('cascade', a, 8, 'cascade') for a in (0x1157fb8, 0x1158040, 0x11580c8, 0x115814c)],
]
def f32(v):
return struct.unpack('<f', struct.pack('<f', v))[0]
def scalar(v):
return struct.unpack('<f', (v & 0xffffffff).to_bytes(4, 'little'))[0]
def main():
ap = argparse.ArgumentParser(description=__doc__)
ap.add_argument('--exefs', type=Path)
ap.add_argument('--cflags', default='-march=x86-64-v3')
args = ap.parse_args()
mods = layout(args.exefs) if args.exefs else [('main', 0x7000000000, 0x472d000)]
table = patches.load(ROOT / 'recomp' / 'patches-v110.txt', mods)
base = mods[0][1]
if args.exefs:
for name, at, _ in mods:
mod = Module(name, args.exefs / name, at)
patches.check(table, mod, name)
print(f'v110: all {sum(len(s) for s in table.sites.values())} sites and '
f'{sum(len(s) for s in table.spins.values())} spin back-edges match local ExeFS')
by_name = {name: i for i, (name, _, _) in enumerate(table.sets)}
resolved = table.for_module('main', base)
bodies, words = [], []
lift = Lifter(base, 'c')
for name, off, _, _ in SITES:
alternatives = table.sites['main'][off]
assert len(alternatives) == 1 and alternatives[0][0] == by_name[name]
orig = alternatives[0][2]
repl = resolved[base + off][0][1]
original = lift.lift(orig, base + off)
replacement = [lift.lift(w, base + off) for w in repl]
assert original.kind == 'op' and all(i.kind == 'op' for i in replacement)
bodies.append('if (c->x[30]) { ' + ' '.join(i.code for i in replacement) +
' } else { ' + original.code + ' }')
words.append((orig, repl))
build = ROOT / 'build'
build.mkdir(exist_ok=True)
groups = {ratio: ([], []) for ratio in (1.0, 0.5, 0.25)}
page = bytearray(0x1000)
# Distinct fields reveal an accidental load from the neighboring page slot.
for off, value in ((0, 0.5), (4, 1 / 60), (56, 21 / 9), (60, 1.2),
(64, 25), (68, 50), (72, 100), (76, 200)):
struct.pack_into('<f', page, off, value)
struct.pack_into('<I', page, 92, 2048)
initial = bytearray(BUF_SIZE)
for off, value in ((0, 3), (4, 5), (8, 0.5), (0x13c, 0.9), (0x140, 16 / 9)):
struct.pack_into('<f', initial, 0x2000 + off, value)
struct.pack_into('<Q', initial, 0x2000, BUF + 0x3000)
struct.pack_into('<f', initial, 0x3008, 0.5)
with tempfile.TemporaryDirectory(prefix='patch-v110-', dir=build) as temp:
work = Path(temp)
exe = build_harness(work, bodies, 2, args.cflags)
for k, (name, off, target, kind) in enumerate(SITES):
pc = base + off
for enabled in (0, 1):
for ratio in (1.0, 0.5, 0.25):
for offset in (0, 0x7fffffff, 0x80000000, 0xffffffff):
mem = bytearray(initial)
struct.pack_into('<f', mem, 0x2008, ratio)
struct.pack_into('<f', mem, 0x3008, ratio)
code = words[k][1] if enabled else [words[k][0]]
lo = pc & ~0xffff
text = bytearray((pc - lo) + len(code) * 4)
struct.pack_into('<' + 'I' * len(code), text, pc - lo, *code)
emu = Emu([(lo, text), (table.page, page)])
emu.mu.mem_write(BUF, bytes(mem))
x = [BUF + 0x2000] * 31
x[8] = BUF + 0x2000
x[25], x[30] = offset, enabled
v = [int.from_bytes(struct.pack('<f', 2.0), 'little')] * 32
v[1] = int.from_bytes(struct.pack('<f', 4.0), 'little')
v[9] = int.from_bytes(struct.pack('<f', 3.0), 'little')
v[10] = int.from_bytes(struct.pack('<f', 4.0), 'little')
v[12] = int.from_bytes(struct.pack('<f', 8.0), 'little')
sp, nzcv = BUF + BUF_SIZE - 0x100, 0xa0000000
ex, esp, enz, epc, ev = emu.run(pc, 0, x, sp, nzcv, v, count=len(code))
assert esp == sp and enz == nzcv
if enabled:
want = {'zero': 0, 'map': 2 * ratio, 'aim': 2 * ratio, 'gyro': 6 * ratio,
'aspect': f32(21 / 9), 'fov': f32(f32(0.9) * f32(1.2))}
if kind in want:
assert math.isclose(scalar(ev[target]), want[kind], rel_tol=1e-6, abs_tol=1e-7), (kind, off)
elif kind == 'offset':
assert ex[target] == offset
elif kind == 'source':
assert ex[target] == x[8] + offset
elif kind == 'shadow':
assert ex[target] == 2055
elif kind == 'cascade':
slot = (64, 68, 72, 76)[(0x1157fb8, 0x1158040, 0x11580c8, 0x115814c).index(off)]
assert ex[target] == struct.unpack_from('<I', page, slot)[0]
# The stack save must preserve the complete x10, not just its lower word.
if name in ('aspect', 'fov'):
assert ex[10] == x[10]
cases, expect = groups[ratio]
cases.append((k, 0, x, sp, nzcv, v, False))
expect.append((ex, esp, enz, epc, ev, 0))
page_path = work / 'page.bin'
page_base = table.page & ~0xffff # Windows reserves at 64 KiB allocation granularity
page_path.write_bytes(bytes(table.page - page_base) + page)
total = 0
for ratio, (cases, expect) in groups.items():
mem = bytearray(initial)
struct.pack_into('<f', mem, 0x2008, ratio)
struct.pack_into('<f', mem, 0x3008, ratio)
records, err = run_harness(exe, work, mem, cases, [(page_base, page_path)])
assert not err and len(records) == len(cases), err
for case, want, got in zip(cases, expect, records):
differences = diff_state(got, want, False, False)
assert not differences, (SITES[case[0]], differences)
total += len(cases)
print(f'v110: {len(SITES)} patch contracts, {total} native/Unicorn cases passed (on and off)')
return 0
if __name__ == '__main__':
sys.exit(main())
+1 -1
View File
@@ -175,7 +175,7 @@
# does. Read when a movie starts, so a change takes effect at the next movie.
# movie_aspect = keep
# Field of view, in percent of the game's own: 70 to 140, 100 (the default) leaves the camera as it is. Higher shows
# more of the world around Link. Game version 1.4.3 only. Changes while the game runs take effect at once.
# more of the world around Link. Game versions 1.1.0 and 1.4.3. Changes while the game runs take effect at once.
# fov = 100
# Anisotropic filtering of surface textures: game (the level the game asks for, as on the Switch) or 2, 4, 8, 16. Keeps
# ground, roads and walls seen at a shallow angle sharp into the distance. Only filtered, mipmapped textures that tile