tools/exefs_plugins.py runs a plugin's init twice and checks the record (#845)

Two service runs with other GetSystemTick values, the words that differ between them listed with what they point
into, and a check that refuses a plugin with a reason per broken rule: a refused run, svcs, GetInfo ids or imports
outside the reviewed lists, writes outside main's .text, and writes that are none of exlaunch's inline hooks
(b to a stur/bl impl/ldur/b/.quad stub whose trampoline is the original relocated plus b site+4), call-site rewrites
(bl to a function start of the plugin's lift) or replace hooks (b from a main function start, Orig trampoline found).
tests/exefs_plugins_test.py covers the layout with and without plugins and one bad record per rule.

After the design in #845 by itaskaev2.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Valiantsin DzerakhandClaude Opus 5.5 committed 2026-11-17 08:05:19 +03:00
1 parent b488d9e41d
commit b2b85c05fa
3 files changed
+641

No files matched your search

+282
View File
@@ -0,0 +1,282 @@
"""recomp/layout.py with and without mod plugins, and tools/exefs_plugins.py's check of a plugin service run record:
a synthetic exlaunch-shaped record with one inline hook that passes, and one bad record per rule. No game files.
Run with .venv (lz4 and numpy, as recomp/): python tests/exefs_plugins_test.py
"""
import json
import struct
import sys
import tempfile
import unittest
from pathlib import Path
ROOT = Path(__file__).resolve().parent.parent
sys.path.insert(0, str(ROOT / 'tools'))
sys.path.insert(0, str(ROOT / 'recomp'))
import exefs_plugins as xp # noqa: E402
import layout # noqa: E402
from nso import Nso # noqa: E402
def nso(size_text, bss=0x1000):
"""An uncompressed NSO: .text of size_text bytes (b over MOD0's offset word), .rodata with MOD0 at 0x1000 past
.text, .data with an empty .dynamic."""
text = bytearray(size_text)
struct.pack_into('<II', text, 0, 0x14000002, size_text) # b +8; the MOD0 offset
ro = b'MOD0' + struct.pack('<6i', 0x1000, 0, 0, 0, 0, 0) # .dynamic at .rodata + 0x1000 = .data
data = bytes(16) # DT_NULL
segs = [(0, bytes(text)), (size_text, ro), (size_text + 0x1000, data)]
hdr = bytearray(0x100)
hdr[0:4] = b'NSO0'
off = 0x100
for i, (mem, d) in enumerate(segs):
struct.pack_into('<IIII', hdr, 0x10 + 0x10 * i, off, mem, len(d), bss if i == 2 else 0)
struct.pack_into('<I', hdr, 0x60 + 4 * i, len(d))
off += len(d)
return bytes(hdr) + b''.join(d for _, d in segs)
def dev_layout_files(exefs, out):
"""layout.json and layout.h as recomp/layout.py wrote them before plugins (dev f8505807), the reference for the
no-plugin case."""
out.mkdir(parents=True, exist_ok=True)
mods, base = [], layout.FIRST_BASE
for name in layout.ORDER:
if (exefs / name).exists():
size = Nso(str(exefs / name)).size
mods.append((name, base, size))
base = layout.align_up(base + size)
(out / 'layout.json').write_text(json.dumps(
[{'name': n, 'base': f'{b:#x}', 'size': f'{s:#x}'} for n, b, s in mods], indent=1) + '\n')
lines = ['// Module layout chosen by recomp/layout.py. Generated; do not edit.', '#pragma once', '']
for n, b, s in mods:
lines.append(f'#define MOD_{n.upper()}_BASE {b:#x}ull')
lines.append(f'#define MOD_{n.upper()}_SIZE {s:#x}ull')
lines += ['', f'#define MOD_COUNT {len(mods)}',
'#define MOD_LIST(X) ' + ' '.join(f'X({n}, {n.upper()})' for n, _, _ in mods), '']
(out / 'layout.h').write_text('\n'.join(lines))
class Layout(unittest.TestCase):
@classmethod
def setUpClass(cls):
cls.tmp = tempfile.TemporaryDirectory()
cls.dir = Path(cls.tmp.name)
cls.exefs = cls.dir / 'exefs'
cls.exefs.mkdir()
for name, size in (('main', 0x30000), ('subsdk0', 0x5000), ('sdk', 0x21000)):
(cls.exefs / name).write_bytes(nso(size))
cls.plugins = [cls.dir / 'mod a' / 'subsdk9', cls.dir / 'mod b' / 'subsdk8']
for p, size in zip(cls.plugins, (0x9000, 0x3000)):
p.parent.mkdir()
p.write_bytes(nso(size))
@classmethod
def tearDownClass(cls):
cls.tmp.cleanup()
def test_no_plugins_identical(self):
dev, ours = self.dir / 'dev', self.dir / 'ours'
dev_layout_files(self.exefs, dev)
layout.write(layout.layout(self.exefs), ours, layout.plugin_files([]))
for f in ('layout.json', 'layout.h'):
self.assertEqual((dev / f).read_bytes(), (ours / f).read_bytes(), f)
def test_plugins_after_sdk(self):
plain = layout.layout(self.exefs)
mods = layout.layout(self.exefs, self.plugins)
self.assertEqual(mods[:3], plain) # the game modules keep their bases
self.assertEqual([n for n, _, _ in mods], ['main', 'subsdk0', 'sdk', 'plugin0', 'plugin1'])
for (_, b0, s0), (_, b1, _) in zip(mods, mods[1:]):
self.assertEqual(b1, layout.align_up(b0 + s0))
self.assertEqual(mods[3][2], Nso(str(self.plugins[0])).size)
out = self.dir / 'with'
files = layout.plugin_files(self.plugins)
layout.write(mods, out, files)
data = json.loads((out / 'layout.json').read_text())
self.assertNotIn('file', data[2])
self.assertEqual(data[3]['file'], self.plugins[0].resolve().as_posix())
self.assertEqual(len(data[3]['sha256']), 64)
self.assertEqual(layout.read(out), mods)
self.assertIn('#define MOD_PLUGIN1_BASE', (out / 'layout.h').read_text())
self.assertIn('#define MOD_COUNT 5', (out / 'layout.h').read_text())
def test_address_limit(self):
old = layout.FIRST_BASE
layout.FIRST_BASE = layout.ADDRESS_LIMIT - 0x400000 # the plugins end above 2^39
try:
with self.assertRaises(ValueError):
layout.layout(self.exefs, self.plugins)
finally:
layout.FIRST_BASE = old
# ---- records
MAIN, PLUGIN = 0x7000000000, 0x7005200000
SITE_OFF, STUB_OFF, TRAMP_OFF, CB_OFF, IMPL_OFF, THUNK_OFF = 0x1000, 0x4000, 0x2000, 0x66f0, 0x73ec, 0xf00
MAIN_TEXT, PLUGIN_TEXT = 0x100000, 0x9000
def b(src, dst, link=False):
return (0x94000000 if link else 0x14000000) | ((dst - src) >> 2) & 0x3FFFFFF
def record(original=0x94000010, trampoline_first=None, stub=None, writes=None, **extra):
"""A record of one inline hook at main+SITE_OFF whose original is `original` (default bl main+SITE_OFF+0x40)."""
site, stub_at, tramp = MAIN + SITE_OFF, PLUGIN + STUB_OFF, PLUGIN + TRAMP_OFF
img = bytearray(0x14000)
words = stub or [xp.STUR_X30, b(stub_at + 4, PLUGIN + IMPL_OFF, True), xp.LDUR_X30, b(stub_at + 12, tramp)]
struct.pack_into('<4IQ', img, STUB_OFF, *words, PLUGIN + CB_OFF)
if trampoline_first is None:
rel = xp.pc_relative(original, site)
trampoline_first = (b(tramp, rel[1], True) if rel and rel[0][0] == 'b' else original)
struct.pack_into('<II', img, TRAMP_OFF, trampoline_first, b(tramp + 4, site + 4))
rec = {
'refused': None, 'svcs': {'0x6': 52, '0x1e': 10, '0x27': 18, '0x29': 17, '0x74': 11, '0x75': 7},
'get_info': {'2': 1, '3': 1, '12': 1, '13': 1, '65001': 1},
'imports': {'_ZN2nn4util8SNPrintfEPcmPKcz': 20, '_ZN2nn2oe17GetDisplayVersionEPNS0_14DisplayVersionE': 1},
'modules': [
{'name': 'main', 'base': MAIN, 'size': 0x200000, 'text_end': MAIN_TEXT, 'data_off': 0x180000, 'init': 0,
'plugin': False},
{'name': 'sdk', 'base': 0x7004400000, 'size': 0x100000, 'text_end': 0x80000, 'data_off': 0xc0000,
'init': 0, 'plugin': False},
{'name': 'plugin0', 'base': PLUGIN, 'size': 0x14000, 'text_end': PLUGIN_TEXT, 'data_off': 0xd000,
'init': PLUGIN + 0x50a0, 'plugin': True, 'functions': [hex(CB_OFF), hex(IMPL_OFF), hex(THUNK_OFF)]}],
'writes': writes if writes is not None else [
{'module': 'main', 'offset': SITE_OFF, 'old': original, 'new': b(site, stub_at)}],
'aliases': [], 'images': {'plugin0': bytes(img)}}
rec.update(extra)
return rec
IMPLS = {PLUGIN + IMPL_OFF: 'exl_inline_hook_impl'}
class Check(unittest.TestCase):
def reasons(self, rec):
return xp.check_record(rec, IMPLS)[1]
def refused(self, rec, text):
r = self.reasons(rec)
self.assertTrue(r, 'accepted')
self.assertTrue(any(text in x for x in r), r)
def test_good(self):
hooks, reasons = xp.check_record(record(), IMPLS)
self.assertEqual(reasons, [])
self.assertEqual(len(hooks), 1)
self.assertEqual(hooks[0]['callback'], f'plugin0+{CB_OFF:#x}')
self.assertEqual(hooks[0]['trampoline'], f'plugin0+{TRAMP_OFF:#x}')
def test_good_plain_original(self):
self.assertEqual(self.reasons(record(original=0xAA0003F3)), []) # mov x19, x0, copied as it is
def test_call_site_rewrite(self): # Quick Weapon Durability: bl straight to a thunk of the plugin
site = MAIN + SITE_OFF
w = [{'module': 'main', 'offset': SITE_OFF, 'old': 0x94000010, 'new': b(site, PLUGIN + THUNK_OFF, True)}]
hooks, reasons = xp.check_record(record(writes=w), IMPLS)
self.assertEqual(reasons, [])
self.assertEqual(hooks[0]['kind'], 'call')
self.assertEqual(hooks[0]['target'], f'plugin0+{THUNK_OFF:#x}')
def test_replace_hook(self): # Full Inventory Expansion: b from a main function start, Orig trampoline in the pool
site, prologue = MAIN + SITE_OFF, 0xA9BA7BFD # stp x29, x30, [sp, #-0x60]!
w = [{'module': 'main', 'offset': SITE_OFF, 'old': prologue, 'new': b(site, PLUGIN + THUNK_OFF),
'fn_start': True}]
hooks, reasons = xp.check_record(record(original=prologue, writes=w), IMPLS)
self.assertEqual(reasons, [])
self.assertEqual(hooks[0]['kind'], 'replace')
self.assertEqual(hooks[0]['trampoline'], f'plugin0+{TRAMP_OFF:#x}')
def test_replace_inside_function(self):
w = [{'module': 'main', 'offset': SITE_OFF, 'old': 0x94000010, 'new': b(MAIN + SITE_OFF, PLUGIN + THUNK_OFF),
'fn_start': False}]
self.refused(record(writes=w), 'from inside a main function')
def test_call_into_function_middle(self):
w = [{'module': 'main', 'offset': SITE_OFF, 'old': 0x94000010, 'new': b(MAIN + SITE_OFF, PLUGIN + 0xf08, True)}]
self.refused(record(writes=w), 'neither an inline-hook stub nor a function start')
def test_bl_to_stub(self): # an inline stub is entered by b; a bl there would skip the saved x30
w = [{'module': 'main', 'offset': SITE_OFF, 'old': 0x94000010, 'new': b(MAIN + SITE_OFF, PLUGIN + STUB_OFF, True)}]
self.refused(record(writes=w), 'neither an inline-hook stub nor a function start')
def test_refused_run(self):
self.refused(record(refused='svc 0x40 at plugin0+0x76a0'), 'the run was refused')
def test_svc(self):
self.refused(record(svcs={'0x6': 1, '0x40': 1}), 'svc 0x40')
def test_get_info(self):
self.refused(record(get_info={'2': 1, '18': 1}), 'GetInfo id 18')
def test_import(self):
self.refused(record(imports={'_ZN2nn2fs8MountRomEPKcPvm': 1}), 'the import _ZN2nn2fs8MountRom')
def test_write_main_data(self):
w = [{'module': 'main', 'offset': 0x180008, 'old': 0, 'new': 1}]
self.refused(record(writes=w), "outside main's .text: main+0x180008")
def test_write_other_module(self):
w = [{'module': 'sdk', 'offset': 0x100, 'old': 0, 'new': 1}]
self.refused(record(writes=w), "outside main's .text: sdk+0x100")
def test_not_a_branch(self):
w = [{'module': 'main', 'offset': SITE_OFF, 'old': 0x94000010, 'new': 0xD503201F}]
self.refused(record(writes=w), 'is no b')
def test_branch_elsewhere(self):
w = [{'module': 'main', 'offset': SITE_OFF, 'old': 0x94000010, 'new': b(MAIN + SITE_OFF, MAIN + 0x8000)}]
self.refused(record(writes=w), "does not reach into a plugin's .text")
def test_stub_shape(self):
stub_at = PLUGIN + STUB_OFF
words = [0xD503201F, b(stub_at + 4, PLUGIN + IMPL_OFF, True), xp.LDUR_X30, b(stub_at + 12, PLUGIN + TRAMP_OFF)]
self.refused(record(stub=words), 'neither an inline-hook stub nor a function start')
def test_stub_impl(self):
stub_at = PLUGIN + STUB_OFF
words = [xp.STUR_X30, b(stub_at + 4, PLUGIN + 0x100, True), xp.LDUR_X30, b(stub_at + 12, PLUGIN + TRAMP_OFF)]
self.refused(record(stub=words), 'not exl_inline_hook_impl')
def test_callback_outside(self):
rec = record()
img = bytearray(rec['images']['plugin0'])
struct.pack_into('<Q', img, STUB_OFF + 16, MAIN + 0x500)
rec['images']['plugin0'] = bytes(img)
self.refused(rec, "callback 0x7000000500 is outside plugin0's .text")
def test_trampoline_not_original(self):
self.refused(record(original=0xAA0003F3, trampoline_first=0xAA0003F4), 'not the original')
def test_trampoline_bl_elsewhere(self):
tramp = PLUGIN + TRAMP_OFF
self.refused(record(trampoline_first=b(tramp, MAIN + SITE_OFF + 0x44, True)), 'not the original')
def test_trampoline_return(self):
rec = record()
img = bytearray(rec['images']['plugin0'])
struct.pack_into('<I', img, TRAMP_OFF + 4, b(PLUGIN + TRAMP_OFF + 4, MAIN + SITE_OFF + 8))
rec['images']['plugin0'] = bytes(img)
self.refused(rec, 'no b to the site + 4')
def test_indirect_original(self):
self.refused(record(original=0xD65F03C0), 'is a br, blr or ret')
class Diff(unittest.TestCase):
def test_lists_differing_words(self):
a, c = record(), record()
img = bytearray(c['images']['plugin0'])
struct.pack_into('<Q', img, 0x13450, 0x2345000000)
c['images']['plugin0'] = bytes(img)
a['pool'] = c['pool'] = {'base': '0x2000000000', 'size': '0x1000000000'}
lines = xp.diff_records(a, c)
self.assertEqual(len(lines), 1)
self.assertIn('plugin0+0x13450', lines[0])
self.assertIn('alias pool', lines[0])
self.assertEqual(xp.diff_records(a, record()), [])
if __name__ == '__main__':
unittest.main()
+1
View File
@@ -55,6 +55,7 @@ TESTS = {
'ncz_test': ('.venv-py314', None, [], ''),
'romfs_prompts_test': ('.venv-py314', None, [], ''),
'exefs_patches_test': ('.venv', None, [], ''),
'exefs_plugins_test': ('.venv', None, [], ''),
'settings_doc_check': ('.venv', None, [], ''),
'mouse_direct_check': ('.venv', 'cc', ['--cc', '<cc>'], 'compiles its checks with clang'),
'cheats_vm_check': ('.venv', 'cc', ['--cc', '<cc>'], 'compiles runtime/cheats.c into a harness with clang'),
+358
View File
@@ -0,0 +1,358 @@
"""Run a mod plugin's init in the plugin service run and check what it did: the build step before the generator emits
a plugin's hook sites. After the design in #845 by itaskaev2; the init runs on this port's runtime (totk.exe
--plugin-init, runtime/plugin_init.c) instead of under Unicorn.
python tools/exefs_plugins.py --exe build/<ver>-x/totk.exe --out <dir> # two runs, their diff, the check
python tools/exefs_plugins.py --check <dir>/run1 # the check of one record
The exe must be built with the plugin in its layout (recomp/gen.py --plugins). --out gets run1/ and run2/, one record
each; run2 adds a large offset to every GetSystemTick (TOTK_PLUGIN_TICK_OFFSET), so the init picks other alias
addresses. The words that differ between the two records are listed with what they look like, not refused: an init
keeps its alias addresses and the regions GetInfo gave it in its .data, and a plugin's callbacks must not use them
(the generator's check of the code the callbacks reach, still to come).
The check (check_record) accepts a record only when every rule holds; each broken rule is one reason:
- the run was not refused (an svc outside the served set, such as CreateSession of exlaunch's process-handle
fallback, ends the run with the reason);
- the init called only the svcs ALLOWED_SVCS, GetInfo with ALLOWED_INFO, and the imports ALLOWED_IMPORTS;
- every write into a game module is a word of main's .text whose original is no br, blr or ret, and it is one of:
- an inline hook (MSFix, Full Inventory Expansion): `b <stub>` into a plugin's .text, the stub in exlaunch's
shape (stur x30, [sp, #-0x10]; bl exl_inline_hook_impl or the float one; ldur x30, [sp, #-0x10];
b <trampoline>; .quad <callback in the plugin's .text>), the trampoline the site's original relocated (the
same word, or the same PC-relative target) and `b <site + 4>`;
- a call-site rewrite (Quick Weapon Durability): `bl` straight to a function start of the plugin's lift (the
record lists them), which the generator can emit as a patch site whose replacement is that branch;
- a replace hook (Full Inventory Expansion's Sort Fixer): `b` from a function start of main to a function start of
the plugin's lift; the Orig trampoline (the original relocated, b site+4) is listed when the pool holds one.
Not checked here yet: a site shared with a built-in patch set or another mod, and svcs in the code the callbacks
reach (both need the generator's view).
"""
import argparse
import json
import os
import struct
import subprocess
import sys
from pathlib import Path
sys.path.insert(0, str(Path(__file__).resolve().parents[1] / 'recomp'))
from nso import Nso # noqa: E402
ALLOWED_SVCS = {0x06: 'QueryMemory', 0x1E: 'GetSystemTick', 0x27: 'OutputDebugString', 0x29: 'GetInfo',
0x74: 'MapProcessMemory', 0x75: 'UnmapProcessMemory'}
ALLOWED_INFO = {2, 3, 4, 5, 12, 13, 14, 15, 65001}
# Reviewed one by one: SNPrintf formats into the caller's buffer; GetDisplayVersion is answered by the service run;
# mersenne_twister_engine<uint64_t, ...>::_M_gen_rand (Full Inventory Expansion's alias picker) refills the state of the
# engine object it is given, which lives in the plugin's .bss; memcmp and strlen only read. malloc stays out: Quick
# Weapon Durability's init keeps a heap block's address in its .bss, and that block does not exist at play time.
ALLOWED_IMPORTS = {'_ZN2nn4util8SNPrintfEPcmPKcz', '_ZN2nn2oe17GetDisplayVersionEPNS0_14DisplayVersionE', 'memcmp', 'strlen',
'_ZNSt23mersenne_twister_engineImLm64ELm312ELm156ELm31ELm13043109905998158313ELm29ELm6148914691236517205'
'ELm17ELm8202884508482404352ELm37ELm18444473444759240704ELm43ELm6364136223846793005EE11_M_gen_randEv'}
HOOK_IMPLS = ('exl_inline_hook_impl', 'exl_inline_float_hook_impl')
STUR_X30 = 0xF81F03FE # stur x30, [sp, #-0x10]
LDUR_X30 = 0xF85F03FE # ldur x30, [sp, #-0x10]
STUB_WORDS = 6 # 4 instructions and the callback's .quad
TICK_OFFSET = 0x0123456789AB
def u(v):
return int(v, 16) if isinstance(v, str) else v
# ---- instructions
def sext(v, bits):
return v - (1 << bits) if v >> (bits - 1) & 1 else v
def branch_target(w, pc):
"""Target of b / bl at pc, else None."""
if w & 0x7C000000 == 0x14000000:
return pc + sext(w & 0x3FFFFFF, 26) * 4
return None
def pc_relative(w, pc):
"""(kind, absolute value) of a PC-relative instruction at pc, else None: b, bl, b.cond, cbz/cbnz, tbz/tbnz, adr,
adrp, ldr (literal). The kind holds the bits besides the offset, so two encodings match when both agree."""
if w & 0x7C000000 == 0x14000000:
return ('b', w & 0xFC000000), pc + sext(w & 0x3FFFFFF, 26) * 4
if w & 0xFF000010 == 0x54000000:
return ('b.cond', w & 0xFF00001F), pc + sext(w >> 5 & 0x7FFFF, 19) * 4
if w & 0x7E000000 == 0x34000000:
return ('cbz', w & 0xFF00001F), pc + sext(w >> 5 & 0x7FFFF, 19) * 4
if w & 0x7E000000 == 0x36000000:
return ('tbz', w & 0xFFF8001F), pc + sext(w >> 5 & 0x3FFF, 14) * 4
if w & 0x9F000000 == 0x10000000:
return ('adr', w & 0x1F), pc + sext((w >> 5 & 0x7FFFF) << 2 | w >> 29 & 3, 21)
if w & 0x9F000000 == 0x90000000:
return ('adrp', w & 0x1F), (pc & ~0xFFF) + (sext((w >> 5 & 0x7FFFF) << 2 | w >> 29 & 3, 21) << 12)
if w & 0x3B000000 == 0x18000000:
return ('ldr', w & 0xFF00001F), pc + sext(w >> 5 & 0x7FFFF, 19) * 4
return None
def is_indirect(w):
"""br, blr, ret (and their pointer-authenticated forms): a site exlaunch could hook but the generator cannot."""
return w & 0xFE1F0000 == 0xD61F0000 and w >> 21 & 0xF in (0, 1, 2)
def relocated(orig, site, word, at):
"""The trampoline word at `at` does what the original at `site` does."""
a, b = pc_relative(orig, site), pc_relative(word, at)
if a is None:
return word == orig
return b is not None and a == b
def inline_stub(img, o, p):
"""The words at image offset o of plugin p have exlaunch's inline-hook entry shape: stur x30; bl; ldur x30; b;
and the .quad after them lies inside the plugin's .text."""
if o + 4 * STUB_WORDS > p['text_end']:
return False
s = struct.unpack_from('<4I', img, o)
return s[0] == STUR_X30 and s[2] == LDUR_X30 and s[1] >> 26 == 0x25 and s[3] >> 26 == 0x05
def orig_trampoline(img, p, original, site):
"""Image offset of a pair in the plugin's .text that runs the site's original instruction relocated, then b site+4
(exlaunch's Orig trampoline of a replace hook), else None."""
base = p['base']
for o in range(0, p['text_end'] - 4, 4):
t1 = struct.unpack_from('<I', img, o + 4)[0]
if t1 >> 26 == 0x05 and branch_target(t1, base + o + 4) == site + 4 and \
relocated(original, site, struct.unpack_from('<I', img, o)[0], base + o):
return o
return None
# ---- records
def load_record(d):
"""record.json of a service run directory, with the images of its plugins as bytes (key 'images')."""
d = Path(d)
rec = json.loads((d / 'record.json').read_text(encoding='utf-8'))
rec['images'] = {}
for m in rec['modules']:
for k in ('base', 'size', 'text_end', 'data_off', 'init'):
m[k] = u(m[k])
if m.get('image'):
rec['images'][m['name']] = (d / m['image']).read_bytes()
for w in rec['writes']:
for k in ('offset', 'old', 'new'):
w[k] = u(w[k])
return rec
def hook_impls(rec):
"""{absolute address: name} of exlaunch's hook entry points in each plugin, from the plugin NSO's exports."""
out = {}
for m in rec['modules']:
if m['plugin'] and m.get('file') and Path(m['file']).is_file():
for name, _, shndx, value, _ in Nso(m['file']).exports():
if name in HOOK_IMPLS:
out[m['base'] + value] = name
return out
def check_record(rec, impls):
"""(hooks, reasons): one dict per hook site, and one line per broken rule (no lines: the record is accepted)."""
reasons, hooks = [], []
if rec.get('refused'):
reasons.append(f'the run was refused: {rec["refused"]}')
for imm in rec.get('svcs', {}):
if u(imm) not in ALLOWED_SVCS:
reasons.append(f'the init called svc {u(imm):#x}')
for i in rec.get('get_info', {}):
if int(i) not in ALLOWED_INFO:
reasons.append(f'the init asked GetInfo id {i}')
for name, calls in rec.get('imports', {}).items():
if calls and name not in ALLOWED_IMPORTS:
reasons.append(f'the init called the import {name}')
mods = {m['name']: m for m in rec['modules']}
plugins = [m for m in rec['modules'] if m['plugin']]
def plugin_word(a):
"""(plugin, word) at absolute a inside a plugin's .text image, else (None, None)."""
for p in plugins:
if p['base'] <= a < p['base'] + p['text_end'] and p['name'] in rec['images']:
return p, struct.unpack_from('<I', rec['images'][p['name']], a - p['base'])[0]
return None, None
main = mods.get('main')
for w in rec['writes']:
where = f'{w["module"]}+{w["offset"]:#x}'
if w['module'] != 'main' or not main or w['offset'] >= main['text_end'] or w['offset'] & 3:
reasons.append(f'a write outside main\'s .text: {where} {w["old"]:#010x} -> {w["new"]:#010x}')
continue
site = main['base'] + w['offset']
stub = branch_target(w['new'], site)
link = bool(w['new'] >> 31)
if stub is None:
reasons.append(f'{where}: the new word {w["new"]:#010x} is no b or bl')
continue
if is_indirect(w['old']):
reasons.append(f'{where}: the original {w["old"]:#010x} is a br, blr or ret')
p, _ = plugin_word(stub)
if p is None:
reasons.append(f"{where}: {'bl' if link else 'b'} {stub:#x} does not reach into a plugin's .text")
continue
if not (not link and inline_stub(rec['images'][p['name']], stub - p['base'], p)):
# A b or bl straight into the plugin's code (CodePatcher-style call-site rewrite): a site whose replacement
# is that branch, when the target is a function start of the plugin's lift.
# A b replaces the whole main function, so it must sit at a function start of main; exlaunch's replace
# hook keeps the function's first instruction relocated + b site+4 in its pool for the callback's Orig.
o = stub - p['base']
hook = {'site': f'main+{w["offset"]:#x}', 'original': f'{w["old"]:#010x}',
'kind': 'call' if link else 'replace', 'target': f'{p["name"]}+{o:#x}'}
orig = orig_trampoline(rec['images'][p['name']], p, w['old'], site)
if orig is not None:
hook['trampoline'] = f'{p["name"]}+{orig:#x}'
hooks.append(hook)
if o not in {u(x) for x in p.get('functions', [])}:
reasons.append(f"{where}: {'bl' if link else 'b'} {p['name']}+{o:#x} is neither an inline-hook stub "
f"nor a function start of {p['name']}'s lift")
if not link and not w.get('fn_start'):
reasons.append(f"{where}: b {p['name']}+{o:#x} from inside a main function (only a function start can "
f"be replaced)")
continue
img, o = rec['images'][p['name']], stub - p['base']
s = struct.unpack_from('<4IQ', img, o)
impl, tramp, cb = branch_target(s[1], stub + 4), branch_target(s[3], stub + 12), s[4]
hook = {'site': f'main+{w["offset"]:#x}', 'original': f'{w["old"]:#010x}', 'kind': 'inline',
'stub': f'{p["name"]}+{o:#x}',
'impl': impls.get(impl, f'{impl:#x}' if impl is not None else None),
'callback': f'{p["name"]}+{cb - p["base"]:#x}' if p['base'] <= cb < p['base'] + p['text_end'] else f'{cb:#x}',
'trampoline': f'{p["name"]}+{tramp - p["base"]:#x}' if tramp is not None else None}
hooks.append(hook)
if impl not in impls:
reasons.append(f'{where}: the stub calls {impl:#x}, not {" or ".join(HOOK_IMPLS)}')
if not p['base'] <= cb < p['base'] + p['text_end']:
reasons.append(f'{where}: the stub\'s callback {cb:#x} is outside {p["name"]}\'s .text')
tp, t0 = plugin_word(tramp)
_, t1 = plugin_word(tramp + 4)
if tp is None or t1 is None:
reasons.append(f'{where}: the trampoline {tramp:#x} is outside a plugin\'s .text')
continue
hook['relocated'] = f'{t0:#010x}'
if not relocated(w['old'], site, t0, tramp):
reasons.append(f'{where}: the trampoline {hook["trampoline"]} starts with {t0:#010x}, not the original '
f'{w["old"]:#010x} relocated')
if branch_target(t1, tramp + 4) != site + 4 or t1 >> 31:
reasons.append(f'{where}: the trampoline\'s second word {t1:#010x} is no b to the site + 4')
return hooks, reasons
# ---- two runs
def where_is(v, rec):
"""What an address-like value points into, for the diff listing."""
for m in rec['modules']:
if m['base'] <= v < m['base'] + m['size']:
return f'{m["name"]}+{v - m["base"]:#x}'
for k in ('rtld', 'pool'):
r = rec.get(k)
if r and u(r['base']) <= v < u(r['base']) + u(r['size']):
return f'the {"alias pool" if k == "pool" else k} (+{v - u(r["base"]):#x})'
for a in rec.get('aliases', []):
if u(a['dst']) <= v < u(a['dst']) + u(a['size']):
return f'an alias of {u(a["src"]):#x}'
return None
def section(m, off, nso_path):
if off < m['text_end']:
return '.text'
if off < m['data_off']:
return '.rodata'
if nso_path and Path(nso_path).is_file():
n = Nso(nso_path)
if off < n.data[0] + n.data[1]:
return '.data'
return '.bss'
return '.data/.bss'
def diff_records(a, b):
"""Lines naming every difference between two records: writes into game modules, plugin image words (8 bytes)."""
out = []
wa = {(w['module'], w['offset']): w for w in a['writes']}
wb = {(w['module'], w['offset']): w for w in b['writes']}
for k in sorted(set(wa) | set(wb)):
x, y = wa.get(k), wb.get(k)
if not x or not y or x['new'] != y['new']:
out.append(f'write {k[0]}+{k[1]:#x}: run 1 {x and hex(x["new"])}, run 2 {y and hex(y["new"])}')
for m in a['modules']:
if not m['plugin']:
continue
ia, ib = a['images'].get(m['name']), b['images'].get(m['name'])
if ia is None or ib is None or len(ia) != len(ib):
out.append(f'{m["name"]}: image missing or of another size')
continue
for off in range(0, len(ia), 8):
if ia[off:off + 8] == ib[off:off + 8]:
continue
va, vb = struct.unpack_from('<Q', ia, off)[0], struct.unpack_from('<Q', ib, off)[0]
what = where_is(va, a) or where_is(vb, b)
out.append(f'{m["name"]}+{off:#x} ({section(m, off, m.get("file"))}): {va:#x} / {vb:#x}'
+ (f', {what}' if what else ''))
return out
def run(exe, out, tick_offset, timeout):
out.mkdir(parents=True, exist_ok=True)
env = dict(os.environ, TOTK_PLUGIN_TICK_OFFSET=f'{tick_offset:#x}', TOTK_BACKGROUND_WINDOW='1',
TOTK_ASSUME_FOCUS='1')
r = subprocess.run([str(exe), '--plugin-init', str(out)], env=env, capture_output=True, text=True,
errors='replace', timeout=timeout)
(out / 'run.log').write_text(r.stdout + r.stderr, encoding='utf-8')
return r.returncode
def report(rec, label):
hooks, reasons = check_record(rec, hook_impls(rec))
print(f'{label}: {len(rec["writes"])} words written into game modules, {len(rec["aliases"])} process-memory maps, '
f'svcs {", ".join(f"{ALLOWED_SVCS.get(u(k), hex(u(k)))} x{v}" for k, v in rec["svcs"].items())}; '
f'GetInfo {", ".join(f"{k} x{v}" for k, v in rec["get_info"].items())}; '
f'imports {", ".join(f"{k} x{v}" for k, v in rec["imports"].items())}')
for h in hooks:
if h['kind'] == 'inline':
print(f' inline hook {h["site"]} (was {h["original"]}) -> stub {h["stub"]} -> {h["impl"]}, callback '
f'{h["callback"]}, trampoline {h["trampoline"]} ({h.get("relocated")}; b site+4)')
else:
print(f' {h["kind"]} {h["site"]} (was {h["original"]}) -> {"bl" if h["kind"] == "call" else "b"} '
f'{h["target"]}' + (f', Orig trampoline {h["trampoline"]}' if h.get('trampoline') else ''))
for r in reasons:
print(f' REFUSED: {r}')
if not reasons:
print(f' accepted: {len(hooks)} hooks')
return reasons
def main():
ap = argparse.ArgumentParser(description=__doc__.splitlines()[0])
ap.add_argument('--exe', type=Path, help='totk.exe built with the plugin in its layout')
ap.add_argument('--out', type=Path, help='directory for run1/ and run2/')
ap.add_argument('--check', type=Path, help='check the record in this directory only')
ap.add_argument('--timeout', type=int, default=300)
args = ap.parse_args()
if args.check:
return 1 if report(load_record(args.check), str(args.check)) else 0
if not args.exe or not args.out:
ap.error('--exe and --out, or --check')
recs = []
for i, offset in enumerate((0, TICK_OFFSET), 1):
d = args.out / f'run{i}'
code = run(args.exe, d, offset, args.timeout)
if not (d / 'record.json').is_file():
print(f'run {i}: no record (exit {code}); see {d / "run.log"}')
return 1
recs.append(load_record(d))
print(f'run {i}: exit {code}, tick offset {offset:#x}')
bad = report(recs[0], 'run 1')
diff = diff_records(*recs)
print(f'run 1 against run 2: {len(diff)} differences' + (':' if diff else ''))
for line in diff:
print(f' {line}')
return 1 if bad else 0
if __name__ == '__main__':
sys.exit(main())