mirror of
https://github.com/MobileGL-Dev/MobileGL
synced 2026-11-18 23:43:23 +09:00
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.
514 lines
36 KiB
Markdown
514 lines
36 KiB
Markdown
# 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.
|