Files
MobileGL/docs/Disaggregated/notes/p5/prompts/v1-round1.md
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

7.9 KiB

You are package v1 — the server role, the apply thread, and the EGL context migration of phase P5 on the MobileGL disaggregation project. This is the phase's highest-risk package: you and package c1 (running in parallel) jointly own the milestone, "the first IPC frame on the reduced path".

Read first, in this order: ~/w7/notes/p5/PACKAGE-PREAMBLE.md (worktree setup, the two day-one traps, build recipe, the four self-tests every package owes, the iron rules), then MobileGL/MG_Remote/CONTRACT-P5.md in the tree (authoritative — it outranks the brief), then ~/w7/notes/p5/BRIEF-P5.md §2 (R-1, R-9, R-11, R-12), §4, §5 "v1", §13 (R-16 — read this one twice), then ~/w7/notes/p5/scout-backend-install-and-thread.md — your subject's 601-line survey, every line number opened. Then skim ~/w7/notes/p5/INTEGRATOR-DECISIONS.md for the rulings that bind you, and the wave-1 package reports under ~/w7/notes/p5/p5-results/ (w1, s1, p1, b1 landed the machinery you are about to drive).

Base: feat/disaggregated @ 32563993 — wave 1 (c0, w1, s1, p1, b1, t1) is merged. Slug v1; worktree ~/w7/p5-v1, branch p5/v1. The full five-part gate is running on that commit right now; if it turns up breakage I will tell you.

What you own

MG_Remote/Server/*, MG_Backend/Init.cpp, and the server-side edits in MG_Backend/DirectGLES/Managers.cpp (b1's file — coordinate through me for anything beyond the R-11 copy below).

What you build

  1. ServerLoop + the mgl-srv-apply thread. No mgl-srv-io in P5 — inproc's control plane is in the same process; P6 splits it. Park through Doorbell::Wait(control.consumerParked, …, kWaitForever) and treat Wait == false && Dead() as shutdown. CondVarDoorbell::Kill() is the only thing that can un-park a kWaitForever waiter: a parked thread never killed hangs Shutdown; one killed but not joined returns into memory the client has freed. Bind the thread with MOBILEGL_IPC_SERVER_AFFINITY (default auto, reuse ShaderCompilePool's big-core probe) and log the resolved mask.
  2. The EGL context migration — the part that can sink the phase. The server role privately holds a BackendObject_DirectGLES; the apply thread runs eglMakeCurrent once and holds the context for life, so g_backendContextOwnerThread is written once, DirectGLES.cpp:11933-11953's six cache invalidations become a one-off, and the 16 IsBackendContextCurrentOnThisThread() sites in DirectGLES.cpp plus the 16 CanTouchGLNow() sites in Managers.cpp answer true on the server instead of silently degrading. The client's EGL lifecycle calls (InitializeEGLDisplay, CreateEGLWindowSurface, MakeEGLCurrent, SwapEGLBuffers, SetEGLSwapInterval, ReleaseEGLSurface, ReleaseEGLResources) become blocking control requests executed on the apply thread. ReleaseEGLResources and ~BackendObject_DirectGLES must block, or MobileGL::Destroy() proceeds while the server still holds the context.
  3. The Init.cpp hook at MG_Backend/Init.cpp:50, before the switch. Note :43-44 also fills gBackendFunctionsTable from the object — that table is c1's emit table, so coordinate rather than inventing one.
  4. Server/PipeApplier: drive w1's decoder into the existing MGPipeApply* free functions; ApplyOne = decode → stamp → apply → reply → advance appliedSeq by one. appliedSeq has exactly one writer, s1's SessionConsumer::ApplyOne — drive it, do not poke RingControl yourself. The 64-record batching is banned while the verb barrier exists.
  5. p1's stamp rule, exactly as p1 specified it (~/w7/notes/p5/p5-results/p1-v1.md; its §7 supersedes parts of its own §2, so read §7): StampVerbBoundary(op) → MGPipeVerbForWireOp(op), kVerbCount ⇒ stamp nothing; otherwise call MG_Pipe::MGPipeServerStampVerbBoundary(verb) once per record before its applier. It bumps the serial, stamps the verb class mask's supplied/derived fields and zeroes everything else — the zeroing is load-bearing, because the client stamps all 63 and without it rsp is identically zero. Four boundary ops: Clear, DrawVbo, ReadPixels, Blit; Present is not one. Two things p1 flagged for you: MGPipeServerClearVerbBoundary() is MANDATORY on leaving the applier (without it a spawned server latches the stamp for life and the sticky-exemption cases start aborting under strict), and PipeApplier::m_residualPulls is vestigial — delete the member rather than wiring both it and the process-wide counter.
  6. R-11 in Managers.cpp: Ops_H_SubData / Ops_H_FlushRange must copy the bytes into server-owned storage instead of leaving GLESBufferResource::hostBytes pointing into the client's shadow. w1's MOBILEGL_IPC_AUDIT=1 fills retired SEG_STAGE bytes with 0xDD, so a retained pointer shows up as 0xDD in the next frame — run with it on. Integrator ruling on b1's open M-6 half (the flush-ladder snapshot): the snapshot extent is exactly the range the record declares, never widened. The server's ladder operates only on staged bytes; if it ever needs bytes outside a staged range that is a Fatal, not a silent re-read. Tier 1's INVALIDATE_RANGE is an assertion that the old bytes are dead, and widening it has already clobbered GPU-written data silently once (Managers.cpp:1126-1129).
  7. Confirm s1's caps defaults. ServerSession::SetConsumedSubsystems / SetCapabilityBits now Fatal{UnsetCallMask} if nobody sets them — that was s1's BLOCKER fix, and you are the "somebody". Set them from what the server's backend actually registered, and make sure a wrong answer fails loudly rather than silently disabling a family (a silently-wrong consumer mask is ID-39's 66 lost uploads).
  8. Teardown, per ARCHITECTURE.md:537 plus the contract's table 3: publish → server drains and acks → stop the apply thread (Kill, then join) → close transport → client drains the compile pool → MobileGL::Destroy() → release sync/query handles. Nothing added in P5 may start a destructor chain that runs after the transport closes.

Acceptance

  • DirectGLES.Split.ClearThenReadPixelsScenario.* green under MOBILEGL_TRANSPORT=inproc. That lane exists and currently skips by name; t1's arming condition is behavioural (transport not monolith, a live client session, a non-zero implemented-verb count, and the client encoder's record ordinal actually moved during the case), so it arms only when the path really runs. You and c1 jointly flip it.
  • The four self-tests in the preamble on all four build dirs, plus the split build. G1 must not move.
  • Teardown clean under GLIBC_TUNABLES=glibc.malloc.tcache_count=0; no hang, no UAF; the shutdown test bounded (5 s join), so a lost wakeup fails red rather than wedging CI.
  • Run the reduced path with MOBILEGL_IPC_AUDIT=1 and report that no 0xDD reaches a draw.

The discipline this wave produced — R-16, and it is not optional

Five packages each shipped at least one check that could not fail for the reason it existed: a self-test control that tripped on another control's message; a persistent-map test that wrote the record field by hand so deleting the producer still passed; a lane probe that armed against stub source text (the reviewer renamed one string and 8 of 11 split lanes went green having run monolith). So: no test may construct the state it is meant to observe; every control asserts its own failure string, not merely that something failed; every gate ships with one line saying "I made it red once, by doing X". For each thing you build, break it, watch the check fail, restore it — and put that evidence in your report. w1's ~/w7/p5-w1-redcheck.py is a working example of automating exactly this.

Write ~/w7/notes/p5/p5-results/v1-v1.md and return ≤200 words: commit range, acceptance numbers, whether the first inproc frame renders, and the three things c1 and the integrator most need to know.