WIP: fix(mods): a hook entered with BL that goes back with B returns, where that is safe #960
No reviewers
Labels
No labels
area/accessibility
area/audio
area/input
area/install
area/menu
area/renderer
area/saves
area/tooling
area/upscaling
beanstalk: approved
beanstalk: failed
beanstalk: needs approval
beanstalk: running
beanstalk: tested
ci: approved
good first issue
gpu/amd
gpu/igpu
gpu/intel
gpu/nvidia
help wanted
kind
bug
kind
chore
kind
docs
kind
feature
kind
performance
kind
question
needs measurements
platform/linux
platform/macos
platform/steam-deck
platform/windows
preview
priority
critical
priority
high
priority
low
regression
risk
high
risk
low
risk
medium
status
blocked
status
confirmed
status
duplicate
status
invalid
status
needs-info
status
wontfix
ci: approved
No milestone
No project
No assignees
1 participant
Notifications
Due date
No due date set.
Dependencies
No dependencies set
Reference
MagicBeanDev/Longshot!960
Loading…
Reference in a new issue
No description provided.
Delete branch "snaildev99/Longshot:mods/bl-return"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Type: fix · Risk: low · Tested on: Windows 11, RTX 3090 (in the game, and the game-free checks) · Needs: nothing more
Why
Many code mods hook the game by writing
bl my_hookover one of its instructions, and the hook jumps back withb <the instruction after the call>because its own calls have used up the return register. On the console thatjump is a return. On a recompiled build it is not: the translator makes
bla C call and the jump a goto, so thehook's C function runs the rest of the game's function inside the call, then returns into it, and the game runs that
rest a second time with its stack frame gone. It crashes a few calls up. Character Select v0.1.2 crashed on Hookshot
exactly so. With #134 mods' patches are built in, so every such mod would crash the same way.
What changed
The build writes such a jump back as a return before the code is translated, when that is exactly the same thing:
when nothing but that one call can reach the hook's code. Otherwise it leaves the jump and says so.
nx2/exefs_patches.py:make_returns()(called bycollect()),hooked_returns(),hook_routine(): for eachblthe patches write into code they write, the routine reached from its target (up to its returns, not past thecall's next instruction). Its
bback becomesRETwhen the routine was all written by the patches and no otherbranch or call in main, no instruction above it falling in, no unwind start, function symbol, relocated pointer or
ADR / ADRP+ADD address reaches into it. The RET goes into the writes of the file that wrote the
b, so the lift'skey changes with it. Each case is named in the build's log and in the file's note in
exefs_patches.txt(made areturn; or left, with the reason: entered from elsewhere too, runs the game's own code, or the way back is a
conditional branch, which has no RET form).
bto a patchedbl's next instruction becomes RET): it also hits aroutine that is entered with
band goes back there on purpose, whosebis right; a RET would leave the game'sfunction. The test has that case.
apply()closes the JSON it reads.Measurements
Verdict: an offline check on the game's code; nothing measured in the game. The check costs about 2 s of the
build when a mod has such a hook and nothing otherwise.
On build e0f3ccfa, with collect() and a64-kit's walk only (no build): Character Select v0.1.2's patch (its picker hook
was entered with
bland went back withb): two branches made returns; the hook's lifted function is 30instructions and ends at its own return, where before it was 78 and ran on into the caller. Character Select v0.2.1's
patch (the call is a
bsince): nothing changed.Flags and settings
None
Testing
Tested:
tests/test_exefs_bl_return.py(18 cases: rewritten, left with a note, untouched, and the lifted C beforeand after) and
tests/run_all.pyon Windows: 539 passed, 25 failed; the same 25 fail on #134's head here. The offlinecheck above.
In the game, Windows 11, RTX 3090 (driver 610.88), a build of #134's head with this branch (and the other follow-ups) merged in, Character Select v0.1.2 (lite) as the only mod: the build's log says
the branch at main+3C463BC back to the call at main+C15C60 made a returnand the same for main+3C463D4; in the game the save loads, A on the Characters page changes the character, several picks in a row and closing the menu work, no crash. With #134 alone that press crashed. The same build with the mod's v0.2.1 (no such hook) ran as before.Not tested: a mod whose hook is left with a note (entered from elsewhere too) in a game.
Must be tested: None
Risks
What could break: a mod whose hook is rewritten behaves differently only if something reaches its code that the
checks do not see (a jump table of the game landing in code the mod overwrote). Mods without such a hook: nothing
changes.
Turning it off: revert the commit.
Compatibility: a mod with such a hook is translated again once (its patched bytes change, and so the lift's key).
Checklist
Everyone
type(scope): description) of the status line's type.main. (Stacked on #134.)python -I -B tests/run_all.pypasses (any failure that also fails onmainis named).third_party/untouched (a new folder with aPROVENANCE.mdinstead).When it applies
Assisted-by:/Co-Authored-By:trailers.mainand passing here.Tested in game: Windows 11, RTX 3090 (driver 610.88), a build of #134's head
5192b46fwith this branch merged in, Character Select v0.1.2 (lite) as the only mod, the Characters page of the game's menu: the build's log names two branches back to the call at main+C15C60 made returns; A on a character changes it, several picks and closing the menu work, no crash (#134 alone crashed on that press). This branch is stacked on #134 (it depends on it), so the diff shows #134's commits too until that merges.38b592e57f6e20446b41Moved onto #134's new head
fafc7ab2(it was rebased onto main @343a1dfa): head6e20446b. No conflict, no change in this branch's own files; its tests pass. Not built or played at this head.6e20446b4107a9030c41Moved onto #134's new head
fb2a419c(rebased onto main @e4d035e9; the Mods tab's functions are API version 25 there, after main's audio outputs): head07a9030c. No conflict, no change in this branch's own files; its tests pass at this head. Not built or played at it.07a9030c41d609270f95Moved onto #134's new head
3fbc327a(the list of mods ismods.jsonthere now: #134 (comment)). Headd609270f.One conflict, in
nx2/exefs_patches.py: this branch's section sits right abovecollect, whose first line #134 changed; both kept. One commit on top: #134'stests/test_mods_list.pygivescollectno game image, so it stubsmake_returnsfor its run.tests/run_all.pyon Windows: nothing fails that #134's head passes. Not built or played at this head; the Linux halves of the changed fixtures were read, not run.d609270f95d2c8c52651Moved onto #134's new head
2b52cd1b(#134 was rebased onto main @8a4aa282: the Mods tab's functions are API version 26, and the patches' hash is named in the lift's key after main's #22: #134 (comment)). Headd2c8c526.No conflict; the commits are unchanged. It sets nothing of its own for the lift.
tests/run_all.pyon Windows: nothing fails that #134's head passes. Not built or played at this head.d2c8c526513aa6ce93c7Moved onto #134's new head
c5cead8d(#134 was rebased onto main @ac778751and brings main's new players' mods guide in line with it: #134 (comment)). Head3aa6ce93.No conflict; the commits are unchanged.
Nothing fails in
tests/run_all.pyon Windows that #134's head passes. Not built or played at this head.View command line instructions
Checkout
From your project repository, check out a new branch and test the changes.