Files
MobileGL/docs/Disaggregated/notes/recovered/wf2/p0-polish-findings.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

28 lines
7.4 KiB
Markdown

# P0 polish package: findings from the final review of feat/disaggregated 8349babe..aa005720
All line numbers refer to the tree at aa005720 (~/w7/pipe). Fix every item below.
## MAJOR
### T-1 (transport, inproc doorbell has no death state -> Shutdown can never join a parked waiter)
`InProcessChannel::Close()` (MobileGL/MG_Remote/Transport/InProcessTransport.cpp:74-88) rings each `CondVarDoorbell` once and the comment at :83-84 claims this stops a peer parked mid-frame from hanging. It does not: `Doorbell::Wait` (Doorbell.h:136-176) consumes that one ring, re-tests `ready()` (false, nothing was published), tests `Dead()` - which `CondVarDoorbell` never overrides (Doorbell.h:113, :199-211; Doorbell.cpp:29-71 has no death state) - and with `kWaitForever` loops straight back into `Park()`, forever. `Shutdown()` of the inproc transport can therefore never join a server thread that is in the design's own steady state (consumer spins, sets consumerParked, then blocks). No test covers it (every `Wait` in MG_Test/Wire uses 5000/30/0 ms).
Fix: give `CondVarDoorbell` an `std::atomic<bool> m_dead` + `void Kill()` (set under the mutex, `notify_all`), override `Dead()`, make `Park` return false immediately when dead, have `Close()` call `Kill()` (keep `Notify()` for raw `Park` callers), and add `InProcessTransportTest.ShutdownUnparksAWaiterWithNoDeadline` (a thread in `Wait(parked, []{return false;}, kDefaultSpinUs, kWaitForever)`, `Shutdown()` from the test thread, join within a bound). Verify the test hangs (or times out) without the fix.
### T-2 (transport, ring accepts records it can never place -> silent producer stall)
Ring.cpp:126 only refuses `total > m_capacity`, but a record with `capacity/2 < total <= capacity` is unreservable at any offset where neither `spaceToEnd >= total` nor `offset >= total` holds, even in an empty ring: `Reserve` (:137-148) needs `spaceToEnd + total` bytes when a pad is required, which exceeds capacity there. Concrete: 256-byte ring, one 16-byte record written, popped and retired (head offset 16, FreeBytes()==256), `Reserve(1, kRecNone, 240)` (total 248) returns nullptr forever; a producer waiting on `FreeBytes() >= 248` deadlocks. For `total <= capacity/2` the worst case is `2*total-8 <= capacity-8`, so half is the correct bound.
Fix: reject `total > m_capacity / 2` at Ring.cpp:126 (same message, "half the ring"), state `Capacity()/2` as the chunking bound in Ring.h:169-174 and in the G3 chunking comment in MobileGL/MG_Pipe generated header comments / gen_pipe.py where the "record larger than the segment -> chunk" rule is stated, and add `RingTest.RecordLargerThanHalfTheRingIsRefused` plus the offset-16/248 scenario as the negative control (today it spins on nullptr).
### P-1 (interface hole: the six backend-owned compute limits have no carrier)
`MGPCaps` (MobileGL/MG_Pipe/MGPipeTypes.h:123-140) is `DynamicBackendParameters` + `CallMask` + two blobs, and `DynamicBackendParameters` (MobileGL/MG_Backend/BackendObject.h:316-530) carries `MaxComputeWorkGroupInvocations` but no per-axis `MaxComputeWorkGroupCount[3]` / `MaxComputeWorkGroupSize[3]`. Those six are exactly the backend-owned answers that survive the getter retirement (GL_Getter.cpp:1160-1177, MG_Util/ShaderTranspiler/CompileEnv.cpp:134-138, DirectVulkan.cpp:672-703 from VkPhysicalDeviceLimits), yet the .def footer (MobileGL/MG_Pipe/PipeCalls.def:143-145) repeats the disproved claim that "only GL_COMPUTE_WORK_GROUP_SIZE is a real backend answer and it lives in MGPCaps".
Fix: add `Int MaxComputeWorkGroupCount[3]; Int MaxComputeWorkGroupSize[3];` to `DynamicBackendParameters` and fill them in BOTH backends at capability init (DirectGLES from `glGetIntegeri_v(GL_MAX_COMPUTE_WORK_GROUP_COUNT/SIZE, i)` where the other limits are probed; DirectVulkan from `VkPhysicalDeviceLimits::maxComputeWorkGroupCount/Size`), keep the `GetIntegeri_v` table path working exactly as today (do NOT change GL_Getter/CompileEnv behaviour in this package - that is P0.5), add the unit/integration assertion that the new fields equal what `glGetIntegeri_v` answers (AdvertisedLimitsScenario is the natural home), and rewrite the .def footer to say the six limits live in MGPCaps and GL_COMPUTE_WORK_GROUP_SIZE is a frontend link artifact. Update the MGPCaps size assertion accordingly (it is a composition of sizeof(DynamicBackendParameters)+...).
## MINOR (one hygiene commit)
- S-1 stats: `PipeStats.cpp` `OnPresent()` does `store(0)` on `g_frameBytes/Calls/Gate*` which races with a concurrent `Bump` from another thread (buffer/texture staging is multi-threaded per the header): a frame-scoped add can be lost from the Tracy plot. Fix: `exchange(0, relaxed)` and plot the exchanged value.
- T-3 FdPassing.cpp:207-209: when `MSG_CMSG_CLOEXEC` is absent (macOS/BSD) received fds have no CLOEXEC; add `fcntl(fd, F_SETFD, FD_CLOEXEC)` for every received fd under `#if !defined(MSG_CMSG_CLOEXEC)`. Same platform: `MSG_NOSIGNAL` (FdPassing.cpp:136, Doorbell.cpp:94) is undefined there; `#ifndef MSG_NOSIGNAL` -> 0 plus `SO_NOSIGPIPE` on the socket.
- T-4 CMakeLists.txt:444-445: `set(... CACHE BOOL ... FORCE)` writes OFF into the cache, so after the operator runs `git submodule update` a plain re-configure still yields OFF with no message. Use a normal-variable `set(MOBILEGL_BUILD_DISAGGREGATED OFF)` (shadows the cache for this configure only) with the same message(WARNING).
- P-2 PipeCalls.def: three live GLFunctionsTable entries have no carrier: `GetGpuTimestampNs` (GL_Getter.cpp:1355/2265, glGetInteger64v(GL_TIMESTAMP), synchronous server answer), `QueryCounterTimestamp` (glQueryCounter, not a begin/end pair), `WaitSync` (GPU-side wait, distinct from FenceWait's client wait). Records are append-only: APPEND `QueryTimestamp` (kCtxQuery, kReplySlot), `QueryCounter` (kCtxQuery) and `FenceWaitServer` (kScreen) at the end of their groups' natural place BUT without renumbering any existing opcode (append to the end of the list if opcodes are positional), regenerate with gen_pipe.py, update the catalogue counts in the .def header and the PipeCatalogueTest expectations.
- P-3 MGPipeTypes.h:411-417 inlines a 32 B `MGHostSpan` in every `MGPBufferRange` of every class, and `MGPStreamOutputTargets` (:429-436) reuses it: 32 B/entry of dead space for SSBO/atomic/XFB records, and the plan's D-B8 says not to freeze this payload's shape before the `stage-ubo-named` numbers exist. Keep the range at 24 B and carry the named-UBO host span as an optional var-tail (flag kHostSpan on set_shader_buffers already exists) - adjust the payload, its field list, the size assertion and the test.
- P-4 (accepted in review 1, never reworked): ConfigLoader.cpp:164-183 `QueryEnvUint64` accepts `-1` and silently reads octal via `strtoull(...,0)` - parse base 10 (and 0x prefix explicitly if wanted), reject a leading '-' with the warning; test.yml pipe-gates stdio grep misses `fprintf(stdout` - extend the alternation; `MGPSubData` has no buffer offset/size convention - document (and if needed add) how the buffer half of resource_subdata expresses [offset,size) (e.g. UnionBox.x/w with target==Buffer) and assert it in the test; `gen_pipe.py` does not check that every call payload has a verify field list - make it fail when a payload named in PipeCalls.def has no entry in PipeFields.def (except the documented memcmp-fallback types), and add the check to `--check`.
- The first-review minor "MGPPixelPackState size assertion is tautological" (it asserts sizeof against itself): assert against the literal 28 that PixelStoreParameters measured.