The generator lifts a mod plugin's hook sites: a call into its stub, its replace target and its call-site rewrite (#845)

After the design in #845 by itaskaev2. New patch lines carry an exlaunch plugin whose init runs at every
start: `plugin` lifts the module from its image after the init (the hook stubs and trampolines the file
has as zeros) and names the hash of that .text, `expect` lists the words the init writes into the game,
`stub` lifts an inline-hook stub's branch to its trampoline as a return, `seed` adds the callbacks, impls
and targets, and `orig` lists an unpatched copy of a hooked main function (fo_<address>) at the replace
hook's trampoline address in the plugin's function table, so the plugin's call of the original does not
reach the hook again and rt_dispatch stays as it is.

A replacement word @call:<module>+<offset> calls the stub without writing x30, with every register in
the Cpu before it and read back after it; the site's own instruction runs after it in place. patches.h
gets RT_PLUGINS, RT_PLUGIN_WRITES and RT_PLUGIN_ROOTS for the runtime. Without plugin lines the output is
byte-identical to dev (generated C, patches.h and layout of 1.2.1 and 1.4.3).

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:48:14 +03:00
1 parent b2b85c05fa
commit db6d548ba2
3 files changed
+240 -23

No files matched your search

+97 -15
View File
@@ -68,7 +68,7 @@ import regs # noqa: E402
import vlocals # noqa: E402
from check_content import GENERATED_MARKER # noqa: E402
from layout import layout, plugin_files, write as write_layout # noqa: E402
from lifter import hx # noqa: E402
from lifter import Insn, hx # noqa: E402
from module import Module # noqa: E402
TERMINATORS = ('b', 'br', 'ret', 'trap')
@@ -89,6 +89,30 @@ def fname(a):
return f'f_{a:x}'
def orig_name(a):
"""The unpatched copy of the function at a that a plugin's replace hook reaches as its original (patches.py `orig`)."""
return f'fo_{a:x}'
def open_module(name, path, base, table, plugin=False):
"""Module name for lifting: a plugin with a `plugin` line of the patch table (recomp/patches.py) is lifted from its
image after the init, its inline-hook stubs returning where they would branch to their trampolines."""
p = table.plugins.get(name)
if not p:
return Module(name, path, base, 'c', plugin=plugin)
image = Path(p['image']).read_bytes()
mod = Module(name, path, base, 'c', plugin=True, image=image, rets=[o + 12 for o in p['stubs']],
seeds=sorted(p['stubs'] | p['seeds']))
t0, t1 = mod.nso.text[0], mod.nso.text[0] + mod.nso.text[1]
if hashlib.sha256(image[t0:t1]).hexdigest() != p['sha256']:
raise patches.PatchError(f'{name}: {p["image"]} is not the image whose .text the patch table names')
for o in p['stubs']:
w = int.from_bytes(image[o + 12:o + 16], 'little')
if not mod.in_text(base + o) or w >> 26 != 0x05:
raise patches.PatchError(f'{name}+{o:#x}: no inline-hook stub (its fourth word {w:08x} is no b)')
return mod
def header(what):
return f'// {GENERATED_MARKER}: {what}, generated by recomp/gen.py from game code. Do not edit or commit.\n'
@@ -233,12 +257,13 @@ class Emitter:
the C (an argument here, or anything else it reads) must go into the lift cache's key: chunk_key."""
def __init__(self, mod, starts, patched=None, reg_locals=regs.LOCALS, callee_saved=True, spins=None,
v_locals=vlocals.LOCALS, v_trust=False, hooks=None, fn_enter_all=False, picks=None):
v_locals=vlocals.LOCALS, v_trust=False, hooks=None, fn_enter_all=False, picks=None, origs=None):
self.mod = mod
self.starts = starts
self.patched = patched or {} # {address: [(set index, [replacement words])]} (recomp/patches.py)
self.picks = picks or {} # {contested site: (pick index, {ordered set: value})} (recomp/patches.py)
self.spins = spins or {} # {spin wait back-edge: its head} (recomp/patches.py `spin`)
self.origs = origs or set() # functions also emitted unpatched, as orig_name() (recomp/patches.py `orig`)
self.reg_locals = reg_locals # recomp/regs.py: registers per function in C locals
self.kept = regs.CALLEE_SAVED if callee_saved else frozenset() # not reloaded after a call
self.v_locals = v_locals # recomp/vlocals.py: V registers per function in C locals (0: all in c->v)
@@ -294,9 +319,12 @@ class Emitter:
alternative may branch (bl, b, b.cond / cbz / tbz, ret)."""
out = []
for _, words in self.patched[a]:
lifted = [self.mod.lifter.lift(w, a) for w in words]
# ('call', target): a plugin's inline hook (recomp/patches.py @call), before the site's own instruction
lifted = [Insn('hook', target=w[1]) if isinstance(w, tuple) else self.mod.lifter.lift(w, a) for w in words]
for j, r in enumerate(lifted):
last = j == len(lifted) - 1
if r.kind == 'hook' and not last:
continue
if r.kind != 'op' and not (last and r.kind in ('bl', 'b', 'bcond', 'ret')):
raise patches.PatchError(f'{a:#x}: replacement word {words[j]:08x} is a {r.kind}')
out.append(lifted)
@@ -375,6 +403,22 @@ class Emitter:
raise patches.PatchError(f'{a:#x}: a patched call that uses flags')
return reads, alts[0][1]
def unpatched_copy(self, entry, end, refs):
"""C of the function [entry, end) without its patched sites, named orig_name(entry): what a plugin's replace
hook calls as the original (its trampoline, recomp/patches.py `orig`). Its own fall-back fb_ is renamed too."""
kept = self.patched
self.patched = {a: alts for a, alts in kept.items() if not entry <= a < end}
try:
lines, r = self.function(entry, end)
finally:
self.patched = kept
refs |= r
text = '\n'.join(lines).replace(f'fb_{entry:x}(', f'fbo_{entry:x}(')
head = f'void {fname(entry)}(Cpu *c) {{'
if head not in text:
raise patches.PatchError(f'{entry:#x}: no function head to rename for its unpatched copy')
return text.replace(head, f'void {orig_name(entry)}(Cpu *c) {{', 1)
def function(self, entry, end):
"""(lines of C, referenced function starts) for the guest function [entry, end)."""
mod, starts = self.mod, self.starts
@@ -457,6 +501,12 @@ class Emitter:
return f'if ({fx(i, r.cond)}) {{ {jump(r.target, i)} }}'
if r.kind == 'ret':
return f'{spill}return;'
if r.kind == 'hook':
# a call that writes no x30, the whole Cpu current before it and read back after it: the stub saves and
# restores x30 itself, and the callback may change any register through exlaunch's hook context
refs.add(r.target)
self.stats['plugin_hook_calls'] += 1
return f'{spill}{fname(r.target)}(c);{reload}'
raise patches.PatchError(f'{a:#x}: patched instruction is a {r.kind}')
def patch(i, ins, a):
@@ -552,6 +602,8 @@ def chunk_text(name, number, emitter, fns):
lines, r = emitter.function(entry, end)
body.append('\n'.join(lines))
refs |= r
if entry in emitter.origs:
body.append(emitter.unpatched_copy(entry, end, refs))
# Every referenced function gets a prototype, including ones defined later in this chunk.
protos = ''.join(f'void {fname(r)}(Cpu *c);\n' for r in sorted(refs))
if emitter.uses_patches:
@@ -618,7 +670,7 @@ def _emitter(name):
e = _W['emitters'].get(name)
if e is None:
path, base = _W['mods'][name]
mod = Module(name, path, base, 'c')
mod = open_module(name, path, base, _W['patches'])
# Module.read is how the jump tables (recomp/jumptables.py _eval) read .text and .rodata at lift time: the
# bytes it returns become part of the generated code, so <mod>/folded.txt lists them
read, reads = mod.read, _W['reads'].setdefault(name, [])
@@ -631,7 +683,8 @@ def _emitter(name):
_W['patches'].for_module(name, base),
spins=_W['patches'].spins_for(name, base),
hooks=_W['patches'].hooks_for(name, base),
picks=_W['patches'].picks_for(name, base), **_W['opts'])
picks=_W['patches'].picks_for(name, base),
origs=_W['patches'].origs_for(name, base), **_W['opts'])
return e
@@ -676,13 +729,19 @@ def _emit_chunk(task):
# ------------------------------------------------------------------------------------------------ driver
def table_text(name, addrs):
def table_text(name, addrs, extra=None):
"""<mod>_table.c: the function starts and their C; extra {address: C function name} adds entries of functions
lifted elsewhere (a plugin's trampoline reaching the unpatched copy of a game function, recomp/patches.py `orig`)."""
extra = extra or {}
names = {a: fname(a) for a in addrs if a not in extra}
names.update(extra)
addrs = sorted(names)
lines = [header(f'{name} function table'), '#include "cpu.h"\n\n']
lines += [f'void {fname(a)}(Cpu *c);\n' for a in addrs]
lines += [f'void {names[a]}(Cpu *c);\n' for a in addrs]
lines.append(f'\nconst uint64_t {name}_fn_addrs[] = {{\n')
lines.append(',\n'.join(hx(a) for a in addrs))
lines.append(f'\n}};\nconst GuestFn {name}_fn_ptrs[] = {{\n')
lines.append(',\n'.join(fname(a) for a in addrs))
lines.append(',\n'.join(names[a] for a in addrs))
lines.append(f'\n}};\nconst uint64_t {name}_fn_count = {len(addrs)};\n')
return ''.join(lines)
@@ -746,7 +805,7 @@ def in_span(addrs, lo, hi):
return addrs[bisect.bisect_left(addrs, lo):bisect.bisect_left(addrs, hi)]
def chunk_key(mod_key, number, fns, patched, site_addrs, spins, spin_addrs, hook_addrs, picks=None):
def chunk_key(mod_key, number, fns, patched, site_addrs, spins, spin_addrs, hook_addrs, picks=None, origs=None):
"""Key of one chunk: its module, number (in its header) and functions, and the patch sites (set index and
replacement words, @page resolved, so the patch page is in them), the pick index and values of its contested
sites, spin waits and hooked functions inside its address range; hook_addrs None (FN_ENTER in every function) keys
@@ -754,10 +813,15 @@ def chunk_key(mod_key, number, fns, patched, site_addrs, spins, spin_addrs, hook
here, with a case in tests/lift_cache_test.py."""
lo, hi = fns[0][0], fns[-1][1]
in_chunk = in_span(site_addrs, lo, hi)
sites = [[a, [[k, words] for k, words in patched[a]]] for a in in_chunk]
sites = [[a, [[k, [list(w) if isinstance(w, tuple) else w for w in words]] for k, words in patched[a]]]
for a in in_chunk]
hooks = None if hook_addrs is None else in_span(hook_addrs, lo, hi)
contested = [[a, picks[a][0], sorted(picks[a][1].items())] for a in in_chunk if a in (picks or {})]
return _key(mod_key, number, fns, sites, [[b, spins[b]] for b in in_span(spin_addrs, lo, hi)], hooks, contested)
parts = [mod_key, number, fns, sites, [[b, spins[b]] for b in in_span(spin_addrs, lo, hi)], hooks, contested]
copies = [e for e, _ in fns if e in (origs or ())]
if copies: # none: the key it had before plugins
parts.append(copies)
return _key(*parts)
def _entry_check(file, entry):
@@ -911,7 +975,7 @@ def main():
continue
t = time.perf_counter()
path = Path(files[name][0]) if name in files else args.exefs / name
mod = Module(name, path, base, 'c', plugin=name in files)
mod = open_module(name, path, base, table, plugin=name in files)
patches.check(table, mod, name)
starts, dstats = discover(mod)
est = estimate_sizes(mod, starts)
@@ -921,8 +985,25 @@ def main():
chunks = partition(est[:n], args.chunk_fns, args.chunk_bytes, args.big_fn)
moddir = args.out / name
moddir.mkdir(parents=True, exist_ok=True)
extra = table.orig_entries(name, {n: b for n, b, _ in mods})
if extra: # a trampoline reaches another function's unpatched copy, not a lift of its own words
keep = ~np.isin(abs_starts, np.array(sorted(extra), dtype=abs_starts.dtype))
starts, est, abs_starts = starts[keep], est[keep], abs_starts[keep]
n = len(starts) if not args.limit else min(args.limit, len(starts))
ends = np.append(abs_starts[1:], mod.hi)
chunks = partition(est[:n], args.chunk_fns, args.chunk_bytes, args.big_fn)
missing = sorted(base + o for o in (table.plugins.get(name) or {}).get('seeds', ())
if base + o not in set(abs_starts.tolist()))
if missing:
raise SystemExit(f'{name}: the seeds {", ".join(hex(a) for a in missing)} are no function starts')
mkey = module_key(gen_key, name, path, base, abs_starts)
if table.plugin_inputs(name):
mkey = _key(mkey, table.plugin_inputs(name), _sha256(Path(table.plugins[name]['image']).read_bytes()))
patched, spins, picks = table.for_module(name, base), table.spins_for(name, base), table.picks_for(name, base)
origs = table.origs_for(name, base)
bad = sorted(origs - set(abs_starts.tolist()))
if bad:
raise SystemExit(f'{args.patches}: orig {", ".join(hex(a) for a in bad)} is no function start of {name}')
site_addrs, spin_addrs = sorted(patched), sorted(spins)
hooks = None if args.fn_enter_all else table.hooks_for(name, base)
stray = sorted(set(hooks or ()) - set(abs_starts.tolist()))
@@ -932,11 +1013,11 @@ def main():
hook_addrs = None if hooks is None else sorted(hooks)
for number, (i0, i1) in enumerate(chunks):
fns = list(zip(abs_starts[i0:i1].tolist(), ends[i0:i1].tolist()))
key = chunk_key(mkey, number, fns, patched, site_addrs, spins, spin_addrs, hook_addrs, picks)
key = chunk_key(mkey, number, fns, patched, site_addrs, spins, spin_addrs, hook_addrs, picks, origs)
tasks.append((int(est[i0:i1].sum()), (name, number, str(moddir / f'{name}_{number:04d}.c'), fns, key)))
paths[name] = (str(path), base)
starts_abs[name] = abs_starts
info[name] = {'base': base, 'lo': mod.lo, 'hi': mod.hi, 'emitted': abs_starts[:n].tolist(),
info[name] = {'base': base, 'lo': mod.lo, 'hi': mod.hi, 'emitted': abs_starts[:n].tolist(), 'extra': extra,
'chunks': len(chunks), 'discover': dstats, 'discover_seconds': time.perf_counter() - t,
'moddir': moddir}
print(f'{name}: {dstats["functions"]} functions ({dstats["seeds"]} seeds, {dstats["rounds"]} rounds), '
@@ -1001,7 +1082,8 @@ def main():
stats.update(r['stats'])
unsupported.update(r['unsupported'])
t = time.perf_counter()
table_written = write_if_changed(moddir / f'{name}_table.c', table_text(name, d['emitted']))
table_written = write_if_changed(moddir / f'{name}_table.c', table_text(
name, d['emitted'], {t: orig_name(f) for t, f in d['extra'].items()}))
write_if_changed(moddir / 'folded.txt', folded_text(name, merge_ranges(folded[name])))
removed = remove_stale(moddir, name, d['chunks'], errors)
manifest = {
+17 -1
View File
@@ -12,6 +12,7 @@ import numpy as np
from lifter import Insn, Lifter, Unsupported, hx
from nso import DT_INIT, DT_INIT_ARRAY, DT_INIT_ARRAYSZ, Nso, R_AARCH64_RELATIVE
RET = 0xD65F03C0
LIFT_CACHE = 1 << 16 # lifted instructions kept per module; analyses revisit nearby addresses only
@@ -33,13 +34,27 @@ def _read_encoded(img, off, enc, pc_base):
class Module:
def __init__(self, name, path, base, simd='c', plugin=False):
def __init__(self, name, path, base, simd='c', plugin=False, image=None, rets=(), seeds=()):
"""image, rets, seeds: a plugin's lift (recomp/patches.py `plugin`): its .text is taken from image (the plugin's
image after its init, holding the hook stubs and trampolines the file has as zeros), the words at the image
offsets rets become `ret` (an inline-hook stub's b to its trampoline), and the image offsets seeds are function
starts too."""
self.name = name
self.nso = Nso(str(path))
self.base = base
self.plugin = plugin # a mod's code module (recomp/layout.py plugin<N>): its init functions are seeds too
n = self.nso
self.image = bytes(n.image)
if image is not None:
t0, t1 = n.text[0], n.text[0] + n.text[1]
if len(image) < t1:
raise ValueError(f'{name}: the image after the init is shorter than its .text')
img = bytearray(self.image)
img[t0:t1] = image[t0:t1]
for o in rets:
img[o:o + 4] = RET.to_bytes(4, 'little')
self.image = bytes(img)
self.extra_seeds = [base + o for o in seeds]
self.lo = base + n.text[0]
self.hi = self.lo + n.text[1]
self.words = np.frombuffer(self.image, dtype='<u4', count=n.text[1] // 4, offset=n.text[0])
@@ -120,6 +135,7 @@ class Module:
starts = set(self.eh_frame_functions())
if self.plugin:
starts.update(self.init_functions())
starts.update(self.extra_seeds)
for _, info, shndx, value, _ in self.nso.syms:
if shndx and (info & 0xF) == 2:
starts.add(self.base + value)
+126 -7
View File
@@ -10,6 +10,12 @@ Lifted code cannot be byte-patched when the game runs, so a patch is applied whe
hook <module> <function> [<function> ...]
plugin <set> <module> <text sha256> <image>
expect <set> <module> <offset> <old> <new>
stub <module> <offset>
seed <module> <offset> [<offset> ...]
orig <set> <module> <offset> <function module> <function offset>
<address> is a module offset (hex), <original> the instruction word the module has there (checked; a mismatch stops
the generator), each <replacement> an instruction word (hex) or `@page:x<n>`, which is `adrp x<n>, <patch page>`
encoded for the site's address. The patch page is the first 4 KiB page after main's image (layout.py leaves the rest
@@ -44,6 +50,28 @@ and the direct branches back to it (module offsets). Each back-edge (checked: a
<head>) is lifted as `rt_spin_gate(c, <head>); goto <head>`, which keeps every register and only adds time
(runtime/kernel.c kern_spin_gate).
The plugin lines carry a mod's exlaunch plugin (layout.py plugin<N>), whose init runs at every start
(runtime/plugin_init.c) and whose hooks are sites of its set (tools/exefs_plugins.py writes them from the plugin service
run's record; the design follows #845 by itaskaev2):
- `plugin`: <module> belongs to the set <set>; it is lifted from <image>, the plugin's image after its init (the
service run's plugin<N>.img), whose .text holds the hook stubs and trampolines the NSO file has as zeros. <text
sha256> is that .text's hash: the runtime compares it with the .text its own run of the init leaves, and keeps the
set off when they differ.
- `expect`: one word the init writes into a game module (the hook branches into main's .text); the runtime compares
the words its run of the init wrote with these, all or nothing per plugin.
- `stub`: an exlaunch inline-hook entry stub (stur x30; bl impl; ldur x30; b trampoline; .quad callback). Its fourth
word is lifted as a `ret`: the generated site calls the stub and runs its own original instruction after it
(`@call` below), so the trampoline (the original relocated, b site+4) never runs.
- `seed`: function starts of the module the lift must have (the callbacks, the hook impls, branch targets).
- `orig`: the plugin calls its replace hook's original through the trampoline at <module>+<offset>; the generator
lifts the function at <function module>+<function offset> a second time without its patched sites
(fo_<address>) and lists that copy at the trampoline's address in <module>'s function table, so the call reaches
the original code and not the hook again.
A replacement word `@call:<module>+<offset>` is a call of the function there that writes no x30: every register in
the Cpu at the call and all read back after it (the callback may change any of them, as exlaunch's hook context
allows); the flags stay as they were. It may stand before the site's last word, which is then the original
instruction.
A `hook` line names guest functions (module offsets of function starts; gen.py stops on any other address) whose
entry the runtime watches: their lifted C starts with FN_ENTER (runtime/cpu.h), a load of g_fnprof and a predicted
branch to fnprof_hit while the runtime sets it. A table with hook lines puts FN_ENTER into these functions only; a table
@@ -73,13 +101,36 @@ class Table:
from here (for_module, picks_for, spins_for, hooks_for) is in the lift cache's key (recomp/gen.py chunk_key); a new
kind of line the Emitter reads must go there too."""
def __init__(self, sets=(), sites=None, page=0, spins=None, hooks=None, ordered=()):
def __init__(self, sets=(), sites=None, page=0, spins=None, hooks=None, ordered=(), plugins=None):
self.sets = list(sets)
self.sites = sites or {}
self.page = page
self.spins = spins or {} # {module: {back-edge offset: head offset}}
self.hooks = hooks or {} # {module: {function offset}}; empty: FN_ENTER in every function
self.ordered = set(ordered)
# {module: {'set', 'sha256', 'image', 'expect': [(module, offset, old, new)], 'stubs': {offset},
# 'seeds': {offset}, 'origs': {trampoline offset: (function module, function offset)}}}; empty without
# plugin lines
self.plugins = plugins or {}
self.bases = {} # {module: base} of the layout load() read
def plugin_inputs(self, name):
"""What the lift of module name takes from its plugin lines (for the lift cache's key), or None."""
p = self.plugins.get(name)
if not p:
return None
return [p['image'], p['sha256'], sorted(p['stubs']), sorted(p['seeds']), sorted(p['origs'])]
def origs_for(self, name, base):
"""The absolute addresses of module name's functions that a plugin's `orig` line copies."""
return {base + fo for p in self.plugins.values() for fm, fo in p['origs'].values() if fm == name}
def orig_entries(self, name, bases):
"""{trampoline address in module name: absolute address of the function it reaches} (`orig`)."""
p = self.plugins.get(name)
if not p:
return {}
return {bases[name] + t: bases[fm] + fo for t, (fm, fo) in p['origs'].items()}
def picks(self):
"""The contested sites, by module name and offset: [(module, offset, [ordered set index in file order])]; the
@@ -110,19 +161,30 @@ class Table:
"""{absolute back-edge address: absolute head address}."""
return {base + b: base + h for b, h in self.spins.get(name, {}).items()}
def for_module(self, name, base):
"""{absolute address: [(set index, [words])]} with @page resolved."""
def for_module(self, name, base, bases=None):
"""{absolute address: [(set index, [words])]} with @page resolved; an @call word becomes ('call', absolute
address), which needs bases ({module: base})."""
out = {}
def word(a, w):
if not isinstance(w, tuple):
return w
if w[0] == 'page':
return adrp(a, self.page, w[1])
known = bases or self.bases
if w[1] not in known:
raise PatchError(f'{name}+{a - base:#x}: @call into {w[1]}, which is not in the layout')
return ('call', known[w[1]] + w[2])
for off, alts in self.sites.get(name, {}).items():
a = base + off
out[a] = [(k, [adrp(a, self.page, w[1]) if isinstance(w, tuple) else w for w in repl])
for k, repl, _ in alts]
out[a] = [(k, [word(a, w) for w in repl]) for k, repl, _ in alts]
return out
def load(path, mods):
"""Table from a patch file; mods is layout() output [(name, base, size)]."""
sets, index, sites, spins, hooks, ordered = [], {}, {}, {}, {}, set()
sets, index, sites, spins, hooks, ordered, plugins = [], {}, {}, {}, {}, set(), {}
bases = {n: (b, s) for n, b, s in mods}
for no, raw in enumerate(Path(path).read_text().splitlines(), 1):
f = raw.split('#', 1)[0].split()
@@ -146,6 +208,11 @@ def load(path, mods):
for w in f[5:]:
if w.startswith('@page:x'):
repl.append(('page', int(w[7:])))
elif w.startswith('@call:') and '+' in w:
target, at = w[6:].split('+', 1)
if target not in bases:
raise PatchError(f'{where}: @call into {target}, which is not in the layout')
repl.append(('call', target, int(at, 16)))
else:
repl.append(int(w, 16))
alts = sites.setdefault(f[2], {}).setdefault(off, [])
@@ -163,6 +230,15 @@ def load(path, mods):
if b in mod:
raise PatchError(f'{where}: {f[1]}+{b:#x} is a back-edge twice')
mod[b] = head
elif f[0] == 'plugin' and len(f) == 5:
if f[1] not in index or f[2] not in bases:
raise PatchError(f'{where}: unknown set {f[1]} or module {f[2]}')
if f[2] in plugins:
raise PatchError(f'{where}: module {f[2]} has two plugin lines')
plugins[f[2]] = {'set': index[f[1]], 'sha256': f[3], 'image': f[4], 'expect': [], 'stubs': set(),
'seeds': set(), 'origs': {}}
elif f[0] in ('expect', 'stub', 'seed', 'orig'):
plugin_line(f, where, index, bases, plugins)
elif f[0] == 'hook' and len(f) >= 3:
if f[1] not in bases:
raise PatchError(f'{where}: module {f[1]} not in the layout')
@@ -174,7 +250,36 @@ def load(path, mods):
nxt = min((b for _, b, _ in mods if b > base), default=None)
if nxt is not None and page + PAGE > nxt:
raise PatchError(f'no room for the patch page after main ({page:#x})')
return Table(sets, sites, page, spins, hooks, ordered)
table = Table(sets, sites, page, spins, hooks, ordered, plugins)
table.bases = {n: b for n, (b, _) in bases.items()}
return table
def plugin_line(f, where, index, bases, plugins):
"""An expect, stub, seed or orig line into the plugin entry it belongs to (its `plugin` line comes first)."""
def plugin(name):
if name not in plugins:
raise PatchError(f'{where}: {name} has no plugin line before this one')
return plugins[name]
if f[0] == 'expect' and len(f) == 6:
if f[1] not in index or f[2] not in bases:
raise PatchError(f'{where}: unknown set {f[1]} or module {f[2]}')
owner = [p for p in plugins.values() if p['set'] == index[f[1]]]
if not owner:
raise PatchError(f'{where}: set {f[1]} owns no plugin')
owner[0]['expect'].append((f[2], int(f[3], 16), int(f[4], 16), int(f[5], 16)))
elif f[0] == 'stub' and len(f) == 3:
plugin(f[1])['stubs'].add(int(f[2], 16))
elif f[0] == 'seed' and len(f) >= 3:
plugin(f[1])['seeds'].update(int(o, 16) for o in f[2:])
elif f[0] == 'orig' and len(f) == 6:
p = plugin(f[2])
if f[1] not in index or p['set'] != index[f[1]] or f[4] not in bases:
raise PatchError(f'{where}: orig of set {f[1]} for {f[2]}, which another set owns, or module {f[4]}')
p['origs'][int(f[3], 16)] = (f[4], int(f[5], 16))
else:
raise PatchError(f'{where}: cannot parse {" ".join(f)!r}')
def check(table, mod, name):
@@ -210,6 +315,20 @@ def header_text(table, marker):
'// X(index, name, env switch, default)',
'#define RT_PATCH_SETS(X) ' + ' '.join(f'X({i}, {n}, "{e}", {d})' for i, (n, e, d) in
enumerate(table.sets)), '']
if table.plugins: # none: the header is what it was before plugins
names = sorted(table.plugins)
writes = [f'X({i}, "{m}", {o:#x}, {old:#010x}u, {new:#010x}u)' for i, n in enumerate(names)
for m, o, old, new in sorted(table.plugins[n]['expect'])]
lines += [f'#define RT_PLUGIN_COUNT {len(names)}',
'// X(index, module, its set, SHA-256 of its .text after the init)',
'#define RT_PLUGINS(X) ' + ' '.join(f'X({i}, "{n}", {table.plugins[n]["set"]}, '
f'"{table.plugins[n]["sha256"]}")' for i, n in enumerate(names)),
f'#define RT_PLUGIN_WRITE_COUNT {len(writes)}',
'// X(plugin index, module, offset, old word, new word): what the init writes into game modules',
'#define RT_PLUGIN_WRITES(X) ' + ' '.join(writes),
'// X(module, offset): the hook entries (seed lines) TOTK_PLUGIN_TRACE counts (runtime/plugin_init.c)',
'#define RT_PLUGIN_ROOTS(X) ' + ' '.join(f'X("{n}", {o:#x})' for n in names
for o in sorted(table.plugins[n]['seeds'])), '']
picks = table.picks()
if picks: # none: the header is what it was before ordered sets
lines += [f'#define RT_PATCH_PICK_COUNT {len(picks)}',