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

34 lines
7.9 KiB
Markdown

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.