mirror of
https://github.com/MobileGL-Dev/MobileGL
synced 2026-11-13 13:03:22 +09:00
swung0x48
aba329cc53
Two things land together: the plan and contract draft P6 needs before it starts, and the
working notes that until now existed on exactly one machine.
1. P6's plan and contract draft (neither started; not one line of code)
docs/Disaggregated/P6-SPAWN-PLAN.md the package plan
docs/Disaggregated/P6-CONTRACT-DRAFT.md the contract draft (moves to
MG_Remote/CONTRACT-P6.md when c6 lands)
The three findings that mattered, all written into the documents:
a. P6 is SMALLER than its roadmap cell suggests. The transport primitives are already in
the tree and already tested: SocketDoorbell including hangup detection and the two
lost-wakeup fences (Doorbell.cpp:211-360, four cases in FdPassingTest), SCM_RIGHTS fd
passing, ShmSegment::Adopt, and the SurfaceOp / WindowKind schema already defined in
protocol.fbs. inproc uses a real second shm mapping rather than an alias, and
SessionRings.h:22-28 says that was done so today is not the first time it runs. P6 is
assembly plus a control plane plus a process, not "write a socket transport".
b. The evidence for "P6 is only a transport swap" has EXPIRED. It was bought by P5c, whose
audit found 59 direct memory accesses in a tree that already looked clean. P5e changed
the tree again. So the first package, a6, is a read-only audit that writes no code, and
every contract row that depends on it is marked PENDING a6 rather than decided in
advance.
c. P6 does not get a game running on the phone. ANativeWindow* is meaningless in the child,
and protocol.fbs:186-196's own comment says Android transfers the window out of band -
that band is P12. P6 lands pbuffer / surfaceless / offscreen, which is what HeadlessGL,
the split-equivalent lane and trace replay need, and which is exactly what P6's own exit
gate measures. A real window reaching the server is a named refusal. This gets its own
section because "P6 is done" would otherwise read as "the game runs now".
The contract adds rule G: a role may not name a process-local handle. It extends P5c's
rule E (a role may not name the other role's memory) from memory to identity - EGLDisplay /
EGLSurface / EGLContext / ANativeWindow* / fd number / pid / mapped address either cross as
a token this contract defines or they do not cross, and a descriptor crosses only through
SCM_RIGHTS, where the kernel renumbers it.
What P5e left for P6 gets its own section. The latch semantics are already designed
(ARCHITECTURE.md:504) and are copied unchanged. What is new is that after run-ahead the
client no longer waits while the peer process can DIE: the client holds records that were
published and will never be applied, and Android's freezer suspends the child without
closing anything. So slow and dead must be distinguishable WITHOUT a timeout threshold.
That is P6's only new design; everything else is carriage. It shares a predicate with E1's
outstanding re-specification (ID-122), and the two should be designed together.
Two gates carried over from P5e's lessons: G2 requires integration-spawn's test-name set to
match integration-split's name for name, because a differing set means the lane is quietly
running less; and the arm-proof gate requires every entry to record the child pid and
transport=spawn in its OWN private log - ID-124 established that this kind of false green
really happens, and a spawn lane that actually ran monolith would pass every other gate.
S2's shape must be settled before it is written, and the document says why: E1 is the
cautionary case.
2. The working notes move into the repository (docs/Disaggregated/notes/, 415 .md files)
ROADMAP / CURRENT_STAGE_PROGRESS / MEASUREMENTS cite ruling numbers, audit line numbers and
the provenance of gate figures from ~/w7/notes/, a directory that exists on one machine and
is under no version control. A record cited hundreds of times that lives only locally is not
a record, so it moves in whole, with its directory structure intact.
Only .md moves. Scripts, run logs, census and gate result JSON, patches, APKs and nm dumps
stay where they are: they are evidence DATA rather than documents - large, regenerated per
run, and mostly carrying absolute paths and device serials that mean something only on the
machine that produced them. The mapping and this split are written in
docs/Disaggregated/notes/README.md.
Two exceptions are recorded there too: P6's BRIEF has been promoted to a first-class
document and keeps no copy under notes/, so the two cannot drift apart; and recovered/ holds
material salvaged from failed workflow runs, which may duplicate the like-named phase
directories and is kept because a few of those were the only complete version at the time.
CI's citation lint takes docs/Disaggregated/*.md only (non-recursive), and notes/ is
deliberately outside it: those notes' file:line citations were written against their own
code heads, and resolving them against today's HEAD would fail wholesale - which is not an
error, it is their correct state as a historical record. To check one, use the revision it
declares (--rev).
3. Inconsistencies fixed in passing
- README.md's status line still said P5e was in progress while the stage table already said
closed.
- CURRENT_STAGE_PROGRESS's next-step item 1 still listed the exit gate as pending, though
(a) and (b) were run in the previous commit; rewritten to closed plus the one item that
actually remains (E1).
- ROADMAP's P6 row still had the pre-phase plan in three of its cells; it now carries the
package order, the scope boundary and the two new gates.
Checked with check_doc_citations.py: 125 citations across docs/Disaggregated/*.md, 0 problems.
68 lines
4.6 KiB
Markdown
68 lines
4.6 KiB
Markdown
# P5e package preamble (read first; applies to every package agent)
|
|
|
|
You implement ONE package of P5e ("retire the lockstep on the Espryt draw path"). The plan is
|
|
`BRIEF-P5E.md` (your package's section is your scope: the files and LINE RANGES you may edit; a line
|
|
outside your range is the integrator's - ask via your report, do not edit it), the rules are
|
|
`CONTRACT-P5E-draft.md` (a draft until c0e lands it as `MobileGL/MG_Remote/CONTRACT-P5E.md`; the
|
|
integrator's rulings in `INTEGRATOR-DECISIONS-P5E.md` override the draft where they differ), and the
|
|
map of the code is your scout report `scout-S?.md` plus the E note and the Kimi audit
|
|
(`kimi-audit.md`, an independent list of every apply-thread read of client memory - cross-check
|
|
your family's rows against it and say in your report which rows you retired, which you left
|
|
barriered, and which you found not to exist).
|
|
|
|
## Where you work
|
|
|
|
Your tree is a WSL git worktree: `~/w7/p5e-<slug>` on branch `p5e/<slug>`, reachable from Windows as
|
|
`//wsl.localhost/Arch/home/swung/w7/p5e-<slug>/` (read and edit files through that UNC path with the
|
|
file tools; `mkdir` does not work over UNC - create directories with a wsl command). Every shell
|
|
command runs inside WSL through a script file:
|
|
```
|
|
MSYS_NO_PATHCONV=1 wsl.exe -d Arch -- bash -lc "cd ~/w7/p5e-<slug> && <command>"
|
|
```
|
|
(For anything longer than one line, write a `.sh` into your tree's `.p5e/` directory over UNC and
|
|
run it with `bash ~/w7/p5e-<slug>/.p5e/<name>.sh`.) Do not touch any other tree, never `~/w7/pipe`,
|
|
never the Windows checkouts under `FoldCraftLauncher/`. No adb, no devices. No `git lfs` commands.
|
|
Never `git reset --hard` / `git checkout -- .` on trees you did not create.
|
|
|
|
Build and gate (the split flavour is already configured in `build-split`; the first build after
|
|
your edits is incremental with ccache):
|
|
```
|
|
bash ~/w7/notes/tools/p5e_gate.sh <slug> build # cmake --build build-split, prints errors
|
|
bash ~/w7/notes/tools/p5e_gate.sh <slug> unit # ctest -L unit (tcache_count=0)
|
|
bash ~/w7/notes/tools/p5e_gate.sh <slug> isplit # ctest -L integration-split (lavapipe)
|
|
bash ~/w7/notes/tools/p5e_gate.sh <slug> strict # the strict lane (MOBILEGL_IPC_STRICT_ERRORS=1)
|
|
bash ~/w7/notes/tools/p5e_gate.sh <slug> gens # gen_pipe / field_ownership / dirty-surface / include-closure / doc citations
|
|
bash ~/w7/notes/tools/p5e_gate.sh <slug> one '<ctest -R regex>' # a subset, with output on failure
|
|
```
|
|
Each writes `~/w7/p5e-logs/<slug>-<step>.log` and prints the tail. A build takes 1-10 minutes; unit
|
|
~1 min; isplit ~10 s; run them in the foreground (they finish inside the tool's timeout) - if a step
|
|
exceeds 9 minutes, run it with `run_in_background` and wait for the notification.
|
|
|
|
## Rules (the same as every phase)
|
|
|
|
- Commit on your branch as you go (`git -C ~/w7/p5e-<slug> commit`), single-line subject
|
|
`[Scope] (Disaggregated): <what>` with `- ` bullets in the body for the why; NO `Co-Authored-By`,
|
|
no attribution lines. Check `git var GIT_COMMITTER_IDENT` prints `Swung0x48 <swung0x48@outlook.com>`
|
|
before your first commit; if not, `git config user.name Swung0x48 && git config user.email
|
|
swung0x48@outlook.com` in your tree only. Do not push, do not merge.
|
|
- Every correctness-bearing change gets a red-once: the brief names them; run the red (revert the
|
|
arm or use the hook), see the named Fatal / red test, put it back, record the exact evidence line
|
|
in your report. Keep tests light otherwise.
|
|
- G1: the pull build must not change. Keep every split-only change under `#if MOBILEGL_BUILD_DISAGGREGATED`
|
|
(or transport-gated inside an existing `MOBILEGL_PIPE_PUSH` arm, per ruling 1); name any delta
|
|
to shared code in the report. G2/G14: a test that exists only in the split build gets a skip twin.
|
|
- No hot-path instrumentation left in; counters behind `MG_Util::PipeStats::Enabled()` are fine.
|
|
- Comments in the file's voice: the WHY, updated not deleted.
|
|
- Rework rule: if your own gate stays red after two full attempts on the same defect, stop and
|
|
report the state precisely rather than thrashing.
|
|
|
|
## Report
|
|
|
|
Write `~/w7/notes/p5e/reports/<slug>-v1.md` (over UNC: `//wsl.localhost/Arch/home/swung/w7/notes/p5e/reports/`)
|
|
BEFORE your final message: what changed per file (with the line ranges you touched), the rows of
|
|
your family retired / left barriered / not found, the red-once evidence (verbatim lines), the gate
|
|
results (exact pass counts), G1/monolith impact, seams you need from other packages and what you
|
|
assumed about them, the rulings you need from the integrator, what you did not do. <= 200 lines.
|
|
Your final message is the structured result only (branch, head sha, report path, gate summary,
|
|
blockers).
|