Files
MobileGL/docs/Disaggregated/notes/p5/p5-results/s1-v1.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

514 lines
36 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# s1 — session and transport, v1
Branch `p5/s1`, worktree `~/w7/p5-s1`, base `feat/disaggregated @ 5175f9cc`.
**Commit range `5175f9cc..4cf59428`, four commits.**
| # | commit | what |
|---|---|---|
| 1 | `5f6c2eca` | `Transport/`: `SessionSegments`, `SessionProducer`, `SessionConsumer`, the `Watermark` namespace, `ReplySlot.h`, `EventRing.h`, `RoleMemory.h` |
| 2 | `0ff8dbde` | `protocol.fbs` + regenerated header |
| 3 | `b0857f38` | `ClientSession`, `ServerSession`, `CapsAbiFingerprint`, `ReplyPool::PostReply` |
| 4 | `4cf59428` | `MG_Test/Wire/SessionTest.cpp` (18 cases) + its CMake entry |
No new `.cpp` was added to the root `CMakeLists.txt`: every new implementation went into a file
the disaggregated source list already carries (`Transport/Ring.cpp`, `Transport/ShmSegment.cpp`,
the two session `.cpp`s) and everything else is a header. That is deliberate — w1, c1 and v1 all
have new files to declare and the P4a lesson was that they would all append at the same point.
**If a later package needs a new `.cpp` under `MG_Remote/`, it is the first one, and it should go
through the integrator so the four appends are one edit.**
---
## 1. Acceptance numbers
### 1.1 The four self-tests
| gate | result |
|---|---|
| **G1** (`symbol_report.py --threshold 0`, `~/w7/p5-before-libMobileGL.so` → `build-linux/libMobileGL.so`) | `.text 10806323 -> 10806323 (+0, +0.000%)`; `27811 -> 27811 defined symbols: 0 added, 0 removed, 0 resized, 0 renamed` |
| **four build dirs** | pull / push / verify / split all `rc=0`; `CTestTestfile.cmake` confirmed present in each before any verdict was reported |
| **`ctest -L unit`** | pull **1785/1785**, push **1785/1785**, verify **1785/1785**, split **1860/1860** (the 1842 baseline + s1's 18) |
| **`ctest -L integration-gpu`** in `build-push` with `MOBILEGL_TRANSPORT=monolith` | **1117/1117**, and `build-push`'s full `ctest -N` list is **byte-identical** to `~/w7/p5-before-ctest-names.txt` (2902 names) — G2/G14 |
| **generators** | `gen_pipe.py --check` up to date; `--self-test` 9 negative-control trips + positive control OK; `gen_pipe_dirty_surface.py --check` clean; **`gen_protocol.py --check` clean** after the schema edit |
| **purity** | `check_include_closure.py`: 4 probes, 0 skipped, **0 problems** — every new `Transport/` header stays clear of `MobileGL/Includes.h` |
| **`nm` role check** | pull `MG_Remote` symbols **0**; split **275** |
Existing Wire suites unmoved: `ctest -R '^Ring|^Doorbell|^Framing|^FdPassing|^InProcessTransport|^Protocol|^Session'`
in `build-split` = **75/75** (52 pre-existing + c0's 5 + s1's 18). **`ProtocolSmokeTest.cpp` was not
edited**, including its `UnionTagsAreFrozenWireValues` case — the schema change was not a wire break.
### 1.2 What `SessionTest` pins (18 cases)
* `SessionSegmentsAreRealSharedMemoryAndNotAHeapAllocation` — the four segments carry real
descriptors. This is the mechanical check that `inproc` did not quietly become `new[]`.
* `TheRingIsTheLargestPowerOfTwoLeftAfterTheControlPage`, `TheDefaultGeometryIsTheFourContractSizes`
— the geometry, including the deviation in §2.1.
* `TheMemoryLedgerIsPerRoleAndIsReleasedOnClose` — the peak-RSS hooks t1 consumes.
* `TwoThreadsMoveTwentyThousandRecordsAndAgreeOnEveryOne` — the acceptance run, over a 32 KiB
ring so it wraps ~10 times and the filler is under load rather than in one contrived case.
* One case per watermark rule: `SubmittedSeqIsThePublishersAndIsPurelyDiagnostic`,
`AppliedSeqAdvancesExactlyOncePerRecordAndIsNeverBatched`,
`RetiredSeqMayTrailTheApplyButCanNeverOvertakeIt`,
`CompletedFrameSerialIsTheServersAndIsIndependentOfAppliedSeq`,
`PresentAckSerialIsWaitedOnWithGreaterOrEqualAndWakesThroughTheReverseBell`.
* `AWrapFillerDoesNotAdvanceTheSessionsAppliedSeq` — R-9's last sentence, against the session's
own counter rather than against `Pop`'s behaviour (RingTest already pins that half).
* `AReplyIsAddressedBySeqAndCarriesItsSeqBackForSelfCheck` (seq 13 must NOT read seq 5's answer
out of slot 5), `DeclinedIsARealAnswerWithNoPayload`, and a **death test** for "a reply larger
than its slot is Fatal, not truncated".
* `TheEventRingCarriesTheThreeReverseCallbacks`, `AFullEventRingLatchesTheFlagRatherThanDecidingWhatToDoAboutIt`.
* `ShutdownUnparksTheApplyThreadAndTheJoinIsBounded` — `InProcessTransportTest.cpp:344`'s shape,
5 s bounded with `detach()` on timeout, so a lost wakeup is red and not a wedged CI job. It
also asserts that a producer blocked in the **verb barrier** comes back as `ShutDown`.
* `TheAbiFingerprintChangesWhenAnyOfItsInputsDoes`.
---
## 2. Rulings I made that the brief and the contract did not
Each says what would overturn it.
### 2.1 The command ring is 4 MiB, not 8, and one record is capped at 2 MiB, not 4
`CONTRACT-P5 §5` and `Config.h`'s `MOBILEGL_IPC_RING_MB` comment both say "8 MiB caps one record
at 4 MiB". **That arithmetic treats the whole segment as ring bytes and does not subtract the
control page.** `Ring.h:11-13` puts `RingControl` at the HEAD of SEG_CMD, it is 4096 bytes by
`static_assert`, and `RingProducer` requires a POWER-OF-TWO capacity because the indexing is a
mask (`Ring.cpp:89-103`). So an 8 MiB SEG_CMD leaves 8 MiB − 4096, and the largest power of two
that fits is **4 MiB** → `MaxRecordBytes() == 2 MiB`.
I took the deviation in the direction that is safe: **the announced `SegmentRef.sizeBytes` stays
the four pinned numbers** (8 / 32 / 8 MiB + 256 KiB, `ProtocolSmokeTest.cpp:72`) and the ring
inside SEG_CMD is half of its segment. R-10's obligation is to PROVE no record approaches the
cap, and a lower cap makes that proof fire earlier and louder rather than later and silently.
Two alternatives, both rejected and why:
* announce `sizeBytes = 4096 + 8 MiB` — breaks the four sizes the brief says to copy and that
`ProtocolSmokeTest.cpp:72` pins, and is the number a P6 peer has to `mmap`;
* move `RingControl` out of SEG_CMD — needs a fifth `SegmentRef` that `Welcome` does not have.
**SEG_STAGE is unaffected**: `RingControl` holds TWO cursor triples and the stage triple is the
second, so SEG_STAGE has no control page of its own and 32 MiB is already a power of two.
SEG_EVENT gets its own control page (a third cursor set would resize the 4096-byte shared page),
so its 256 KiB yields a 128 KiB ring.
**Overturned by**: a decision that `SegmentRef.sizeBytes` may carry `ring + one page`; or a
`RingProducer` that accepts a non-power-of-two capacity.
### 2.2 `CapsSnapshot` gains `callMask` and `backendType`; `Hello`/`Welcome` gain `abiFingerprint`
Table 0 deletes four `CapsSnapshot` fields and **names no carrier for `MGPCaps::CallMask`** — but
R-8/C-4 makes `CallMask` the *only* legal client-side source of "does the server consume this
family", and `dynamicParameters` is the image of `DynamicBackendParameters`, which `CallMask` is
not a member of. Without a carrier, R-8 is unimplementable for a second time. Likewise
`CapsMirror::Backend()` must return the **server's** `BackendType` and nothing on the control
plane carried it (`Hello.backendType` is the client's request).
Four appends, all safe: the deleted four were the LAST four fields, so no surviving field moved a
vtable slot, and every addition is at the end.
| table | added | why |
|---|---|---|
| `CapsSnapshot` | `callMask: ulong` | R-8/C-4's consumer mask + the nine `MGPCapBit`s |
| `CapsSnapshot` | `backendType: uint` | `CapsMirror::Backend()`; frontend branches take a wrong arm rather than fail on a value they do not know |
| `Hello` | `abiFingerprint: ulong` | table 0's ABI agreement; `Hello` already carried the string, not the sizes |
| `Welcome` | `buildFingerprint: string`, `abiFingerprint: ulong` | the server's half of the same assertion; the string is only so the Fatal can name both builds |
**Overturned by**: folding `CallMask` into the head of the `dynamicParameters` blob (cheaper on the
wire, worse to read), or carrying the server's backend type inside `rendererInfo`.
### 2.3 The SERVER creates all four segments; the client attaches
`Welcome` announces all four `SegmentRef`s and `Welcome` is server → client, and
`ServerSession::Accept`'s own doc comment says "maps the four segments". "Client-owned" in
`protocol.fbs`'s comments is about who WRITES a segment, not who allocates it. Under `inproc` the
client attaches to the same mapping under its own ledger role; under `spawn` that call becomes
`ShmSegment::Adopt` of the fds the server passed by SCM_RIGHTS, which is why nothing below
`SessionSegments` knows which it was.
### 2.4 Reply pool geometry: **8 slots of 1 MiB**
`ReplyPool::SlotBytes()` is "sized from the scenario's largest read rather than guessed", and the
trade is the opposite way round from the obvious one: **while the verb barrier holds, the in-flight
depth is exactly ONE**, so every extra slot buys nothing except a smaller maximum answer. 8 MiB /
8 = 1 MiB, which covers a 512×512 RGBA8 `ReadPixels`. The slot count must be a power of two (the
addressing is a mask, and a division on the apply thread in the reply path of every blocking call
is not free). **Overturned by**: t1's scenarios needing a bigger single read, which is spelled as a
*lower* slot count, not a higher one. P9 re-chooses the whole geometry when it makes the pool
asynchronous.
### 2.5 `ReplyPool::PostReply` is implemented inside v1's `PipeApplier.cpp`
The SEG_REPLY slot pool is s1's deliverable (BRIEF §5) but c0 declared the class in
`Server/PipeApplier.h`, which is v1's file. The resolution: the addressing lives once, in
`Transport/ReplySlot.h`, which the CLIENT reads the same slots back through; `PostReply`'s body is
a two-line delegation that rebuilds the view from `ReplyPool`'s existing four members. **v1's
header is untouched, `ReplyPool`'s members are untouched, and every `PipeApplier::*` body is
untouched** — the diff in v1's file is one `#include` and one function body.
### 2.6 The consumer mask and the cap bits are setters with derived defaults, and v1 owns the answer
**Nothing in the tree produces `MGPCaps::CallMask`** — it is declared at `MGPipeTypes.h:133` and
written by nobody. So `ServerSession` takes both halves through setters:
* `SetConsumedSubsystems(mask)`. The default derives from the only registration that exists:
`PipeFill.cpp:920`'s `P4aFamilyHasItsConsumer` says every P4a family hangs off
`MGPipeGetResourceOps()` and that there is deliberately "no per-family registration to add", so
the default is `kMGPipeSubsystemsMigratedAtP2` when that table is null and
`kMGPipeSubsystemsMigratedAtP4a` when it is not. **This is a default, not a ruling — v1 should
confirm or replace it.** Publishing a bit the server does not consume is ID-39's shape from the
other side: the client emits and nothing applies.
* `SetCapabilityBits(bits)`. The default sets only `kCapResidentSubData`, from
`MGPipeResourceOpsHaveSubDataResident()`. Every other bit is **0**, deliberately: R-15's
cross-cutting rule is that a cap bit set on a guess answers "supported" for a path that does not
exist, which is how a split lane produces a plausible picture for the wrong reason.
`kCapNeedsHostIndexBytes` / `kCapNeedsHostUboBytes` stay 0 for all of P5 by ruling.
### 2.7 Doorbell placement — contract §3.9, implemented as ruled
The two accessors stay **off** `ITransport`. `ServerSession::ConsumerDoorbell()` /
`ProducerDoorbell()` resolve the pair from `ITransport::Role()` in **one switch in one file**, and
P6 adds one arm there rather than two virtuals every transport has to find a home for. Everything
else takes `SessionProducer&` / `SessionConsumer&`, which already hold the right two references,
so no call site outside those two functions knows which bell is which.
---
## 3. What does NOT run yet, and why that is the honest answer
`ServerSession::Accept` and `ClientSession::Start` are complete and compile, and each runs
end-to-end until it reaches a dependency that has not landed:
| call | stops at | owner |
|---|---|---|
| `ServerSession::Accept` step 5 | `Wire::SegmentTable::Install` / `InstallProcessResolver` | **w1** |
| `ServerSession::PublishCapsSnapshot` | `EncodeFormatCapabilities` / `EncodeRendererInfo` | **w1** |
| `ClientSession::Start` step 8 | `ServerLoop::Start` | **v1** |
| `ClientSession::EmitAndWait` | still c0's stub — the barrier is c1's | **c1** |
All four are c0's named-Fatal stubs and they abort loudly. **I deliberately did not route around
any of them**: a session that skipped `Install` and carried on would be a decoder with no segments,
which is the "split lane ran monolith and went green" shape the whole phase exists to prevent. The
consequence is that `SessionTest` pins the **Transport-level** session pair — which is the
ring-owning object scout-transport §3/§7.1 and the exit gate are actually about — and not the two
role classes. The first end-to-end `Accept` runs the day w1 lands.
s1 supplies the four primitives c1's `EmitAndWait` composes from, so that the barrier's wait and
the reply's wait stay ONE wait (R-3/R-5): `Encoder()`, `Producer()` (publish → submittedSeq →
ring, in that order), `WaitForApplied(seq, timeoutMs)`, `ReadReply(seq, …)`.
---
## 4. Where I think the brief or the contract is wrong
1. **§5's "8 MiB caps one record at 4 MiB" is off by 2×** — §2.1 above. `Config.h`'s
`MOBILEGL_IPC_RING_MB` comment carries the same arithmetic and should be corrected with it.
2. **Table 0 deletes `tableSlotMask` without giving `MGPCaps::CallMask` a carrier**, which leaves
R-8/C-4 unimplementable for the same reason R-8 was unimplementable before c0 fixed it — §2.2.
The contract's §6.1 argues against "a SECOND mask field", which is not the same as arguing
against the first one.
3. **`CapsSnapshot` has no carrier for the server's `BackendType`** and `CapsMirror::Backend()`
needs one — §2.2.
4. **The brief's "`Welcome`'s four `SegmentRef` sizes … 照抄" and §5's record cap cannot both be
satisfied**, because the control page has to come out of one of them. I kept the announced
sizes; the integrator should say if that was the wrong half to keep.
---
## 5. Accounts left open
* **P6 (spawn).** `SessionSegments::AttachInProcess` is the one function that becomes an
`ShmSegment::Adopt` path; `ConsumerDoorbell`/`ProducerDoorbell` gain one `SocketTransport` arm
each. `Welcome`'s four `SegmentRef`s are already cross-checked against the server's real mapping
on the client side, so the assertion that would otherwise first run in P6 runs today.
* **P9.** SEG_EVENT's overflow POLICY. The mechanism is here — a full ring latches
`eventRingFull`, a dropped lossy event counts in `eventDropped`, and `EventRingProducer::Reserve`
returns nullptr rather than deciding — but nothing chooses between blocking, dropping and
escalating. The reply pool's geometry is P9's too, once seq becomes "the id's initial value".
* **P7.** The fixed-width `DynamicBackendParameters` rewrite that would make
`CapsAbiFingerprint()` unnecessary.
* **The git stamp inside the fingerprint is weak and is there for diagnostics.** `GIT_COMMIT_HASH_SHORT`
is captured at CMake CONFIGURE time, so an incremental build after a commit still reports the
configured hash (this is the same trap as `android-build-bisect-traps`). The three `sizeof`s are
the load-bearing inputs; under P6's same-machine same-binary spawn all four are trivially equal.
* **Duplication.** `ReceiveEnvelope` + `ParseEnvelope` + `FatalAbiMismatch` are ~30 lines repeated
in `ClientSession.cpp` and `ServerSession.cpp`. Left as-is because factoring them out needs a new
header under `MG_Remote/` and both copies are s1's; worth folding into whatever control-plane
helper P6 needs anyway.
* **`MOBILEGL_IPC_ADOPT_TIER`, `PERSISTENT_BLOCK_KB`, `STRICT_ERRORS`, `AUDIT`, `SERVER_AFFINITY`,
`SERVER_PATH`** are parsed by c0 and read by nobody in s1's surface — they belong to b1, p1 and
v1. s1 reads `RingMb`, `StageMb`, `SpinUs` and `VerbBarrier`.
---
## 6. Files
Owned and changed: `MG_Remote/Transport/{SessionRings.h, ReplySlot.h, EventRing.h, RoleMemory.h}`
(new), `Transport/{Ring.cpp, ShmSegment.cpp}`, `MG_Remote/Protocol/{protocol.fbs,
generated/protocol_generated.h}`, `MG_Remote/CapsCodec.cpp` (the `CapsAbiFingerprint` half only),
`MG_Remote/Client/ClientSession.{h,cpp}`, `MG_Remote/Server/ServerSession.{h,cpp}`,
`MG_Test/Wire/{SessionTest.cpp, CMakeLists.txt}`.
Touched outside my ownership, minimally and by necessity: `MG_Remote/Server/PipeApplier.cpp` —
one `#include` and `ReplyPool::PostReply`'s body (§2.5). **No `PipeApplier::*` body, no header, no
`.def`, no generator, no root `CMakeLists.txt`.**
Logs kept: **`~/w7/p5-s1-round2.log`** — the whole final acceptance in one file (four builds, G1,
purity, generators, the four unit lanes, integration-gpu, the name identity, the flake hunt) — plus
`~/w7/p5-s1-symbols.md`, `~/w7/p5-s1-names-push.txt`, and the scripts
`~/w7/p5-s1-{gate,verify2,cfg,setup,submodlinks,genproto}.sh`. `~/w7/p5-s1-flatc-build/flatc` is the
pinned flatc, kept so `gen_protocol.py` re-runs without a rebuild.
---
# 7. Fix round 1 — against `s1-review-v1.md` (1 BLOCKER, 8 MAJOR, 7 MINOR, 3 QUESTION)
**Commits `4cf59428..7c8d2b44`, five.** `7eff493d` B-1, `0732e1bb` M-1, `31099ef7` the Transport
MAJORs, `ffa90ccc` the Client MAJORs, `7c8d2b44` the seven new cases.
The review is right on every finding I could check, including the two it graded as judgement calls,
and it is right about the thing I got most wrong: **§2.1's rejection of the zero-cost geometry was
false on the facts, and I should have checked `ProtocolSmokeTest.cpp` before citing it.** It
constrains the schema's ability to carry a number, not what a session announces. Everything below
is what changed; where I did not change something I say why in one line.
## 7.1 Acceptance, re-run in full at `7c8d2b44`
| gate | result |
|---|---|
| four builds | pull / push / verify / split all `rc=0`, `CTestTestfile.cmake` confirmed first |
| **G1** `--threshold 0` | `.text 10806323 -> 10806323 (+0, +0.000%)`; `27811 -> 27811 defined symbols: 0 added, 0 removed, 0 resized, 0 renamed` — unmoved |
| `ctest -L unit` | pull **1785**, push **1785**, verify **1785**, split **1867** (1842 baseline + 25), 0 failed |
| `ctest -L integration-gpu`, `build-push`, `MOBILEGL_TRANSPORT=monolith` | **1117 / 1117** |
| `ctest -N` name set vs `p5-before-ctest-names.txt` | **identical**, 2902 names, sorted diff 0 lines |
| `gen_protocol.py --check` | clean — the committed header is byte-identical to what the pinned flatc produces from the edited schema |
| `gen_pipe.py --check` / `--self-test` | up to date; 9 negative-control trips, positive control OK |
| purity | `4 probes, 0 skipped, 0 problem(s)` |
| `nm` role check | pull `MG_Remote` **0**, split **282** |
| **flake** | whole Wire lane (82 tests) `-j 8` × **8 reps**: 0 failing reps. `SessionTest --gtest_repeat=30`: 25 × 30, `rc=0` |
One observation that is NOT drift and should not be read as one: `gen_pipe_dirty_surface.py
--check` prints a census line whose "N members are written outside those roots" went 385 (base) →
427 (here). `--check` returns **0** and no generated artifact is dirty; `git diff` over
`MG_State/GLState`, `MG_Impl` and `MG_Pipe` against the base is **empty**. The number moves because
that count is over writes found anywhere outside `STATE_ROOTS` and the script states its own
imprecision in the same line — "a FIELD token is not scoped to a type" — so `MG_Remote`'s new
members (`m_slots`, `m_appliedSeq`, …) land in it. It only ever WIDENS the undecided set. My gate
script's `| tail -1` shows that census instead of a verdict; that is a reporting wart in
`~/w7/p5-s1-gate.sh`, not a result.
## 7.2 BLOCKER
**B-1 — fixed, and the fix is the absence of a mechanism rather than a better one.**
`DeriveConsumedSubsystems()` and `DeriveCapabilityBits()` are **deleted**, and with them the reads
of `MGPipeGetResourceOps()` and `MGPipeResourceOpsHaveSubDataResident()` (both includes removed).
`ServerSession::CallMask()` now calls `FatalUnsetCallMask` — `MGLOG_F` + `std::abort`, named
`Fatal{UnsetCallMask}` — when either half was never set, so the omission is loud at the **first
CapsSnapshot** instead of silent for a phase. `PublishCapsSnapshot` reaches it before it builds a
buffer. `Accept` additionally emits one `MGLOG_W` when the mask is unset, in the same shape as the
existing missing-backend line, so the warning arrives even for a session that publishes no snapshot.
`CallMaskIsSet()` is the non-fatal probe for a caller that can handle the absence.
Both setters are mandatory, not just the consumer one. `SetCapabilityBits(0)` is a legitimate and
explicit answer — "this server offers no optional capability" — and is the right call while the
packages that own each bit land; what is refused is *not saying*. The reviewer's severity note
("downgraded to MAJOR by any mechanism that makes an unconfirmed mask loud or fatal") is the exact
shape of what landed.
## 7.3 MAJOR
**M-1 — fixed, `(deprecated)`.** The four retired `CapsSnapshot` fields keep their declarations with
`(deprecated)`, so slots **14 / 16 / 18 / 20 stay burned** and `callMask` / `backendType` moved to
**22 / 24** (verified in the regenerated header). No ABI-major bump, no wire break, no accessor
generated for the retired names. My original report's "four appends, all safe … every addition is at
the end" was wrong in flatbuffers' sense and the reviewer's reading of the base header is correct.
The report's "`ProtocolSmokeTest` was not edited … so the schema change was not a wire break" was a
non-sequitur; that file pins union tags and enum values only. **`SessionTest.CapsSnapshotFieldIds‑
AreFrozenAndTheRetiredSlotsStayBurned` is now the first test in the tree that pins a table field id**,
and it covers the `Hello` / `Welcome` appends too.
**M-2 — fixed.** `SizesFromConfig()` is called whenever `SetSegmentSizes` did not run
(`m_sizesSet`), instead of behind a condition that could never be true. `MOBILEGL_IPC_RING_MB` and
`_STAGE_MB` now reach the mapping. My §5's claim that s1 "reads RingMb, StageMb, SpinUs and
VerbBarrier" is true as of this commit and was not before.
**M-3 — fixed in both files.** `envelope->msg_as_Hello() == nullptr` / `msg_as_Welcome() == nullptr`
are now part of the same guard as the tag check. `SessionTest.AVerifiableFrameCanCarryANullUnion‑
Payload` builds the reviewer's 24-byte shape and asserts that it verifies, carries the identifier,
reports `msg_type() == Hello` and hands back `nullptr` — so the guard cannot be simplified away by
someone who assumes verification implies a payload.
**M-4 — fixed.** `Stop()`'s `!m_started` branch closes the client's view, then
`ServerSessionInstance().Close()`, then the transports — so the five post-`Accept` failure paths no
longer leave the server `m_accepted` (which made every later `Start` return
`MOBILEGL_ERR_INVALID_ARGUMENT` for the life of the process), no longer leave the process resolver
installed, and no longer destroy a transport that `ServerSession` still points into.
**M-5 — fixed.** `SessionConsumer::ApplyOne` now tracks `m_retirableCursor`, which stops AT the
first `kRecBorrowSlot` record and does not move again until `RetireBorrowedUpTo` releases it;
`RetireThrough` publishes through `PublishRetiredUpTo` instead of `PublishRetired`, which stored the
local tail into both tails and handed back every popped byte. `PublishRetiredUpTo` now has a caller.
`SessionTest.ABorrowedSlotIsNotHandedBackUntilItIsReleased` asserts `cmdRetiredTail <
cmdAppliedTail` while the borrow is held, and equality after the release, with `RingCursorsValid` at
both points. The header comments and the code now say the same thing.
**M-6 — fixed, the reviewer's alternative.** `AttachInProcess` dups each of the owner's descriptors
and goes through `ShmSegment::Adopt` + `Map` on POSIX, so the inproc peer has **its own mapping,
its own fd and its own lifetime** — the attach half, which is exactly what P6 replaces with an
SCM_RIGHTS adopt, is exercised now, and the raw aliasing that made M-4's ordering load-bearing is
gone. Windows still aliases (there is no `Adopt` there; the section travels by name) and now says so
in place. `SessionTest.TheInprocPeerGetsItsOwnMappingOfTheSameSharedMemory` pins different fds,
different virtual addresses, stores visible in both directions, and an owner unaffected by the
peer's `Close`. The `SessionTest` fixture was rewired so each role drives its own mapping, which is
the shape spawn has.
**M-7 — fixed by taking the alternative, not by correcting the documents.** The knob now names the
**ring** and the segment is `ring + one control page`: `SessionSegmentSizes` is `CmdRingBytes` /
`StageRingBytes` / `ReplyBytes` / `EventRingBytes`, and `SegmentBytesForRing()` is the one place the
page is added. So SEG_CMD's ring is 8 MiB, `MaxRecordBytes()` is **4 MiB**, and CONTRACT-P5 §5 and
`Config.h:471-473` are **true as written** — no edit to either of c0's files is needed, which is the
better outcome since neither is mine to change. It also reclaims the 4 190 208 + 129 920 bytes that
were mapped and unreachable. `SegmentRef.sizeBytes` announces the mapping size (`8 MiB + 4096`),
which is what a spawn peer must `mmap`; the four numbers a reader recognises are the ring sizes,
which is what the knobs name. **My §2.1 above is superseded by this section** and its citation of
`ProtocolSmokeTest.cpp:72` was wrong.
**M-8 — fixed.** `AdvanceMonotonic` on a backwards move is now `Fatal{ProtocolCorruption,
"watermark"}` rather than an `MGLOG_E` and a return, because the logged version left every later
advance a no-op and every `WaitForApplied(kWaitForever)` blocked for ever — a hang with one ERROR
line. `SessionTestDeath.AWatermarkThatMovesBackwardsIsFatalRatherThanIgnored` is the control.
One consequence, handled at the one boundary where a stale argument is legitimate:
`SessionProducer::PublishAndNotify` clamps its `submittedSeq` argument **up** to
`m_lastPublishedSeq` before publishing, because republishing an older bound (teardown does exactly
that) is publishing LATE, which R-9 permits, and is not the same thing as a watermark moving back.
## 7.4 MINOR
| # | disposition |
|---|---|
| **m-1** | Fixed. `m_owns = true` moves **before** the create/map loop, so `Close()` on an in-loop failure really closes segments 0..n-1 as `ShmSegment.h:66` promises. |
| **m-2** | Fixed. `RoleMemory.h`'s comment now says INFO, matches the implementation, and names the grep tag `MG_Remote memory[`. |
| **m-3** | Fixed. The three post-attach failure paths in `Accept` call `Close()` rather than `m_shm.Close()`, so `m_consumer` / `m_replies` / `m_events` / `m_transport` are not left pointing into unmapped memory. |
| **m-4** | Fixed as far as it can be without an atomic header: the pool now REFUSES a geometry whose slots would not be 8-aligned, and a base that is not itself 8-aligned, so the 8-byte `Seq` the self-check reads is always naturally aligned. `SessionTest.AReplyGeometryThatWouldMisalignASlotHeaderIsRefused`. Making the stamp a real `std::atomic_ref` is P9's, together with the widening m-5 asks for. |
| **m-5** | **Not fixed; written into the accounts.** A drift of exactly `slotCount` lands on the same slot with a matching stamp. It cannot arise under R-1's depth-1 barrier, and the fix (a generation beside the seq) belongs with P9, which is what removes the barrier. Named in `ReplySlot.h`'s header so it is not rediscovered. |
| **m-6** | Fixed by documentation, where the defect was. `RetireThrough`'s comment now says IT IS MANDATORY and why — `FreeBytes()` reclaims against `retiredTail` only, so an apply loop that never calls it wedges the producer on the first full ring. v1 writes that loop. |
| **m-7** | Fixed. `ReplySlotPool::m_size` and `ClientSession::m_caps` are gone; `ClientSession` reads `MG_Config::Ipc` through two `#if MOBILEGL_BUILD_DISAGGREGATED` helpers, the shape `ServerSession` already used. |
## 7.5 QUESTION
**q-1 — changed.** `SessionProducer::LastPublishedSeq()` is the producer's own count and teardown's
drain uses it instead of `RingControl::submittedSeq`, which `Ring.h:72-77` explicitly permits to
lag. Under `MOBILEGL_IPC_VERB_BARRIER=0` the two differ and the old drain would have under-waited
and freed an emitter-owned var-tail while a record still named it.
`SessionTest.TheProducerRemembersWhatItPublishedEvenIfTheWatermarkLags`.
**q-2 — changed.** `SessionConsumer::CompleteFrame` / `ReturnPresentCredit` advance **and** ring;
`ServerSession`'s two methods delegate to them. The free functions in `namespace Watermark` stay
advance-only and now say so in the header, because the advance and the doorbell are two separate
stores and only the pair is a wakeup.
**q-3 — changed.** `ServerSession::PublishEvents()` is the sanctioned path and picks the bell
itself; `EventRingProducer::PublishAndNotify`'s two-argument form stays for the test that drives the
ring directly, with a header line saying to prefer the session's.
## 7.6 What fix round 1 changed in the accounts
* **`SetConsumedSubsystems` / `SetCapabilityBits` are now blocking for v1**, in the literal sense:
a server that publishes a snapshot without calling both aborts. That is deliberate and is the
whole of B-1's fix. v1 should call them where it registers the backend.
* **The record cap is 4 MiB again**, so CONTRACT-P5 §5's arithmetic is the one to size against and
the correction I asked for in §4.1 is withdrawn. §4.2/§4.3 (no carrier for `CallMask`, none for
the server's `BackendType`) still stand.
* **`RetireThrough` is mandatory** for whoever writes the apply loop, and
`RetireBorrowedUpTo(cursor)` is how a borrowed slot comes back once `completedFrameSerial` passes
it. Nothing sets `kRecBorrowSlot` yet.
* The duplication noted in §5 (`ReceiveEnvelope` / `ParseEnvelope` / `FatalAbiMismatch` in both
session `.cpp`s) is unchanged and still worth folding into whatever control-plane helper P6 needs.
---
# 8. Fix round 2 — w1's `SEG_STAGE` ruling, and the flag-space collisions
**Commit `69cf5a0c`** (branch total `5175f9cc..69cf5a0c`, 10 commits). Something did need to change.
## 8.1 Who owns the stage cursors now: NOBODY, and that is now pinned
The integrator's first question answers clean: **no `RingConsumer` is or ever was constructed over
`RingCursorSet::Stage`** anywhere in `ClientSession`, `ServerSession` or the test fixture. The
second question did not: I was constructing a stage **`RingProducer`**, held by `SessionProducer`,
published by `PublishAndNotify` and waited on by `WaitForStageSpace`. With w1's encoder owning
staging, that is the half-wiring the integrator warned about, and it is not merely dead — it is a
**guaranteed hang**: the producer publishes `stageHead`, nothing advances `stageAppliedTail` or
`stageRetiredTail`, so `FreeBytes()` reaches 0 the first time the head laps the capacity and never
recovers, and `WaitForStageSpace` blocks for ever after the first 32 MiB of staging.
Removed: `SessionProducer::m_stage`, its `Attach` parameter, `Stage()`, `WaitForStageSpace()` and
the stage `Publish()`; `ClientSession::m_stage`; the fixture's `stageProducer`.
`PipeWireEncoder`'s `stage` argument is now `nullptr` — c0's signature predates w1's ruling, the
encoder reaches SEG_STAGE through the `SegmentTable` view, and `nullptr` is the honest value.
**Flagged for w1 / the integrator**: if w1's encoder still wants that parameter, the fix is to
delete it from the signature, not to hand it a producer over a triple nobody consumes.
`RingControl`'s stage triple is **kept and documented**, not removed: `RingCursorSet`, Ring.cpp's
three cursor accessors and `RingTest`'s fixture are all written against a two-triple page, and
P8/P11's shadow and adopt segments are the ring-shaped users it was reserved for. Ring.h now carries
a paragraph saying it is dead in P5 on purpose, who owns staging instead, and what the middle state
costs — and `SessionTest.TheStageCursorTripleStaysDeadAcrossAWholeSession` drives 500 records through
SEG_CMD and asserts all three stage cursors are still **0** while `cmdHead` and `retiredSeq` moved.
That is the difference between "on purpose" and "forgotten": one of them is a test.
**`retiredSeq`'s text was already right** and needed no change — Ring.h's watermark table, the
`Watermark::AdvanceRetired` comment and `SessionTest.RetiredSeqMayTrailTheApplyButCanNeverOvertakeIt`
all say the staging allocator reclaims behind `retiredSeq`, which is exactly w1's allocator. What
*was* wrong is now fixed: three places called SEG_STAGE a ring (`SessionRings.h`'s header block,
`ShmSegment.cpp`'s `DeriveViews`, one `SessionTest` comment). `SessionSegmentSizes::StageRingBytes`
→ `StageBytes`, `SessionSegments::StageCapacity()` → `StageBytes()`, and **the power-of-two rounding
is gone** — it was a ring requirement, and keeping it would have silently turned an operator's
`MOBILEGL_IPC_STAGE_MB=24` into 16, which is M-2's class of defect one knob along.
## 8.2 The flag-space collisions
`RingRecordHeader::flags` is read in exactly two places of mine, and there are **three** colliding
bits, not one — w1's `kReplySlot ≡ kRecVarTail` is the least dangerous of them:
| bit | `MGPipeCallFlags` | `RingRecordFlags` | consequence if a call's flags reach the header |
|---|---|---|---|
| 2 | `kVarTail` | `kRecPad` | **worst**: `Pop` skipped every var-tail record as a wrap filler, silently, record lost, nothing logged |
| 3 | `kHostSpan` | `kRecBorrowSlot` | my `ApplyOne` stops reclaiming ring bytes behind it — the producer wedges on the first full ring |
| 4 | `kReplySlot` | `kRecVarTail` | a blocking call reads as having a tail it does not have |
Translating is the encoder's job, but neither of my two readers now depends on it:
* **`RingConsumer::Pop` requires a filler to carry `kRecPad` AND `kind == kRingPadRecordKind`.** A
genuine filler always does (Reserve writes it); a call record always carries a real opcode,
because the catalogue starts at 1. One comparison turns a lost record into a delivered one.
`SessionTest.ARecordWearingThePadBitIsDeliveredRatherThanEatenAsAFiller`.
* **`SessionConsumer` counts and names every `kRecBorrowSlot` sighting** (`BorrowedRecordsSeen()`,
one `MGLOG_E` on the first). P5 implements no borrowed slots and is ruled to produce no host spans
either, so the bit arriving *is* the collision; the conservative arm is still taken, but a
producer that then wedges has a line saying why.
`SessionTest.ABorrowSlotSightingIsCountedRatherThanJustActedOn`.
* Four `static_assert`s in `ServerSession.cpp` — the nearest `.cpp` that legally sees both headers,
since nothing under `Transport/` may reach `MobileGL/Includes.h` — pin all three collisions and
the two bits that agree, so a renumber of either enum is a build break rather than news. Ring.h's
`RingRecordFlags` carries the table in prose.
## 8.3 Reply-pool sizing from `MGPipeCallFlagsFor` — not yet, by instruction
`kDefaultReplySlotCount` is still 8 and is still justified by depth, not by a count of
`kReplySlot` rows (§2.4: while the verb barrier holds the in-flight depth is one, so fewer slots
and bigger replies is the right trade). Nothing in my pool sizing hard-codes *which calls* have a
reply, so there is no false derivation to remove. I will switch the sizing to
`MGPipeCallFlagsFor` when the integrator says c0's four `Bool` acceptance rows have landed.
## 8.4 Acceptance, re-run in full at `69cf5a0c`
Every number from §7.1 reproduces, with the two test counts up: four builds `rc=0`; **G1 `.text
10806323 -> 10806323 (+0)`, `27811 -> 27811`, 0/0/0/0**; `ctest -L unit` **1785 / 1785 / 1785** and
split **1870** (1842 + 28); `integration-gpu` in `build-push` under `MOBILEGL_TRANSPORT=monolith`
**1117 / 1117** with the `ctest -N` name set identical to the 2902-name baseline;
`gen_protocol.py --check` clean; `gen_pipe.py --check` / `--self-test` clean; purity 4 probes /
0 problems; `nm` pull 0, split 282. Flake: the whole Wire lane (**85** tests) at `-j 8` × 8 reps,
0 failing reps; `SessionTest --gtest_repeat=30`, 28 × 30, `rc=0`. **`RingTest` is unmoved at 21/21**,
which is the check that mattered for the `Pop` change.