mirror of https://github.com/MobileGL-Dev/MobileGL synced 2026-11-07 01:53:24 +09:00

Files

T

swung0x48 aba329cc53 [Docs] (Disaggregated): P6's plan and contract draft; the working notes move from a local directory into the repository

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.

2026-09-18 23:31:39 -04:00

5.7 KiB

Raw Blame History

P5e wave 3 — integration and the flip, as an executable checklist

Base 7c6f6886. Integration tree ~/w7/p5e-int (branch p5e-wave2-landed, fetched to the Windows worktree MobileGL-disagg via remote wslpipe, pushed to origin/feat/disaggregated). G below = bash /home/swung/w7/notes/tools/p5e_gate.sh int <step>.

Rulings this implements: ID-111 … ID-123.

Phase A — land the three packages

package	tree	scope	brief
`pa`	`~/w7/p5e-pa`	the program family, 69 of 109 red entries, the per-draw pull	`TASK-pa.md`
`mv`	`~/w7/p5e-mv`	`MultiDraw.cpp`'s bound-VAO read, 9 entries (ID-113)	`TASK-mv.md`
`gl`	`~/w7/p5e-gl`	the gate mechanism + two latent crashes (ID-111/112/115/116/117/118/119/120)	`TASK-gl.md`

Merge order: gl first (it changes the strict knob and the generator, so the other two want to be measured under it), then pa, then mv. Expect conflicts only where pa and gl both touch PipeInputs.*; gl was told to stay out of DirectGLES.cpp and MultiDraw.cpp.

After each merge: G build, G unit, G isplit, G gpu, G gens. gpu is not optional — it is the push-monolith runtime arm and the only thing that would catch an ID-81 violation (ID-107/109; the last one cost 137 SEGFAULTs across 38 scenarios).

Phase B — make the lane's claim evaluable, then measure it

Re-take the census on the corrected harness. The current census re-runs each entry under a FIXED environment, which is wrong for 14 of 109 (the PersistentMapArm. and SmallRing. and NamedBlit. prefixes carry extra ENVIRONMENT). Drive the environment from ctest -L integration-split -N -V per entry. Until that is done, any marker table is provisional.
The census is a first-fault histogram, not an inventory. The 62 entries that abort on GetProgramForDraw@DrawArrays will not go green when that row lands; they will advance to their next pull. Budget a second census immediately after pa merges, before claiming any distance to hard green.
Baselines to record BEFORE the flip so the deltas are attributable (all measured green at 7c6f6886 by the controls scout, re-confirm after the merges):
- MOBILEGL_IPC_RUN_AHEAD=0 ctest --test-dir build-split -L integration-split -j 4 → 116/116
- MOBILEGL_IPC_AUDIT=1 ctest --test-dir build-split -L integration-split -j 4 → 116/116
- MOBILEGL_IPC_STRICT_ERRORS=1 ctest -L unit → 2250/2250
- the default arm's split logs carrying "run-ahead requested … running lockstep"

Phase C — the things BRIEF §3 asks for that do not exist or are broken

BRIEF item	real state	action
§3.4(a) `RUN_AHEAD=0` identical picture	control exists and is green; SSIM harness does not	host-side pixel equality on the lane's readback scenarios is cheaper and stronger than SSIM; write that
§3.4(b) `VERB_BARRIER=0` red at a barriered row	`scripts/ci/split_negative_controls.sh` fails its own check and demands a `Fatal{BarrierViolation}` that cannot fire at `BATCH_WAITS=1`	ID-122: fix, re-specify, or delete with a named reason. Do not leave it
§3.4(c) Magma logs once and runs lockstep	already true and already in every split entry's private log	assert it, no new fixture
§3.5 per-package red-once	not executable — every candidate is red before the revert (ID-121)	re-sequence after the lane is green; evidence form becomes "the table gains exactly this one pair"
§3.6 G1	the gate configures only `build-split`; no pull flavour exists (ID-123)	integrator runs one `-DMOBILEGL_PIPE_PUSH=OFF` configure+build; packages must write "not verified locally", never "G1 green"
§3.7 `MOBILEGL_IPC_AUDIT=1` clean	measured 116/116 today	re-run post-flip, when a present-ahead client is the new consumer of retired staging

Phase D — the flip, in one commit

Flip together, never separately:

kMGPipeP5eRunAheadReady — MG_Backend/Init.cpp:98
kMGPipeP5eClientWaitRuleLanded — MG_Pipe/PipeApply.h:969

and in the SAME commit, ID-111's one-line fix to the barriered stamp (MG_Remote/Server/PipeApplier.cpp:1180-1182), if gl has not already landed it. Without it the Vulkan backend stamps every draw unbarriered while its client is still lockstep and dies on the first draw.

Phase E — the device matrix

Four arms, interleaved, 30 s windows, GPU pinned per arm (the pin is lost across app restarts), fan on, and the core each thread landed on recorded:

arm	what it answers
monolith	the parity target
inproc, `MOBILEGL_IPC_RUN_AHEAD=0`	the paired A/B control: identical server code, identical records, the only difference is whether the client waits
inproc, run-ahead, `PRESENT_CREDIT=1`	the shipping configuration
inproc, run-ahead, `PRESENT_CREDIT=2`	ID-92's measurement arm

Do not use MOBILEGL_IPC_VERB_BARRIER=0 as the control (ID-114): it is the first conjunct of RunAheadArmed(), so it turns run-ahead off as a side effect, and it aborts within seconds with Fatal{UnmigratedPipeInput, "IsCapabilityEnabled@ClientWaitSync"}.

Acceptance, in order of what actually decides it:

cli per frame falls from ~916 to the handful of records that stay barriered by ID-84.
rsp stops scaling with draws (it was exactly the draw count under inproc, 0 under monolith).
client thread CPU ms/frame falls from 6.1 toward the projected ~3.0 (PERF-PROFILE-7c6f6886.md §5).
fps, last, and only compared within one interleaved session.

Phase F — docs

CURRENT_STAGE_PROGRESS.md §2.5, MEASUREMENTS.md §10, ROADMAP.md's P5e row, and a P5e report. The perf story belongs in the report, not scattered: PERF-BASELINE-7c6f6886.md and PERF-PROFILE-7c6f6886.md are its raw material.

5.7 KiB Raw Blame History