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.
43 KiB
c0 — contract package, v1
Branch p5/c0, seven commits, 41b4f8df..b4bbcc11, forked from feat/disaggregated @ a29807cc.
Worktree ~/w7/p5-c0. Nothing pushed; nothing merged.
41b4f8df [Fix] (MG_Pipe, gen_pipe): export the per-opcode call flags and give GetCaps and
CreateSamplerState the kHasBlob their payloads have always owned
ec20e700 [Feat] (Config, ConfigLoader): parse MOBILEGL_TRANSPORT and the MOBILEGL_IPC_* family
entirely behind the disaggregated option, so the pull build's symbol set cannot move
1ee6c895 [Build] (CMake): add MOBILEGL_BUILD_DISAGGREGATED_INPROC, make DISAGGREGATED imply
PIPE_PUSH, and list the new MG_Remote Wire/Client/Server sources
418e6f50 [Feat] (MG_Remote): land the P5 contract headers and their named-Fatal stubs so all
seven parallel packages compile and link on day one
72a4cba5 [Fix, Test] (MG_Test): include the header that defines MOBILEGL_PIPE_POISON - seven
emitter suites tested the macro without it, compiled the non-aborting arm, and turned
eighteen expected refusals into aborts the moment a disaggregated build armed it
dd4afb0f [Docs, Test] (MG_Remote, Wire): state the five sequence watermarks, the
late-never-early batching rule and the pad-does-not-count rule on RingControl, and pin
all three with five cases
b4bbcc11 [Docs] (MG_Remote): CONTRACT-P5.md - the encoding, byte-carrier, field-ownership and
role-ownership tables every P5 package is held to
1. What landed, against BRIEF §5's nine items
| # | item | state |
|---|---|---|
| 1 | MG_Remote/CONTRACT-P5.md, tables 0/1/2/3 |
done. Table 1 is 23 rows, not 19 (see §3.5). Table 2 is the spec + the four class definitions + every known row; p1 generates the authoritative instance. |
| 2 | PipeCalls.def flag corrections + the ResourceRespecify initial-bytes ruling |
done. GetCaps → kReplySlot|kHasBlob; CreateSamplerState → kHasBlob. R-13.3 confirmed with evidence; R-13.2 overturned in a third direction (§3.2). No opcode moved; PipeCatalogueTest's last-four pins untouched. |
| 3 | gen_pipe.py per-opcode flags table |
done. kMGPipeCallFlags[kOpCount] + MGPipeCallFlagsFor() + six generator-authored static_asserts, in generated/PipeWire.inc. Plus a new gate: a flag token that is not an MGPipeCallFlags enumerator, or kNone OR'd with a real flag, stops the generator. Two new negative controls; --self-test went 7 → 9 controls, all trip. .inc regenerated and committed. |
| 4 | MG_Config::Transport + MOBILEGL_TRANSPORT + the MOBILEGL_IPC_* family |
done, all nine knobs plus MOBILEGL_IPC_SERVER_PATH. Runtime-verified on six arms (§2.5). |
| 5 | CMake | done, plus one implication the brief did not ask for: DISAGGREGATED now implies PIPE_PUSH (§3.8). |
| 6 | headers and stubs | done, 8 headers + 8 .cpp. Every stub is MGLOG_F + std::abort. |
| 7 | verb census | done — and for OpenRA it is measured, not estimated: the fixture was already hydrated locally. ~/w7/notes/p5/verb-census.md. |
| 8 | Ring.h + five cases |
done. RingTest 16 → 21 cases; the Wire suites go 52 → 57 and are 57/57 green. |
| 9 | purity | done. check_include_closure.py: 4 probes, 0 skipped, 0 problems. No new header is reachable from ITransport.h. |
2. Acceptance numbers
All in ~/w7/p5-c0, GLIBC_TUNABLES=glibc.malloc.tcache_count=0.
2.1 Builds — four for four
build-linux (pull), build-push, build-verify, build-split
(-DMOBILEGL_PIPE_PUSH=ON -DMOBILEGL_BUILD_DISAGGREGATED=ON -DMOBILEGL_BUILD_DISAGGREGATED_INPROC=ON):
configure rc=0, build rc=0, all four.
2.2 G1 — did not move
nm --defined-only build-linux/libMobileGL.so | grep -ic MG_Remote -> 0
nm --defined-only build-split/libMobileGL.so | grep -ic MG_Remote -> 188 (was 98 at a29807cc)
symbol-report vs ~/w7/p5-before-libMobileGL.so, --threshold 0:
.text 10806323 -> 10806323 (+0, +0.000%)
27811 -> 27811 defined symbols: 0 added, 0 removed, 0 resized, 0 renamed
This is the gate the brief calls the easiest to break, and it held because every knob and the
whole parser sit behind #if MOBILEGL_BUILD_DISAGGREGATED — including the parser. A
FeaturesTable member would have resized MG_Config::Features; a warning in the unconditional
part of ConfigLoader would have resized MG_ConfigLoader::Init.
2.3 Generators and purity
gen_pipe.py --check : generated files are up to date
gen_pipe.py --self-test : 9 negative-control trips, positive control OK (was 7)
gen_pipe_dirty_surface.py --check / --self-test : green, 27 controls all trip
check_include_closure.py : 4 probes, 0 skipped, 0 problem(s)
2.4 Test lanes
| lane | result |
|---|---|
ctest -L unit build-linux |
1785 / 1785 |
ctest -L unit build-push |
1785 / 1785 |
ctest -L unit build-verify |
1785 / 1785 |
ctest -L unit build-split |
1842 / 1842 — the 18 aborts are gone (§4) |
the five MG_Test/Wire suites in build-split |
57 / 57 (52 + my 5) |
ctest -L integration-gpu build-push, MOBILEGL_TRANSPORT=monolith |
1117 / 1117 |
ctest -L integration-gpu build-push, no MOBILEGL_TRANSPORT |
1117 / 1117 |
ctest -L integration-gpu build-split, MOBILEGL_TRANSPORT=monolith |
1117 / 1117 |
Name-for-name identity, integration-gpu in build-push, mine vs ~/w7/pipe/build-push at
a29807cc: 1117 = 1117, diff lines 0.
G2 (pull vs push ctest names, all labels): 0 diff lines.
G14 (split vs push): 57 added, 0 removed — the added 57 are exactly the Wire suites.
2.5 The knobs, at runtime
Six arms through a binary that actually runs MG_ConfigLoader::Init()
(ctest -R ClearThenReadPixels in build-split, 10/10 green on every arm):
| arm | observed |
|---|---|
| defaults | silent — nothing logged, because Transport == Monolith |
inproc + tuned |
IPC ring=4MiB stage=16MiB spin=10us persistent-block=64KiB adopt-tier=2 verb-barrier=1 strict=0 audit=0 affinity='auto' |
inproc + both negative controls |
both warnings fire by name, and the line shows persistent-block=0KiB verb-barrier=0 |
spawn |
names a transport P6 implements and P5 does not; staying on monolith. This run is NOT a split run. |
MOBILEGL_TRANSPORT=banana |
Ignoring invalid env variable MOBILEGL_TRANSPORT='banana' |
MOBILEGL_IPC_RING_MB=0 |
Ignoring invalid env variable MOBILEGL_IPC_RING_MB='0', falls back to 8 |
2.6 The CMake implications actually fire
-- MOBILEGL_BUILD_DISAGGREGATED_INPROC=ON forces MOBILEGL_BUILD_DISAGGREGATED ON for this configure
-- MOBILEGL_BUILD_DISAGGREGATED=ON forces MOBILEGL_PIPE_PUSH ON for this configure: ...
-- PipeInputs push ON, appending the MGPipe fill sources
-- disaggregated transport ON, appending MG_Remote sources
Both are normal variables shadowing the cache for one configure, matching the house shape the
flatbuffers guard's own comment argues for — so an operator's cached ON stays theirs.
3. Rulings I made that the brief did not
Every one is also in CONTRACT-P5.md §6, with what would overturn it. Here, only the ones a
package will trip over.
3.1 CallMask bits 32..47 carry the consumer mask. R-8 says the client's liveness gates
read the CallMask mirror instead of MGPipeGetResourceOps(). But CallMask as declared has
only the nine MGPCapBit feature bits and no per-family bit, so R-8 was not implementable
as written — c1 and b1 would each have invented one. Ruling: bits 0..8 stay MGPCapBit; bits
32..47 are (serverConsumedSubsystems & 0xFFFF) << 32. Constants and the fold/test helpers are
in MG_Remote/CapsCodec.h; CapsCodec.cpp asserts the block does not collide with the cap bits
and that P4a's 0x1fff fits. Overturned by a decision to carry a second schema field instead.
3.2 ResourceFlushRange carries no bytes at all — a third answer, not either of R-13.2's
two. The ladder it drives rewrites its range "from the authoritative shadow"
(Managers.cpp:1047-1076), and under R-11 the authoritative shadow is server-owned, so
resource_subdata is already the only way bytes reach it. A blobref would be a second,
forgeable way to say the same thing. Overturned by evidence that tier-1 INVALIDATE_RANGE
needs bytes and range in one record — impossible while the verb barrier holds; revisit when
the barrier retires for the buffer family.
3.3 ResourceRespecify has a SECOND uncarried companion and the brief does not mention it.
const MGPRespecifiedLevel* level (PipeApply.h:792-795) is the scope of the redefinition
and MGPResourceDesc cannot express it. Without a carrier, every per-level glTexImage2D in
OpenRA silently takes the whole-resource arm and drops every pending upload — precisely the
texel loss the server-side set exists to prevent. Ruling: two named fields in the existing
pads — Pad1 (4 B) becomes {Uint16 RespecifiedUploadTarget; Uint16 RespecifiedLevel;} and
one byte of Pad0 becomes Uint8 HasRespecifiedLevel. Zero size change,
MGP_ASSERT_POD(MGPResourceDesc, 88) does not move. I ruled and specified it; I did not
implement it — MGPipeTypes.h is not c0's file. It is coupled to PipeFields.def, which is
mine (pads are excluded from field lists, so the two named members must be added there or
--check fails). Integrator: land this before w1 encodes the record.
3.4 R-13.3 confirmed, with the cost that makes it obvious. MGPBlobRef is 24 bytes;
MGPResourceDesc's two pads total 6. A blob member takes the struct 88 → 112 and moves the
POD assertion. The recommended route reuses MGPipeForEachSubDataRecordRange, which is already
chunked and already acceptance-gated, and the texture path already does exactly this —
TextureEmit.h:1137 passes nullptr and relies on a following upload. So the ruling
generalises today's texture behaviour to buffers rather than inventing anything.
3.5 Table 1 is 23 rows. The brief's 19 and scout-premortem:§3's 19 are different lists;
the four only the premortem carries — MapPersistent, ResourceReadback, ReadPixels,
GetTextureImage — are exactly the server → client ones. A phase that omits them discovers in
week three that it never decided where readback pixels land. Ruling for ReadPixels:
destination is always SEG_REPLY in P5, so MGPReadbackInfo gains no Seg field.
3.6 tableSlotMask is deleted, not renamed (R-8 allowed either). Decisive: GLFunctionsTable
has 69 function-pointer slots and ulong is 64 bits — the field cannot address the table its
own comment names, and never could. maxComputeWorkGroupCount/Size and
prefersCpuXfbPrimitiveAccounting go with it.
3.7 The persistent-map census is 21 sites, not 20, and DirectGLES.cpp:361
(ResolveIndirectCommandBytes) is in the set. MEASUREMENTS.md:111 says 20 and
Managers.cpp:5047-5048 says eleven Espryt; both are exactly one low and the missing one is
Espryt's. A shared helper that reaches a persistently-mapped range can read stale bytes exactly
as a draw site can. ARCHITECTURE.md:290's cited "§5.7" attribution table does not exist in
the tree — b1 should not go looking. Correcting MEASUREMENTS.md:111 is b1's line.
3.8 MOBILEGL_BUILD_DISAGGREGATED implies MOBILEGL_PIPE_PUSH. The split path decodes into
the MGPipe applier and PIPE_PUSH is what compiles the applier, so
-DMOBILEGL_BUILD_DISAGGREGATED=ON alone used to configure cleanly and fail at link — a shape
indistinguishable at the CMake level from a legitimate transport-only build.
3.9 The two doorbell accessors stay off ITransport. They are on InProcessTransport
today (InProcessTransport.h:64-68). Ruling: the session owns the pair and hands out
references, so ITransport stays the dumb control-plane interface its own header describes and
SocketTransport does not grow two accessors with no natural home. Deciding this in P6 would
mean re-laying one package's call sites.
3.10 gMGPipeSegmentResolver is installed by the SERVER role only. It is one process-wide
non-atomic inline variable (MGPipeHostSpan.h:47), so it cannot be per-role — and under R-2 the
client never resolves a span anyway, it only ever writes Ptr = nullptr.
SegmentTable::InstallProcessResolver() asserts if one is already installed.
3.11 DrawVbo's host span stays in the variable tail. MGPipeTypes.h:1221-1224 defers the
fixed-head-versus-tail question to P5. There are no per-draw byte histograms yet, so moving it
would be a wire-format change with no measurement behind it. Keep.
3.12 Silent MOBILEGL_TRANSPORT in a non-disaggregated build is accepted and unfixable at
runtime. A complaint would have to live in the unconditional part of ConfigLoader, which
resizes a pull-build symbol and breaks G1. The guard is therefore t1's build-level nm check,
and it is written into the contract so nobody re-litigates it.
4. The 18 split-build unit aborts — root cause and disposition
Disposition: FIXED here, by c0, in one test-local commit. Nothing is left red, and none of it is p1's.
The brief's leading hypothesis — a PipeInputs poison read hitting
Fatal{UnmigratedPipeInput, "<Field>@<none>"} — is refuted. MG_Test/ScopedPipeVerb.h is
not involved at all.
All 18 are Fatal{ProtocolCorruption} trip wires in PipeApply.cpp that the tests
deliberately provoke and expect, e.g.
MGPipe: Fatal{ProtocolCorruption} create_vertex_elements {slot=5, gen=2}: the declared blob
length is not the byte length the two counts describe (attributes=3, bindingPoints=2, that
describes 104 bytes, blob declares 103)
MOBILEGL_PIPE_POISON is derived from MOBILEGL_BUILD_DISAGGREGATED
(PipeInputs.h:20-26, exactly as the brief says) — but what it arms here is a second consumer,
PipeApply.cpp:42-52, which flips 32 trip wires from MGLOG_E to MGLOG_F + abort. Each of
the seven test files has a two-armed helper keyed on #if MOBILEGL_PIPE_POISON || MOBILEGL_PIPE_VERIFY
that picks between "fork a child and expect it to die" and "run in process and read the log".
None of those seven TUs included <MG_Backend/MGPipe/PipeInputs.h>, the only header that
defines the macro. So the token was undefined, the #if silently read 0, and they compiled
the non-aborting arm while PipeApply.cpp — which does include the header — compiled the
aborting one. Invisible in a push build (POISON really is 0) and in a verify build
(-DMOBILEGL_PIPE_VERIFY=1 is on the command line); MOBILEGL_BUILD_DISAGGREGATED is the one
arming condition that lives behind the header, so build-split is the first configuration
that could ever expose it.
Fix: one include per file, matching what the two sibling files that get it right already do
(RenderStateSpansTest.cpp:63, PipeInputsTest.cpp:34), each with the six-line note explaining
why. Plus one latent guard correction that the same invisibility was masking:
ResourceEmitTest.cpp's TheLiveHostWritesWireFiresOnTheCallAPersistentMapProducerWouldSetItOn
guarded itself with #elif !(MOBILEGL_PIPE_POISON || MOBILEGL_PIPE_VERIFY) while
PinNoLiveHostWrites is #if MOBILEGL_PIPE_VERIFY only (PipeApply.cpp:838-853) — so in a
split build the wire genuinely is compiled out and the case must skip. Corrected to
#elif !MOBILEGL_PIPE_VERIFY; verified SKIPPED in push, SKIPPED in split, OK in verify.
Why it is c0's and not p1's: p1's artefacts are all correct as they stand. PipeInputs.h
derives the macro the way its own comment says it must; PipeApply.cpp consumes it correctly;
PipeFill.cpp and gen_pipe_dirty_surface.py are not in the path. The defect is entirely
consumer-side visibility in seven files under MG_Test/Pipe/, which are not p1's (t1 owns only
MG_IntegrationTest/**), and the fix introduces no new convention — that MG_Test →
MG_Backend/MGPipe/PipeInputs.h edge already exists twice in the same directory.
One hardening left on p1's account, deliberately not taken: if the integrator wants
MOBILEGL_PIPE_POISON to be unmissable, the derivation could move into a header every push TU
already sees (MG_Pipe/MGPipe.h), or PipeInputs.h could grow a tripwire for TUs that test the
macro without it. That changes a p1-owned header and touches every push TU's macro surface —
a much larger blast radius than a seven-line include for a defect the include closes completely.
Filed as a p1 note; not done here.
(One caveat inherited, not introduced: running a whole fixed binary by hand — all cases in one
process — leaves some FramebufferEmit/TextureEmit fork cases red, because the parent has
already opened the log file and the child inherits a handle to the unlinked inode. That is the
limitation RenderStateSpansTest.cpp:1034-1040 names; under ctest every case is its own process
and it does not arise.)
5. Every stub signature, with one line each
MG_Remote/Wire/PipeWireCodec.h — owner w1
| signature | why this shape |
|---|---|
enum SegmentId { kSegNone=0 … kSegAdopt=6 } |
one id space with Protocol::SegmentKind, tied by static_assert in the .cpp, which is the only place the flatbuffers header and the codec meet. |
struct SegmentView { void* Base; Uint64 Size; } |
a role's view of one segment; two roles in one process hold two different tables over the same memory on purpose. |
SegmentTable::{Install, Get, Resolve, InstallProcessResolver, UninstallProcessResolver} |
Resolve returns nullptr rather than Fatal-ing so a unit test can exercise the arithmetic without dying; the caller escalates. |
WireProtocolFatal(what, detail) / WireProtocolFatalAt(what, got, expected) |
not stubs — worded once so encoder, decoder and every package's own check emit the same line. |
CheckBlobIsHonest(op, blob, segments) / CheckHostSpanIsHonest(span) |
R-2.3's arms as functions, so "honest" means one thing. |
PipeWireEncoder::StageBytes(bytes, size) -> MGPBlobRef |
returns the ref; a zero-size call Fatals rather than returning an empty ref, because "declared no blob" and "declared an empty blob" must not be spelled the same way. |
PipeWireEncoder::EncodeRecord(op, payload, payloadBytes, varTail, varTailBytes) -> Uint64 seq |
returns the seq, which is also the reply-slot id (R-3). One function for fixed payload + tail so no package invents a second framing. |
PipeWireEncoder::{Publish, EmitSeq, MaxRecordBytesSeen} |
MaxRecordBytesSeen is R-10's proof obligation, on the encoder because that is where the number exists. |
class ReplySink { PostReply(seq, status, bytes, size) } |
declared in Wire, not Server, so the codec does not depend on the session: the decoder's job ends at "produce the answer bytes". |
PipeWireDecoder::DecodeAndApply(const RingRecordView&) -> Bool |
one record in; false = "this build does not implement it", malformed never returns. A kRecPad reaching it Fatals — the caller skips pads before counting. |
PipeWireDecoder::AppliedSeq() |
separate from the control page so the batching ban (R-9) has something to be checked against. |
MG_Remote/CapsCodec.h — owner w1 (codecs) / s1 (handshake)
| signature | why |
|---|---|
kMGCapsConsumerBitShift, kMGCapsConsumerMask, MGCapsConsumerBits(mask), MGCapsServerConsumes(callMask, bit) |
the ruling of §3.1 as four constexprs, so neither side hand-shifts. |
Encode/DecodeFormatCapabilities, Encode/DecodeRendererInfo |
the two serializers MGPipeTypes.h:134-136 defers to this phase. Decoders return false on truncation; these bytes arrive over a wire. |
CapsAbiFingerprint() -> Uint64 |
mixes the three sizeofs and the build fingerprint; compared in Hello/Welcome, Fatal{AbiMismatch} and never a downgrade. |
MG_Remote/Client/CapsMirror.h — owner c1
| signature | why |
|---|---|
Adopt(caps, formats, renderer, apiVersion, backend) |
one call, whole snapshot; re-arrival is the invalidation (R-12), so there is no separate Invalidate(). |
Generation() |
++ per Adopt. The only thing on the client that can see a server context death; a client memo must key on it. |
Renderer() returns a reference |
GetRendererInfo() is const RendererInfo& (BackendObject.h:590), so the mirror must own an instance — including a placeholder before the first snapshot, because LogBackendInfo reads it at Init.cpp:21. |
Dynamic(), Formats(), ApiVersion(), Backend() |
the other 55 read points. Backend() returns the server's type, never a new "Remote" enumerator. |
ServerConsumes(subsystemBit) |
R-8's only legal client-side spelling. |
PrefersCpuXfbPrimitiveAccounting() |
it is a GLFunctionsTable member (:274), not a Dynamic one, so under split it has to come from the cap bit. |
MG_Remote/Client/EmitTables.h — owner c1
| signature | why |
|---|---|
RemoteEmitTable() -> const GlobalBackendFunctionsTable& |
71 function pointers, not 69 (§3 of the contract): 69 GL.* + Present + SetSwapInterval. |
UnmigratedVerbFatal(slot) [[noreturn]] |
not a stub — same shape as MGPipeInputPoisonFatal, live at every log level, so the wording lives in one place and a death test can filter on it. |
ImplementedVerbCount() / kRemoteEmitSlotCount = 71 |
a table that silently loses an emitter must not look like one that never had it; EmitTables.cpp asserts the 71 against the struct. |
MG_Remote/Client/ClientSession.h — owner s1 (construction) / c1 (barrier)
| signature | why |
|---|---|
Active() returns nullptr, not a Fatal |
MG_Backend::Init() legitimately asks "is there a session" and the monolith answer is no. |
Start(mode, endpoint) |
returns a named error rather than falling back to monolith. |
Stop() |
publish → Kill → join → only then free emitter-owned memory. |
EmitAndWait(op, payload, bytes, tail, tailBytes, replyOut, replyBytes, statusOut) -> seq |
one call, because the barrier's wait and the reply's wait are the same wait (R-3/R-5). Separating them is how a package re-derives an acceptance answer locally. |
BarrierArmed(), InBarrierWait(), ApplyThreadIsInsideApplier() |
R-1's mutual-exclusion invariant as a checkable pair rather than a sentence. Both return false in the stub — an assertion helper that aborts when asked is worse than useless. |
MG_Remote/Server/PipeApplier.h — owner v1 (with p1 for the stamp)
| signature | why |
|---|---|
ReplyPool(base, size, slotCount, slotBytes) + PostReply override |
addressed seq % slots, seq stamped back into the header for self-check. |
ReplyPool::SlotBytes() |
a reply bigger than a slot is Fatal, not chunked: P5's only big answer is ReadPixels, whose size the client knows before it emits. |
PipeApplier::ApplyOne(record) |
decode → stamp → apply → reply → advance appliedSeq by one. |
PipeApplier::StampVerbBoundary(op) |
the prerequisite nobody else owns (§3 of the contract). p1 defines what; v1 calls it. |
PipeApplier::ResidualPullCount() |
rsp; its end-of-P5 value is the P6/P7/P8 debt. |
PipeApplier::PoisonRetiredStageBytes(offset, size) |
R-2.5's 0xDD, the only mechanical control on rule C. |
MG_Remote/Server/ServerSession.h — owner s1
| signature | why |
|---|---|
Accept(ITransport&) |
the ABI assertion happens here, before a single record is decoded. |
PublishCapsSnapshot() |
callable more than once; the second call is the invalidation. |
ConsumerDoorbell() / ProducerDoorbell() |
§3.9: the pair lives on the session, not on ITransport. |
MG_Remote/Server/ServerLoop.h — owner v1
| signature | why |
|---|---|
Start(session) |
names the thread mgl-srv-apply, applies the affinity and logs the resolved mask. |
Stop() / Running() |
Running() is not a stub: teardown asks it before deciding to Kill and join, and a helper that aborts when the thread never started is a hang. |
Backend() |
the server's private BackendObject_DirectGLES, not pActiveBackendObject. |
RunOnApplyThread(ControlWork, void*) |
a raw function pointer plus a user pointer, not std::function: this runs on the teardown path and the teardown path may not allocate (ID-8). |
6. Everything in the brief I believe is wrong or incomplete
Ordered by how much it would cost a package to discover it.
- R-13.3 covers only one of
ResourceRespecify's two uncarried companions. §3.3. TheMGPRespecifiedLevel*scope needs a carrier or OpenRA's per-level uploads are silently lost. This is the one I most want the integrator to act on before w1 starts. - R-4's "69 slots" is
GLFunctionsTable's count; the table the client installs is 71.Presentis on the reduced path andPresent/SetSwapIntervalhave zeroMG_Implcall sites — they are reached through the EGL path, so an emit table built by mirroring GLImpl covers neither. - R-4's predicted minimum set names
Flush. There is noFlushslot, andglFlush/glFinishare literally empty bodies (Definitions.cpp:111-112). ATriangleScenariothat usesglFlushto order its readback is ordering nothing. - The census's real surprise:
GetIntegeri_vis reached by the firstglCompileShaderof a context, viaCaptureCompileEnv(CompileEnv.cpp:134-138), not by any verb. An all-Fatal emit table aborts on the first shader compile of every scenario. It needs a real emitter or a caps-mirror answer. - R-8 is not implementable as written —
CallMaskhad no per-family bit. §3.1. - Table 1's 19 rows are the wrong 19 (§3.5), and one of them,
SetResidualValueState, is a fourth typed companion nobody named:MGPipeApplySetResidualValueStatetakesconst ResidualValueBlock&andMGPResidualValueStateis never instantiated on the live path. Budget it as w1's hardest row, not one of the easy eight. - Three of the 19 have no applier entry point at all —
SetShaderBuffers,SetStreamOutputTargets,DrawVbo.scout-premortem:§3cites five entry points for a six-call row and those five belong to other calls. - The brief's diagnosis of the 18 aborts is wrong (§4). It cost nothing here because it was
checked rather than assumed, but a package that had taken it at face value would have gone
looking in
ScopedPipeVerband p1's poison machinery, both of which are innocent. CanTouchGLNow()guards 16 sites, not 19 (19 = 1 definition + 2 comments + 16 calls), andScopedDefaultUnpackStatehas six value shadows, not five.DirectGLES.cpp:12446is notClampSamplesToBackendSupport— it isPresent()'s fence poll, andDirectGLES.cppcontains nopActiveBackendObjectreference at all. The real function isBackendObject_DirectGLES.cpp:807-828, and there are seven backend-internal reads across six functions, not one. Table 3's conclusion survives; the diff does not.MGPipeApply*is 37 entry points / 41 call sites, not "~45".- The persistent-map census is 21, not 20, and the attribution table
ARCHITECTURE.md:290cites does not exist (§3.7). - Doc corrections carried into the contract:
ARCHITECTURE.md:83says 61PipeInputsfields (it is 63);:492citesPipeStats.h:126formpr(it is:141);:19says eight EGL lifecycle virtuals (there are nine —ResizeEGLWindowSurface); ROADMAP's P4a row says sixMGPipeUnmigratedEmulationsites (five calls + one comment). MGHostSpan, notMGPHostSpan— the latter does not exist.
7. Notes for the integrator
- The worktree's submodules are symlinks to
~/w7/pipe's.git worktree addpopulates no submodule content and a recursive init needs the network (apitrace's brotli tree is not in the local object store), so~/w7/p5-c0-setup.shlinks every.gitmodulespath —include/skaincluded, which is whatIncludes.h:53reaches for. git refuses to run at all while they are symlinks ("expected submodule path X not to be a symbolic link"), so~/w7/p5-c0-submodlinks.sh off|ontoggles them:offbefore any git command,onbefore any build. Every parallel package will hit this on day one. It is worth telling them once rather than seven times. - An earlier bring-up script reported four green builds that never happened — it dropped
$COMMONand its build loop passed no directory, socmake --build -j 24only printed usage and$?was 0. If any P5 script reports a build result, check that aCTestTestfile.cmakeexists before believing it. ~/w7/p5-c0-gate.shis c0's own gate (four dirs, generators, purity, G1, the four unit lanes) and is a reasonable skeleton for t1'swsl_p5_gate.shpart 1/3/5.- Retained logs this report cites:
~/w7/p5-c0-gaterun.log,~/w7/p5-c0-acceptrun.log,~/w7/p5-c0-symbols.md,~/w7/p5-c0-names-push-{mine,base}.txt. Everything else under~/w7/p5-c0-*is a re-runnable script. The diagnosis scratch (~/w7/p5-c0-diag-*) is deleted. - Not run here, and not c0's:
ctest -L integration-verify, the retrace sweeps, and the device lane.integration-gpuwas run on bothbuild-pushandbuild-splitand is name-for-name identical toa29807ccon both.
8. Follow-up round — integrator rulings A and B, and the respecify-scope carrier
Two more commits. Range is now 41b4f8df..5175f9cc, nine commits.
45b759e7 [Feat] (MG_Pipe): give resource_respecify's redefinition scope a wire carrier in the
descriptor's two existing pad fields, so a per-level glTexImage cannot cross as a
whole-resource redefinition and eat every other level's pending upload
5175f9cc [Docs] (MG_Remote): record R-15 and split the emit table's 71 slots into
answered-locally, emitted and Fatal, with the forty-one null checks that are really
capability probes
8.1 Ruling A — MGPipeTypes.h is c0's
Recorded in CONTRACT-P5.md §8. Worth keeping the causal note: that file being unowned is
precisely why the row-19b gap had nobody to close it, and the same is true of anything else that
falls between the .def files and a package's own directory. Ownership now reads: the three
.def files, gen_pipe.py, MGPipeTypes.h, Config.h, ConfigLoader.cpp, the root
CMakeLists.txt, CONTRACT-P5.md, the MG_Remote stub headers, Ring.h/RingTest.cpp.
8.2 Work item 1 — the carrier, landed
MGPResourceDesc (MGPipeTypes.h), exactly the §3.3 spec and nothing more:
Uint8 HasRespecifiedLeveltakes the high byte of the oldPad0(Uint16 Pad0→Uint8 HasRespecifiedLevel; Uint8 Pad0;);Uint16 RespecifiedUploadTarget; Uint16 RespecifiedLevel;take all of the oldPad1, in that order, so they areMGPRespecifiedLevel(PipeApply.h:792-795) byte for byte. Spelled as twoUint16s rather than as that type becausePipeApply.hincludes this header, not the reverse;MGP_ASSERT_POD(MGPResourceDesc, 88)did not move, and a newoffsetofassertion pins the pair adjacent and in that order — the layout is the contract, not the field names.
Five helpers, because three fields are one value. MGPipeRespecifyIsWholeResource,
MGPipeRespecifiedUploadTargetOf, MGPipeRespecifiedLevelOf, MGPipeSetRespecifiedLevel,
MGPipeClearRespecifiedLevel. The two readers return 0 for a whole-resource descriptor rather
than whatever the pad held, so a misuse is deterministic; the writers set or clear the presence
byte with the pair so it cannot be left behind. An open-coded reader that forgets the presence
byte reads level 0 of upload target 0 as a real scope, which is the one wrong answer that
looks plausible — hence the helpers rather than a comment.
No emitter or applier behaviour changed. The producer is a later package's. What did change:
PipeFields.defgains the three rows — required, not optional: the generator's cover check only excludes members literally namedPad*, so omitting them fails--check. Both directions verified as negative controls: droppingF(HasRespecifiedLevel)→ "member(s) with no F(...) in PipeFields.def: HasRespecifiedLevel"; adding a name the struct lacks → "F(...) name(s) that are not members: RespecifiedNothing". They are also real G4 comparands now, which matters: a verify build that let the scope differ silently would be blind to the one field deciding whether a respecify drops one pending upload or all of them.PipeApply.cppgainsPinWholeResourceRespecifyScope, thePinNoLiveHostWritesshape (:839-850), called fromMGPipeApplyResourceRespecifybeside it. Verify-build only, and verified so: theFatal{PipeRespecifyScope}string appears inbuild-verify/libMobileGL.soonce and inbuild-pushandbuild-splitzero times. It pins that P5 builds only whole-resource descriptors, so the phase that wires the carrier cannot arrive unannounced — and in particular cannot land a descriptor saying "whole resource" while the still-live trailingMGPRespecifiedLevel*says "level 1".- A standalone round-trip compile (value-init → whole-resource; set a cube face + level 3; read both back; clear; read 0 not the pad) returns 0.
8.3 Ruling B — R-15, and the three-class split
CONTRACT-P5.md §7, cross-referenced from MG_Remote/Client/EmitTables.h and from
verb-census.md so c1 meets it wherever it starts reading.
- Class A, answered locally from the caps mirror, never emitted and never Fatal — 2 slots:
GetIntegeri_v(fromMGPCaps::Dynamic.MaxComputeWorkGroupCount/Size) andIsTimerQuerySupported(fromkCapTimerQuery), plus the non-slot BoolPrefersCpuXfbPrimitiveAccounting(fromkCapCpuXfbPrimitiveAccounting). - Class B, emitted — 5 slots:
Clear,DrawArrays,ReadPixels,BlitFramebuffer,Present. - Class C,
Fatal{UnmigratedVerb}— 64 slots, includingSetSwapIntervalandGetGpuTimestampNs(a live GPU timestamp, not a static device property, so deliberately not class A).
One thing R-15 surfaced that is bigger than R-15. R-4 forbids a null slot — and 41 of the
69 slots are null-checked at their call site, with several of those checks being capability
probes rather than safety checks. In an emit table with no null slots every one of them answers
"supported" and the fallback behind it silently disappears. Named in the contract:
BeginOcclusionQuery (GL_Query.cpp:481, :785) → kCapOcclusionQuery;
BeginXfbPrimitivesQuery's ternary (:534) → kCapXfbPrimitivesQuery; SubDataResident →
kCapResidentSubData. The rule generalises: a null check on a slot may not survive into the
client under split — it becomes a caps-mirror read. This is ARCHITECTURE.md:114's "CallMask
replaces 'is this table slot null'" with a concrete list attached, and it is c1's to carry.
8.4 Work item 2 — the gate, re-run in full
G1 is the one this edit could plausibly have moved (a PipeFields.def row can widen a
generated array, and the descriptor's pads became named members). It did not move:
.text 10806323 -> 10806323 (+0, +0.000%)
27811 -> 27811 defined symbols: 0 added, 0 removed, 0 resized, 0 renamed
nm pull MG_Remote 0 / nm split MG_Remote 188
| check | result |
|---|---|
| four build dirs, configure + build | rc=0, all four |
gen_pipe.py --check |
up to date |
gen_pipe.py --self-test |
9 / 9 controls trip, positive control OK |
gen_pipe_dirty_surface.py --check / --self-test |
green, 27 controls all trip |
check_include_closure.py |
4 probes, 0 skipped, 0 problems |
ctest -L unit build-linux / push / verify |
1785 / 1785 each |
ctest -L unit build-split |
1842 / 1842 |
| Wire suites, build-split | 57 / 57 |
integration-gpu names, build-push vs a29807cc |
1117 = 1117, diff 0 |
integration-gpu build-push, MOBILEGL_TRANSPORT=monolith |
1117 / 1117 |
All four lanes held.
9. Wave-1 round — the acceptance rows' reply slot, and the two flag spaces
Three commits on p5/c0, b5b6cef2..225819ab, on top of feat/disaggregated @ 5175f9cc.
b5b6cef2 [Fix] (MG_Pipe): give the four acceptance calls the kReplySlot their applier entry
points have always answered through, so the flags table is the single thing that sizes
the reply pool and the decoder posts against
c2273df1 [Fix, Test] (gen_pipe, Wire): stop the generated header comment inviting a stamp of the
call flags into the ring's framing flags - three of the six bits mean something else
there, and only one of the three is masked on one path
225819ab [Docs] (MG_Remote): record R-16 and R-17 - the fourteen reply-slot rows and why the
barrier makes them cost no block, and the two flag spaces being disjoint by translation
9.1 Item 1 — the four acceptance rows, verified before editing
The set is exactly the one the ruling names. Verified by enumerating every MGPipeApply*
entry point that returns a value, not by taking the brief's word:
Bool MGPipeApplyResourceCreate PipeApply.h:820
Bool MGPipeApplyResourceRespecify PipeApply.h:868
Bool MGPipeApplyResourceSubData PipeApply.h:897
Bool MGPipeApplySetTextureParams PipeApply.h:1023
void* MGPipeApplyMapPersistent PipeApply.h:917 (already kReplySlot)
No others return anything. So: ResourceCreate kNone → kReplySlot; ResourceRespecify
kNeedsAck → kNeedsAck|kReplySlot; SetTextureParams kNone → kReplySlot;
ResourceSubData kHasBlob|kVarTail → +kReplySlot. kReplySlot rows 10 → 14. No opcode
moved.
One correction to the ruling's expectation, and it changes the work rather than the outcome:
PipeCatalogueTest had no kReplySlot count to update. grep -rn kReplySlot MobileGL/MG_Test/
returns nothing at this base, and none of the five wave-1 branches adds one. Rather than leave
the number unpinned now that it is load-bearing, I added the pin, in the house shape the
neighbouring kNeedsAck count already uses (MGP_COUNT_ACKING_CALLS): a count assertion
(== 14) and a by-name assertion that all four acceptance rows carry the flag (== 4). A
count alone would let one row lose the flag while another gained it.
The "never blocks" contradiction is resolved in the contract rather than papered over.
MGPipe.h:49 says a reply-slot call never blocks; R-5 says these four answers are read
synchronously. Both hold, because under the verb barrier the client is already waiting for
appliedSeq >= mySeq at that verb boundary and the reply is read inside that wait. A
kReplySlot row therefore adds no block — it adds a read to a wait that was already happening.
The flag keeps its literal meaning; the barrier blocks, and the barrier retires per family, at
which point these four become genuinely asynchronous and the acceptance answer becomes a real
latency question. That is P9's account.
9.2 Item 2 — and the part of w1's finding that the tree contradicts
The generated comment said Flags was "MGPipeCallFlags of the call, for asserts and tracing",
which invited exactly the stamp w1 found. It now says what the field is: ring framing flags,
and the two spaces are disjoint by translation, not shared.
But the finding as relayed is stronger than the tree supports, and I would rather correct it
than pin something false. RingProducer::Reserve masks kRecPad out of a caller's flags
(Ring.cpp: flags & ~kRecPad). So:
| collision | status |
|---|---|
kVarTail → kRecPad |
defended, one bit wide, one path wide. A stamp through Reserve does not delete the record. A producer that writes the header itself — which is what a codec with its own header struct does, since these are the same eight bytes — loses the mask, and then Pop skips the record as a wrap filler. |
kHostSpan → kRecBorrowSlot |
undefended. The consumer believes the record borrowed a slot into the GPU timeline and retires it on completedFrameSerial instead of on apply. |
kReplySlot → kRecVarTail |
undefended — and after item 1 this now fires on fourteen rows rather than ten. |
So the real failure is not one dramatic disappearance: it is a lifetime lie and a phantom tail
on every affected record, plus a disappearance only on the path that bypasses Reserve. My
first version of the test asserted the dramatic version, and it failed — which is the system
working. The landed test pins all three shapes including the masking, so the one defence that
exists cannot quietly go away either.
Enforcement, split by what each file can see. MG_Pipe is below MG_Remote and may not include
Ring.h, so no generated .inc can hold a cross-enum assertion:
gen_pipe.pynow readsenum MGPipeCallFlagsout ofMGPipe.hrather than hard-coding it, and emits a value assertion per flag pluskMGPipeCallFlagsAllBits == 0x3F. A renumbering or a seventh flag is a build break, and — because the parse also feeds the existing unknown-flag gate — a flag added to the header no longer has to be added to the generator by hand, which is the copy that would have gone stale in exactly the case that matters.MG_Test/Wire/RingTest.cppholds the cross-enum table: the one place in the tree that sees both enums, and built only underMOBILEGL_BUILD_DISAGGREGATED. Six correspondences, both totals (0x3Fand0x1F), and a runtime half that demonstrates each of the three shapes.
9.3 Acceptance — re-run in full, against this rebuilt tree
.text 10806323 -> 10806323 (+0, +0.000%)
27811 -> 27811 defined symbols: 0 added, 0 removed, 0 resized, 0 renamed
nm pull MG_Remote 0 / nm split MG_Remote 188
| check | result |
|---|---|
| four build dirs | rc=0, all four |
gen_pipe.py --check / --self-test |
up to date; 9 / 9 controls trip |
gen_pipe_dirty_surface.py --check / --self-test |
green, 27 controls |
check_include_closure.py |
4 probes, 0 problems |
ctest -L unit build-linux / push / verify |
1785 / 1785 each |
ctest -L unit build-split |
1843 / 1843 (1842 + the new cross-enum case) |
| Wire suites, build-split | 58 / 58 |
integration-gpu names, build-push vs base |
1117 = 1117, diff 0 |
integration-gpu build-push, MOBILEGL_TRANSPORT=monolith |
1117 / 1117 |
9.4 Three things for the integrator
- The unit baselines have not moved, because nothing has landed.
~/w7/pipe'sfeat/disaggregatedis still at5175f9cc— my own tip. The five wave-1 branches (p5/w1,p5/s1,p5/p1,p5/t1,p5/b1) exist and are ahead, but none is merged. My numbers above are therefore directly comparable to §8's, and the only unit delta is the one case I added. - Two wave-1 branches have edited c0-exclusive files.
p5/w1→scripts/gen_pipe.py(the decoder hook ingen_wire);p5/b1→MGPipeTypes.h(aHasLiveHostWritesbyte out ofMGPSubData's pad),PipeFields.def,CMakeLists.txt. Both look like good work and both may well have been authorised the way my ownPipeApply.cppedit was — I raise it only so the ownership table means something. Their regions are disjoint from mine, so the merge is clean except forgenerated/*.inc, which both sides regenerate: the integrator should take either side and re-rungen_pipe.py, never hand-merge a generated file. - The submodule-symlink trap bit me once and will bit others. A git command needs them off,
a build needs them on, and the failure mode when they are left off is four CMake "source
directory does not exist" errors that look nothing like the cause.
~/w7/p5-c0-gate.shnow restores them itself and refuses to run if they are unpopulated; worth copying intowsl_p5_gate.sh.