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

668 lines
43 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.
# p1 — the poison, the field-ownership table and the visibility of unmigrated inputs, v1
Branch `p5/p1`, worktree `~/w7/p5-p1`, base `feat/disaggregated @ 5175f9cc`.
**Ten commits, `5175f9cc..9d40d3e9`** — round 1 `388364d5..6fc1bcc8`, fix round 1
`6fc1bcc8..9d40d3e9`. Not pushed. Working tree clean.
**§7 is the fix round against `p1-review-v1.md` and it SUPERSEDES parts of §1, §2 and §8.** Where
they disagree, §7 is newer: the self-test is 15 controls and not 11 (§7.1 M-1), the stamp map is
12 rows + 3 exemptions and not 4 (§7.1 M-2), and `MGPipeServerClearVerbBoundary` is mandatory for
the applier rather than optional (§7.2 M-5).
---
## 0. The one-paragraph answer
Table 2 is now **generated, checked and load-bearing at runtime**. 63 fields + 7 sticky forwards
= 70 rows, each in exactly one of four classes; `RECORD-SUPPLIED` is *derived* from Coverage.def
and PipeFill.cpp rather than asserted, so the table cannot drift away from the emitters it
describes. The class decides what a stale read *means* under split: a `BARRIER-PULLED` read is
counted as `rsp` and is `Fatal` under `MOBILEGL_IPC_STRICT_ERRORS=1`; everything else is `Fatal`
as today. The prerequisite — the server-side stamp — is defined, implemented and unit-pinned,
and its **withdrawal** half is what makes `rsp` a real number instead of a decoration. The seven
sticky forwards' exemption dies for free, because the stamp zeroes their generation and
`PipeFilled.inc` tests "never filled" before it tests sticky. `MGPipeUnmigratedEmulation` has
teeth. `GetPixelStoreParameters` is split **by argument** rather than into a second field id, and
§6 says why that is a deviation and what would overturn it.
---
## 1. What landed
Five commits, all single-line messages, no trailer lines.
| # | scope | what |
|---|---|---|
| 1 | `MG_Pipe/FieldOwnership.def`, `scripts/gen_pipe_field_ownership.py`, `generated/PipeFieldOwnership.inc`, `PipeInputs.h` | the generator, its mapping file, the generated table, and the one `#include` that puts it where the poison check and the stamp both already are |
| 2 | `MG_Backend/MGPipe/PipeInputs.{h,cpp}`, `MG_Impl/Pipe/PipeFill.cpp`, `MG_Util/Metrics/PipeStats.{h,cpp}` | the server stamp, the four-way read verdict, `rsp`, and the sticky forwards' hook |
| 3 | `MG_Pipe/PipeApply.cpp` | `MGPipeUnmigratedEmulation`'s split arm — one function, five call sites |
| 4 | `MG_Test/Pipe/FieldOwnershipTest.cpp` + `MG_Test/Pipe/CMakeLists.txt` | 20 cases: 6 arithmetic (any push build) + 14 behavioural (split only) |
| 5 | `docs/Disaggregated/{ARCHITECTURE,MEASUREMENTS}.md` | the G8 generator row and the two stale "61 fields" lines |
### 1.1 The generator (deliverable 1)
`scripts/gen_pipe_field_ownership.py`, in `gen_pipe.py`'s shape (write / `--check` / `--self-test`)
with `gen_pipe_dirty_surface.py`'s mapping-file + negative-control discipline.
- **Sources.** `Coverage.def` (the ordered 63 accessors, the 7 sticky, the 40 emitted),
`MG_Impl/Pipe/PipeFill.cpp` (`EmittedCallSuppliesTheWholeField`'s nine refusals, parsed out of
the function rather than restated), `MG_Pipe/FieldOwnership.def` (the hand half),
`PipeCalls.def` + `FillPoints.def` (the two name spaces the stamp map joins).
- **RECORD-SUPPLIED is DERIVED.** emitted ∧ ¬refused. A `.def` row that claims it is a
contradiction and stops the generator — which is the only thing that keeps the hand half true
as the emitted list grows.
- **A field in no class stops the generator**, so the committed header can never contain an
unclassified row, and a `static_assert(MGPipeEveryFieldIsClassified())` in the emitted header
catches a hand edit of the generated file.
- `--self-test`: **11 negative controls, all trip**; positive control passes. They are, by name:
a field in no class (GetActiveTextureUnit's row removed — **E4's control**), a RECORD-SUPPLIED
field claimed by hand, a row naming a non-field, a BARRIER-PULLED row with no retiring phase,
a fifth class, a sticky forward with no row, a forward row contradicting its field row, an
argument exception that narrows nothing, the derivation's source function renamed away, and
two stamp-map rows naming an op / a verb that does not exist.
- Output also prints **the debt by retiring phase**, which is the table's whole point.
### 1.2 The table, as it came out
| class | count | |
|---|---|---|
| RECORD-SUPPLIED | **32** | derived |
| APPLIER-DERIVED | 1 | `GetPixelStoreParameters` (pack half) |
| BARRIER-PULLED | 27 | 20 non-sticky + the 7 sticky forwards |
| FATAL | 3 | `GetBoundTransformFeedbackName`, `GetTransformFeedbackPausedPrimitiveCounter`, `GetProgramForDispatch` |
| | **63** | + 7 forward rows = 70 |
**The contract's "31 fields today" for RECORD-SUPPLIED is arithmetically wrong and the right
number is 32.** `40 − 9` double-subtracts `GetPixelStoreParameters`, which is already `kNone` in
`kMGPipeFieldEmittedBy` and so was never among the 40; only eight of the nine refusals are.
The census's own "31 of 63 fields are not served by any pushed record" is right, and
63 − 31 = 32. Nothing else in either document depends on the 31.
### 1.3 `rsp` (deliverable 2)
`PipeStats::CallClass::ResidualPulls`, short name `rsp`, **inside the `#if MOBILEGL_PIPE_PUSH`
block** (`PipeStats.h`), name `"residual-pulls"`, published per frame on the summary line's
`emit[...]` bracket beside `trp=`. A process-wide raw counter
(`MGPipeResidualPullCount()`) sits beside it because `PipeStats` can be switched off and the exit
gate may not be; `PipeApplier::ResidualPullCount()` should forward to it (§3).
Both are incremented at **one** place — `CountBarrierPull` in `PipeInputs.cpp` — so the 56
checked accessors and the seven sticky forwards cannot drift apart on what a pull is.
### 1.4 The four-way read verdict
`MGP_INPUT_CHECK` grows a split arm. On a **not-fresh** read:
| condition | verdict |
|---|---|
| not inside a server-stamped verb | `Fatal` (today's behaviour, unchanged) |
| class ≠ BARRIER-PULLED | `Fatal` |
| field outside the verb's own class mask | `Fatal` |
| otherwise | `++rsp`; `Fatal` under `MOBILEGL_IPC_STRICT_ERRORS=1` |
The third row is not in the contract and is worth keeping: a `BARRIER-PULLED` field outside the
verb's `kMGPipeClassFieldMask` was never copied *for this verb* by the client's residual fill, so
answering it would trade a loud staleness for a quiet one. Pinned by
`ABarrierPulledFieldOutsideTheVerbsClassIsStillFatal`.
**The arming condition is the server stamp, not the build.** `build-split` runs
`MOBILEGL_TRANSPORT=monolith` in every unit and integration lane, and there the client fills and
stamps all 63 fields at every verb — so a stale read there is the same defect it is in a verify
build and gets the same `Fatal`. Arming on `MOBILEGL_BUILD_DISAGGREGATED` would have taken 1862
unit cases' ability to go red away with it.
### 1.5 The sticky exemption, cancelled (deliverable 4)
Two halves, and both are needed:
1. the stamp **zeroes** the seven's `FilledGen`, and `generated/PipeFilled.inc:420` tests
"never filled" *before* `:421` tests sticky — so `0` wins and the exemption is gone **without a
line of the generated file changing**, i.e. without touching `gen_pipe.py` (c0's);
2. the seven carry no `MGP_INPUT_CHECK` at all, so freshness can never *reach* them. Each body in
`PipeFill.cpp` opens with `MGP_STICKY_FORWARD_PULL(<Field>)`, which is what actually puts them
in `rsp` and makes them `Fatal` under strict.
Assignments per the contract: the first five and `RecordError` → BARRIER-PULLED;
`InvalidateCompileEnv` → BARRIER-PULLED **retiring in P5 via `OnCapsInvalidated`** (see §6.2 —
there is no fifth class to put it in, and its forward row carries the mechanism). The hook is a
no-op outside a server-stamped verb, which is exactly what keeps `InvalidateCompileEnv`
reachable from backend initialisation — the case the exemption was written for
(`PipeInputs.h:565`).
### 1.6 `MGPipeUnmigratedEmulation` (deliverable 6)
One function edit in `PipeApply.cpp` (shared with w1 — **I touched that one function and its
include block and nothing else**), five call sites armed: `Managers.cpp:5334`,
`DirectGLES.cpp:8051`, `:8702`, `:8997`, `:10623`.
**The arm is the TRANSPORT, not the build**, and this is a correction to the contract's wording
("in a split build"): `build-split`'s own 1117 integration cases run monolith and several of the
five are on ordinary monolith paths they exercise (`glGenerateMipmap` reaches two). Arming on the
build would have turned that lane red for running code that is correct in the role it runs in.
Pinned both ways by `AnUnmigratedEmulationIsFatalUnderARealTransportAndInertUnderMonolith`.
### 1.7 `MOBILEGL_IPC_STRICT_ERRORS=1` (deliverable 5)
`MG_Config::Ipc.StrictErrors` (c0 landed the knob and its parse) promotes a BARRIER-PULLED read —
including the seven sticky forwards — to:
```
MGPipe: Fatal{UnmigratedPipeInput, "GetActiveTextureUnit@ReadPixels"} [BARRIER-PULLED,
MOBILEGL_IPC_STRICT_ERRORS=1, retires in P3b/P4b]
```
Same first clause as the ordinary poison Fatal so every existing filter still matches, plus the
class **and the phase that owes the answer** — a strict abort that did not name the phase would
leave the reader exactly where the gate found them.
Three named death tests assert it actually aborts:
`StrictErrorsTurnsABarrierPulledReadIntoANamedAbort`,
`StrictErrorsAlsoPromotesTheStickyForwards`, and the non-strict control
`TheSameReadWithoutStrictErrorsSurvivesAndIsCounted`.
---
## 2. THE STAMP RULE — v1 reads this section
`Server/PipeApplier::StampVerbBoundary(MGPWireOp op)` should be exactly:
```cpp
void PipeApplier::StampVerbBoundary(MG_Pipe::MGPWireOp op) {
const MG_Pipe::MGPipeVerb verb = MG_Pipe::MGPipeVerbForWireOp(op);
if (verb == MG_Pipe::MGPipeVerb::kVerbCount) return; // not a verb boundary: stamp nothing
MG_Pipe::MGPipeServerStampVerbBoundary(verb);
}
Uint64 PipeApplier::ResidualPullCount() const { return MG_Pipe::MGPipeResidualPullCount(); }
```
Both entry points are declared in `MG_Backend/MGPipe/PipeInputs.h` under
`#if MOBILEGL_BUILD_DISAGGREGATED` and defined in `PipeInputs.cpp`.
**WHEN.** Once per record, **before** the record's applier runs, exactly as
`PipeApplier.h` already says. `MGPipeVerbForWireOp` is generated from
`MGP_VERB_OP_LIST` in `FieldOwnership.def` and answers `kVerbCount` for every op that is not a
verb boundary, so calling it unconditionally on every record is correct and cheap.
**WHICH OPS.** Four: `Clear → Clear`, `DrawVbo → DrawArrays`, `ReadPixels → ReadPixels`,
`Blit → BlitFramebuffer`. The two name spaces do not line up by name, which is why the map is a
table and is checked against `PipeCalls.def` and `FillPoints.def`.
**`Present` IS DELIBERATELY NOT A STAMP POINT**, although CONTRACT §7 puts it in class B:
`FillPoints.def:21` — *"Present and SetSwapInterval go through BackendObject virtuals and read no
frontend state, so they are not verbs here"*. There is no `MGPipeVerb::Present`,
`MGPipeValidateForVerb` is never called for it, and stamping there would retire the previous
verb's answers with nothing to put in their place. Pinned by
`VerbBoundaryOpsAreTheFourTheStampRuleNames`.
**WHAT IT DOES**, in three lines, the third being the load-bearing one:
1. `++CurrentVerbSerial` and set `m_currentVerb`, so a Fatal names the verb instead of `<none>`;
2. **stamp** `FilledGen[i] = CurrentVerbSerial` for every field that is (RECORD-SUPPLIED or
APPLIER-DERIVED) **and** in this verb's `kMGPipeClassFieldMask`;
3. **zero** `FilledGen[i]` for everything else — BARRIER-PULLED, FATAL, and anything outside the
class mask.
(3) is what makes the instrumentation real. The client's residual fill stamps **all 63** fields at
its own verb boundary, so without the withdrawal every field would read fresh on the server, `rsp`
would be identically 0, and the exit gate would be decoration — the exact "an inproc
implementation proves nothing" failure R-2 exists to prevent. It is also, for free, what cancels
the sticky exemption.
The value a BARRIER-PULLED read then gets is still the client's residual fill's, and it is still
**correct**, because the verb barrier (R-1) leaves exactly one of the two threads runnable. That
is the debt, not a bug.
**CLEARING.** `MGPipeServerClearVerbBoundary()` disarms it. The client's own
`MGPipeValidateForVerb` and `MGPipeLeaveVerb` already call it (landed here), so v1 does **not**
have to — but calling it when the apply thread leaves the applier is harmless and makes the flag
mean "the current stamps are the server's" even if a future phase stops routing through the
client's fill.
**WHAT V1 MUST NOT DO.** Do not stamp per record on non-verb ops (a `set_dynamic_state` between
two draws is part of the draw's verb); do not batch two verbs into one stamp (the withdrawal is
per verb and a batched stamp would let the second verb read the first's answers).
---
## 3. Acceptance
All four build directories, `~/w7/p5-p1-gate.sh`.
| gate | number |
|---|---|
| configure / build, 4 dirs | rc=0 × 4, `CTestTestfile.cmake` present in all four |
| `gen_pipe.py --check` | up to date |
| `gen_pipe_dirty_surface.py --check` / `--self-test` | green / **27** controls tripped |
| `gen_pipe_field_ownership.py --check` / `--self-test` | green / **11** controls tripped, positive control OK |
| `check_include_closure.py` | 4 probes, 0 skipped, **0 problems** |
| **G1** | `.text` 10806323 → 10806323 (**+0**); 27811 → 27811 defined symbols, **0 added / 0 removed / 0 resized / 0 renamed** |
| G1 purity | `nm` pull `MG_Remote` = **0**; split = **188** |
| `ctest -L unit` pull / push / verify | **1791 / 1791 / 1791**, 0 failed (baseline 1785 + 6 arithmetic cases) |
| `ctest -L unit` split | **1862 / 1862**, 0 failed (baseline 1842 + 20 cases) |
| `ctest -L integration-gpu`, `MOBILEGL_TRANSPORT=monolith` | build-push **1117/1117**, build-split **1117/1117** |
| G14 (build-push, all labels, vs `p5-before-ctest-names.txt`) | **0 removed**, +6 added (the six arithmetic cases) |
| integration-gpu names, push vs split | **identical** (0 diff lines) |
**Why G1 held**, stated so it is not rediscovered: every new line is behind
`MOBILEGL_BUILD_DISAGGREGATED` or inside a translation unit the pull build does not compile.
`PipeInputs.{h,cpp}` and `PipeFill.cpp` are push-only (`CMakeLists.txt:519`), `PipeApply.cpp` is
push-only, and the generated table is included **from `PipeInputs.h`, not from
`MG_Pipe/MGPipe.h`** — which is the one decision in this package that G1 actually turned on,
because `MGPipe.h` is in the pull build's include closure. The only file that is in the pull
build at all is `PipeStats.{h,cpp}`, and both of its new lines are inside the existing
`#if MOBILEGL_PIPE_PUSH` block.
### 3.1 The named negative controls
- **E4's field control**: `gen_pipe_field_ownership.py --self-test` control #1, "a field in NO
class (GetActiveTextureUnit's row removed)". Verified red by name.
- **E4's supplied→FATAL control**: `--self-test` control #2 refuses it at generation time, and if
it is forced through the *generated header*, two named cases go red —
`FieldOwnershipTest.TheClassSizesPartitionTheFieldSet` and
`FieldOwnershipTest.ARecordSuppliedFieldIsReadableAfterAServerStamp`. (v1 of this report said
the latter goes red because "the read aborts instead of completing"; it does not — its
`ASSERT_EQ` on the field's class fires first and returns. Red by name either way, but the
mechanism is the assertion, not the abort. Reviewer's m-7.)
- **the instrumentation can go red**: `StrictErrorsTurnsABarrierPulledReadIntoANamedAbort`.
---
## 4. The size of the debt
The exit gate wants `rsp`'s end-of-P5 value. **It cannot be measured yet**: `rsp` counts *reads*
inside a server-stamped verb, and nothing stamps until v1 places the call and s1/c1 supply a
session. What *can* be derived now, and is, is the **field** debt — the distinct BARRIER-PULLED
fields each reduced-path verb class may read, intersected out of `kMGPipeClassFieldMask`:
| verb class | fields it may read | of those, BARRIER-PULLED |
|---|---|---|
| `kClear` | 25 | **14** |
| `kDraw` | 54 | **26** |
| `kReadback` | 24 | **18** |
| `kBlitOrCopy` | 29 | 18 |
| `kTextureOp` | 17 | 16 |
| `kProgramOp` | 18 | 14 |
**Union over the reduced path (kClear ∪ kDraw ∪ kReadback) = 27 distinct fields**, which is the
census's 20 non-sticky rows plus the seven sticky forwards. (The census's "21" counted
`GetPixelStoreParameters`, which is APPLIER-DERIVED here, and did not count the sticky seven,
which were invisible to the gate before this package.)
Per-frame `rsp` will be larger than 27, because several of these are read many times per verb —
`GetFramebufferBindingSlot` alone has eight Espryt call sites through
`GetFramebufferBindingSlotChecked`, and `GetBufferBindingSlot` has 18. **The first real number is
v1+c1+s1's to record**; the retiring-phase histogram the generator prints is what says which phase
takes which share of it:
```
P3b/P4b 7 P8 1
P3b/P4b (Espryt), P7 (Magma) 7 P8 (Espryt), P7 (Magma) 1
P3b/P4b, P7 3 P8 (indirect), P9 (readback), P13 … 1
P5 1 P9 3
P7 1 P7/P13 1
P7/P9 1
```
---
## 5. Findings
**F-1. Every backend read of the pixel store passes `false`.** All six
`MGB_CTX->GetPixelStoreParameters(...)` sites in the tree read the PACK half:
`DirectGLES.cpp:7924`, `:9399`, `:10893`, `:11272`, `Utils.cpp:2302` and
`VulkanRenderer.cpp:10980` — **six, not the five the contract names**; the scout named five and
did not open them. `PipeFill.cpp`'s `EmitPixelPackState` says the same from the other side:
*"PACK only, deliberately: nothing on the far side of the boundary reads unpack state"*. So the
unpack half is not merely uncarried — **it has no reader at all**, which is what makes FATAL the
right class for it rather than BARRIER-PULLED.
**F-2. RECORD-SUPPLIED is 32, not 31** (§1.2).
**F-3. The applier's derivation and the record-supplied set overlap completely.** The contract
describes APPLIER-DERIVED as "the render-state mirrors, `m_pixelStore[0]`, capability bits, the
current vertex attribute and the patch fields", but all of those except the pixel store are
*also* emitted, and `GetCurrentVertexAttribute` is emitted-and-still-pulled (the applier writes it
and cannot reproduce GLContext's cross-view conversion — `PipeFill.cpp:1884-1896`), so it is
BARRIER-PULLED, exactly as the contract's own 21-row list says. With "each row in exactly one
class" enforced, APPLIER-DERIVED has precisely one member: the field with a record that supplies
*half* of it. That is a real class, not a degenerate one — it is the shape "a record arrives and
the applier writes the field, but no row of the emitted list may claim it".
**F-4. `Present` is class B but not a verb** (§2).
---
## 6. Where I did not do what the contract said, with evidence
### 6.1 `GetPixelStoreParameters` is split BY ARGUMENT, not into a second field id
The contract (§3) and the brief (R-7, §5 p1) both say: split it into pack and unpack field ids,
`kMGPipeInputFieldCount` 63 → 64. **I did not**, and the table narrows it by argument instead —
one field row (`APPLIER_DERIVED`) plus one row in `MGP_FIELD_OWNERSHIP_ARG_LIST`
(`arg0 == 1 → FATAL`), consulted by the accessor through `MGP_INPUT_CHECK_ARG`.
Four reasons, in order of weight:
1. **The tree already ruled this exact shape, in the file the contract cites.**
`Coverage.def:62-69`, about `GetBufferBindingSlot`: *"THE ROW STAYS ONE ROW, and that is
structural rather than a shortcut: this list IS the `MGPipeInputField` enum and the
`PipeInputs` field set, and the field is ONE array … that a second row of the same name could
only duplicate."* `m_pixelStore[2]` indexed by `isUnpack` is the same shape as
`m_bufferBindingSlot[15]` indexed by a `BufferTarget`, and `GetBufferBindingSlot` is
half-migrated in exactly the same way (8 of 15 targets carried, 7 not) without anyone
proposing 15 field ids for it.
**The same file also says the opposite about *this* field**, eleven lines down
(`Coverage.def:173-181`): *"**Until the field is split**, the whole of it keeps going through
the fill loop and the pack half is simply written twice."* So the precedent is genuinely
two-sided and v1 of this report presented only the half that supported the decision
(reviewer's q-3). What settles it for P5 is reason 4, not the precedent: the tree anticipates
a split into two *storage* halves so that each can be independently filled and verified, and
this package needed a split into two *verdicts*, which is a smaller thing and is available
without a field id.
2. **A second field id costs c0's files and mine cannot.** The enum is generated from
`Coverage.def`'s accessor list; the class masks come from `FillPoints.def`. Both are c0's,
`gen_pipe.py` is c0's, and the preamble's 铁律 is that a package does not edit another's files.
The argument-keyed form needed **zero** c0-owned files.
3. **It would break the strangler invariant.** `PipeInputs.h:140-142`: *"every accessor keeps the
NAME, PARAMETERS and RETURN TYPE of its GLContext counterpart … so the strangler sed is
type-neutral"*. `GLContext::GetPixelStoreParameters(Bool isUnpack)` is one accessor; two field
ids want two accessors or a field id chosen from an argument anyway — and if it is chosen from
an argument, the second id buys nothing the argument row does not.
4. **The result is strictly stronger than the contract's.** Two field ids would make the unpack
half BARRIER-PULLED — counted and *silently served* out of the client's fill. Because no
backend reads it (F-1), FATAL is available, and a future reader gets a named abort on its first
read instead of a stale struct. `TheUnpackHalfOfThePixelStoreAbortsWhileThePackHalfDoesNot`
pins both halves.
**What would overturn it:** a decision by the integrator that the 63 → 64 move is wanted anyway
(e.g. because the verify comparator or a later phase needs per-half stamping). The change is then
small and localised: add `GetPixelStoreUnpackParameters` to `Coverage.def`'s accessor list and to
`FillPoints.def`'s `kReadback`/`kTextureOp` rows, add its storage row to
`MGP_INPUT_STORAGE_LIST`, and replace the one row in `MGP_FIELD_OWNERSHIP_ARG_LIST` with a normal
field row. I did not pre-stage it because it would have left c0's files edited by p1.
Consequently **`kMGPipeInputFieldCount` stays 63** and there were no asserts to move. The two
stale doc lines the package was asked to fix were stale for a different reason — they said
**61** — and both are corrected to 63 (`ARCHITECTURE.md:83`, `MEASUREMENTS.md:82`).
### 6.2 `InvalidateCompileEnv` is BARRIER-PULLED with retiring phase "P5"
The contract lists the seven sticky forwards' P5 assignment as "five → BARRIER-PULLED,
`InvalidateCompileEnv` → `OnCapsInvalidated`, `RecordError` → BARRIER-PULLED". There is no fifth
class, and R-7.1 requires every row to be in exactly one of four. So `InvalidateCompileEnv` is
**BARRIER-PULLED, retiring in P5**, and `OnCapsInvalidated` is recorded as its *mechanism* in the
forward row (`kMGPipeFieldOwnershipForwardMechanism`). It is the only row in the table whose
retiring phase is P5 itself. Nothing about the runtime behaviour differs from the contract's
intent: it is counted in `rsp` and `Fatal` under strict, and it stops being either the moment
R-12's reverse channel replaces the forward.
### 6.3 `PipeFilled.inc:421` is not edited
The contract asks that the unconditional-fresh line stop being unconditional in a split build.
It is **generated by `gen_pipe.py`**, which is c0's, and editing it there would change
`MGPipeInputFieldIsFresh` for every push build. It is also unnecessary: `:420`'s
`gen == 0 ⇒ not fresh` is tested **first**, so the stamp's withdrawal already wins. Pinned by
`TheStickyExemptionIsCancelledByTheServerStamp`, which shows the seven fresh after a client fill
and stale after a server stamp. **What would overturn it:** a phase that wants the seven poisoned
*without* a server stamp having happened — at which point the line has to move, in c0's file.
### 6.4 `MGPipeUnmigratedEmulation` arms on the transport, not the build (§1.6)
### 6.5 The class-mask condition on a BARRIER-PULLED read (§1.4) is mine, not the contract's
---
## 7. Files I touched that are not mine, and what the integrator should sequence
| file | owner | what I did | conflict risk |
|---|---|---|---|
| `MG_Util/Metrics/PipeStats.{h,cpp}` | **b1** | one enumerator, one name string, one `line +=` — all inside the existing `#if MOBILEGL_PIPE_PUSH` block, appended after `TextureRemintPulls` | b1 adds `persistent-map-push` in the same block. **Textual conflict is likely and trivial**; both are appends at the same point. Land either order, keep both. |
| `MG_Pipe/PipeApply.cpp` | shared with **w1** | `MGPipeUnmigratedEmulation`'s body (last function in the file) + one guarded `#include <Config.h>` | low; w1 works in the record entry points |
| `MG_Test/Pipe/CMakeLists.txt` | shared | one `add_executable` + one `gtest_discover_tests`, appended | the P4a same-point-append shape; other packages adding suites here will conflict textually |
| `docs/Disaggregated/{ARCHITECTURE,MEASUREMENTS}.md` | shared | `ARCHITECTURE.md:83` 61→63 + a G8 paragraph; `MEASUREMENTS.md:82` 61→63 | b1 owns `MEASUREMENTS.md:111` (20→21); different line |
**`.github/workflows/test.yml` is t1's and I did not touch it.** The two lines t1 must add, beside
`gen_pipe_dirty_surface.py`'s at `:1664-1665`:
```yaml
python3 scripts/gen_pipe_field_ownership.py --check
python3 scripts/gen_pipe_field_ownership.py --self-test
```
Without them the table is generated and committed but nothing diffs it in CI, which is exactly
the half of R-7.1 a build-level `static_assert` cannot cover.
---
## 8. The account left for later phases
1. **`rsp`'s first real value.** Needs v1's stamp call and a session. §4 has the field-level
ceiling and the per-phase histogram; MEASUREMENTS wants the runtime number.
2. **The strict lane end-to-end.** `MOBILEGL_IPC_STRICT_ERRORS=1` is proven to abort at unit
level, on reduced-path verbs (`Clear`, `DrawArrays`, `ReadPixels`) and reduced-path fields.
The *lane* — a `DirectGLES.Split.*` run under strict that aborts and names the field — needs
t1's ctest `ENVIRONMENT` block and a live session, and it is the last third of E4.
3. **`MOBILEGL_PIPE_POISON`'s visibility** (c0's filed note, left on p1's account). c0 closed the
seven-TU defect with per-file includes. I did **not** move the derivation into
`MG_Pipe/MGPipe.h` or add a tripwire for TUs that test the macro without including its header:
the derivation lives in a header that the pull build does not see, and moving it there would
put a new macro on every push TU's surface — a much larger blast radius than the defect. It
stays filed.
4. **The 41 null-checked emit-table slots** (CONTRACT §7's cross-cutting rule) are c1's, not
touched here, but they are the same shape as this package's problem: a probe that reads as
"supported" because the thing it probes cannot be null any more.
5. **`MGPipeVerbForWireOp` has four rows.** Every phase whose record becomes a verb boundary adds
its row to `MGP_VERB_OP_LIST` in `FieldOwnership.def`; the generator refuses a row whose op or
verb does not exist, so the failure mode is a red generator rather than a silently absent
stamp.
---
# §7 — Fix round 1, against `p1-review-v1.md`
Verdict answered: **0 BLOCKER / 5 MAJOR / 8 MINOR / 4 QUESTION**, conditional on M-1, M-2, M-3.
All three conditions are closed. Second commit range below; §3's numbers re-run in full.
## 7.1 The three conditions
### M-1 — a vacuous negative control, and the harness that let it be vacuous. **CLOSED.**
The reviewer is right, and the root cause is the part worth keeping. `expect_trip` caught any
`SystemExit` and asked nothing about which one, so control #4's raw replacement string could
mangle the row past `ROW_RE`'s reach, make the row *disappear*, and exit with control **#1**'s
message while the report counted a trip for #4. The guard that every debt row names its retiring
phase had no control at all.
Three changes, in order of importance:
1. **`expect_trip(name, because, fn)`** now takes the substring the control's own message must
contain and **fails when the message belongs to another control**, printing both. This is the
discipline `gen_pipe_dirty_surface.py` already used (`:1574` `p.startswith("UNMAPPED")`,
`:1581` `"STALE row"`, …) and the half that had been dropped.
2. **A harness control**, so the harness itself cannot rot back: control #1's edit, asserted
against control #4's reason, must be **rejected**, and the self-test exits if it is accepted.
That is the reviewer's instrumentation made permanent instead of thrown away.
3. Control #4's replacement is no longer a raw string.
**Re-audit of every control under the stricter harness**, as instructed: each was re-run with its
actual exit message printed and compared. Evidence in `~/w7/p5-p1-selftest-evidence.log`
(produced by `~/w7/p5-p1-selftest-evidence.py`, which monkeypatches `expect_trip` and changes
nothing on disk). Result:
```
15 controls, 15 DISTINCT exit messages, 15 asserted against their own message
```
No second duplicate existed — #4 was the only one — but the check can no longer be skipped, and
the count went 11 → 15 because M-2 added four.
### M-2 — the stamp map could not see an OMITTED row. **CLOSED.**
`check_verb_ops` now asks the other direction. The required set is **derived twice**, not
asserted: a call is verb-shaped if (a) `PipeCalls.def` gives it the kind `kCtxVerb` — the
catalogue's own word for it — or (b) its name is also an `MGPipeVerb` name in `FillPoints.def`.
That is **15 calls**, and every one must have a stamp row or an **exemption row with a reason**.
The map went from 4 rows to **12 rows + 3 exemptions**:
- the four class-B boundaries (`Clear`, `DrawVbo`, `ReadPixels`, `Blit`) — unchanged;
- **eight mapped ahead of the phase that will emit them**: `LaunchGrid`→`DispatchCompute`,
`MemoryBarrier`, `BeginStreamOutput`→`BeginTransformFeedback`, `EndStreamOutput`,
`PauseStreamOutput`, `ResumeStreamOutput`, `GenerateMipmap`, `GetTextureImage`. All are class C
today and cannot arrive in P5, which is why mapping them is free — and the reviewer's point is
that the failure of *not* mapping them is silent, so free is the right price;
- three exemptions with their reasons in the file: `Present` and `SetSwapInterval`
(`FillPoints.def:21`, they are not verbs), `Flush` (BRIEF §12 C-3: not a slot at all, and
`glFlush`/`glFinish` are empty function bodies, so there is no `MGPipeVerb::Flush` to name).
Four new negative controls, each asserting its own message: an omitted row (**#12**), an exemption
for a call that was never required (**#13**), an exemption with no reason (**#14**), and — the one
that keeps the derivation honest — **#15**, the catalogue's `kCtxVerb` kind renamed away, which
collapses the required set and must be caught. `VerbBoundaryOpsCoverEveryVerbShapedCall` pins all
twelve rows, the three exemptions and two non-boundaries at runtime.
**Not claimed, and the .def says so**: a call that is a verb boundary, is not `kCtxVerb`, and is
renamed. `ResourceCopyRegion` is the one in the tree and it maps to *three* verbs
(`CopyImageSubData` / `CopyTexSubImage2D` / `CopyTexImage2D`), so it cannot be a row without a
rule for choosing; the phase that emits it writes its row. **§8.5 of this report was wrong in the
direction that mattered** — it claimed the failure mode was a red generator rather than a silently
absent stamp — and is superseded by this section.
### M-3 — `--check` ran in no CI job. **CLOSED, and it is t1's file.**
Landed as a step in the `pipe-gates` job of `.github/workflows/test.yml`, immediately after the
dirty-surface step its siblings live in:
```yaml
- name: MGPipe PipeInputs field-ownership table is complete (R-7.1, table 2)
run: |
python3 scripts/gen_pipe_field_ownership.py --check
python3 scripts/gen_pipe_field_ownership.py --self-test
```
**No branch guard**, deliberately, unlike the two G5 steps below it: the question is "does the
committed table still follow from the .def files", which every branch can answer and which
outlives `feat/disaggregated`.
Why the existing "Regenerate the MGPipe interface (G1-G7)" step does not already cover it: that
step runs `gen_pipe.py` and diffs `MobileGL/MG_Pipe/generated`, and `gen_pipe.py` does not write
`PipeFieldOwnership.inc` — so a drifted ownership table passes it untouched. The reviewer proved
in §E4 control C that a hand edit changing a *class* builds clean (the `static_assert` catches
only `kUnclassified`), so `--check` is the only thing in the tree that catches it.
**`.github/workflows/test.yml` is t1's file.** I landed the step rather than skipping it, on the
coordinator's instruction. It is a pure insertion of one step between two existing ones, so the
merge is textual and trivial — but **the integrator should sequence it against t1**.
## 7.2 The other MAJORs
### M-4 — the stamp asserts freshness from the table, not from the records that arrived
**Not changed. Documented — and the reviewer's proposed repair does not work as stated**, which is
the useful half of this answer.
The finding is right: for the 33 RECORD-SUPPLIED + APPLIER-DERIVED fields, a dropped emitter or an
over-eager suppressor now renders wrong instead of aborting, and the report did not say so.
The suggested repair — *"have `MGPipeApplyAccess`'s writers stamp the field they write, and let
the verb boundary only withdraw"* — would abort on nearly every verb. `MGPipeInputFieldIsFresh`
requires `gen == CurrentVerbSerial` for a non-sticky field, and the applier's mirror is
**persistent across verbs by design**: `bind_render_state` / `set_dynamic_state` /
`set_sampler_views` are all suppressed when nothing changed (`PipeFill.cpp:1917-1923`), so a field
written at verb N and legitimately not rewritten at verb N+1 would carry stamp N, read stale and
Fatal. The client's fill does not have this problem because it copies **every** field in the class
mask at **every** verb; the applier structurally cannot.
So the real choice is between three designs, and it needs a **c0 ruling**, because two of them
change `MGPipeInputFieldIsFresh`, which `gen_pipe.py` generates:
| | rule | catches a dropped emitter? | cost |
|---|---|---|---|
| **A (landed)** | the boundary stamps by class + mask | no | 0 |
| **B** | writers stamp; the boundary stamps a supplied/derived field **only if it already has a non-zero generation** | yes, for a field whose record *never* arrives | one call per applier write site in `PipeApply.cpp` (w1-shared): 6 sites + `MGPipeDeriveRenderStateFields`' 29 fields |
| **C** | writers stamp; supplied/derived become *server-sticky* (`gen != 0 ⇒ fresh`) and the boundary withdraws only the other two classes | yes, same scope as B, and it is the honest generation model for a mirror that persists | B's cost **plus** a change to `MGPipeInputFieldIsFresh` in `gen_pipe.py` |
Neither B nor C catches the case the reviewer names first — *a chunk dropped from a record that
does arrive* — because the write site still runs. That case's oracle is the verify lane's
compare-at-read, which is what `MOBILEGL_PIPE_VERIFY` is for and which does not exist under split;
saying so is more useful than implying a stamp could cover it.
**Recommendation: C, in a later round or a later phase, not mid-flight.** It touches a c0 file and
a w1 file and it changes the rule v1 is coding against *now*. Landing A and writing this table
down is the smaller risk. The integrator should rule before v1 places the call if they disagree.
### M-5 — `MGPipeServerClearVerbBoundary` was described to v1 as optional. **CLOSED.**
The reviewer is right that it holds only for inproc: in a spawned server MG_Impl is not in the
process, nothing calls `MGPipeValidateForVerb`, and `m_serverStampedVerb` would latch TRUE for the
life of the server — after which `MGPipeStickyForwardPull` stops being a no-op outside a verb and
`InvalidateCompileEnv` from a later context's backend initialisation (the exact case the sticky
exemption exists for) is counted and, under strict, aborts.
- `PipeInputs.h`'s `ServerStampedVerb()` and `MGPipeServerClearVerbBoundary()` now say **MANDATORY
for the applier**, with that failure written out.
- **§2 of this report is superseded on that point: v1 must clear on leaving the applier.**
- New named test `TheAppliersOwnClearDisarmsTheStampWithoutTheClientsFill` reaches that path
directly — stamp, pull a forward, clear, pull it again, assert the count did not move — instead
of relying on the client's fill, which is what the old test did.
## 7.3 MINOR
| # | disposition |
|---|---|
| **m-1** | **Fixed.** `AServerStampMakesRecordSuppliedFieldsFreshAndWithdrawsTheRest` now also asserts four **named** fields against expectations that are arguments of this package rather than lookups into the array under test: `GetClearColor` and `GetRenderStateParameters` fresh, `GetFramebufferBindingSlot` and `RecordError` withdrawn. The loop stays, because it is what catches a stamp that disagrees with the table. |
| **m-2** | **Fixed.** The argument-keyed abort now prints `[argument 0 = 1 is FATAL while the field is APPLIER-DERIVED]` after the standard `Fatal{UnmigratedPipeInput, "…@…"}` clause, so it is no longer byte-identical to a stale pack read. Asserted in `TheUnpackHalfOfThePixelStoreAbortsWhileThePackHalfDoesNot`. |
| **m-3** | **Not fixed; documented at the stamp entry point.** `draw_vbo` carries no verb id, so all twenty draw verbs stamp as `DrawArrays`. The class mask is right and only the NAME in a Fatal is wrong. Fixing it needs a field on the record or a second argument to the stamp, and it belongs with the phase that widens `draw_vbo` to the multi-draw family (P8). Written into `PipeInputs.h`'s note (b) so v1 does not rediscover it. |
| **m-4** | **Fixed.** `MGPipeInputArgumentRead` returns `Bool handled` and `MGP_INPUT_CHECK_ARG` skips the field-level check when the argument row decided. Worth noting the bug would have been the *other* way round from the report's guess: with the field's own class not BARRIER-PULLED, the field-level check would have **aborted** a read the argument row had just declared legal, rather than double-counting it. |
| **m-5** | **Fixed (comment).** `MGPipeResidualPullCount`'s declaration now states that `g_residualPulls`, `m_serverStampedVerb` and `FilledGen[]` all rest on the verb barrier's mutual exclusion — CONTRACT §4's ruling for `gPipeInputs` itself — and that `MOBILEGL_IPC_VERB_BARRIER=0` is therefore a data race on all three as well as the correctness failure it exists to show. |
| **m-6** | **Documented here.** `PipeApplier::m_residualPulls` (c0's `Server/PipeApplier.h:99`) is **vestigial** under §2's snippet: `ResidualPullCount()` forwards to the process-wide counter, because the count is made at the accessor and the accessor has no applier to reach. v1 should delete the member rather than wire both. |
| **m-7** | **Fixed in §3.1.** |
| **m-8** | **Fixed in §1.5 and §6.3** (`:419`/`:422` → `:420`/`:421`). |
## 7.4 QUESTION
- **q-1 — `texture-remint-pull` has no documented exclusion.** Correct, and I cannot close it from
the source: `Managers.cpp:5334` is reached from the image-bindable re-mint transition, BRIEF §4's
reduced-path exclusions do not name it, and OpenRA's fixture is the only thing that could answer.
**The consequence of being wrong is an abort in E2's inproc arm, not a degraded frame** — the
safe direction for a gate and the loud direction for a lane. Two cheap ways out if the
integrator does not want the risk: run the OpenRA fixture once with the other four sites armed
and this one still `(void)name;`, or put the five sites behind `MOBILEGL_IPC_STRICT_ERRORS`
instead of the transport. **Integrator's call; I have not taken it.**
- **q-2 — the transport-keyed arm is inert in a server that does not inherit the env.** Right, and
the third option the reviewer names is better than either of mine: key on *"am I inside a server
role"*. That predicate does not exist yet — `ServerLoop` / `PipeApplier` are v1's and land this
phase — and once it does, `MGPipeUnmigratedEmulation` should read it instead of
`MG_Config::Transport`. **P6's account**, because P6 is where a child process without the
variable can exist at all; under inproc the variable is this process's and correct.
- **q-3 — `Coverage.def:173-181` cuts against §6.1.** Accepted; §6.1 now quotes both halves and
says which reason actually carries the decision (reason 4, not the precedent).
- **q-4 — non-boundary records apply under the previous verb's stamp.** Accepted and now written
into the rule v1 inherits, as note (a) at `MGPipeServerStampVerbBoundary`'s declaration: it is
correct today because every `MGPipeApply*` entry point touches `gPipeInputs` through
`MGPipeApplyAccess`, which carries no `MGP_INPUT_CHECK`; the day one of them calls back into the
backend, its reads will be judged against a verb they do not belong to.
## 7.5 Fix-round acceptance, re-run in full
Second commit range: **`6fc1bcc8..9d40d3e9`**. Everything below was re-run from the gate script, not
carried over.
| gate | fix round | round 1 |
|---|---|---|
| configure / build, 4 dirs | rc=0 × 4, `CTestTestfile.cmake` present in all four | same |
| `gen_pipe.py --check` | up to date | same |
| `gen_pipe_dirty_surface.py --check` / `--self-test` | green / 27 controls tripped | same |
| `gen_pipe_field_ownership.py --check` | green | green |
| `gen_pipe_field_ownership.py --self-test` | **15 controls, each asserted against its OWN message; harness control OK; positive control OK** | 11, one of them vacuous |
| per-control evidence | **15 distinct exit messages / 15 controls** (`~/w7/p5-p1-selftest-evidence.log`) | — |
| `check_include_closure.py` | 4 probes, 0 skipped, 0 problems | same |
| **G1** (`--threshold 0`) | `.text` 10806323 -> 10806323 (**+0**); 27811 -> 27811, **0 added / 0 removed / 0 resized / 0 renamed** | `+0`, 0/0/0/0 |
| G1 purity | `nm` pull `MG_Remote` = 0; split = 188 | same |
| `ctest -L unit` pull / push / verify | **1791 / 1791 / 1791**, 0 failed | 1791 × 3 |
| `ctest -L unit` split | **1863**, 0 failed (+1: the new applier-clear case) | 1862 |
| `integration-gpu`, `MOBILEGL_TRANSPORT=monolith` | push **1117/1117**, split **1117/1117** | 1117 / 1117 |
| G14 vs `p5-before-ctest-names.txt` | **0 removed**, +6 added (one of the six renamed this round; the baseline is the phase base, so a rename of my own round-1 name is not a deletion) | 0 removed, +6 |
| integration-gpu names, push vs split | **identical**, 0 diff lines | identical |