WIP: docs(design): the lifted code's contract with the host, as rules (section 14) #1626
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
2 participants
Notifications
Due date
No due date set.
Dependencies
No dependencies set
Reference
MagicBeanDev/Longshot!1626
Loading…
Reference in a new issue
No description provided.
Delete branch "dyst/Longshot:docs/lift-contract-rules"
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: docs · Risk: low · Tested on: Windows 11, Ryzen 9 3900X · Needs: none
Stacked on #1587 (and through it on #1560): rule 1 anchors to
nx2/emit.py, which #1560 adds. Review those first.TL;DR
The translated game code and the host rely on each other in ways the code shows only in pieces: the guest context's layout, where a guest register lives, when a thread gives up its core, how a store and its page mark are ordered, what each barrier and atomic becomes, and how the host replaces SDK functions. This writes those down in
docs/design.mdas six rules, each naming the function that keeps it, and gives those functions adoc:comment pointing at the rule.tests/test_doc_anchors.pychecks that every anchor resolves and that the functions keep theirs.Breakdown
docs/design.mdsection 14, sevendoc:comment lines, and seven rows intests/test_doc_anchors.py.host/andnx2/are comments.tests/test_doc_anchors.pypasses: 19 anchors, each resolves.Why
The wiki's CPU rework plan, milestone C2: before the lift is restructured, the contract between the lifted code and the host is written as rules, each with the function that keeps it, so that a change can be checked against them.
What changed
docs/design.md, section 14, "The lifted code's contract with the host, as rules":GuestContext(Ctx) for each guest thread, written bynx2/rtgen.pyfrom the kit'srt/a64.h, read by the host throughhost/hos.h, checked field by field by the emulator shim.localize_regswrites back at every context mark. A function whose C something edits by its text keeps its registers in the context (Lifter.no_local). Lines put first in a function (an entry hook's call, the goto to an entry with code below it) come after the locals' declarations (nx2/emit.py, the rule #1587 fixes).A64_POLLbefore each backward goto (nx2/poll.py). A thread waiting for a virtual core sets the holder'spoll; the holder gives the core up at its next poll ornn::oscall (host/mkw_glue.c'sa64_poll_cur,host/hos_thread.c). A host call that runs long checkpoints between its pieces, and never while a host lock is held.A64_MARK,nx2/rtgen.py); host writes mark after their last write (HOS_WRITTEN). The renderer takes the marks with an acquire exchange (host/rx_backend.c'scollect_in). The marks' grouping joins them only in straight-line runs.LDAR/STLRsequentially consistent,LDAPRan acquire load; the LSE forms,SWP,CASandCASPsequentially consistent read-modify-writes (nx2/insn.py). EveryDMB, aDSBand anISBarerecomp_barrier(), a sequentially consistent fence. The load-only and store-onlyDMBs lifted as an acquire and a release fence alone made OoT crash at its start (#1507).HLE(sym)function replaces the SDK'ssymwhole; anENTRY_HOOK_SYM(sym)hook is called first in the liftedsymand may decline. The lift finds both by readinghost/*.c, so their names are in the lift key.doc:comments aboveemit(),add_polls(),MARK_NATIVE_64,ldar_stlr(),collect_in(),a64_poll_cur()andvc_acquire(); their rows intests/test_doc_anchors.py'sREQUIRED.Measurements
Verdict: nothing to measure: documentation and comment lines.
Flags and settings
None.
Testing
Tested:
tests/test_doc_anchors.pyon Windows 11 (the Builder's Python 3.14): 19 anchors, each resolves; the seven functions keep theirs. The lines added tohost/andnx2/are comments, so the game builds and runs as #1587's tree, which played 4 runs of PR #801's route in the game here.Not tested:
tests/run_all.pyin full.Must be tested: None.
Risks
What could break: nothing that runs. A later change that moves one of the seven functions fails
tests/test_doc_anchors.pyuntil its anchor moves with it, which is the point.Turning it off: revert the commit.
Compatibility: nothing changes.
Checklist
Everyone
type(scope): description) of the status line's type.can't be run by hand is in Testing's Not testable by hand, with why.
in Risks.
main. On #1587, on #1560, on310e7c9d.python -I -B tests/run_all.pypasses (any failure that also fails onmainis named). The anchor check only.third_party/untouched (a new folder with aPROVENANCE.mdinstead).When it applies
Assisted-by:/Co-Authored-By:trailers.doc:comment names a rule written in docs/design.md, and tests/test_doc_anchors.py checks it.🤖 Generated with Claude Code
Tested in game: Windows 11, RTX 3080, Ryzen 9 3900X: the lines this adds to host/ and nx2/ are comments only (doc: anchors), so the game builds and runs as #1587's tree, which played 4 runs of PR #801's route (Hyrule Field, the Market) here with no crash or hang.
Possibly related, for context:
View command line instructions
Manual merge helper
Use this merge commit message when completing the merge manually.
Checkout
From your project repository, check out a new branch and test the changes.