Files
MobileGL/docs/Disaggregated/notes/p4a/scout-pipe-and-client.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

1052 lines
87 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.
# P4a scout — the MGPipe scaffolding and the P3a client conventions
Tree read: `C:/Users/geekerwan/AndroidStudioProjects/FoldCraftLauncher/MobileGL-disagg`, branch
`feat/disaggregated` @ `37da3c3a` (P3a docs; landing hash `fde5fda3`). Every line number below was opened.
Repo-relative paths are under `MobileGL/` unless the path starts with `scripts/`, `.github/` or `~/w7/`.
Read first: `~/w7/notes/p3a/INTEGRATOR-DECISIONS.md` (ID-1..ID-24) and `BRIEF-P3A.md` §A (lines 108-207) and §C
(1012-1365). P4a's roadmap row is `docs/Disaggregated/ROADMAP.md:20`.
---
# PART 1 — The MG_Pipe scaffolding P4a builds on
## 1.1 `MG_Pipe/PipeCalls.def` — the rows P4a implements
The file is 183 lines. `MGP_CALL_LIST_DOCUMENTED_COUNT 71` at `PipeCalls.def:75`; **the wire opcode is the 1-based
position in `MGP_CALL_LIST`** (`:29`), so P4a **may not reorder, insert into a group, or retire a row**. A new call is
appended at the very end (the three appended rows at `:160-166` are the precedent). Class tokens are unscoped
(`MGPipe.h:29-37`: `kScreen kCtxCso kCtxState kCtxObject kCtxVerb kCtxQuery`); flag tokens at `MGPipe.h:39-55`
(`kNone=0, kNeedsAck=1<<0, kHasBlob=1<<1, kVarTail=1<<2, kHostSpan=1<<3, kReplySlot=1<<4, kOptional=1<<5`).
Opcode = line position within `MGP_CALL_LIST` starting at `PipeCalls.def:80`. P4a's rows, with opcode:
| # | row | file:line | payload | class | flags |
|---|---|---|---|---|---|
| 2 | `ResourceCreate` | `:81` | `MGPResourceDesc` | `kScreen` | `kNone` |
| 3 | `ResourceRespecify` | `:82` | `MGPResourceDesc` | `kScreen` | `kNeedsAck` |
| 4 | `ResourceDestroy` | `:83` | `MGPHandleOnly` | `kScreen` | `kNone` |
| 17 | `CreateRenderState` | `:98` | `MGPRenderStateDesc` | `kCtxCso` | `kHasBlob` |
| 23 | `CreateSamplerState` | `:104` | `MGPSamplerDesc` | `kCtxCso` | `kNone` |
| 24 | `DeleteSamplerState` | `:105` | `MGPHandleOnly` | `kCtxCso` | `kNone` |
| 25 | `CreateSamplerView` | `:106` | `MGPSamplerView` | `kCtxCso` | `kNone` |
| 26 | `DeleteSamplerView` | `:107` | `MGPHandleOnly` | `kCtxCso` | `kNone` |
| 27 | `CreateShaderState` | `:108` | `MGPProgramDesc` | `kCtxCso` | `kHasBlob` |
| 28 | `BindShaderState` | `:109` | `MGPHandleOnly` | `kCtxCso` | `kNone` |
| 29 | `DeleteShaderState` | `:110` | `MGPHandleOnly` | `kCtxCso` | `kNone` |
| 31 | `SetFramebufferState` | `:113` | `MGPFramebufferState` | `kCtxState` | `kNone` |
| 35 | `SetSamplerViews` | `:117` | `MGPSamplerViews` | `kCtxState` | `kVarTail` |
| 36 | `BindSamplerStates` | `:118` | `MGPSamplerStates` | `kCtxState` | `kVarTail` |
| 37 | `SetShaderImages` | `:119` | `MGPShaderImages` | `kCtxState` | `kVarTail` |
| 40 | `SetGlobalConstants` | `:122` | `MGPGlobalConstants` | `kCtxState` | `kHasBlob` |
| 44 | `SetDrawProgram` | `:126` | `MGPHandleOnly` | `kCtxState` | `kNone` |
| 45 | `SetDispatchProgram` | `:127` | `MGPHandleOnly` | `kCtxState` | `kNone` |
| 47 | `SetTextureParams` | `:133` | `MGPTextureParams` | `kCtxObject` | `kNone` |
| 48 | `ResourceSubData` | `:134` | `MGPSubData` | `kCtxObject` | `kHasBlob\|kVarTail` |
| 50 | `ResourceSubDataComplete` | `:136` | `MGPSubDataComplete` | `kCtxObject` | `kNone` |
| 53 | `ResourceCopyRegion` | `:139` | `MGPCopyRegion` | `kCtxObject` | `kNone` |
| 54 | `GenerateMipmap` | `:140` | `MGPMipPlan` | `kCtxObject` | `kNone` |
| 55 | `GetTextureImage` | `:141` | `MGPReadbackInfo` | `kCtxObject` | `kReplySlot` |
| 56 | `Blit` | `:143` | `MGPBlit` | `kCtxVerb` | `kNone` |
| 57 | `Clear` | `:144` | `MGPClear` | `kCtxVerb` | `kNone` |
| 58 | `ReadPixels` | `:145` | `MGPReadbackInfo` | `kCtxVerb` | `kReplySlot` |
Notes that bind P4a:
- **No `BindSamplerState` / `SetSamplerView` singular calls exist**; `PipeCalls.def:53-57` explains why: those two
binds live only as the array forms under `kCtxState`, so the CSO group holds 13 rather than 15.
- **`CreateVertexElements` is `kHasBlob` and `BindVertexElements` is `MGPHandleOnly`** (`:101-103`) — the shape
`CreateShaderState`/`BindShaderState` copies.
- The `kNeedsAck` legend (`:18-24`) says the flag means *records of this call MAY require an ack*, with the per-record
predicate `MGPipeResourceRespecifyNeedsAck(desc)` deciding. Texture/renderbuffer respecify travels on the same
`ResourceRespecify` row and inherits that predicate — `desc.Immutable != 0` (`MGPipeTypes.h:681-683`), which for a
texture means `glTexStorage*`. **If P4a wants a different answer for textures, the predicate is where it changes,
not the flag word.**
- `PipeCalls.def:169-183` is the explicit-deletions footer: `GetIntegeri_v`/`GetInteger64i_v`, `GetProgramiv`,
`ShaderStorageBlockBinding` (folded into `MGPProgramDesc`'s reflection archive), `set_pixel_unpack_state`, a
compressed-format concept, `pipe_transfer`, and **the stage dimension of `set_sampler_views`** (the texture unit
space is merged, not per-stage).
## 1.2 `MG_Pipe/MGPipeTypes.h` — payloads and their asserts
Every payload carries `MGP_ASSERT_POD(T, Size)` (`MGPipeTypes.h:44-46`: trivially copyable + exact `sizeof`). The
macro is `#undef`ed at `:880`. Sizes are asserted because wire records are `memcpy`d (`:21-23`).
P4a's payloads, verbatim from the header:
- **`MGPResourceDesc`** `:150-176`, `MGP_ASSERT_POD(..., 88)` at `:177`; `kMGPipeWholeBuffer = ~0ull` at `:178`.
Fields: `Resource`; `Uint8 Target` (`Buffer | Tex1D..TexCubeArray | Tex2DMS.. | Renderbuffer | TexBuffer`);
`Uint8 StorageKind` (`== TextureStorageType`); `Uint16 BindMask` (12 bits, see §2.1); `Uint32 InternalFormat`
("already resolved to an uncompressed fallback by the client"); `Width, Height, Depth`;
`Uint16 ArrayLayers, Levels, Samples`; `Uint8 FixedSampleLocations, Immutable`; `Uint32 Usage`
(`BufferUsage`); `Uint32 StorageFlags`; `Uint8 HasDefinedContent`; `Uint8 ImageBindableHint`
("client-side everImageBound; pre-emptive allocation"); `Uint32 GlNameForDiag` (**diagnostics only, never an
identity/memo key/hash input** — `:171-174`); `MGPipeHandle ViewOf` (storage owner for a texture view);
`MGPipeHandle BufferForTexBuffer`; `Uint64 BufOffset, BufSize`.
**The texture half of this struct is already fully specified and unused** — P3a wrote only the buffer fields
(`ResourceTracker.h:160-162` pins `kMGPipeResourceTargetBuffer = 0` and
`kMGPipeResourceStorageKindBuffer = TextureStorageType::Buffer`, and says the contract package "minted no enum for
the first list"). **P4a must mint the `Target` enum**, because `Buffer` being 0 is currently justified only by "it
is the leading member".
- **`MGPSurface`** `:343-352`, `MGP_ASSERT_POD(..., 24)`: `Res`, `Uint32 InternalFormat` (inline "so the four
cross-object masks fall out at push time with no lookup"), `Uint8 Kind` (`Texture | Renderbuffer | None`),
`Uint8 Layered`, `Uint16 Level`, `Uint32 Layer`, `Uint16 UploadTarget`, `Uint16 Pad0`.
- **`MGPFramebufferState`** `:355-377`, `MGP_ASSERT_POD(..., 304)`: `MGPipeHandle Fbo`
(`kMGPipeDefaultFramebuffer` for the default FBO), `MGPSurface Color[8]`, `Depth`, `Stencil`,
**`MGPSurface ReadSurface` — the RESOLVED read surface, not an index** (`:359-361`, "structurally closes the
read-buffer-shared-FBO defect class"; that defect is in memory as `read-buffer shared FBO`),
`Int8 DrawBuffers[8]` (attachment index, `-1` = NONE), `Uint16 Width, Height, Layers, Samples`,
`Uint8 FixedSampleLocations, IsDefault, Complete, Pad0`, `Uint32 Pad1`, **`Uint64 ContentHash`** with two jobs
(`:369-373`): the server's render-pass memo key **and the client's emission suppressor** — "an unchanged hash means
this record is not sent at all. **The same pattern is mandatory for every `kVarTail` `set_*` below**, or 26.2's
redundant `glBindSampler` traffic reappears as a variable-length record per batch."
- **`MGPSamplerDesc`** `:283-286`, `MGP_ASSERT_POD(..., 32)`: `Cso`, `MGPBlobRef Parameters`.
`:279-282`: `SamplerParameters` crosses byte for byte **including `borderColorForm`**, without which the backend
cannot pick between `glSamplerParameterIiv`/`fv` or the `VkBorderColor` families. `SamplerParameters` is
`MGPipeValueTypes.h:462`, `sizeof == 100` asserted at `MGPipeValueTypes.h:615`. Note the row carries **no**
`kHasBlob` flag in `PipeCalls.def:104` even though the payload holds an `MGPBlobRef` — an asymmetry P4a should
either fix in the flag word or document (compare `PipeApply.h:67-68`, which says `resource_respecify` deliberately
does *not* carry `kHasBlob` because `MGPResourceDesc` has no `MGPBlobRef` member; here the member exists).
- **`MGPSamplerView`** `:293-303`, `MGP_ASSERT_POD(..., 36)`: `Cso`, `Texture`, `Uint32 InternalFormat` (aliasing
format for `glTextureView`), `Uint8 Target`, `Uint8 Pad0[3]`, `Uint16 MinLevel, NumLevels, MinLayer, NumLayers`,
`Uint16 Samples`, `Uint8 FixedSampleLocations`, `Uint8 Pad1`. `:288-292`: **only the view restrictions** — anything
a `glTexParameter` writes goes on `set_texture_params`, because a texture that is only an FBO attachment, only an
image binding, or only a `glCopyImageSubData` endpoint has no sampler view to hang it on. (That sentence is the
design source of the ROADMAP's mandatory new scenario.)
- **`MGPTextureParams`** `:307-317`, `MGP_ASSERT_POD(..., 32)`: `Res`, `Uint16 BaseLevel, MaxLevel`,
`Uint8 Swizzle[4]`, `Uint8 DepthStencilMode`, `Uint8 ForceResync` (mirrors `m_forceTextureParamsResync` — "the
widened-channel carrier needs a swizzle override that the frontend params version does not move for"),
`Uint8 Pad0[2]`, `Float MinLod, MaxLod, LodBias`. **Per texture OBJECT, independent of any view.**
- **`MGPProgramDesc`** `:323-335`, `MGP_ASSERT_POD(..., 192)`: `Cso`, `Uint32 StageMask` (`== GetLinkedShaderStages()`),
`Uint32 GlobalUboSize`, `Uint32 ReservedNumSamplesOffset`, `Uint8 SpirvStatus`, `Uint8 NativeFloat64`,
`Uint8 PointSizeDemoted`, `Uint8 EnableSpirvValidation`, `MGPBlobRef Spirv[6]` (per stage), `MGPBlobRef Reflection`
("the whole `LinkArtifacts` + `SpirvArtifacts` archive; P0.5 extracts those types out of `ProgramObject.h`").
- **`MGPBoundView`** `:432-437`, `MGP_ASSERT_POD(..., 24)`: `View`, `Texture`, `Uint32 Unit`, `Uint32 Pad0`.
`:428-431`: no stage dimension, `TextureState::m_textureUnits` is one array of `MAX_TEXTURE_IMAGE_UNITS = 192`.
- **`MGPSamplerViews`** `:440-444`, `MGP_ASSERT_POD(..., 16)`: `Uint32 Start, Count; Uint64 ContentHash`.
Var-tail = `MGPBoundView[Count]`.
- **`MGPSamplerStates`** `:447-451`, `MGP_ASSERT_POD(..., 16)`: same shape; var-tail is
`MGPipeHandle[Count]` of sampler CSOs (`:446`).
- **`MGPImageView`** `:453-462`, `MGP_ASSERT_POD(..., 24)`: `Res`, `Uint32 Unit`, `Uint32 InternalFormat`,
`Uint32 Layer`, `Uint16 Level`, `Uint8 Layered`, `Uint8 Access`.
- **`MGPShaderImages`** `:464-469`, `MGP_ASSERT_POD(..., 16)`: `Uint32 Start, Count; Uint64 ContentHash`.
- **`MGPGlobalConstants`** `:507-513`, `MGP_ASSERT_POD(..., 40)`: `ShaderCso`, `Uint32 Version`, `Uint32 Pad0`,
`MGPBlobRef Blob`. `:506`: **default uniform block only (D6)**.
- **`MGPSubData`** `:636-648`, `MGP_ASSERT_POD(..., 72)`: `Res`, `Uint16 Target, Level`,
`Uint8 SourceIsVerbatimLevelShadow` (replaces the backend's `uploadData == mipData` pointer comparison),
`MGPBox UnionBox`, `Uint32 RegionCount` (`MGPSubRegion[]` in the tail), `MGPBlobRef Blob`.
`:611-613`: **carries the union box AND the region list so the SERVER picks the upload shape** — "Mali prices
texture upload by JOB COUNT: ~100 sprite rects against one union box measured +6 ms/frame". The **buffer half**
convention (`:615-618` and the helpers `MGPipeSetSubDataBufferRange` `:651-660`, `MGPipeSubDataBufferOffset`
`:661-666`, `MGPipeSubDataBufferSize` `:667`) is exactly what the texture path does **not** use: with a texture
target, `Level`, `RegionCount` and the real box come back into play, and `SubDataBoxFault`'s buffer-only
refusals (`PipeApply.cpp:510-531`) must be branched on `Target`.
- **`MGPSubRegion`** `:607-614`, `MGP_ASSERT_POD(..., 40)`: `Int32 X,Y,Z; Uint32 W,H,D; Uint64 SrcOffset;
Uint32 SrcRowStride` (0 = tightly packed), `Uint32 SrcSliceStride`. `:602-605`: source strides are **carried, not
inferred** from a pointer comparison.
- **`MGPSubDataComplete`** `:686-691`, `(..., 24)`; **`MGPCopyRegion`** `:708-716`, `(..., 64)`;
**`MGPBlit`** `:718-727`, `(..., 56)`; **`MGPClear`** `:729-739`, `(..., 48)` (one discriminated record replacing
`glClear`, four `glClearBuffer*`, four `glClearNamedFramebuffer*`); **`MGPMipPlan`** `:741-745`, `(..., 16)`;
**`MGPReadbackInfo`** `:748-756`, `(..., 64)` (`Res` null for `read_pixels`: the bound read surface answers).
- **`MGPSurfaceInfo`** `:872-878`, `(..., 24)` — the reverse-channel `OnSurfaceChanged` payload.
Two blanket rules P4a inherits:
- **THE ONE BLOB RULE** stated at `MGPipeTypes.h:270-285` (on `MGPVertexElements`) and again at `:619-631`
(on `MGPSubData`): `Blob.Size` is the record's own statement of its blob length; a **non-zero** size that
disagrees with what the record's other fields describe is `Fatal{ProtocolCorruption}` and the call is refused; a
**zero** size means "this record does not declare its blob" (a monolith emission, bytes travelling beside the
record through the entry point's companion `const void*`) and is **not** a fault. The bytes read are always
bounded by the record's *other* fields. The implementation of both halves lives at `PipeApply.cpp:521-527` and
`PipeApply.cpp:390-402`.
- `kMGPipeMaxVertexAttribs = 32` at `:378`, pinned against `VertexArrayObject::MAX_VERTEX_ATTRIBS` in the one TU
that sees both — `MG_Impl/Pipe/PipeFill.cpp:1035-1038`. **P4a needs the same shape for the unit/attachment/image
bounds** (there is no `kMGPipeMaxTextureUnits`, `kMGPipeMaxColorAttachments` or `kMGPipeMaxImageUnits` today;
`MGPFramebufferState` hard-codes 8 colours and 8 draw buffers).
## 1.3 `MG_Pipe/PipeFields.def` — the verify comparator's field lists
Purpose at `PipeFields.def:9-19`: one macro per payload listing the fields that carry MEANING; **padding is
deliberately absent** (a `Pad<n>` member is padding and is not listed) because `MOBILEGL_PIPE_VERIFY` must have zero
false positives. `gen_pipe.py` asserts — in both modes, hence in `pipe-gates` — **that every list names exactly its
struct's direct data members**; a member added without a row here fails the CI job.
P4a's existing rows (all already complete, none need adding unless a payload gains a member):
`MGP_FIELDS_MGPResourceDesc` `:44-48`; `MGP_FIELDS_MGPSamplerDesc` `:74-75`; `MGP_FIELDS_MGPSamplerView` `:77-79`;
`MGP_FIELDS_MGPTextureParams` `:81-83`; `MGP_FIELDS_MGPProgramDesc` `:85-87`; `MGP_FIELDS_MGPSurface` `:89-90`;
`MGP_FIELDS_MGPFramebufferState` `:92-94`; `MGP_FIELDS_MGPBoundView` `:108-109`; `MGP_FIELDS_MGPSamplerViews`
`:111-112`; `MGP_FIELDS_MGPSamplerStates` `:114-115`; `MGP_FIELDS_MGPImageView` `:117-118`;
`MGP_FIELDS_MGPShaderImages` `:120-121`; `MGP_FIELDS_MGPGlobalConstants` `:132-133`; `MGP_FIELDS_MGPSubRegion`
`:156-157`; `MGP_FIELDS_MGPSubData` `:159-160`; `MGP_FIELDS_MGPSubDataComplete` `:162-163`;
`MGP_FIELDS_MGPCopyRegion` `:171-172`; `MGP_FIELDS_MGPBlit` `:174-176`; `MGP_FIELDS_MGPClear` `:178-180`;
`MGP_FIELDS_MGPMipPlan` `:182-183`; `MGP_FIELDS_MGPReadbackInfo` `:185-186`; `MGP_FIELDS_MGPSurfaceInfo` `:223-224`.
`MGP_VERIFY_PAYLOAD_LIST` at `:315-331` is **what `gen_pipe.py` reads to know what to emit**; every payload above is
already in it. The tail of the file (`:226-311`) holds the *value* structs the comparator must see into
(`RenderStateParameters`, `PixelStoreParameters`, `PerBufferBlendState`, `StencilFaceState`,
`DynamicBackendParameters`, `MGHostSpan`) plus **P3a's two wire views** `MGP_FIELDS_MGPVertexAttribWire` `:306-308`
and `MGP_FIELDS_MGPVertexBindingPointWire` `:310-311`. **If P4a carries `SamplerParameters` as a typed value rather
than a blob, that is the pattern**: a `MGP_FIELDS_SamplerParameters` row plus a `P(SamplerParameters)` entry.
## 1.4 `MG_Pipe/Coverage.def` — which accessor each call answers, and the emitted-list discipline
Header `:9-25`: `gen_pipe.py` joins `scripts/data/backend_read_inventory.md` (477 rows, 57 files) against
`MGP_COVERAGE_ACCESSOR_LIST` and `MGP_COVERAGE_DELTA_LIST`, writes `generated/PipeCoverage.inc`. Three pseudo-calls
stand for read points that never become a forward call: `kClientResolved`, `kReverseChannel`, `kStructuralHandle`.
Unmapped rows are counted in P0 and must be **zero from P5 onward**.
**`MGP_COVERAGE_ACCESSOR_LIST`** (`:29-132`) — the P4a-relevant rows already present:
| accessor | call | line |
|---|---|---|
| `GetActiveTextureUnit` | `SetSamplerViews` | `:30` |
| `GetFramebufferBindingSlot` | `SetFramebufferState` | `:84` |
| `GetImageTextureBinding` | `SetShaderImages` | `:85` |
| `GetMaxTouchedTextureUnit` | `SetSamplerViews` | `:88` |
| `GetProgramForDispatch` | `SetDispatchProgram` | `:99` |
| `GetProgramForDraw` | `SetDrawProgram` | `:100` |
| `GetProgramObject` | `CreateShaderState` | `:101` |
| `GetSamplingResolutionGeneration` | `SetSamplerViews` | `:109` |
| `GetTextureBindGeneration` | `SetSamplerViews` | `:112` |
| `GetTextureContextId` | `SetSamplerViews` | `:113` |
| `GetTextureObject` | `SetSamplerViews` | `:114` |
| `GetTextureUnitObject` | `SetSamplerViews` | `:115` |
**No accessor row names `SetTextureParams`, `CreateSamplerState`, `CreateSamplerView`, `BindSamplerStates` or
`SetGlobalConstants`** — those five calls have no backend *read point* in the inventory, they carry object
descriptors. That is the shape P4a inherits, not a hole to fill by inventing accessors: `gen_pipe.py` refuses a name
that is not an accessor.
**`MGP_COVERAGE_STICKY_LIST`** `:144-151` — the seven F-class forwarded accessors, no per-verb generation.
Two are P4a's: `GetProgramObject` and `GetTextureObject`, both *"keyed by GL name: an object lookup, not verb
state"*. `:141-142`: the verify lane's `Fatal{UnmigratedPipeInput}` is fixed by a `FillPoints.def` row, **never** by
a row here.
**`MGP_COVERAGE_DELTA_LIST`** `:156-158` — read by `gen_pipe.py` only: `handle-ify (wire handle) →
kStructuralHandle`, `Buffer ops delta → ResourceRespecify`.
**`MGP_COVERAGE_EMITTED_LIST`** `:198-232` — the discipline P4a copies. The rules stated in the comment block
`:160-197`:
- every name must be an accessor in the accessor list and every call a real call in `PipeCalls.def`;
- `gen_pipe.py` turns it into `kMGPipeFieldEmittedBy[]` in `generated/PipeFilled.inc` — see
`generated/PipeFilled.inc:306-314`, where the `MGPipeFieldEmitter` enum today is exactly
`{kNone, BindRenderState, BindVertexElements, CreateRenderState, SetDynamicState, SetPatchState,
SetVertexAttribDefaults}`. **Adding a row mints a new enumerator, which `PipeFill.cpp`'s `SubsystemForEmitter`
switch must then handle** (that switch is exhaustive over the enum, `PipeFill.cpp:957-976`);
- a field with no row keeps going through the fill loop, "which is what makes the `MOBILEGL_PIPE_PUSH` bitmask a
true per-subsystem A/B";
- `GetPixelStoreParameters` is **deliberately absent** (`:173-181`): the field is both halves of
`m_pixelStore[2]` and `set_pixel_pack_state` carries pack only; a row would be a half-truth;
- **P3a added exactly one row**, `GetBoundVertexArray → BindVertexElements` (`:202`), and `:183-197` explains that a
row may land **before** the call that carries it exists, because `kMGPipeWiredSubsystems` is the guard. The final
paragraph (`:191-197`) is written *for the commit that wires it* and is the model P4a should copy: the row is
shape-only until the backend's twin resolution reads the applier's state instead of the object, and
**`PipeFill.cpp`'s `EmittedCallSuppliesTheWholeField` arm is where that is decided, deliberately rather than
silently by the row's presence.**
## 1.5 `MG_Pipe/MGPipeHandles.h` — the kinds
`MGPipeKind` at `:24-40`: `None=0, Buffer=1, Texture, Renderbuffer, Framebuffer, Xfb, RenderStateCso,
VertexElementsCso, SamplerCso, SamplerViewCso, ShaderCso, Fence, Query, Context, KindCount`.
**P4a's kinds are `Texture`, `Renderbuffer`, `Framebuffer`, `SamplerCso`, `SamplerViewCso`, `ShaderCso`.**
- `MGPipeHandle{Uint32 Slot; Uint32 Gen;}` `:54-61`, `sizeof == 8`, `alignof == 4` asserted `:63-65`.
**`Gen` increments only when a slot is REUSED, never on a respecify** (`:44-48`).
- `kMGPipeNullHandle{0,0}` `:72`; **`kMGPipeDefaultFramebuffer{0,1}`** `:73` — kind `Framebuffer` slot 0 gen 1, which
exists "so the four `pDefaultFramebufferInfo->defaultFBO` identity comparisons in DirectGLES retire into an
ordinary handle compare" (`:69-71`). This is P4a's single most load-bearing reserved value.
- `MGPipeHandleIsNull` `:75-77`; `kMGPipeFirstAllocatableSlot = 1` `:81`.
- **The ShaderCso composite band** `:83-97`: `kMGPipeShaderCsoSlotLimit = 1<<20`,
`kMGPipeShaderCsoCompositeSlotBase = limit - (limit >> 4)` (top 1/16), `MGPipeIsCompositeShaderSlot(slot)` `:92-94`,
and a `static_assert` that the band cannot swallow the ordinary slots `:96-97`. A composite is minted client-side
out of the stage programs bound to a pipeline object and **the server never learns it is a composite**.
The allocator honours the band at `MG_Impl/Pipe/SlotAllocator.cpp:19-24` (`SlotIsAllocatable` refuses the band for
kind `ShaderCso`) and asserts exhaustion at `:57-60`.
## 1.6 `MG_Pipe/PipeApply.{h,cpp}` after P3a
### `MGPipeResourceOps` (`PipeApply.h:74-91`)
```
struct MGPipeResourceOps {
void (*Create) (MGPipeHandle res, const MGPResourceDesc& desc);
void (*Respecify) (MGPipeHandle res, const MGPResourceDesc& desc, const void* initialBytes);
void (*SubData) (MGPipeHandle res, const MGPSubData& record, const void* bytes);
void (*SubDataResident)(MGPipeHandle res, const MGPSubData& record, const void* bytes); // kOptional, may be null
void (*FlushRange) (MGPipeHandle res, const MGPFlushRange& record, const void* bytes);
void (*Readback) (MGPipeHandle res, const MGPReadback& record);
void (*Destroy) (MGPipeHandle res);
void* (*MapPersistent) (MGPipeHandle res, Uint64 size, const void* seedBytes);
void (*UnmapPersistent)(MGPipeHandle res);
};
void MGPipeSetResourceOps(const MGPipeResourceOps*); // :90
const MGPipeResourceOps* MGPipeGetResourceOps(); // :91
```
`:52-56`: **the SECOND backend op table, beside `BufferBackendOps`**; a null table means "this backend has not taken
the resource family over" and the frontend dispatches the old way — *"which is what lets the client half land on its
own"*. `:58-61`: **no frontend type appears here** (gate G13 greps `PipeApply.h` for `MG_State`).
`:63-68`: the companion `const void*` is the client's own shadow base, zero-copy, and `resource_respecify`
deliberately does **not** carry `kHasBlob` because a `kHasBlob` record must own an `MGPBlobRef` and `MGPResourceDesc`
has none.
**P4a's texture/renderbuffer `resource_*` calls travel on this same table.** The signatures are already
handle+record+bytes and carry no buffer-specific type, so the table likely needs **no new members** for
create/respecify/subdata/destroy; what it lacks is any hook for `GenerateMipmap`, `ResourceCopyRegion`,
`GetTextureImage`, `Blit`, `Clear`, `SetTextureParams` and the sampler/program/framebuffer CSOs — those are new
tables or new members and that is a contract decision.
### The applier's records and state (`PipeApply.h:96-274`, `PipeApply.cpp`)
- Bounds: `kMGPipeMaxResourceSlots = 1<<20` and `kMGPipeMaxVertexElementsSlots = 1<<16` at `PipeApply.h:112-113`,
with the argument at `:97-111`: *a slot at or above these is `Fatal{ProtocolCorruption}` — the same verdict as any
other record that would make the server act outside its own storage — and never a resize.* The tables grow only to
the client's own dense high-water mark. `RecordAt` implements it at `PipeApply.cpp:404-425` (returns null above the
limit, `resize(slot+1)` otherwise).
- `MGPipeRenderStateCsoRecord` `:42-46` (Gen, Live, 396 pipeline bytes).
- `MGPipeResourceRecord` `:117-132`: `Uint32 Gen`, `Bool Live`, `MGPResourceDesc Desc` (the last create/respecify,
verbatim — "the backend reads its Width / Usage / StorageFlags / HasDefinedContent instead of asking the frontend
object"), `Uint64 Serial` (**server-owned MGGen-class, `++` on every mutation; no MGPipe call may require the
client to provide or know one**), `Bool HasLiveHostWrites` — *always false in P3a, written by nobody*, pinned by a
verify-only trip wire (`PipeApply.cpp:533-547`, `PinNoLiveHostWrites`).
- `MGPipeVertexElementsRecord` `:141-152`: Gen/Live/counts/two unpacked views/`Uint64 ContentSerial`.
- `MGPipeApplierState` `:154-274`. **The two halves and their different lives are the single most important P3a
ruling for P4a** (`:196-216`): *object records* (`Vector<MGPipeResourceRecord> Resources` `:217`,
`Vector<MGPipeVertexElementsRecord> VertexElementsCsos` `:218`) describe **share-group** objects and outlive a
make-current; *working state* (`BoundVertexElements` `:236`, `VertexBuffers`/`Start`/`Count` `:240-242`,
`VertexFetchBaseInstance` `:250`, `IndexBuffer` `:262`) is per-context and is cleared. **P4a's framebuffer/sampler/
program/image bindings are working state; its texture/renderbuffer/sampler-CSO/program-CSO records are object
records.**
- **Refusal counters** `:220-229`: `Uint64 RefusedResourceCalls`, `Uint64 RefusedVertexInputCalls`. The rationale at
`:220-227` and again at `PipeApply.cpp:441-473`: `MOBILEGL_ASSERT` compiles out at INFO — which all three gate
builds and every shipped build are — so *"a no-op nobody can see is a dropped call nobody can see"*; the counters
are the observable in **every** build. The two resolvers that assert **and** count are `ResolveResource`
`PipeApply.cpp:478-486` and `ResolveVertexElements` `:488-494`, with `kResourceRefusalNote` at `:475-476`
(*"the record is not this applier's; the call is dropped, not applied"*). **P4a adds its own counter(s) in the
same shape.** The one *legal* refusal sequence is documented at `PipeApply.cpp:452-462`: teardown →
`MGPipeApplierReleaseObjectRecords()` → `~Object` → death notices naming records already dropped.
- Serials that **only advance, never zero**: `VertexBuffersSerial` `:251-258`, `IndexBufferSerial` `:263-264`, with
the three-way argument spelled out at `PipeApply.cpp:651-665` (carry over → wrong immediately; restart at 0 → walks
back through values already stamped into a twin that outlived the switch; advance → safe direction). Both
`MGPipeApplierReset` (`PipeApply.cpp:664-665`) and `MGPipeApplierReleaseObjectRecords` (`:677-678`) `++` them.
- `MapPersistentRoundtrips` `:266-273` plus the long note at `PipeApply.cpp:636-650`: this member is **per applier and
zeroed at every make-current**, while `PipeStats`' process-wide `mpr` (emitted from the client) is what the gates
read through `MG_IntegrationTest/Harness/PipeStatsWindow.h`; nothing outside `MG_Test` reads the member.
### The three lifecycle functions
- `MGPipeApplier()` `PipeApply.h:277` / `PipeApply.cpp:596`.
- **`MGPipeApplierReset()`** `PipeApply.h:279-291`, body `PipeApply.cpp:601-666`: **a make-current, not a teardown**;
runs on every change of the current `GLContext`; drops render-state CSOs, the residual mirror and the vertex-input
working state; **does NOT drop the object records** (`PipeApply.cpp:617-627`: dropping them "made every
`glBufferSubData` after a context switch resolve to nothing and be dropped, with the only trace an assertion that
compiles out at INFO"); **does not clear the op table** (`:626-627`).
- **`MGPipeApplierReleaseObjectRecords()`** `PipeApply.h:293-300`, body `PipeApply.cpp:667-678`: the served context's
teardown; **deliberately wired to NOTHING in the monolith** — one applier behind every context, so calling it on
one context's destruction would drop every other context's records. A record is cleared by its object's own death
signal. The only caller in the tree is the unit fixture `ApplierGuard`
(`MG_Test/Pipe/ResourceEmitTest.cpp:146-157`), whose comment says a test fixture *"is the one caller in the tree
that legitimately means 'this applier is going away'"*.
### The never-destroyed singletons (ID-18, ID-21)
- `MGPipeApplierState& g_applier = *new MGPipeApplierState{};` at `PipeApply.cpp:384`, with the reason at `:380-383`:
destroy notices are raised from `~BufferObject` / `~VertexArrayObject`, released by exit handlers that run *after*
this TU's globals are gone.
- `MGPipeResourceTrackerInstance()` — `new`, never deleted, `MG_Impl/Pipe/ResourceTracker.h:554-560`.
- `MGPipeVertexInputEmitterInstance()` — `MG_Impl/Pipe/VertexInputEmit.h:428-440`, with the concrete UAF it closes.
- `MGPipeSetHashSuppressorInstance()` — `MG_Impl/Pipe/SetHashSuppressor.h:88-94`; `MGPipeCsoCacheInstance()` —
`MG_Impl/Pipe/CsoCache.h:196-202`; `MGPipeSlots()` — `MG_Impl/Pipe/SlotAllocator.cpp` (the rule's origin, cited by
every other one). **The rule stated in the comments is "every MGPipe process singleton", not only the ones on
today's death paths** — P4a's new singletons (a texture tracker, an FBO emitter) inherit it verbatim.
- The other half of the closure is ID-21's `6515c8e6`: leak-at-exit storage for the four static `PipeInputs` holders.
Proof recipe: `GLIBC_TUNABLES=glibc.malloc.tcache_count=0` on both lanes (ID-18, ID-20, ID-21).
### The 23 apply entry points, with exact line numbers
`PipeApply.h:309-329` declares the seven P2 ones; bodies `PipeApply.cpp:680, 730, 749, 763, 772, 776, 834, 880`.
P3a's nine resource entry points: declared `PipeApply.h:347-380`, bodies at `PipeApply.cpp:951`
(`ResourceCreate`), `:984` (`ResourceRespecify`), `:1010` (`ResourceSubData`), `:1016` (`BufferSubDataResident`),
`:1022` (`ResourceFlushRange`), `:1051` (`ResourceReadback`), `:1088` (`ResourceDestroy`), `:1113` (`MapPersistent`),
`:1142` (`UnmapPersistent`); the section header at `:931-949` is worth copying verbatim as a template — *"what the
applier owns here is IDENTITY, EXTENT AND ORDER — NOT CONTENT"*, and each body does three things in this order:
resolve the handle against the record, check the record against its own declared extent, then move the record and
hand the call to the backend.
P3a's five vertex-input entry points: declared `PipeApply.h:386-404`, bodies `PipeApply.cpp:1173, 1263, 1279, 1303,
1349`; the section header `:1157-1171` says **these five dispatch to nobody** — the backend reads them at its own
draw-time sync out of the applier's working state, which is what the serials are for.
The derivation step `MGPipeDeriveRenderStateFields` / `...ForChunks` is `PipeApply.h:420` / `:431`.
Body-level idioms P4a should copy:
- **A create starts the record over rather than editing it** — `PipeApply.cpp:960-967`: a recycled slot's record must
not contribute one field. Generation is taken from the handle and nothing else survives. `Serial` stays 0 (a create
is not a mutation) so a fresh backend twin starting at 0 agrees without either side publishing anything (`:968-171`).
- **Serial moves BEFORE the backend is told** — `ApplyBufferWrite`, `PipeApply.cpp:578-582`: the backend stamps its
own synced serial from inside the hook, so a bump afterwards leaves the twin one mutation behind.
- **A readback moves no serial** — `PipeApply.cpp:1062-1075`, and the writeback precedes the epoch bump.
- **Destroy drops the record whole and keeps the generation** — `:1092-1095`; the *client* frees the slot afterwards,
in that order.
- **A re-create on the same handle keeps the serial and counts up; a different identity starts over** —
`PipeApply.cpp:1200-1204`; and it **does not rebind** (`:1223-1226`).
- **A dead handle leaves the previous binding untouched** — `MGPipeApplyBindVertexElements`, `:1263-1278`;
the null handle is legal and means "nothing bound".
- **The var-tail window is the bound**: `Start + Count > kMGPipeMaxVertexAttribs` is `Fatal{ProtocolCorruption}`,
and entries outside the declared window are **not** cleared — "this record is 'the last set as received'"
(`PipeApply.cpp:1303-1324`). Every P4a `kVarTail` set inherits this.
## 1.7 `MG_Pipe/MGPipeCallbacks.h` — the reverse channel
Ten callbacks in `struct MGPipeCallbacks` (`:27-51`), count asserted at `:55-57` (`kMGPipeCallbackCount = 10`,
`sizeof == 10 * sizeof(void(*)())`) — *"an eleventh cannot be added without touching the transport's
reverse-channel record table"*. `inline MGPipeCallbacks gMGPipeCallbacks{}` at `:60`, null-initialised: a backend
that installs nothing sends nothing.
The six that are P4a's business: `OnGlError` `:29`; `OnTextureWriteback(res, box, bytes)` `:33`;
**`OnTexturePullRequest(res, target, firstLevel, levelCount, pullSerial)`** `:37-38` — "the one new stall class in
this design (D-B6): the server recast a texture and needs its texels back. The client answers with zero or more
`ResourceSubData` records terminated by `ResourceSubDataComplete` carrying the same `pullSerial`";
`OnMipLevelsGenerated(res, base, count)` `:41` — **shape only, never bytes**; `OnSurfaceChanged(info)` `:44` —
"retires the layering inversion where the swapchain writes into MG_Impl's `pDefaultFramebufferInfo`";
`OnCapsInvalidated()` `:45`. `:24-25`: their **order is a correctness requirement**, not an optimisation.
The client's half of the channel is installed additively and never over an entry a backend already claimed —
`MGPipeInstallClientResourceCallbacks()` at `ResourceTracker.h:623-630` (`if (... == nullptr) ... = &Client...`).
---
# PART 2 — The P3a client conventions to copy
## 2.1 `MG_Impl/Pipe/ResourceTracker.h` (632 lines, header-only, all inside `#if MOBILEGL_PIPE_PUSH`)
The file header `:12-40` states the shape: where it runs (**the ONE exception to push-at-validate** — the seven
`BufferBackendOps` hooks already dispatch at the GL call, so their pipe calls are emitted from the same
`BufferObject` dispatchers, not from `MGPipeValidateForVerb`); what lives here; **header-only for the ownership
reason** (the root `CMakeLists.txt` that would name a new `.cpp` belongs to the contract package); and **no timer and
no per-call record copy on a hot path** — the observables are written only by create/respecify, and the hot call is
observed through pure builders instead.
- **The BindMask table** `:60-149`. `enum MGPipeBindBit : Uint16` `:67-86` gives `MGPResourceDesc::BindMask`'s twelve
bits, `kMGPipeBindElementArray = 1<<11` being the D-B7 switch. `kMGPipeBindUnmapped = 0x10000u` `:92` is a
sentinel that is *not* a legal mask value; `MGPipeBindMaskForBufferTarget` `:96-134` has **no `default:` arm on
purpose**, and `MGPipeEveryBufferTargetIsMapped()` + `static_assert` `:136-149` make adding a `BufferTarget` a
build break. **P4a inherits `kMGPipeBindSampler` (1<<5), `kMGPipeBindShaderImage` (1<<6),
`kMGPipeBindRenderTarget` (1<<7), `kMGPipeBindDepthStencil` (1<<8)`, which nothing sets today**, and
`:64-66` says explicitly: *"They are spelled HERE rather than in MGPipeTypes.h because that header is the contract
package's and the mask has, so far, exactly one producer: this file. The integrator moves them beside the field
when a second producer appears (P4a's texture family)."* **That move is a P4a contract action.**
- **Payload builders are pure** `:164-235`, so a unit case can assert field by field.
`MGPipeBuildResourceDesc(buffer, handle, bindMask, storageDefined)` `:171-205`, including the narrowing alarm at
`:180-194` (a store ≥ 4 GiB cannot be declared, and truncating silently would make the applier's range gate name a
corruption that is really a narrowing here). `MGPipeBuildSubDataRecord` `:225-235` fills `Blob.Seg =
kMGHostSpanSegNone` and `Blob.Size = size` — *"Leaving it 0 would be legal too; declaring it correctly is the
stronger of the two."*
- **The range splitter** `:237-276`: `kMGPipeSubDataMaxRecordOffset = 0x7FFFFFFF`, `kMGPipeSubDataMaxRecordSize =
0xFFFFFFFF`, `MGPipeForEachSubDataRecordRange(offset, size, piece, maxChunk)`. Two properties are load-bearing:
**contiguous and ascending** (`:238-242`) — splitting into overlapping or reordered pieces changes what the
backend's queue-and-drain sees and the Mali WAR-stall fix depends on that queue being exactly the writes the
application made. **Every piece is proved encodable before the first one is emitted** (`:263-268`): a half-emitted
range is a partial content write landed as if it were whole. `maxChunk` is a parameter *"exercised at a reachable
value by the unit gate, so that lowering it is one argument rather than a new code path written under pressure"*.
- **`class MGPipeResourceTracker`** `:282-550`:
`Acquire(buffer)` `:292-299` — **minting is NOT gated on a backend having registered `MGPipeResourceOps`**: the
handle is client state and `set_vertex_buffers` names it whether or not the resource family is on; only the CALLS
are gated. `Find` `:303-305` never mints. `Resolve(handle)` `:313-320` is the reverse-channel inverse: a **raw**
pointer is exact (a `WeakPtr` would be wrong at construction/destruction), and it double-checks
`MGPipeSlots().GenOfSlot(...) == handle.Gen`. `Retire(handle)` `:325-329` — **the caller frees the slot
afterwards, in that order**, because `Free` erases the lifetimeId→slot mapping.
**`NotePublished` / `WasPublished`** `:331-350` — the create/destroy **latch**: the create is gated at its call site
and the destroy inside the emitter, so the two ask the same question at two different moments; a buffer created
while a table was registered and destroyed after `UnregisterBufferBackendOps()` would take the second answer, free
its slot, and leave the applier's record `Live` on a slot about to be re-handed-out. **P4a needs one latch per
kind it mints.**
`BindMask` `:355-358` (sticky, ORed, never cleared); `NoteBoundAs(handle, target)` `:369-374` — closes the sampling
window from the *draw* side; `RefreshBindMask(ctx, buffer, handle)` `:407-445` — samples the frontend's live
binding state at create/respecify, with the **recorded deviation** at `:379-399` (the brief pointed at
`BufferState.{h,cpp}` but the `.Bind()` calls are in `GL_Buffer.cpp`, which C.5 assigns to nobody, so the mask is
sampled instead of hooked) and the honest statement of the residual hole. The `BindEpoch` shutter `:522-534` and
its stated blind spot `:516-521` (it does not see the 84×4 indexed binding points, sound only because
`BindBufferBase/Range_State` also bind the generic slot). **All of that is the template for a texture bind mask.**
Observables for unit cases `:447-463`: `LastDesc()`, `CreateCount()`, `RespecifyCount()`, `DestroyCount()`,
`MapPersistentCount()`, `NoteDesc(desc, isCreate)`, `NoteDestroy()`, `NoteMapPersistent()`.
**`ResetForTest()` and its 20-line rule** `:465-498`: *"A buffer handle and the applier record it names are
SHARE-GROUP OBJECT STATE… this tracker needs no re-publication path on a fresh context and must not have one:
re-emitting `resource_create` for a record the applier still holds would move its `Serial` for nothing."* This is
ID-12's B-C2 resolved, and P4a must state the same rule for its own trackers rather than leaving absence as policy.
- **The client's half of the reverse channel** `:562-630`: `MGPipeClientOnBufferWriteback` `:570-589` (monolith: `Seg`
is `kMGHostSpanSegNone` and `Offset` **is** the address of the backend's mapped bytes) and
`MGPipeClientOnGpuWritten` `:596-618`, whose shape is a **contract point**: *one range covering
`kMGPipeWholeBuffer`, deliberately not zero ranges*, because zero will mean "fully narrowed" at P8/P9. The
backend's producer side is `MG_Backend/DirectGLES/Managers.cpp:2491-2521`, which also records the other half of
the contract (the client's `OnGpuWritten` must set **both** `m_hasDefinedContent` and `m_gpuWritePending`, or the
next respecify orphans and drops shader-written contents).
## 2.2 `MG_Impl/Pipe/VertexInputEmit.h` (444 lines)
Header `:11-38`: these three emit at the **validate point**, from `MGPipeValidateForVerb`'s step 3, in the fixed
order **elements → buffers → index**; the CSO is **identity-addressed, not content-addressed** (D-G1, a recorded
deviation), one handle per frontend VAO minted off its lifetime id, `create_vertex_elements` **re-issued on the same
handle** whenever the configuration moves. It also states what the unit gate reads and why the conversion is a pure
function per field (that is what makes G7 able to name a dropped field).
- **Wire conversion** `:59-116`: `MGPipeBuildVertexAttribWire(attrib, bindingIndex)` `:82-107` and
`MGPipeBuildVertexBindingPointWire(point)` `:111-116`. The comment `:60-81` enumerates, field by field, what the
wire form carries and **what it deliberately omits and why** (Divisor travels in `MGPVertexBuffer`; `LegacyStride`/
`LegacyPointer` are query answers and stay client-side; `Buffer` identity travels in `set_vertex_buffers`; a
surviving `Stride == 0` is meaningful; `IsLong` is separate from `Type == Float64`). It asserts rather than assumes
across the three narrowing casts `:87-93`. **This is the exact form a `MGPSamplerParametersWire` or a
texture-descriptor conversion should take.**
- **ContentHash** `:118-133`: `MGPipeVertexBufferSetContentHash(entries, start, count, baseInstance)` — `XXH64` over
the entries, then `MGPipeMixShutter` of `start`, `count` and `baseInstance`. The comment `:118-125` states the hard
requirement: **the hash must cover every input the record carries**, because the set is suppressed on an unchanged
hash. P4a's `MGPFramebufferState`, `MGPSamplerViews`, `MGPSamplerStates` and `MGPShaderImages` all carry a
`ContentHash`; the same rule applies to each.
- **`class MGPipeVertexInputEmitter`** `:135-425`:
`kAttribs`/`kBindings` with a `static_assert` against `kMGPipeMaxVertexAttribs` `:139-143`.
**`EmitVertexElements(ctx)`** `:158-193` implements the three arms verbatim (`:145-156`): no VAO → bind the null
handle; the bound VAO changed → (re)create if its configuration moved *since this handle last published one*, then
bind; same VAO, configuration moved → create on the same handle and **do not rebind**. The latch is **per handle,
in a slot-indexed table**, so ping-ponging between two VAOs re-binds but never re-creates.
**`EmitVertexBuffers(ctx, baseInstance)`** `:195-248`: one entry per attribute slot, `Start = 0`,
`Count` = highest enabled attribute + 1; a client-memory array is `Res == kMGPipeNullHandle` and that is *how the
server learns the attribute is client-sourced*; it calls `NoteBoundAs(entry.Res, BufferTarget::Vertex)` at every
draw (`:216-222`, the bit that survives the DSA idiom); it goes through
`MGPipeSetHashSuppressorInstance().ShouldEmit(MGPipeSuppressorSlot::SetVertexBuffers, hash)` `:230-233` and
**returns 0 bytes when suppressed**.
**`EmitIndexBuffer(ctx)`** `:250-273`: emitted unconditionally (no suppressor slot), `Offset`/`IndexSize` left 0
because there is no draw at the validate point.
Unit observables `:275-290`, **none of which costs a copy** — the emitter builds into the same arrays it hands the
applier.
**`RecordIsPublished(handle)`** `:292-311` and **`NoteRecordDestroyed(handle)`** `:313-327` — the **record half** of
the latch, deliberately kept OUT of `Reset()` because object records are precisely what `MGPipeApplierReset` does
not clear. The comment `:293-303` records the trap: *a slot can exist with no record behind it*, because a backend
that keys its twins on the handle mints the slot itself (`BackendSlotTable::GetOrCreate → MGPipeSlots().Acquire`)
whether or not the subsystem ever asked the client to emit — **which is exactly what a `MOBILEGL_PIPE_PUSH=0x7f`
lane runs**. `delete_*` on such a handle is a refused call and the resolver asserts. **Every P4a kind whose slot a
backend twin table mints has this same trap.**
**`Reset()`** `:329-343` — the per-context half only (`Published`, `Gen`, `ConfigVersion`, the bound handle);
re-creating an unchanged configuration is a bounded over-fire, forgetting that the applier holds one would leak the
record and its slot at the object's death.
`EmitCreate` `:359-406`: **all 32 of each, deliberately** (the record declares both counts and the applier refuses
one whose counts do not describe its blob; G6 is stated over all 32 slots); blob is attributes-then-binding-points,
ascending and contiguous; `Blob.Seg = kMGHostSpanSegNone`, `Blob.Offset = 0`, `Blob.Size = kAttribBytes +
kBindingBytes`; sets `latch.RecordLive/RecordGen` — **the one producer of the record half** (`:400-403`).
Storage `:408-424` is fixed-size `Array`s, one blob buffer, one entries buffer; no allocation per draw.
## 2.3 `MG_Impl/Pipe/PipeFill.cpp` — the validate point and its discipline
- **The resource emitters** (the exception to push-at-validate) `:602-798`:
`MGPipeResourceSubsystemEnabled()` `:602-605` = `(Features.PipePush & kMGPipeSubsystemResources) != 0 &&
MGPipeGetResourceOps() != nullptr` — **both halves matter** (`PipeMutation.h:100-105`).
`MGPipeResourceOpsHaveSubDataResident()` `:607-610`. `MGPipeMintResourceHandle` `:612-624` — **unconditional in a
push build**. `MGPipeEmitResourceCreate` `:622-637`. `MGPipeEmitResourceRespecify` `:638-683`, including the
**self-healing create** at `:648-673` (the create's gate and the consumer's gate disagree across a
register/unregister boundary; a buffer born in that window latched `Published = false`, so every later respecify
was refused and the twin drew through id 0 with no diagnostic anywhere). `MGPipeEmitResourceSubData` `:684-704`
drives the splitter. `MGPipeEmitMapPersistent` `:762-775` is the `mpr` counting site.
**`MGPipeEmitResourceDestroyAndFree`** `:777-799` and **`MGPipeEmitVertexElementsDestroyAndFree`** `:801-849` —
the two death paths, both returning "did the call go out"; the second has the three-position ordering argument
(`:836-848`): applier record dropped **first**, the backend death notice raised **second** (it resolves the handle
through the allocator, and a backend told after the `Free` could no longer find its twin), the slot goes back
**last**, and the double free is a proven no-op.
Declarations are in `MG_Pipe/PipeMutation.h:106-153`, deliberately so `MG_State` sees a declaration and never the
client's tracker (`PipeMutation.h:79-92`; the closure gate's mutation-header probe enforces it).
- **Subsystem mapping and the pairing asserts** `:955-1038`: `SubsystemForEmitter(MGPipeFieldEmitter)` `:957-976`
(exhaustive switch over the generated enum); five `static_assert`s pairing it against
`MGPipeSubsystemForDirty` `:986-1002`; **P3a's three** at `:1004-1030`, with the explicit lesson (`:1016-1023`):
*all three compare against `SubsystemForEmitter`, not against the constant* — pinning the dirty half to a constant
asks a weaker question and would let an emitter row move onto another subsystem unnoticed. The escape hatch that
existed at the contract commit (`MGPipeSubsystemForDirty(...) == 0 ||`) **was removed once the dirty half was
mapped** (`:1009-1015`) — P4a will need the same hatch, and must remove it in the same commit that maps its bits.
The vertex-attrib capacity pin is `:1032-1038`.
- **`kMGPipeWiredSubsystems`** `:1071-1076` = RenderState | PixelPack | PatchState | VertexAttribDefaults |
**Resources | VertexInput**. The comment `:1040-1070` is the model: *"a field whose emitter is not wired here keeps
being pulled - so adding a row to `Coverage.def` can never silently drop a field on the floor before the call that
carries it exists"*; each bit is added **by the commit that gives its own emitters their bodies**; and it states
which bits retire a pull (**neither of P3a's does**). It also records the one-directional A/B trap (`:1062-1069`):
**bit 8 without bit 7 sends the server handles it cannot resolve and every one of those lands in
`RefusedResourceCalls`; bit 7 without bit 8 is fine.** Neither `0x1ff` nor `0x7f` is in that arm.
- **`EmittedCallSuppliesTheWholeField(field)`** `:1116-1124`, returning **false** for
`GetPixelStoreParameters`, `GetCurrentVertexAttribute`, `GetBoundVertexArray`. The 60-line argument `:1078-1115`
is the one to reread when P4a decides its own rows — in particular the `GetBoundVertexArray` paragraph
(`:1094-1115`): the field's storage is a `SharedPtr<VertexArrayObject>`, the call carries an 8-byte handle, so the
row is **emitted-and-still-pulled**; *"what retires the pull is not a better applier - it is P8"*. **Every P4a
candidate (`GetTextureObject`, `GetProgramObject`, `GetFramebufferBindingSlot`, `GetImageTextureBinding`) has the
same pointer-storage problem** and will land in the same arm unless P4a also changes what the backend reads.
`AppliedWithoutDerivation(field)` follows at `:1126+`.
- **The validate point** `MGPipeValidateForVerb(verb)` `:1505-1687`. Step order: knob parse / verify arm / poison
serial `:1507-1521`; set verb + identity `:1522-1524`; **the no-context early return that still clears the pending
base instance** `:1525-1535`; step 2 the dirty walk `:1541-1543`; step 3 the emission gate
`const auto wants = [&](MGPipeDirty bit){ subsystem != 0 && (pushMask & subsystem) && (dirty & bit) }` `:1550-1555`
— *"Every gate below goes through `MGPipeSubsystemForDirty`, the ONE map"*; **the `FreshlyPrimed` arm** `:1570-1585`
(`CsoCache.Reset()`, `MGPipeApplierReset()`, `SetHashSuppressor.InvalidateAll()`,
`VertexInputEmitter.Reset()`, `g_residualDue = true`) with the P3a paragraph `:1577-1584` explaining that the
emitter's reset is needed **not** because the applier dropped its records but because the emitter's bound-handle
latch mirrors `BoundVertexElements`, which `MGPipeApplierReset` does clear, and that the **resource tracker is
deliberately NOT reset here**; the four P2 emitters `:1587-1598`; **P3a's vertex segment in the fixed order**
`:1600-1616`; `tracker.ClearPendingBaseInstance()` `:1620`; step 4 the residual fill `:1623-1655` (with the
`supplied` predicate at `:1643-1647` = subsystem non-zero **and** wired **and** in the push mask **and**
`EmittedCallSuppliesTheWholeField` **and** (`applierDerives || AppliedWithoutDerivation`)); step 4b the residual
value block `:1656-1678`; `PipeStats::RecordDrawPayloadBytes` `:1679-1686`; the verify `EntryCompare` `:1683-1685`.
- **The base-instance macro** `MG_Impl/Pipe/PipeFill.h:114-123`: `MGP_FILL(Verb)` and
`MGP_SET_BASE_INSTANCE(BaseInstance)`, the latter a macro **because the three call sites compile in the pull build
too**, where `MGPipeSetPendingBaseInstance` is neither declared nor defined. Declaration + the rules at
`PipeFill.h:46-73`. The three sites are `MG_Impl/GLImpl/Drawing/GL_Drawing.cpp:662, 685, 715` (ID-10's grant),
one line each immediately above the `MGP_FILL`. Setter/getter/clear on the tracker:
`Tracker.h:453-455`, member `:477`.
## 2.4 `MG_Impl/Pipe/Tracker.h` — the dirty bits, and which are P4a's
`enum class MGPipeDirty : Uint32` at `:57-84`, **the comment table is the roadmap**:
| bit | name | line | comment says | subsystem today |
|---|---|---|---|---|
| 0 | `NewRenderState` | `:60` | `RenderState::m_version` → `set_dynamic_state` | RenderState |
| 1 | `NewPipelineState` | `:61` | → `create/bind_render_state` | RenderState |
| 2 | `NewPixelPack` | `:62` | → `set_pixel_pack_state` | PixelPack |
| 3 | `NewPatchState` | `:63` | → `set_patch_state` | PatchState |
| 4 | `NewVertexAttribDefaults` | `:64` | → `set_vertex_attrib_defaults` | VertexAttribDefaults |
| 5 | `NewVertexElements` | `:67` | → `create/bind_vertex_elements` | VertexInput (P3a) |
| 6 | **`NewShader`** | `:67` | the current program's link version | **0 — P4a** |
| 7 | **`NewShaderBindings`** | `:68` | image units, block bindings, uniform write set | **0 — P4a/P4b** |
| 8 | **`NewGlobalConstants`** | `:69` | the default-uniform-block image | **0 — P4a** |
| 9 | `NewVertexBuffers` | `:75` | → `set_vertex_buffers` (P3a) | VertexInput |
| 10 | `NewIndexBuffer` | `:76` | → `set_index_buffer` (P3a) | VertexInput |
| 11 | **`NewFramebuffer`** | `:76` | — | **0 — P4a** |
| 12 | **`NewSamplerViews`** | `:77` | — | **0 — P4a** |
| 13 | **`NewSamplers`** | `:78` | — | **0 — P4a** |
| 14 | **`NewShaderImages`** | `:79` | — | **0 — P4a** |
| 15 | `NewConstBuffers` | `:80` | — | 0 — P4b |
| 16 | `NewShaderBuffers` | `:81` | — | 0 — P4b |
| 17 | `NewSoTargets` | `:82` | — | 0 — P4b |
(The line-number collisions above are because two enumerators share a comment line; the enum order is exactly as
listed.) `kMGPipeDirtyCount <= 32` asserted `:87`. The file header `:22-26` says P2 emitted for bits 0..4, **P3a adds
5, 9 and 10**, "the rest are still computed, latched and counted so the per-bit fire rate is a measurement rather
than a plan, with their fields going through the residual fill until P3b/P4a/P4b". **So P4a's fire rates already
exist as a measurement** — `FireCount(bit)` / `FireCount(bit, verbClass)` / `WalkCount()` at `:395-410`.
Phase constants that are never edited in place (`:93-104`): `kMGPipeDirtyEmittedAtP2` `:96-99`,
`kMGPipeDirtyEmittedAtP3a` `:102-104` (= P2 | 5 | 9 | 10). **P4a adds `kMGPipeDirtyEmittedAtP4a` beside them.**
`kMGPipeDirtyNames[]` `:106-127`. `MGPipeSubsystemForDirty(bit)` `:130-155` — P3a's three arms at `:145-149`, and
`default: return 0` at `:150-154` for "no call of its own until P3b/P4a/P4b".
**The shutters P4a will narrow** — all already computed in `Update()`:
- `NewShader` `:249-262`: `MixShutter(program->GetLifetimeId(), program->GetLinkVersion())`, deliberately **not**
`GetProgramForDraw` (which joins a pending link; the tracker must not force a compile to answer "did the shader
move").
- `NewShaderBindings` `:253-258`: a four-way mix of `GetImageUnitVersion`, `GetBackendStateVersion`,
`GetBlockBindingVersion`, `GetUniformWriteSetVersion`.
- `NewGlobalConstants` `:259`: `MixShutter(lifetimeId, GetUBOContentVersion())`.
- `NewFramebuffer` `:303-306`: `MixShutter(GetAnyFramebufferAttachmentGeneration(),
m_framebufferBind.Observe(GetFramebufferBindingSlot(Draw).GetVersion()))`.
- `NewSamplerViews` `:307-308`: `MixShutter(textureContent, GetTextureBindGeneration())`.
- `NewSamplers` `:309-310`: `MixShutter(textureParams, GetSamplingResolutionGeneration())`.
- `NewShaderImages` `:311-312`: `MixShutter(MixShutter(textureContent, textureParams), programImages)`.
The composite-collision argument `:157-171` (each mix is 64→64, ~2^-64 per pair, inputs an application cannot steer)
and the **over-fire-is-free / under-fire-is-fatal** rule `:28-35` are what P4a's narrowing arguments must be written
against. `MGPipeWidenedCounter` `:181-205` is how a wrapping `Uint16` crosses the tracker boundary
(**never widened in `MG_State`**), with its one stated blind spot (`:187-192`: an advance of exactly 65536 between
walks reads as unchanged).
`Reset()` `:365-393` — clears every latch, **deliberately not `m_pendingBaseInstance`** with the 12-line reason.
## 2.5 `MG_Impl/Pipe/SetHashSuppressor.h` — the seven slots
`enum class MGPipeSuppressorSlot : Uint32` `:44-53`:
`SetVertexBuffers = 0` (**P3a — wired, and its hash includes `BaseInstance`**), `SetSamplerViews` (**P3b**),
`BindSamplerStates` (**P3b**), `SetShaderImages` (**P4b**), `SetShaderBuffers` (**P4b**),
`SetStreamOutputTargets` (**P4b**), `SetVertexAttribDefaults` (**P2 — wired**), `Count`.
**Note the phase labels in the enum disagree with `ROADMAP.md:20`**, which puts `set_sampler_views`,
`bind_sampler_states` **and** `set_shader_images` in P4a. Three of P4a's four `kVarTail` sets therefore already have
slots (2, 3, 5 by index) and **`SetFramebufferState` has none** — it is not `kVarTail`, but it does carry a
`ContentHash` whose second job `MGPipeTypes.h:369-373` states is exactly the client's emission suppressor. **P4a must
either add a `SetFramebufferState` slot or suppress it another way, and update the phase labels it touches.**
Mechanics: `ShouldEmit(slot, contentHash)` `:61-67` — **hash 0 is reserved for "never emitted"** and a computed 0 is
remapped to 1 (`:31-33`: one collision in 2^64 costs an extra emission and never a missed one);
`Invalidate(slot)` `:71`; `InvalidateAll()` `:73-75` (called from the `FreshlyPrimed` arm);
`LastEmitted(slot)` `:79-81` exposed for the unit test that pins the reserved value. The file header `:12-33` is the
whole rule, including that this is the carrier for the ~175 lines of debounce that move off the backends
(Espryt's `UnitBindingsSnapshot` / `CaptureUnitBindings` / `UnitBindingsUnchanged`) **in P3b and P4b**.
## 2.6 `MG_Pipe/DirtySurface.def` — the rows P4a's mutators land in
The mechanism (`:9-27`, `:150-155`): `scripts/gen_pipe_dirty_surface.py` scans **`MG_Impl/GLImpl` AND
`MG_State/GLState`** (the second root is P3a's widening) for every `pGLContext->` mutator call and every
`MGP_NOTE_MUTATION` site, and `--check` fails **both directions**. Answer vocabulary at `:103-149`:
`NEW_*`, `kImmediate`, `kReverseChannel`, `kNoBackendRead`, `kExplicitDestroy`, `kUnpublishedDestroy`,
`kPulledEveryVerb`, `kPulledPartialShutter`. The rule at `:29-45`: **a row lists every publisher that fires on
EVERY path that mutates**, because a shutter built from this file would otherwise under-fire; a redundant-write
guard does not make a publisher conditional, but a publisher reached on only *some* mutating paths must not be named.
The derivation is checked mechanically for every `NEW_*` answer (`:46-60`) with `MGP_DIRTY_SURFACE_UNDECIDED_LIST`
(`:326-330`, empty today) as the only escape, and a mark that outlives its reason is itself a red gate.
Rows P4a owns or will touch:
- `X(SetActiveTextureUnit, kImmediate)` `:164`.
- `X(BumpTextureBindGeneration, NEW_SAMPLER_VIEWS)` `:248`.
- **`X(BumpSamplingResolutionGeneration, NEW_SAMPLERS)`** `:257` — a P3a addition found only by the widened scan root
(`:249-256`).
- **`X(NoteUnitTouched, kPulledPartialShutter|NEW_SAMPLER_VIEWS)`** `:270` — the other P3a addition, and the reason
`MGP_NOTE_MUTATION` became a recognised publish mechanism (`:258-269`): every texture and sampler bind routes
through it, it moves two pushed fields with two different answers (`GetTextureBindGeneration` moves only on the
`bindingChanged` arm; `GetMaxTouchedTextureUnit` has **no shutter at all** and is copied at every verb).
- The destroy family `:288-297` / `:296-306`: `MarkTextureObjectForDeletion`, `MarkFramebufferObjectForDeletion`,
`MarkRenderbufferObjectForDeletion`, `MarkSamplerObjectForDeletion`, `MarkVertexArrayForDeletion`,
`MarkBufferObjectForDeletion` are `kExplicitDestroy`; **`MarkProgramForDeletion`,
`MarkProgramPipelineForDeletion`, `MarkShaderForDeletion` are `kUnpublishedDestroy`** `:301-305`, i.e. a **known
hole**: "programs, program pipelines and shaders have no per-object handle on the wire at all in P2". **P4a's
shader CSO is what closes that hole, and those three rows are what must change.**
- `X(SetNamedTransformFeedbackBinding, kPulledEveryVerb)` `:284` — with the note that narrowing is P3b's.
## 2.7 Subsystem bits — `MG_Pipe/MGPipe.h:66-95`
```
bit 0 kMGPipeSubsystemRenderState :72
bit 1 kMGPipeSubsystemPixelPack :73
bit 2 kMGPipeSubsystemPatchState :74
bit 3 kMGPipeSubsystemVertexAttribDefaults :75
bit 4 kMGPipeSubsystemResidualValues :76
bit 5 kMGPipeSubsystemEsprytSlots :77 (Track H, Espryt 0b)
bit 6 kMGPipeSubsystemMagmaVertexInput :78 (Track H, Magma subsystem 4)
bit 7 kMGPipeSubsystemResources :84 (P3a)
bit 8 kMGPipeSubsystemVertexInput :85 (P3a)
// bits 9..62 reserved for the later phases, allocated in ROADMAP order :86
bit 63 kMGPipeBehaviourNoCsoContentAddressing :90 (a BEHAVIOUR, not a subsystem)
kMGPipeSubsystemsMigratedAtP2 = 0x7f :94
kMGPipeSubsystemsMigratedAtP3a = 0x1ff :95
```
`:66-70`: **bits are allocated in ROADMAP order and never reused — "an operator's recorded `0x7f` has to keep
meaning what it meant"**; a clear subsystem bit means "keep pulling", valid only while
`MOBILEGL_PIPE_LEGACY_MEMOS` compiles the pre-handle arm beside it (`ARCHITECTURE.md:367` keeps that arm through
**P3a/P4a**). `:80-83` justifies why P3a took **two** bits rather than one: separate A/Bs, "a buffer path that
regressed and a vertex path that regressed are different findings".
**P4a therefore takes bits 9 and upward, in ROADMAP order, and adds
`kMGPipeSubsystemsMigratedAtP4a` beside `:95` without editing `0x7f` or `0x1ff`.** ROADMAP's P4a row names five
groupings (framebuffer state; sampler CSO; sampler view + texture params; the three unit-array sets; shader CSO +
draw/dispatch program + global constants + CompositeResolver; texture/renderbuffer `resource_*`), so the honest split
is likely 3-4 bits (framebuffer, texture-and-sampler, program, texture resources) — the P3a precedent argues for
splitting wherever two regressions would be different findings, and against splitting into an arm that is
non-functional on its own (`PipeFill.cpp:1062-1069`'s bit-8-without-bit-7 trap: **P4a's texture `resource_*` bit is
to its sampler-view bit what bit 7 is to bit 8**, and the same paragraph has to be written for it).
## 2.8 Espryt's slot tables — the seventh is P3a's
`MG_Backend/DirectGLES/SlotTables.h:138` defines `BackendSlotTable<StateObject, BackendObject, kKind>`; the
holder list (`:420-436`, `s_firstHolder` `:541-543`) is what makes `DestroyByLifetimeId` static-and-answered-by-every-
live-table. `TwinRegistry` instances, one per kind:
`VertexElementsCso` `Managers.h:1181` / `Managers.cpp:4673`; `Texture` `Managers.h:1521` / `Managers.cpp:7001`;
`Framebuffer` `Managers.h:1612` / `Managers.cpp:7754`; `ShaderCso` `Managers.h:2130` / `Managers.cpp:8065`;
`SamplerCso` `Managers.h:2230` / `Managers.cpp:10583`; `Renderbuffer` `Managers.h:2257` / `Managers.cpp:10695`.
The **seventh**, P3a's, is the buffer table at `Managers.h:691`
(`BackendSlotTable<BufferObject, GLESBufferResource, MGPipeKind::Buffer>`).
**`SamplerViewCso` has no twin registry at all** — it is the one P4a kind with no existing backend table.
The death dispatcher `OnFrontendStateObjectDestroyed(kind, lifetimeId)` is `Managers.cpp:198-245`: arms for
`Texture` `:202`, `Framebuffer` `:205`, `Renderbuffer` `:208`, `SamplerCso` `:211`, `ShaderCso` `:214`,
`VertexElementsCso` `:217-231` (P3a's C-1 note: this is now the *second*, redundant path — the client speaks the
whole death), and the `default:` arm `:232-243` recording that **buffer death crosses as `ResourceDestroy`**, so no
seventh raiser was added. The op table is installed/uninstalled at `Managers.cpp:2529-2557`
(`RegisterBufferBackendOps` / `UnregisterBufferBackendOps`), **unconditionally in a push build**, because the
subsystem bit is the *frontend's* dispatch predicate — "a build with bit 7 clear registers a table nobody calls and
the A/B stays a pure configuration question rather than a bring-up-order one" (`:2532-2537`).
---
# PART 3 — The gates after P3a
## 3.1 `scripts/p3a_untouched_regions.sh` (467 lines) — the byte-identical set
**Eleven** functions in `MobileGL/MG_Backend/DirectGLES/Managers.cpp` (`SOURCE_PATH` at `:85`):
`FUNCTIONS` `:87` = `IsPoolable EnrollIntoPool AcquireFromPool TrimBufferPool ClearBufferPool
ProcessDeferredBufferReleases CreateRingStorage RingAvailable RingAllocate FlushPendingRangesNow`;
`PINNED_FUNCTIONS` `:91` = `FlushPendingRangesFrom` with `PINNED_BASELINE_REF=3e298c9a` `:92` and
`PINNED_SHA_FlushPendingRangesFrom=37fc94ff…` `:93`; `EXPECTED_FUNCTION_COUNT=11` `:95`;
`SELF_TEST_FUNCTIONS="ClearBufferPool FlushPendingRangesNow FlushPendingRangesFrom"` `:104`.
The shape P4a copies (all from the header `:1-84`):
- **Why a file diff cannot say it**: the file is rewritten by design, so the claim is about *bodies*, extracted and
hashed on their own (`:5-11`).
- **Each row is annotated with what the function is and why it matters** (`:13-30`).
- **The extraction is preprocessor-blind and mask-first** (`:53-64`): comments and string/char/raw-string literals
are replaced by spaces of the same length, the *definition* is found as the one `<name> (` whose closing paren is
followed (past qualifiers) by `{`, the body is brace-matched in the masked text and **hashed from the ORIGINAL
text** — so a comment change inside one of these functions is a difference too, deliberately.
- **Exactly one definition must be found per name; zero or two is exit 2, never a silent pass** (`:66-68`).
- Three usages (`:70-76`): `<ref-a> <ref-b>` compares, `<ref>` prints the baseline list, `--self-test` proves the
comparison can go red. **stdout is always the sha list** so the baseline capture is a plain redirect; everything
else goes to stderr (`:78-79`).
- **Both arguments are git refs** — an uncommitted edit is invisible by design (`:81-82`).
- Exit codes `:84`-ish: 0 identical / 1 moved (naming the first in the fixed order) / 2 could not run.
- ID-15's ruling is transcribed at `:32-42`: two preprocessor arms, both hashed, the pull ladder against `BASELINE`
and the push ladder against a **pinned** sha, because that one was born in P3a and has no body at the base ref.
**P4a's own byte-identical set will have the same two shapes** (functions that predate the phase → compared against
the base ref; functions born in the phase → pinned sha captured at the commit where they were reviewed).
## 3.2 `scripts/p3a_vertex_input_negative_control.sh` (278 lines) — G7 for the vertex conversion
`HEADER=MobileGL/MG_Impl/Pipe/VertexInputEmit.h` `:80`, `FIELD=IsBgra` `:81`, `TEST_NAME='VertexInputEmit\.'` `:82`.
The design (`:1-64`): the break is chosen so **the compiler cannot see it** — the struct still has the member, still
24 bytes, its four `static_assert`s still hold, `PipeFields.def` still names it and the generated comparator still
compares it; what breaks is the **value**. `IsBgra` is picked because it has the least other coverage (`Size` stays
4 for `GL_BGRA`, so a dropped `IsBgra` does not even change the attribute's size). The patch is applied **by regex,
not by an exact line**, because the header belongs to another package (`:25-29`); if the field is not assigned at
all, that is exit 2, never a pass. **Restore is not enough — the rebuild is part of the contract** (`:38-49`):
every exit goes through `repair()` (restore, rebuild, re-run), which also runs from the `EXIT` trap, and a failed
repair downgrades the verdict to 2. Logs live in `<build-dir>/p3a-g7-logs/`, inside the build tree so nothing is
left in the repository (`:51-53`). Exit codes `:55-62`: 0 tripped **and named the field**; 1 the control did not
answer (green with the field dropped, **or** red without naming it — both findings about the test); 2 could not run.
**Not a CI lane** — it rebuilds the library twice (`:31-32`).
`scripts/g7_negative_control.sh` is P2's sibling for the pipeline/dynamic split: it demotes `ColorMasks` out of
pipeline chunk P1 by inserting two boundaries, expects `RenderStateSpansTest` to go red **naming `SetColorMask`**,
relaxes the four measurement pins so the patch stays a semantic break rather than a build break (`:33-36`), and has a
`--verify-patch-only` mode (`:41-45`) that checks the mechanism without claiming the control passed.
## 3.3 The itest lanes and their `MOBILEGL_PIPE_PUSH` pins
`MobileGL/MG_IntegrationTest/CMakeLists.txt` (1389 lines). The scenarios are at
`Scenarios/{HandleRecycle, CsoContentAddressing, ResourceSubsystemControl}Scenario.cpp` `:133-135`.
- **The Handles-arm knobs** `:948-955`: `MGL_ITEST_HANDLES_ARM_KNOBS = "MOBILEGL_PIPE_LEGACY_MEMOS=0"
"MOBILEGL_PIPE_PUSH=0x1ff"`, `MGL_ITEST_ABA_ARM_KNOBS = "MOBILEGL_PIPE_HANDLE_ABA_CONTROL=1"`, empty in a pull
build. **The mask is the PHASE DEFAULT, not a hand-picked bit** (`:936-947`): it was `0x7f` and is now `0x1ff`,
because *"pinning it at `0x7f` after P3a would leave the Handles arm asserting the P2 shape while the buffer and
vertex-input handles it is supposed to be about stayed switched off - a lane that still passes and no longer
measures the key that ships"*. **P4a must raise all of these to its own phase constant** — this is closed
contract-review item 11 (`:1120-1128`) and it is stated for all three lane families.
- Six `HandleRecycle` lanes `:975-1030`: `DirectGLES.HandleRecycle.Handles.`, `DirectVulkan.HandleRecycle.Handles.`,
`DirectGLES.HandleRecycle.Legacy.` (`MOBILEGL_PIPE_PUSH=0`), `DirectVulkan.HandleRecycle.Legacy.`,
`DirectVulkan.HandleRecycle.AbaControl.` (`PUSH=0` + the ABA knob), `DirectVulkan.HandleRecycle.AbaControlHandles.`
(the handles knobs + the ABA knob). The last one exists because *"the guard P2 SHIPS is the generation: a control
that only defeated the retired guards would be green forever"* (`HandleRecycleScenario.cpp:87-93`).
- Four `CsoContentAddressing` lanes `:1067-1105` and their env `:1130-1146`: `0x1ff` for On,
**`0x80000000000001ff`** for Off (bit 63 + the phase default) — the mask moves with the phase, the control is bit
63, and the two must not be confused (`:1112-1128`).
- Two `ResourceSubsystemControl` lanes `:1147-1175`: On = `0x1ff`, **Off = `0x7f`** — "the two phase constants, not
hand-picked bits". DirectGLES only, because Magma registers no `MGPipeResourceOps` (`:1121-1124`).
- Two `MapPersistentRoundtrips` counting lanes `:1177-1210`, each selecting **one** case by `TEST_FILTER` with a
**private `MOBILEGL_LOG_FILE_PATH`**, plus `MOBILEGL_PIPE_STATS=1 MOBILEGL_PIPE_STATS_PERIOD=1`. The private-log
rule is stated three times (`:1035-1046`, `:1126-1140`, `Harness/PipeStatsWindow.h:19-25`): the library opens the
log `fopen(path,"w")`, so **every process in a lane truncates it**, and two readers in one lane race under
`ctest -j` with a failure that looks exactly like "the counter was never emitted".
- Two `LargeArenaAdoption` A/B lanes `:1212-1243`: `ResourceSubsystemOn.` (`0x1ff`) and `ResourceSubsystemOff.`
(`0x7f`) over the whole scenario.
- **Everything is registered in EVERY build, including the pull build, so `ctest -L integration-gpu` stays
name-for-name identical between pull and push (G2)**; in a pull build `MGITEST_PIPE_PUSH_BUILD` is absent and the
cases **SKIP saying so** (`:362-378`, `:408-506`, `:1141-1146`). The CMake side greps the backend sources for the
subsystem constant and the knob name and passes the answer in as `MGITEST_HANDLE_REKEY_<backend>` /
`MGITEST_HANDLE_ABA_IMPLEMENTED`, with `CMAKE_CONFIGURE_DEPENDS` so the answer cannot go stale
(`HandleRecycleScenario.cpp:98-103`).
- The verify block `:1246-1389`: `MGL_ITEST_VERIFY_TIMEOUT 900`; the ambient `DirectGLES.Verify.` /
`DirectVulkan.Verify.` re-registrations labelled `"integration-gpu;integration-verify"`; the **arming** lane with
its own log and `MGITEST_PIPE_ARMING_LANE=1`; negative control A (`MOBILEGL_PIPE_VERIFY_CORRUPT=
GetRenderStateParameters` with `MOBILEGL_PIPE_VERIFY_FATAL=0` so the process survives and can read its own report
back) and negative control B (`MOBILEGL_PIPE_POISON_OMIT=GenerateMipmap:GetActiveTextureUnit`, the scenario forks
so the `abort()` is a datum in `waitpid()`).
## 3.4 `HandleRecycleScenario` — the arms, and which kinds already have ABA controls
`Scenarios/HandleRecycleScenario.cpp`. Three arms `enum class Arm {Handles, Legacy, AbaControl}` `:141-145`,
selected by the harness marker `MGITEST_HANDLE_ARM` (`:146-152`; **the library never reads it**). The arm
descriptions are at `:74-93`, the skip policy at `:95-113` (*"never a silently-deleted registration and never a green
that means 'the thing I test does not exist yet'"*).
Seven cases:
| line | case | kind |
|---|---|---|
| `:521` | `TheReproducerRecyclesEveryName` | — |
| `:568` | `AVertexArrayAtARecycledAddressDoesNotInheritItsPredecessorsVertexInput` | VertexElementsCso |
| `:677` | (continuation case, VAO/vertex-input) | VertexElementsCso |
| `:768` | `ABufferAtARecycledAddressDoesNotInheritItsPredecessorsContents` | Buffer (P3a) |
| **`:869`** | **`ATextureAtARecycledAddressDoesNotInheritItsPredecessorsTwin`** | **Texture** |
| **`:920`** | **`AFramebufferAtARecycledAddressDoesNotInheritItsPredecessorsTwin`** | **Framebuffer** |
| `:1015` | `DestroyedVertexArraysReturnTheirVertexElementsSlots` (the leak test) | VertexElementsCso |
**The texture and framebuffer cases already exist but are NOT ABA controls**: `:865-868` says in as many words *"The
`AbaControl` knob does not steer this path, so this case expects the correct pixels in EVERY arm — stated explicitly
rather than by omission"*, and the assertion is
`ExpectPixelsFor(m_arm, /*armExpectsCorruption=*/false, ...)` `:903-904`. The framebuffer case's readback is
deliberately **not** through the framebuffer under test (`:913-918`): it uses `glGetTexImage` on the replacement's own
attachment, so "the clear went somewhere else" is visible. **P4a's kinds (`Texture`, `Framebuffer`, `Renderbuffer`,
`SamplerCso`, `SamplerViewCso`, `ShaderCso`) need `armExpectsCorruption=true` controls of their own**, i.e. the
`MOBILEGL_PIPE_HANDLE_ABA_CONTROL` knob has to defeat the identity half of the memo keys P4a introduces
(the Magma side of that knob is `MG_Backend/DirectVulkan/Renderer/MagmaPipeArms.h`'s
`MagmaPipeAbaControlDefeatsIdentity`, per ID-1). **Renderbuffer, SamplerCso, SamplerViewCso and ShaderCso have no
case at all today.**
## 3.5 The leak test and the `PipeSlotPeek` harness
`Harness/PipeSlotPeek.h` (44 lines) + `.cpp`. `enum class PipeSlotKind { Buffer, VertexElementsCso }` `:29-32` —
*"Mirrors `MG_Pipe::MGPipeKind` for exactly the kinds a scenario has a reason to count, so that the enum does not
travel through this header and the GL headers together"*. **P4a extends this enum for each kind it mints.**
`bool PeekPipeSlotLiveCount(kind, unsigned*)` / `PeekPipeSlotHighWater(kind, unsigned*)` `:41-42`, both returning
**false, touching nothing**, where the allocator is out of reach — a pull build has none, and on Android the module
links the shipping `libMobileGL.so` built `-fvisibility=hidden`. **`:37-39`: a caller that gets false must SKIP
rather than pass — "could not look" is not "did not leak".** It is its own translation unit because the scenario
sources include the GL headers with prototypes (`:19-21`).
The leak case `DestroyedVertexArraysReturnTheirVertexElementsSlots` `HandleRecycleScenario.cpp:1015-1110`:
skips unless `m_arm == Arm::Handles` (`:1019-1025`: the client mints the slot only when the subsystem is on);
skips if the peek is out of reach (`:1027-1032`); one shared VBO so only the VAO kind's slots churn;
one round = create → **DRAW** (which is what mints the slot and publishes the record) → unbind → delete;
**two warm-up rounds before the baseline is taken** (`:1076-1085`, so what is measured is growth *with* the churn and
not the one-off cost of drawing at all, the default VAO's slot above all); `kChurn = 48`; three assertions
(`:1098-1110`): `liveAfter == liveBefore`, `highWaterAfter == highWaterBefore`, `peakLive - liveBefore <= 1`.
The failure message names the cost (a `SlotState`, a lifetime-id map node, the applier's ~1.3 KB record, and past
`kMGPipeMaxVertexElementsSlots` a permanent `Fatal{ProtocolCorruption}`) and the backend. `:1005-1013` records why
the four ABA cases ran green over the leak: **the observable is the allocator, not pixels** — the leak produces
correct pictures the whole way to the fatal.
## 3.6 The verify lane, `retrace_gate.py` and `wsl_p3a_gate.sh`
- **Arming line** (ID-4 errata in `BRIEF-P3A.md:150-153`): `MGPipe: verify armed - 63 fields, 69 verbs, fatal=1`;
per-case retrace logs carry `MGPipe verify: <case> <backend> armed, zero divergences, zero unmigrated reads`.
The field count is pinned in `generated/PipeFilled.inc:96` (`kMGPipeInputFieldCount == 63`).
- **ctest name extraction**, mandatory (ID-4): `grep -E "^[[:space:]]*Test[[:space:]]+#[0-9]+:" | sed -E "s/^ *Test
+#[0-9]+: //" | LC_ALL=C sort` — the naive `^\s+Test #` **drops every id under 1000**.
- **`~/w7/retrace_gate.py`**: `--tree --lib --out [-j] [--only REGEX]` (`:9`, args at `:34-39`).
**`--only` is a REGEX**, applied as `re.search(a.only, k)` at `:51` — ID-15 records that the gate script once
passed a comma list and matched 0 cases while reporting success. There is **no `--ssim` and no `--backend`**; the
threshold is the per-case one in `trace_cases.json`.
- **`~/w7/notes/tools/wsl_p3a_gate.sh`** (70 lines), `usage: wsl_p3a_gate.sh [quick]`, `BASE=44c2b5cf` `:7`.
Three builds first and **fails fast** (`:20-22`: *"results from a stale binary must never look like a verdict"*).
`FAMILY` `:12` is the buffer/VAO regex
(`LargeArenaAdoption|StorageBufferRegrow|VertexAttribBinding|MultiDraw|PrimitiveRestart|CrossFrameBuffer|
ResidentIndex|BufferTexture|AtomicCounter|XfbCaptureBufferReuse|PackedWordReadback|DoublePrecision|
VertexArrayEnableDisable|DrawParameters`) — **P4a needs its own FBO/texture/program family regex**.
`NAMED` `:13` is the G3b regex, with the comment `# retrace_gate.py --only is a regex`.
Part 1 (purity) `:24-32`: include closure, the `pGLContext` grep, the `MG_State`-in-`PipeApply.h` grep,
`symbol_report.py --threshold 0`, the Resized table, `p3a_untouched_regions.sh $BASE HEAD`, the `RenderStateImpl`
sha, `HandleRecycle` under verify.
Part 5 `:34-38`: `gen_pipe.py --check/--self-test`, `gen_pipe_dirty_surface.py --check/--self-test`,
`ctest -R 'RenderStateSpans\.|Residual|VertexInputEmit\.|ResourceEmit\.'`, the G5 self-test.
Part 3 `:40-52`: G2 name diff, G14 removed/added, unit ×3 builds, then **five `integration-gpu` arms** —
default, `MOBILEGL_PIPE_PUSH=0`, `MOBILEGL_PIPE_PUSH=0x7f`, `MOBILEGL_ESPRYT_DISABLE_INVALIDATE_FLUSH=1`, and the
family subset — plus `g7_negative_control.sh`, `p3a_vertex_input_negative_control.sh`,
`CsoContentAddressing|ResourceSubsystemControl`, and the verify controls
(`PoisonOmitted\.|VerifyCorrupted\.|HandleRecycle`).
Part 2 `:54-68`: `integration-verify`, the Fatal-line census, then the three retrace sweeps (verify / push / named)
with the armed-count and Fatal-log checks, skipped by `quick`. Prints `P3A_GATE_DONE`.
- Tree/integration helpers are phase-parameterised (ID-3): `wsl_tree.sh p3a <slug> <base> [verify]` and
`wsl_integrate.sh p3a <slug>…`.
## 3.7 CI (`.github/workflows/test.yml`)
Triggers `:3-21`: pushes to `dev`, the two backend branches, and — **`# TEMPORARY, remove before merging the MGPipe
work into dev`** `:9-12` — `feat/disaggregated`, so a phase's landing is not gated on someone dispatching by hand;
plus `workflow_dispatch` with a `baseline_sha` input defaulting to `087685d1` `:13-21` (**the SYMBOL baseline, not
the phase base ref**).
Jobs `:24-1554`: `build-linux`, `test`, `integration`, `build-linux-verify`, `integration-verify`, `flatc-check`,
`include-graph-check`, `benchmark`, `build-retrace`, `trace-cases`, `trace-fixtures`, `retrace`, `retrace-summary`,
`retrace-verify`, `monolith-symbol-report`, `remove-artifact-clutter`, **`pipe-gates`** `:1554`.
`pipe-gates` (`:1554-1687`), *"deliberately independent of `build-linux`: these are source-level gates, they take
seconds, and a broken build must not hide a drifted interface"*, `env: BASELINE: "44c2b5cf"` with the note
distinguishing it from `baseline_sha` `:1560-1565`, and `fetch-depth: 0` because the G5 gate reads `Managers.cpp` at
`BASELINE` with `git show` `:1567-1572`. Steps:
1. `Regenerate the MGPipe interface (G1-G7)` — `python3 scripts/gen_pipe.py` then
`git diff --exit-code -- MobileGL/MG_Pipe/generated` `:1579-1583`.
2. `The MGPipe generators' checks can still fail` — `gen_pipe.py --self-test` `:1585-1591`.
3. `The symbol report's buckets and gates can still fail` — `symbol_report.py --self-test` `:1593-1595`.
4. `No stdio instrumentation in MG_Backend or MG_State` `:1597-1612` — one grep alternation covering
`fprintf(stderr|stdout)`, `printf(`, `puts(`, `std::cout|cerr`, **with no exceptions**.
5. `MGPipe dirty-surface mapping is complete (G9)` — `gen_pipe_dirty_surface.py --check` **and** `--self-test`
`:1614-1636`.
6. **`The buffer pool, the deferred-release drain and the rings did not move (G5)`** `:1638-1665`, guarded
`if: github.ref == 'refs/heads/feat/disaggregated' || github.event_name == 'workflow_dispatch'` — *"the question
is 'did these eleven move since P3a started'… it belongs with the TEMPORARY trigger lines at the top of this file
and retires with them"*.
7. `The untouched-region gate can still fail (G5)` — the `--self-test`, same guard `:1667-1669`.
8. `Documentation citation lint` — **warning only** (`|| true`) while the documents settle `:1671-1687`.
ID-16 / ID-22 record the two reds that are **not** code signals: GitHub artifact-download `digest-mismatch` on
retrace matrix entries, and an HTTP 504 from `gh api --method DELETE` in "remove artifact clutter" after every test
passed.
---
# PART 4 — The measurement infrastructure as of P3a
All under `~/w7/notes/tools/` (integrator-owned, ID-3).
- **`wsl_build_trace_apks.sh`** (29 lines). `usage: wsl_build_trace_apks.sh <phase> [tree]`; builds the trace-flavour
APK (arm64-v8a, **release**, debuggable, INFO) twice — pull, then push via `-Pmobilegl.pipePush=ON` — and
**debug-signs both**, because a WSL build has no `SIGNING_*` keys and the release APK comes out unsigned
(`adb install` fails `INSTALL_PARSE_FAILED_NO_CERTIFICATES`). It creates `~/.android/debug.keystore` if absent,
wipes `android-plugin/app/.cxx` between arms, and **prints the lib size plus the `MGPipe` and
`map-persistent-roundtrips` string counts** for each APK — ID-17's guard, so an -O0 APK can never pass unnoticed
again (**Release `.text` ≈ 9.4 MB; the P2-era A/B APK's 21.8 MB `.text` was a Debug-flavour build**). Output:
`~/w7/notes/<phase>/apk/trace-{pull,push}.apk`.
- **`p3a_ab.sh`** (53 lines) — the paired device A/B, run from Windows Git Bash with `adb.exe` on PATH.
`usage: p3a_ab.sh <serial> [case …]`; default cases: `improved-transparency-minecraft-26.3`,
`minecraft-1.21.4-rd12-odinlite-in-world`, `minecraft-1.21.4-fabric-sodium-in-world`,
`minecraft-1.21.1-neoforge-create-instancing-in-world`. Matrix `{pull,push} × {nofinish,finish} × cases ×
{DirectGLES,DirectVulkan}`. Protocol: **reboot-clean once**, wait for `sys.boot_completed` **and** for root, wake,
**pin verified and retried up to 3 times** (`pin_device.sh pin` then `check`, exit 43 on failure), then a
**device-lock hold per run** (`mkdir` lock with a 900 s timeout → exit 42) and `pin-before.txt` / `pin-after.txt`
around each run. The runner is
`tools/trace_replay/run_android_retrace_local.py --case … --backend … --benchmark [--benchmark-no-finish]
--benchmark-repeats 3 --benchmark-tail-frames 200 --env MOBILEGL_PIPE_STATS=1 --env MOBILEGL_PIPE_STATS_PERIOD=120`.
Outputs go to a **Windows-local** scratchpad dir (Git Bash cannot create directories on `//wsl.localhost`) and are
copied back by `copy_ab.sh`. Note at the top: **do not export `MSYS_NO_PATHCONV` globally** here.
- **`p3a_ab_7f.sh`** — the same script with four differences (verified by diff): the output root
(`p3a-ab7f`), the loop restricted to `arm=push` × `mode=nofinish`, the directory suffix `push7f`, and
**`--env MOBILEGL_PIPE_PUSH=0x7f`**. It is ID-17's supplementary arm: the *same push APK* run with P2's
subsystems only = the device-side T2.
- **`ab_reduce3.py`** (84 lines) — `usage: ab_reduce3.py <main-root> <7f-root> <out.md>`. Reads the runner's own
"best of N" line (lowest mean wall frame time repeat) for CPU p50/p99 over the trailing window
(`runner_best` `:14-24`), the pin verdicts from `pin-before/after.txt` (`pin` `:26-37`), and the **summed `mpr=`**
out of every `MGPipe stats: frames=` line in `mobilegl.log` (`mpr_total` `:39-49`). Emits a 13-column table:
pull p50 | P2-only (0x7f) p50 | P3a (0x1ff) p50 | Δ P2 | Δ P3a total | pull p99 | P3a p99 | pins pull/7f/P3a |
mpr 7f/P3a, with the footnote *"the P3a-only share is the difference of the two"*.
- **`wsl_p3a_bench.sh`** (62 lines) — desktop DriverBench, run on an **idle box (no gate, no builds)**.
`REPEATS=5`, `DRIVERBENCH_FRAMES=240`, cases `mc_vanilla_draw mc_state_toggle mc_pass_switch`, lavapipe/llvmpipe
ICDs, `EGL_PLATFORM=surfaceless`. Eleven arms: `native`, and for each of `espryt`/`magma`:
`-pull`, `-push`, **`-push7f` (`MOBILEGL_PIPE_PUSH=0x7f` = T2)**, `-push0` (`=0`),
`-nocso` (`=0x80000000000001ff`). Writes `driverbench.csv` (every repeat) and `driverbench.md` (medians +
**T1 = push(0x1ff) − pull, T2 = push(0x7f) − pull, T1 − T2 = what the phase added**).
- **The recorded numbers** (ID-19, ID-24), which are P4a's comparison baseline:
desktop `mc_vanilla_draw` ns/draw — Espryt pull 5115 / push(0x1ff) 6162 / push(0x7f) 5463 / push(0) 5693;
Magma pull 17099 / 17709 / 17287 / 17739. **T1 = +1048 (+20.5%) / +611 (+3.6%); T2 = +349 / +189;
P3a itself = +699 / +422 ns/draw** — the largest boundary cost so far. Device (Release APKs from `3e298c9a`):
P2's boundary = +6-12% p50 on both devices and backends; P3a adds ~0 on 26.3 and sodium but **+17-19 points on
rd12** (Espryt +30%, Magma +27% total); MC 26.3 p99 on Adreno 25.46 → 26.32 ms (+3.4%). `mpr` on device: 26.3 = 8
per run, sodium 1.
- **Thermal / device traps** (ID-23 and the `fcl-device-testing` memory): rd12 on Magma on the Xiaomi **aborts on
every arm including pull** (a scudo map error inside a `calloc` from libMobileGL seconds after start, with 6 GB
free) — pre-existing, excluded from the table, task chip open. **Side effect: the GPU pwrlevel pin resets after the
crash** (`pin_device` then reports "range 2..5"), so every row taken *after* rd12 on that device carries a **DRIFT**
verdict on both arms (still paired). Also excluded: `create-instancing` (a 2-frame fixture, not a benchmark) and
sub-ms sodium rows (noise). The protocol memory adds: CPU big 1.96 / little 1.55 GHz fixed, GPU pinned, a 40 °C
entry threshold, downclock afterwards, and the harness's `pidof` single-sample kill is on the optimisation list.
- Artefact locations (ID-24): `~/w7/notes/p3a/ab` (60 `benchmark.json`), `ab7f` (15), `ab3-final.md`;
bench `~/w7/notes/p3a/bench/driverbench.md`; APKs `~/w7/notes/p3a/apk/`.
---
# What P4a has to decide that P3a did not
Collected, each with the file that forces the question:
1. **The `MGPResourceDesc::Target` enum does not exist.** `ResourceTracker.h:154-162` says the contract package
minted none and that `Buffer` is 0 only because it is the leading member of a comment. Every texture target,
`Renderbuffer` and `TexBuffer` need real values, in `MG_Pipe`, before a second producer writes the field.
2. **`MGPipeBindBit` must move out of `ResourceTracker.h`.** `ResourceTracker.h:64-66` names P4a's texture family as
exactly the second producer that triggers the move, and four of the twelve bits
(`Sampler`, `ShaderImage`, `RenderTarget`, `DepthStencil`) have no writer today.
3. **`kMGPipeMaxResourceSlots` is one bound for all resource kinds** (`PipeApply.h:105-113` argues the two existing
bounds differ *because the two records differ*). A texture record carrying an 88-byte descriptor plus per-level
state is a third size class.
4. **`MGPSubData`'s buffer-only gate** (`PipeApply.cpp:510-531`) refuses `Level != 0` and `RegionCount != 0`
unconditionally; the texture path needs the branch on `Target` plus a real box/level/region validator.
5. **`SamplerViewCso` is the one P4a kind with no `TwinRegistry`** (`Managers.h` has six, `:1181/:1521/:1612/:2130/
:2230/:2257`, plus the buffer table `:691`), and therefore no backend death arm in
`OnFrontendStateObjectDestroyed` (`Managers.cpp:198-245`). Its lifetime is client-only, like
`VertexElementsCso` after C-1.
6. **`kUnpublishedDestroy` for programs/pipelines/shaders** (`DirtySurface.def:301-305`) is exactly what P4a's
shader CSO closes; three rows change and the gate checks both directions.
7. **`SetFramebufferState` has no `MGPipeSuppressorSlot`** although its `ContentHash`'s stated second job is client
suppression (`MGPipeTypes.h:369-373`); and the three slots P4a will wire are labelled `P3b`/`P4b` in
`SetHashSuppressor.h:46-50`, which disagrees with `ROADMAP.md:20`.
8. **The `EmittedCallSuppliesTheWholeField` answer for every P4a accessor is almost certainly "no"** for the same
pointer-storage reason as `GetBoundVertexArray` (`PipeFill.cpp:1094-1115`); that has to be decided in that
function, deliberately, and not inherited from a `Coverage.def` row's presence.
9. **`MGPSamplerDesc` carries an `MGPBlobRef` but its `PipeCalls.def:104` row is `kNone`**, unlike every other
blob-carrying row.
10. **Bit ordering**: P4a's texture-`resource_*` bit is to its sampler-view bit what bit 7 is to bit 8
(`PipeFill.cpp:1062-1069`) — one direction of the A/B is non-functional and must be documented in the same place.