mirror of
https://github.com/MobileGL-Dev/MobileGL
synced 2026-11-16 14:33:24 +09:00
Two things land together: the plan and contract draft P6 needs before it starts, and the
working notes that until now existed on exactly one machine.
1. P6's plan and contract draft (neither started; not one line of code)
docs/Disaggregated/P6-SPAWN-PLAN.md the package plan
docs/Disaggregated/P6-CONTRACT-DRAFT.md the contract draft (moves to
MG_Remote/CONTRACT-P6.md when c6 lands)
The three findings that mattered, all written into the documents:
a. P6 is SMALLER than its roadmap cell suggests. The transport primitives are already in
the tree and already tested: SocketDoorbell including hangup detection and the two
lost-wakeup fences (Doorbell.cpp:211-360, four cases in FdPassingTest), SCM_RIGHTS fd
passing, ShmSegment::Adopt, and the SurfaceOp / WindowKind schema already defined in
protocol.fbs. inproc uses a real second shm mapping rather than an alias, and
SessionRings.h:22-28 says that was done so today is not the first time it runs. P6 is
assembly plus a control plane plus a process, not "write a socket transport".
b. The evidence for "P6 is only a transport swap" has EXPIRED. It was bought by P5c, whose
audit found 59 direct memory accesses in a tree that already looked clean. P5e changed
the tree again. So the first package, a6, is a read-only audit that writes no code, and
every contract row that depends on it is marked PENDING a6 rather than decided in
advance.
c. P6 does not get a game running on the phone. ANativeWindow* is meaningless in the child,
and protocol.fbs:186-196's own comment says Android transfers the window out of band -
that band is P12. P6 lands pbuffer / surfaceless / offscreen, which is what HeadlessGL,
the split-equivalent lane and trace replay need, and which is exactly what P6's own exit
gate measures. A real window reaching the server is a named refusal. This gets its own
section because "P6 is done" would otherwise read as "the game runs now".
The contract adds rule G: a role may not name a process-local handle. It extends P5c's
rule E (a role may not name the other role's memory) from memory to identity - EGLDisplay /
EGLSurface / EGLContext / ANativeWindow* / fd number / pid / mapped address either cross as
a token this contract defines or they do not cross, and a descriptor crosses only through
SCM_RIGHTS, where the kernel renumbers it.
What P5e left for P6 gets its own section. The latch semantics are already designed
(ARCHITECTURE.md:504) and are copied unchanged. What is new is that after run-ahead the
client no longer waits while the peer process can DIE: the client holds records that were
published and will never be applied, and Android's freezer suspends the child without
closing anything. So slow and dead must be distinguishable WITHOUT a timeout threshold.
That is P6's only new design; everything else is carriage. It shares a predicate with E1's
outstanding re-specification (ID-122), and the two should be designed together.
Two gates carried over from P5e's lessons: G2 requires integration-spawn's test-name set to
match integration-split's name for name, because a differing set means the lane is quietly
running less; and the arm-proof gate requires every entry to record the child pid and
transport=spawn in its OWN private log - ID-124 established that this kind of false green
really happens, and a spawn lane that actually ran monolith would pass every other gate.
S2's shape must be settled before it is written, and the document says why: E1 is the
cautionary case.
2. The working notes move into the repository (docs/Disaggregated/notes/, 415 .md files)
ROADMAP / CURRENT_STAGE_PROGRESS / MEASUREMENTS cite ruling numbers, audit line numbers and
the provenance of gate figures from ~/w7/notes/, a directory that exists on one machine and
is under no version control. A record cited hundreds of times that lives only locally is not
a record, so it moves in whole, with its directory structure intact.
Only .md moves. Scripts, run logs, census and gate result JSON, patches, APKs and nm dumps
stay where they are: they are evidence DATA rather than documents - large, regenerated per
run, and mostly carrying absolute paths and device serials that mean something only on the
machine that produced them. The mapping and this split are written in
docs/Disaggregated/notes/README.md.
Two exceptions are recorded there too: P6's BRIEF has been promoted to a first-class
document and keeps no copy under notes/, so the two cannot drift apart; and recovered/ holds
material salvaged from failed workflow runs, which may duplicate the like-named phase
directories and is kept because a few of those were the only complete version at the time.
CI's citation lint takes docs/Disaggregated/*.md only (non-recursive), and notes/ is
deliberately outside it: those notes' file:line citations were written against their own
code heads, and resolving them against today's HEAD would fail wholesale - which is not an
error, it is their correct state as a historical record. To check one, use the revision it
declares (--rev).
3. Inconsistencies fixed in passing
- README.md's status line still said P5e was in progress while the stage table already said
closed.
- CURRENT_STAGE_PROGRESS's next-step item 1 still listed the exit gate as pending, though
(a) and (b) were run in the previous commit; rewritten to closed plus the one item that
actually remains (E1).
- ROADMAP's P6 row still had the pre-phase plan in three of its cells; it now carries the
package order, the scope boundary and the two new gates.
Checked with check_doc_citations.py: 125 citations across docs/Disaggregated/*.md, 0 problems.
913 lines
68 KiB
Markdown
913 lines
68 KiB
Markdown
# P3a scout — the MGPipe scaffolding and the gates
|
||
|
||
Tree read: `C:/Users/geekerwan/AndroidStudioProjects/FoldCraftLauncher/MobileGL-disagg`, branch
|
||
`feat/disaggregated`, HEAD `55d2af9b` ("make the handle-ABA negative control construct its own
|
||
collision and defeat the {slot, gen} generation"). Read-only; nothing edited.
|
||
|
||
What P3a is, per the plan the tree carries (`docs/Disaggregated/ROADMAP.md:19`): handle wave 1 on
|
||
Espryt — the seven `BufferBackendOps` become `resource_*` / `buffer_subdata_resident` (may be null) /
|
||
`resource_flush_range` / `resource_readback` / `map_persistent`; pool and deferred release move as-is;
|
||
vertex elements (all three calls, both backends); `set_vertex_buffers` with an explicit `baseInstance`
|
||
field; `set_index_buffer`; the Adreno SIGSEGV workaround stays. Acceptance: the full gate set,
|
||
buffer/VAO scenario families (`LargeArenaAdoption`, `StorageBufferRegrow` publishing
|
||
`map-persistent-roundtrips`, `VertexAttribBinding`, `MultiDraw`, `PrimitiveRestart`), Create/rd12/26.3/
|
||
sodium traces, and MC 26.3 p99 unchanged on Adreno. `ROADMAP.md:64` sets the rebaseline trip wire:
|
||
**P3a over 27 days means the narrow-handle-ification premise was wrong.** `ROADMAP.md:34` puts the
|
||
full `gl44to46` caselist (~56,271 cases) at P3a, because P3a is one of the five architecture
|
||
boundaries.
|
||
|
||
---
|
||
|
||
## 1. MG_Pipe: the catalogue and the payloads P3a fills in
|
||
|
||
### 1.1 `MobileGL/MG_Pipe/PipeCalls.def` — the call catalogue
|
||
|
||
The wire opcode is the **1-based position in `MGP_CALL_LIST`** (`PipeCalls.def:20-23`): appending is
|
||
the only legal edit; reordering is a protocol break; a retired call keeps its slot with a comment.
|
||
`MGP_CALL_LIST_DOCUMENTED_COUNT 71` (`:69`) is the authority and `MG_Test/Pipe/PipeCatalogueTest.cpp`
|
||
pins the arithmetic against the two generated tables.
|
||
|
||
The rows P3a lands (opcode = line order within `MGP_CALL_LIST`, which begins at `:74`):
|
||
|
||
| line | call | payload | class | flags |
|
||
|---|---|---|---|---|
|
||
| `:75` | `ResourceCreate` | `MGPResourceDesc` | `kScreen` | `kNone` |
|
||
| `:76` | `ResourceRespecify` | `MGPResourceDesc` | `kScreen` | `kNone` |
|
||
| `:77` | `ResourceDestroy` | `MGPHandleOnly` | `kScreen` | `kNone` |
|
||
| `:78` | `MapPersistent` | `MGPHandleOnly` | `kScreen` | `kReplySlot\|kOptional` |
|
||
| `:79` | `UnmapPersistent` | `MGPHandleOnly` | `kScreen` | `kOptional` |
|
||
| `:95` | `CreateVertexElements` | `MGPVertexElements` | `kCtxCso` | `kHasBlob` |
|
||
| `:96` | `BindVertexElements` | `MGPHandleOnly` | `kCtxCso` | `kNone` |
|
||
| `:97` | `DeleteVertexElements` | `MGPHandleOnly` | `kCtxCso` | `kNone` |
|
||
| `:108` | `SetVertexBuffers` | `MGPVertexBuffers` | `kCtxState` | `kVarTail` |
|
||
| `:109` | `SetIndexBuffer` | `MGPIndexBuffer` | `kCtxState` | `kNone` |
|
||
| `:110` | `SetIndirectBuffers` | `MGPIndirectBuffers` | `kCtxState` | `kNone` |
|
||
| `:128` | `ResourceSubData` | `MGPSubData` | `kCtxObject` | `kHasBlob\|kVarTail` |
|
||
| `:129` | `BufferSubDataResident` | `MGPSubData` | `kCtxObject` | `kHasBlob\|kOptional` |
|
||
| `:130` | `ResourceSubDataComplete` | `MGPSubDataComplete` | `kCtxObject` | `kNone` |
|
||
| `:131` | `ResourceFlushRange` | `MGPFlushRange` | `kCtxObject` | `kNone` |
|
||
| `:132` | `ResourceReadback` | `MGPReadback` | `kCtxObject` | `kReplySlot` |
|
||
|
||
**`kNeedsAck` is declared but used by no call in the tree today.** It is defined at
|
||
`MG_Pipe/MGPipe.h:42` (`1u << 0`, "the caller must not proceed until the server has acknowledged.
|
||
Rare by design"), listed in the `PipeCalls.def:18` flag legend, and referenced once more only as
|
||
prose in `MG_Remote/Transport/Doorbell.h:19`. **No `X(...)` row carries it** — verified by
|
||
`grep -rn kNeedsAck`. So if P3a wants `glBufferStorage` to be acknowledged, it is *adding the first
|
||
use of the flag*, not reusing an existing one: `ResourceCreate` (`:75`) / `ResourceRespecify` (`:76`)
|
||
currently carry `kNone`, and the immutable-storage discriminator already exists in the payload as
|
||
`MGPResourceDesc::Immutable` and `MGPResourceDesc::StorageFlags` ("glBufferStorage flags",
|
||
`MGPipeTypes.h:161-163`). Changing a flag word does not move an opcode, so this is an in-place edit,
|
||
but it does change the generated tables and therefore requires a `gen_pipe.py` regeneration + diff.
|
||
|
||
Deliberately **not** migrated, recorded in the footer `PipeCalls.def:163-177`: `GetIntegeri_v` /
|
||
`GetInteger64i_v` (the six compute-workgroup answers live in `MGPCaps::Dynamic`), `GetProgramiv`,
|
||
`ShaderStorageBlockBinding`, `set_pixel_unpack_state` ("no such state crosses the line"), a
|
||
compressed-format concept, `pipe_transfer`, and a stage dimension on `set_sampler_views`.
|
||
|
||
### 1.2 `MobileGL/MG_Pipe/MGPipeTypes.h` — the payloads
|
||
|
||
Every payload is `MGP_ASSERT_POD(T, Size)` (`:44-46`): trivially copyable **and** an exact stated
|
||
size. Adding a member is a build break until the number is updated, and the field list in
|
||
`PipeFields.def` must be updated in the same commit or `gen_pipe.py` refuses.
|
||
|
||
- `MGPResourceDesc` — `:150-176`, **88 bytes**. One discriminated descriptor for buffers, every
|
||
texture target and renderbuffers. `Resource` handle, `Target`, `StorageKind`, `BindMask`
|
||
(`:154-157`; the `ELEMENT_ARRAY` bit is the D-B7 switch: with `kCapNeedsHostIndexBytes` the server
|
||
mirrors this resource), `InternalFormat`, `Width/Height/Depth`, `ArrayLayers/Levels/Samples`,
|
||
`FixedSampleLocations`, `Immutable`, `Usage` (`BufferUsage`), `StorageFlags` (glBufferStorage
|
||
flags), `HasDefinedContent` ("false after a NULL-data respecify"), `ImageBindableHint`
|
||
(client-side `everImageBound`, pre-emptive allocation), `GlNameForDiag` (**diagnostics only** —
|
||
`:167-170`: a GL name is never an identity, never a memo key, never part of a content hash),
|
||
`ViewOf`, `BufferForTexBuffer`, `BufOffset`/`BufSize` with `kMGPipeWholeBuffer == ~0ull` (`:177`).
|
||
- `MGPSubData` — `:587-599`, **72 bytes**. `Res`, `Target`, `Level`,
|
||
`SourceIsVerbatimLevelShadow` (`:590-592`, replaces the backend's `uploadData == mipData` pointer
|
||
comparison), `UnionBox`, `RegionCount` (`MGPSubRegion[]` var-tail), `Blob`.
|
||
**The UnionBox buffer convention** is `:579-586`: with `Target == Buffer` there is no level and no
|
||
box, so the destination byte range rides in the box — `UnionBox.X` is the byte offset,
|
||
`UnionBox.W` the byte size, `Y = Z = 0`, `H = D = 1`, `Level = 0`, `RegionCount = 0`, `Blob` holds
|
||
exactly `Size` source bytes. That caps one record at a 2^31-1 offset and a 2^32-1 size; **the
|
||
emitter must split a range beyond either**, and at `SEG_STAGE`'s 32 MiB the ring's half-capacity
|
||
bound is the far tighter constraint. The three accessors are the *only* legal spelling:
|
||
`MGPipeSetSubDataBufferRange(record, offset, size)` (`:603-611`, returns **false with the record
|
||
untouched** when the range does not fit — that is the emitter's split signal),
|
||
`MGPipeSubDataBufferOffset` (`:612-616`; reads `UnionBox.X` through `Uint32` so a corrupt negative
|
||
X lands above the encodable bound and the applier's bounds gate refuses it) and
|
||
`MGPipeSubDataBufferSize` (`:617`). Carrying source strides rather than inferring them is
|
||
deliberate (`:562-565`): the old pointer test cannot survive a split.
|
||
`MGPSubRegion` is `:566-573`, 40 bytes, `SrcRowStride`/`SrcSliceStride` where 0 means tightly
|
||
packed. The union box **and** the region list both travel so the *server* picks the upload shape —
|
||
Mali prices texture upload by job count, ~100 sprite rects vs one union box measured +6 ms/frame
|
||
(`:575-577`).
|
||
- `MGPVertexBuffer` — `:356-364`, 32 bytes: `Res`, `Offset`, `Stride`, `Divisor`, `BindingIndex`.
|
||
**There is no `baseInstance` field here today**; `ROADMAP.md:19` asks P3a for an explicit one, and
|
||
`MGPDrawInfo` currently carries `StartInstance` (`PipeFields.def:189`).
|
||
- `MGPVertexBuffers` — `:367-371`, 16 bytes: `Start`, `Count`, `ContentHash`. Var-tail header;
|
||
`MGPVertexBuffer[Count]` follows. The `ContentHash` is mandatory for **every** `kVarTail` `set_*`
|
||
(`:350-352`): "or 26.2's redundant `glBindSampler` traffic reappears as a variable-length record
|
||
per batch".
|
||
- `MGPIndexBuffer` — `:374-380`, 24 bytes: `Res`, `Offset`, `IndexSize`. `:373` states it is **an
|
||
independent call, NOT a subset of the VAO configuration version (D5)**.
|
||
- `MGPIndirectBuffers` — `:382-386`, 16 bytes: `DrawIndirect`, `Parameter`.
|
||
- `MGPBufferRange` — `:435-440`, 24 bytes: `Res`, `Offset`, `Size`. No inline host span, by design
|
||
(`:429-434`): the named-UBO host bytes needed under `kCapNeedsHostUboBytes` (D-B8) travel as an
|
||
*optional second* var-tail of `MGHostSpan[HostSpanCount]` behind the ranges, so SSBO / atomic /
|
||
XFB ranges do not each pay 32 dead bytes.
|
||
- `MGPShaderBuffers` — `:445-454`, 32 bytes: `Class` (Uniform | ShaderStorage | AtomicCounter),
|
||
`Start`, `Count`, `WritableMask`, `HostSpanCount`, `ContentHash`. `HostSpanCount` is 0, or `Count`
|
||
for the Uniform class under `kCapNeedsHostUboBytes`; a range with nothing to ship carries an empty
|
||
span so the two arrays stay index-aligned.
|
||
- `MGPVertexElements` — `:253-…`, `kHasBlob`; fields `Cso`, `AttributeCount`, `BindingPointCount`,
|
||
`Blob` (`PipeFields.def:71-72`).
|
||
- `MGPFlushRange` — `:629-635`, 32 bytes, carries **the application's real access flags**
|
||
(`Flags<BufferMappingAccessBit>`), not a normalised subset.
|
||
- `MGPReadback` — `:637-641`, 24 bytes. `MGPSubDataComplete` — `:621-626`, 24 bytes, the forward
|
||
terminator for a server-initiated texture pull, may carry zero regions.
|
||
- Shared primitives: `MGPBlobRef` `:55-61` (24 B; monolith `Seg == kMGHostSpanSegNone` and `Offset`
|
||
is an address into the caller's staging arena), `MGPBox` `:70-74`, `MGPReplySlot` `:78-81`
|
||
("every server query in this catalogue is async-with-handle; none of them blocks"),
|
||
`MGPHandleOnly` `:93-98` (16 B, `Handle` + widened `Kind`).
|
||
- Cap bits P3a cares about, `MGPCapBit` `:108-124`: `kCapResidentSubData` (bit 2),
|
||
`kCapNeedsHostIndexBytes` (bit 7 — arms the index host mirror under split, D-B7),
|
||
`kCapNeedsHostUboBytes` (bit 8, D-B8).
|
||
|
||
### 1.3 `MobileGL/MG_Pipe/MGPipeHandles.h` — identity
|
||
|
||
`MGPipeKind` `:24-40`: `None, Buffer, Texture, Renderbuffer, Framebuffer, Xfb, RenderStateCso,
|
||
VertexElementsCso, SamplerCso, SamplerViewCso, ShaderCso, Fence, Query, Context, KindCount`.
|
||
`MGPipeHandle` `:54-61` is `{Uint32 Slot, Uint32 Gen}`, 8 bytes, alignment 4, trivially copyable
|
||
(`:63-65`). **Gen increments only when a SLOT IS REUSED — never on a respecify** (`:44-48`), so a
|
||
`glBufferData` on a live buffer keeps its handle. Two generations exist and are strictly separate
|
||
(`:50-53`): this one is the client's "is this the same GL object"; `MGGen` is the *server's* epoch
|
||
for "did I recast my driver object", and **no MGPipe call may require the client to know MGGen**.
|
||
Reserved: `kMGPipeNullHandle{0,0}` and `kMGPipeDefaultFramebuffer{0,1}` (`:72-73`),
|
||
`kMGPipeFirstAllocatableSlot = 1` (`:81`). ShaderCso has a reserved composite band,
|
||
`kMGPipeShaderCsoSlotLimit = 1<<20` and `kMGPipeShaderCsoCompositeSlotBase` = limit − limit/16
|
||
(`:88-94`) — not P3a's business but it constrains the allocator.
|
||
|
||
### 1.4 `MobileGL/MG_Impl/Pipe/SlotAllocator.h` — minting and recycling
|
||
|
||
`MGPipeSlotAllocator` (`:39-96`), one free list plus a high-water mark **per kind** (`kKindCount` =
|
||
`MGPipeKind::KindCount`, `:41`), so slots stay dense and the server's table is an array. API:
|
||
`Allocate(kind)` `:47`, `AllocateFor(kind, lifetimeId)` `:49`, `FindByLifetimeId` `:53`,
|
||
`Acquire(kind, lifetimeId)` `:55` (find-then-allocate — the ordinary client path),
|
||
`Free(kind, handle)` `:60` (**the Gen bump happens on the NEXT handout of the slot, not here**, so
|
||
a double free cannot skip a generation), `IsLive` `:62`, `GenOfSlot` `:65`, `LifetimeIdOfSlot` `:66`,
|
||
`HighWater` `:69` (what a server-side slot-indexed table must be sized to), `LiveCount`/`FreeCount`
|
||
`:70-71`, `Reset()` `:74`. Storage: `SlotState{Gen, Live, EverHandedOut, LifetimeId}` `:77-82`,
|
||
`KindState{Vector<SlotState> Slots, Vector<Uint32> FreeList, UnorderedMap<Uint64,Uint32>
|
||
ByLifetimeId, LiveCount}` `:84-90`. Process singleton `MGPipeSlots()` `:99`; compiled only under
|
||
`MOBILEGL_PIPE_PUSH` (`:34-36`). The lifetimeId→slot map is what keeps a GL name out of every key
|
||
(`:30-32`); it has nothing to do with `MG_State`'s `IndexGenerator`, whose LIFO name reuse is the
|
||
problem `{slot, gen}` exists to close (`:19-22`). Implementation: `SlotAllocator.cpp` (174 lines);
|
||
unit coverage `MG_Test/Pipe/SlotAllocatorTest.cpp` (recycle/gen/stale-free at `:63-102`, `:163`,
|
||
`:263`).
|
||
|
||
### 1.5 The death notice — and the hole P3a has to fill
|
||
|
||
`MobileGL/MG_State/GLState/StateObjectDeathNotice.h` (`MOBILEGL_PIPE_PUSH` only, `:12`):
|
||
`StateObjectDeathOps{ void (*OnDestroyed)(MGPipeKind, Uint64 lifetimeId) }` `:39-43`, a plain
|
||
non-atomic pointer `g_stateObjectDeathOps` `:45` written once at backend bring-up,
|
||
`SetStateObjectDeathOps` `:47`, and `NotifyStateObjectDestroyed(kind, lifetimeId)` `:55-59`. It
|
||
carries `{kind, lifetimeId}` and **not the object**, because by the time the last `SharedPtr` drops
|
||
there is nothing left to pass (`:23-26`); one entry point serves all kinds because the backend's
|
||
answer is the same for all of them: free the slot, drop the twin (`:26-27`). In a pull build the
|
||
header declares nothing (G1 requires a byte-identical symbol set).
|
||
|
||
Frontend raisers today (`grep NotifyStateObjectDestroyed`) — six, and **Buffer is not one of them**:
|
||
|
||
- `FramebufferState/FramebufferObject.cpp:36` (Framebuffer)
|
||
- `ProgramState/ProgramObject.cpp:43` (ShaderCso)
|
||
- `RenderbufferState/RenderbufferObject.cpp:40` (Renderbuffer)
|
||
- `SamplerState/SamplerObject.cpp:39` (SamplerCso)
|
||
- `TextureState/TextureObject.cpp:40` (Texture)
|
||
- `VertexArrayState/VertexArrayObject.cpp:53` (VertexElementsCso)
|
||
|
||
Backend consumer: `MG_Backend/DirectGLES/Managers.cpp:191-217`
|
||
`OnFrontendStateObjectDestroyed(kind, lifetimeId)`, installed as
|
||
`g_glesStateObjectDeathOps = {.OnDestroyed = OnFrontendStateObjectDestroyed}` `:219-221`. It drops
|
||
out early on `InProcessTeardown()` `:192` (a notice after `exit()` has begun is dropped — the twin
|
||
is a *deliberate* leak, `:187-190`), then switches to `<Kind>Impl::g_backend<Kind>Objects.
|
||
DestroyByLifetimeId(lifetimeId)`. **`MGPipeKind::Buffer` falls into `default:` with the comment
|
||
"Buffer already has its own death signal (`BufferBackendOps::OnDestroy`)"** (`:212-215`).
|
||
|
||
That existing buffer signal is `BufferBackendOps::OnDestroy(SharedPtr<BackendBufferResource>&&)`
|
||
declared at `MG_State/GLState/BufferState/BufferObject.h:103` and called from
|
||
`~BufferObject` at `BufferState/BufferObject.cpp:39-43` — it hands over the *resource*, not
|
||
`{kind, lifetimeId}`, and it fires only when `m_resource.Backend()` is set. **P3a must decide
|
||
whether the buffer slot is freed through the ops table's `OnDestroy` or by adding the seventh
|
||
`NotifyStateObjectDestroyed(MGPipeKind::Buffer, m_lifetimeId)` raiser and an arm in the
|
||
`Managers.cpp` switch.** The `SlotTables.h` header prose already says "All six re-keyed object
|
||
classes raise …" (`DirectGLES/SlotTables.h:38`), i.e. the seventh is exactly the P3a delta.
|
||
|
||
`DestroyByLifetimeId` is **static** and answered by *every live table of the kind*, not just the
|
||
global — a by-value copy held by a fixture or a context reset is a real configuration — and the slot
|
||
goes back **once, last**, after every holder has let go (`SlotTables.h:49-59`,
|
||
`Managers.cpp:180-185`). That holder-list discipline is load-bearing because the allocator erases
|
||
its lifetimeId→slot mapping on `Free`, so a notice resolved twice would find nothing the second time.
|
||
|
||
Other `SlotTables.h` facts P3a inherits: the key stops being a frontend heap address, so the
|
||
`weak_ptr` per entry stops being an identity test and `OwnerEquals` / three `TwinLookupMemo`s /
|
||
`UnitSamplerLookupMemo`'s owner compare lose their reason to exist (`:23-28`); the lookup becomes one
|
||
bounds check plus one array index, so a returned `BackendPtr*` survives the next `Find` (`:29-32`);
|
||
there is **no GC on this arm** — no draw tick, no creation tick, no sweep; the seven
|
||
`CollectGarbageIfNeeded` sites in `DirectGLES.cpp` drive the legacy registry only (`:43-47`). The
|
||
`weak_ptr` survives for one reason: `ForEachLive()` hands a strong reference to
|
||
`ScopedDetachedTextureFramebufferAttachments` (`:61-68`).
|
||
|
||
**Recorded debt P3a should be aware of, `SlotTables.h:70-77`:** this header is under `MG_Backend/`
|
||
and it *mints* handles (`MGPipeSlots().Acquire`) off a frontend `SharedPtr`'s `GetLifetimeId()`,
|
||
which contradicts `MGPipeHandles.h:13-16` ("minted by the CLIENT and never by the server"). It is
|
||
monolith glue; the minting and the resolution belong on the client and the backend should receive the
|
||
handle in the verb payload. **Not covered by any gate** — `check_include_closure.py` does not probe
|
||
`MG_Backend` headers.
|
||
|
||
Magma's side: `MG_Backend/DirectVulkan/Renderer/MagmaPipeArms.h`. `MagmaPipeIdentityTable` (entry
|
||
storage `:369-378`: `m_entries`, `m_freeSlots`, `m_index`, plus a one-entry front memo
|
||
`m_lastLifetimeId/m_lastIndex/m_lastHandle`), and `MagmaPipeIdentityTables` `:384-402` owning
|
||
`m_vaos{"VertexElementsCso"}` and `m_buffers{"Buffer"}`. `HandleOf(kind, lifetimeId)` `:388-391`
|
||
routes `Buffer` to the buffer mint and everything else to the VAO mint — **a VAO is kind
|
||
`VertexElementsCso`** (`:386-387`). These are **per renderer, not process-global** (`:381-383`), so
|
||
Magma is *not* a holder in Espryt's holder list and does not mint out of `MGPipeSlots()`.
|
||
`MagmaPipeSlotIndex(handle)` `:411-417` is `handle.Slot - kMGPipeFirstAllocatableSlot` with an assert
|
||
(compiled out at INFO) and a ternary that has effect in a shipped build.
|
||
`MagmaPipeSlotTable<T, kChunkEntries=256>` `:427+` grows by appending chunks so **entry addresses
|
||
never move** — the draw path holds references across nested calls.
|
||
`VertexInputStateFactory.cpp:64` already calls
|
||
`m_identity->HandleOf(MGPipeKind::Buffer, attr.Buffer->GetLifetimeId())`, i.e. Magma's vertex-input
|
||
hash is already keyed on the buffer handle (commit `43f8b470`).
|
||
|
||
### 1.6 `PipeApply.{h,cpp}` — the in-process applier
|
||
|
||
`MG_Pipe/PipeApply.h` (150 lines) / `PipeApply.cpp` (667 lines), compiled **only** under
|
||
`MOBILEGL_PIPE_PUSH` (`PipeApply.h:30`). Under split this file becomes
|
||
`MG_Remote/Server/PipeApplier`; in the monolith it writes `MG_Backend/MGPipe/PipeInputs`'s
|
||
`gPipeInputs` directly, so a call and its effect are one function call apart (`:15-18`).
|
||
**The server's per-context working block *is* `PipeInputs::m_renderState`** (`:20-25`) — which is why
|
||
DirectGLES' `SyncRenderState` did not change a line, and why the verify comparator is a real oracle
|
||
("assembled == live", field by field, at every backend read).
|
||
|
||
Per-context stores, `MGPipeApplierState` `:48-87`:
|
||
- `Vector<MGPipeRenderStateCsoRecord> RenderStateCsos` `:51`, indexed by `MGPipeHandle::Slot`, slot 0
|
||
never live. Each record `:42-46` = `{Uint32 Gen, Bool Live, Array<Uint8,
|
||
kMGPipePipelineChunkBytes> PipelineBytes}` — it keeps the 396 pipeline bytes because an incremental
|
||
`create_render_state` names only the chunks that moved against a `BaseCso`.
|
||
- `MGPipeHandle BoundRenderStateCso` `:53` — the last bind, so a rebind of the same handle needs no
|
||
scatter.
|
||
- `ResidualValueBlock Residual` + `Bool HasResidual` `:56-57`.
|
||
- `Uint32 ScatteredChunkBits` `:77` — the applier's own ledger of which global chunk bits it (rather
|
||
than the fill loop) wrote. Both trip wires arm off it, and the contract is spelled at `:62-76`:
|
||
with the render-state subsystem OFF nothing is scattered, the ledger stays empty and the wires say
|
||
nothing; with it ON the applier is the block's only writer. `set_patch_state`'s own write
|
||
deliberately does **not** enter the ledger — a wire comparing against bytes it wrote itself is a
|
||
tautology (`:74-76`).
|
||
- Four observable counters `:83-86`: `ResidualCapabilitiesCompared`, `ResidualDivergences`,
|
||
`PatchCarrierComparisons`, `PatchCarrierDivergences`. Rationale `:79-82`: only a poison or verify
|
||
build aborts, so the shipped push build counts and logs and a unit case can see the wire fire in
|
||
*every* build.
|
||
- Singletons `MGPipeApplier()` `:90` (`PipeApply.cpp:393`) and `MGPipeApplierReset()` `:93`.
|
||
|
||
**Seven apply entry points today, and that is all of them** (`PipeApply.h:99-122`, definitions at
|
||
`PipeApply.cpp:407, 457, 476, 490, 499, 503, 561, 607`):
|
||
`MGPipeApplyCreateRenderState`, `…BindRenderState`, `…DeleteRenderState`, `…SetDynamicState`,
|
||
`…SetPixelPackState`, `…SetPatchState`, `…SetVertexAttribDefaults`, `…SetResidualValueState`.
|
||
**Nothing for buffers, resources, vertex elements, vertex buffers or the index buffer exists yet —
|
||
that is P3a's server half.**
|
||
|
||
Plus the derivation step (`PipeApply.h:124-149`): `MGPipeDeriveRenderStateFields(inputs)`
|
||
(`PipeApply.cpp:657`) recomputes every `PipeInputs` field that is a pure function of the working
|
||
`RenderStateParameters`, and `MGPipeDeriveRenderStateFieldsForChunks(inputs, globalChunkBits)`
|
||
(`:664`) is the scoped form the applier actually calls, so a per-frame `glViewport` (dynamic chunk D0
|
||
alone) does not pay the 8-wide blend loop, the 16-wide depth-range loop or the 35-arm capability
|
||
switch. Every guard's chunk set is computed with `MGPipeRenderStateChunkBitsCovering`, so a boundary
|
||
move cannot leave one stale. Trip-wire log tag: `MGP_TRIP_WIRE_TAG(name)` = `"Fatal{" name "}"`,
|
||
`PipeApply.cpp:29-31` — that is the marker G4 greps the retrace logs for.
|
||
|
||
Client-side CSO cache, `MG_Impl/Pipe/CsoCache.h` — the shape P3a's vertex-elements CSO should copy.
|
||
Lookup (`:14-25`): (1) widened `m_pipelineStateVersion` did not move → reuse the last handle, **zero
|
||
hashing, zero probing** — the steady state; (2) moved → hash the 396 pipeline bytes, probe, and
|
||
**confirm with a memcmp** before reuse (a bare 64-bit equality would alias two states onto one CSO —
|
||
silent wrong pixels with no gate that could see it; Mesa's `cso_cache` memcmps for the same reason);
|
||
(3) miss → mint a slot, emit `create_render_state` with every chunk, bind. Capacity 64
|
||
(`kMGPipeCsoCacheCapacity`, `:53`), ~26 KB per context, provisional pending the P13 retune.
|
||
Counters `:57-69`: `Mints`, `Binds`, `Hits`, `Collisions`, `Evictions`.
|
||
|
||
---
|
||
|
||
## 2. The P2 tracker and the emission step
|
||
|
||
### 2.1 `MobileGL/MG_Impl/Pipe/Tracker.h` (436 lines, header-only)
|
||
|
||
Header-only for an ownership reason, not a design one (`:40-44`): the root `CMakeLists.txt` that
|
||
would name a new `.cpp` belongs to package A and is frozen behind the `p2/contract` tag. Splitting it
|
||
out is one `list(APPEND)` line. **P3a will hit the same wall if it wants `Tracker.cpp`.**
|
||
|
||
`enum class MGPipeDirty` `:57-80`, 18 bits, one per row of `ARCHITECTURE.md 5.2`:
|
||
- value class, **emitted at P2** (`:58-63`): `NewRenderState` 0, `NewPipelineState` 1, `NewPixelPack`
|
||
2, `NewPatchState` 3, `NewVertexAttribDefaults` 4.
|
||
- value class, **computed and counted, emitted from P3a on** (`:64-68`): `NewVertexElements` 5,
|
||
`NewShader` 6, `NewShaderBindings` 7, `NewGlobalConstants` 8.
|
||
- object class, from P3b/P4b (`:69-78`): `NewVertexBuffers` 9, `NewIndexBuffer` 10, `NewFramebuffer`
|
||
11, `NewSamplerViews` 12, `NewSamplers` 13, `NewShaderImages` 14, `NewConstBuffers` 15,
|
||
`NewShaderBuffers` 16, `NewSoTargets` 17.
|
||
|
||
Names table `:95-114`, `kMGPipeDirtyEmittedAtP2` `:90-93`, `kMGPipeDirtyCount <= 32` asserted `:83`.
|
||
**`ROADMAP.md:19` puts `set_vertex_buffers` and `set_index_buffer` in P3a, but bits 9 and 10 are
|
||
labelled P3b/P4b in this enum — reconcile that before wiring, and update `:64-78`'s comments.**
|
||
|
||
`MGPipeSubsystemForDirty(bit)` `:119-135` maps a bit to its runtime `MOBILEGL_PIPE_PUSH` subsystem
|
||
and **returns 0 for bits 5..17** ("no call of their own until P3a/P3b/P4a/P4b, so there is no
|
||
subsystem to switch and the residual fill keeps supplying their fields"). Subsystem constants are in
|
||
`MG_Pipe/MGPipe.h:72-85`: bit 0 RenderState, 1 PixelPack, 2 PatchState, 3 VertexAttribDefaults,
|
||
4 ResidualValues, 5 EsprytSlots (Track H), 6 MagmaVertexInput (Track H); **bits 7..62 reserved,
|
||
allocated in ROADMAP order and never reused** (`:79` — an operator's recorded `0x7f` has to keep
|
||
meaning what it meant); bit 63 is `kMGPipeBehaviourNoCsoContentAddressing`, the negative control, not
|
||
a subsystem. Default for a push build with the knob unset: `kMGPipeSubsystemsMigratedAtP2 = 0x7f`
|
||
(`:85`). **P3a's new subsystem bits are 7 and up.**
|
||
|
||
`MGPipeMixShutter(acc, value)` `:143-146` is the composite shutter hash. Its collision caveat is
|
||
explicit (`:137-142`): a collision costs a *missed* fire, which is acceptable **for bits 5..17 and
|
||
only for them**, because nothing consumes those bits in P2 — "P3 replaces each with its own exact
|
||
shutter as it takes the subsystem over". The five P2 emits for are never composed.
|
||
`MGPipeWidenedCounter` `:159-177` widens a `Uint16` at the tracker boundary (`Observe` `:161`);
|
||
a decrease is a wrap and adds 65536. The one case it cannot see is stated at `:153-158`: a counter
|
||
advancing by exactly a multiple of 65536 inside one verb boundary reads as unchanged.
|
||
|
||
`MGPipeTracker::Update(ctx, verbClass)` `:188-307`, the dirty walk. A different context calls
|
||
`Reset()` first (`:192-195`) so the first walk publishes a complete state. Shutters:
|
||
- bits 0/1 `:202-205` — widened render-state and pipeline-state versions.
|
||
- bit 4 `:208` — `ctx.GetAnyVertexAttribDefaultGeneration()`.
|
||
- `vaoIdentity = MixShutter(vao->GetLifetimeId(), vao->GetConfigVersion())`, 0 when unbound
|
||
(`:210-212`); bit 5 `NewVertexElements` **is exactly this** (`:213`).
|
||
- bits 6/7/8 `:219-236` from the current program's `GetLinkVersion` / `GetImageUnitVersion` +
|
||
`GetBackendStateVersion` + `GetBlockBindingVersion` + `GetUniformWriteSetVersion` /
|
||
`GetUBOContentVersion`. `:215-218` — deliberately **not** `GetProgramForDraw`, which joins a
|
||
pending link; the tracker must not force a compile to answer "did the shader move".
|
||
- aggregate reads `:239-241`: `GetAnyTextureContentGeneration`, `GetAnyTextureParamsGeneration`,
|
||
`buffers = ctx.GetAnyBufferChangeGeneration()`.
|
||
- bit 9 `NewVertexBuffers` = `MixShutter(ctx.GetAnyVaoAttributeGeneration(), vaoIdentity)` `:243-244`.
|
||
- bit 10 `NewIndexBuffer` = `MixShutter(buffers, vaoIdentity)` `:248`, with the reason at `:245-247`:
|
||
the index buffer lives in the bound VAO's element slot, P2 has no cheap shutter for that slot
|
||
alone, so it **shares the buffer aggregate and over-fires on any buffer write anywhere. "P3b
|
||
narrows it when it takes the subsystem over."** — the narrowing P3a/P3b owes.
|
||
- bits 15/16 `NewConstBuffers`/`NewShaderBuffers` are the raw `buffers` aggregate `:259-260`;
|
||
bit 17 mixes it with the XFB generation `:261-262`.
|
||
- bits 2 and 3 are `memcmp` shutters handled outside the loop (`:266-270`, `:275-293`) — bit 3
|
||
because **NaN is a legal `glPatchParameterfv` value and must compare equal to itself**, which float
|
||
equality denies and memcmp grants.
|
||
- latch and count `:271-272`, `:299-305`, behind `MG_Util::PipeStats::Enabled()`.
|
||
|
||
`Reset()` `:313-326` clears the latches but **deliberately not the fire tallies** (`:311-312`): they
|
||
are a per-run measurement. `ResetCounters()` `:328`. Readouts: `FireCount(bit[, verbClass])`
|
||
`:333-340`, `WalkCount` `:341-349`, `LastDirty()` `:350`, `Primed()` `:351`, `FreshlyPrimed()` `:355`.
|
||
**No timer lives here** (`:35-38`): ROADMAP forbids committing hot-path instrumentation; absolute
|
||
ns/draw comes from DriverBench, from outside the library.
|
||
|
||
Design rule P3a must keep (`:27-33`): **every shutter over-fires on purpose.** A bit that fires too
|
||
often costs one extra push; a bit that fires too rarely renders stale, and the P1 verify comparator
|
||
**cannot see that for object-class state** (it compares those by identity only). Narrowing is P3's
|
||
work, paid for with the fire rates this file publishes.
|
||
|
||
### 2.2 How a new call family gets an emitter — `MG_Impl/Pipe/PipeFill.cpp` (1198 lines)
|
||
|
||
`MGPipeValidateForVerb(verb)` `:1053-1197` is the validate point, five steps (declared in
|
||
`PipeFill.h:21-35`):
|
||
|
||
1. `:1055-1075` — parse the poison knob, arm verify, bump `filled.CurrentVerbSerial` (starts at 1,
|
||
so a read before the first bump is `Fatal{UnmigratedPipeInput, "<Field>@<none>"}` rather than
|
||
default storage, `:1068-1071`), set verb and context identity. `MG_Config::Features.PipeVerify`
|
||
set without the compiled comparator emits `MGLOG_W_ONCE` `:1061-1064` — a lane's arming assertion
|
||
turns that into red.
|
||
2. `:1084-1085` — the dirty walk.
|
||
3. `:1087-1128` — emission. The gate closure `wants(bit)` `:1093-1097` is
|
||
`MGPipeSubsystemForDirty(bit) != 0 && (pushMask & subsystem) && (dirty & bit)`. `:1088-1091`
|
||
states the rule: **every gate goes through `MGPipeSubsystemForDirty`, the one map**; naming the
|
||
constants inline would be a second copy of the map in the only path that runs.
|
||
`tracker.FreshlyPrimed()` handling is **before** the per-subsystem gates `:1110-1115` and resets
|
||
`MGPipeCsoCacheInstance()`, `MGPipeApplierReset()`, `MGPipeSetHashSuppressorInstance().
|
||
InvalidateAll()` and `g_residualDue = true` — it used to live inside `EmitRenderState`, which runs
|
||
only when bit 0 is set, so a per-subsystem A/B that cleared bit 0 gave a fresh context a
|
||
never-reset applier (`:1100-1109`). Then the four emitters `:1117-1128`
|
||
(`EmitRenderState` `:982`, `EmitPixelPackState` `:767`, `EmitPatchState` `:777`,
|
||
`EmitVertexAttribDefaults` `:824`); each returns `payloadBytes`.
|
||
4. `:1130-1161` — the residual fill. For each field in the verb class's mask: skip sticky fields
|
||
(`:1136-1144`; under poison, stamp them once with `FilledGen = 1`), then compute
|
||
`supplied = subsystem != 0 && (subsystem & kMGPipeWiredSubsystems) && (pushMask & subsystem) &&
|
||
EmittedCallSuppliesTheWholeField(field) && (applierDerives || AppliedWithoutDerivation(field))`
|
||
`:1150-1155`, and `CopyField` only when not supplied `:1156`. **The stamp is written either way**
|
||
(`:1145-1149`) — a stamp says "this verb published this field", which is as true of an emitted
|
||
field as of a copied one, and withholding it would abort every backend read of exactly the fields
|
||
the migration just took over.
|
||
4b. `:1162-1186` — the residual value block. `g_residualDue` is armed **outside** the subsystem gate
|
||
`:1163-1170` (whether the capability set may have moved is a fact about the frontend), and the
|
||
block is emitted **after** step 4 `:1171-1174` because its trip wire compares against the
|
||
assembled mirror; it is held rather than dropped at verbs whose class does not read
|
||
`IsCapabilityEnabled` `:1176-1185`.
|
||
5. `:1187-1193` `PipeStats::RecordDrawPayloadBytes(payloadBytes)`; `:1194-1196` the verify
|
||
`EntryCompare`.
|
||
|
||
**The wiring checklist for a new emitter** (from `:621-672`):
|
||
- add rows to `Coverage.def`'s `MGP_COVERAGE_EMITTED_LIST` (§2.4);
|
||
- add the emitter arm to `SubsystemForEmitter(MGPipeFieldEmitter)` `:624-638` — the map from a
|
||
*field's emitter* to the subsystem;
|
||
- add the matching `MGPipeSubsystemForDirty` arm in `Tracker.h`;
|
||
- **add the `static_assert` pairing them.** `:640-644` states why: the two maps answer different
|
||
questions (one takes an emitter, one takes a dirty bit) and must agree, because emission is gated
|
||
on one and the residual-fill skip on the other; a divergence would push a call whose field is still
|
||
pulled, or worse skip a field whose call was never emitted. Existing asserts `:645-663`;
|
||
- extend `kMGPipeWiredSubsystems` `:669-672` — "it grows one commit at a time, and 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";
|
||
- extend `EmittedCallSuppliesTheWholeField` `:693+` if the call supplies a field completely.
|
||
|
||
Other machinery in this file P3a touches: `MGPipeNoteFrontendMutation` `:498`,
|
||
**`MGPipeNoteAggregate(aggregate)` `:518`** (§2.5), the seven F-class forwarders `:568-604`,
|
||
`MGPipeLeaveVerb` `:607`, `MGPipeVertexAttribDefaultRepairCount`/`…LastHeader` `:1049-1050`.
|
||
|
||
### 2.3 The set-hash suppressor — `MG_Impl/Pipe/SetHashSuppressor.h` (85 lines)
|
||
|
||
Coalescing rule 4 (`:12-13`): **every `kVarTail` `set_*` hashes the resolved set on the client and
|
||
does not emit when the hash has not moved.** `MGPipeSuppressorSlot` `:36-45` already has the slots:
|
||
`SetVertexBuffers = 0` (**marked P3b**), `SetSamplerViews`, `BindSamplerStates`, `SetShaderImages`,
|
||
`SetShaderBuffers`, `SetStreamOutputTargets`, `SetVertexAttribDefaults` (**the one P2 wired**).
|
||
`ShouldEmit(slot, contentHash)` `:53-59` latches and returns; **hash 0 is reserved for "never
|
||
emitted"** and a computed 0 is remapped to 1 (`:23-25`, `:54`) — one collision in 2^64 costs an extra
|
||
emission and never a missed one. `Invalidate(slot)` `:63`, `InvalidateAll()` `:65-67`,
|
||
`LastEmitted(slot)` `:71`. Singleton `:80-83`. This is the carrier for the ~175 lines of debounce
|
||
that move off the backends in P3b/P4b — Espryt's `UnitBindingsSnapshot` / `CaptureUnitBindings` /
|
||
`UnitBindingsUnchanged` and Magma's equivalents (`:15-21`).
|
||
|
||
### 2.4 `MobileGL/MG_Pipe/Coverage.def` — the emitted list and the semantic-merge trap
|
||
|
||
`MGP_COVERAGE_ACCESSOR_LIST` `:29-104` joins the 477-row read inventory
|
||
(`scripts/data/backend_read_inventory.md`, 57 files) against a pipe call. Three pseudo-calls stand
|
||
for rows that never become a forward call (`:19-24`): `kClientResolved`, `kReverseChannel`,
|
||
`kStructuralHandle`. Rows matching neither list are UNMAPPED — merely counted today, **zero from P5
|
||
on** (`:16-17`).
|
||
|
||
Buffer/VAO rows:
|
||
- `GetBoundVertexArray → BindVertexElements` `:36`
|
||
- `GetBufferBindingSlot → SetIndirectBuffers` `:42`, with the caveat `:37-41`: **the accessor is
|
||
polymorphic over `BufferTarget` and its rows really split across `set_vertex_buffers`,
|
||
`set_index_buffer`, `set_indirect_buffers` and `set_shader_buffers`**; the split waits on the
|
||
inventory being re-vendored carrying the target argument (the extractor lives in MobileGL-CS,
|
||
deferred out of P1). It is named for the plan's explicit `DrawIndirect`/`Parameter` replacement.
|
||
- `GetBufferBindingPoint` / `GetBufferBindingPointCount` / `GetTouchedBufferBindingPointCount →
|
||
SetShaderBuffers` `:43-45`
|
||
- `MGP_COVERAGE_DELTA_LIST` `:128-130`: `handle-ify (wire handle) → kStructuralHandle`,
|
||
**`Buffer ops delta → ResourceRespecify`**. This list is read by `gen_pipe.py` only, never by the
|
||
preprocessor, because the delta kinds are the inventory's free-text labels, not C tokens.
|
||
|
||
`MGP_COVERAGE_STICKY_LIST` `:116-123` — exactly the seven F-class accessors whose value is valid
|
||
across verbs, so the poison's per-verb generation does not apply. The argument is uniform (`:106-115`):
|
||
each takes an argument that is not verb state (a GL name, a lifetime id, a target), so there is no
|
||
value the filler could copy and no verb whose fill could make it stale. **None of the
|
||
version/generation accessors is sticky** — those change under verbs and are precisely what the poison
|
||
must protect. A verify-lane `Fatal{UnmigratedPipeInput}` is fixed by a `FillPoints.def` row, **never**
|
||
by a sticky row, and `gen_pipe.py` refuses a name that is not an accessor above.
|
||
|
||
`MGP_COVERAGE_EMITTED_LIST` `:154-187` — which P2 call now *supplies* a `PipeInputs` field so the
|
||
residual fill loop can skip it; `gen_pipe.py` turns it into `kMGPipeFieldEmittedBy[]` in
|
||
`generated/PipeFilled.inc`. A field with no row here keeps going through the fill loop, **which is
|
||
what makes the `MOBILEGL_PIPE_PUSH` bitmask a true per-subsystem A/B rather than an all-or-nothing
|
||
switch** (`:135-136`). 33 rows, all render-state / patch / attrib-default. The one row whose call
|
||
differs from the accessor list's is `GetPrimitiveRestartIndex` (coverage maps it to `draw_vbo`
|
||
because that is where a backend reads it, but the value travels in dynamic chunk D6, so
|
||
`set_dynamic_state` supplies it) `:141-143`.
|
||
|
||
**`GetPixelStoreParameters` is deliberately absent, `:145-153`** — and this is the semantic-merge
|
||
trap. The field is `PipeInputs::m_pixelStore[2]` (pack **and** unpack) while `set_pixel_pack_state`
|
||
carries the pack half only, permanently (D10). A row here would be a half-truth: with the bitmask
|
||
bit set, the unpack half would be written by nothing while its poison stamp said it was published, so
|
||
neither the poison nor the verify comparator could see it. Until the field is split, the whole of it
|
||
goes through the fill loop and the pack half is written twice.
|
||
|
||
**How the trap actually fired (commit `bb2a236d`, "drop the emitter arm for set_pixel_pack_state that
|
||
spans retired"):** the spans work (`d1a7c5f1`) removed `GetPixelStoreParameters` from the emitted
|
||
list, so the generated `MGPipeFieldEmitter` **no longer had a `SetPixelPackState` enumerator** — but
|
||
the tracker's subsystem map and its `static_assert`, written against the contract, still named it, and
|
||
**the push and verify builds did not compile on the integrated tree.** The fix
|
||
(`PipeFill.cpp:651-657`) drops the emitter arm and keeps a `static_assert` on the *dirty bit* instead:
|
||
`MGPipeSubsystemForDirty(NewPixelPack) == kMGPipeSubsystemPixelPack`, because the bit is what the
|
||
emission gate consults while the field stays in the residual loop by design. **The lesson for P3a:
|
||
`Coverage.def`'s emitted list is generated-enum input, and every semantic merge that touches it must
|
||
be re-checked against `SubsystemForEmitter`'s switch arms and their static_asserts in `PipeFill.cpp`
|
||
and `Tracker.h`. Green on two branches separately is not green on the merge — build push AND verify.**
|
||
|
||
### 2.5 Fields, verbs, mutation surface
|
||
|
||
`MobileGL/MG_Pipe/PipeFields.def` — the G4 comparator's field lists, one macro per payload. Padding
|
||
is deliberately absent because verify must have **zero** false positives and a padding byte is what
|
||
makes a `memcmp` of `RenderStateParameters` falsely differ (`:9-13`). Hand maintained alongside
|
||
`MGPipeTypes.h`, `MGPipeValueTypes.h`, `MGPipeHostSpan.h`, `MG_Backend/BackendObject.h`;
|
||
`gen_pipe.py` asserts **in both modes, hence in `pipe-gates`**, that every list names exactly the
|
||
direct data members of its struct, `Pad<n>` excluded (`:16-19`). Rows relevant to P3a:
|
||
`MGP_FIELDS_MGPResourceDesc` `:44-48` (22 fields), `MGP_FIELDS_MGPVertexElements` `:71-72`,
|
||
`MGP_FIELDS_MGPVertexBuffer` `:96-97`, `MGP_FIELDS_MGPVertexBuffers` `:99-100`,
|
||
`MGP_FIELDS_MGPIndexBuffer` `:102-103`, `MGP_FIELDS_MGPIndirectBuffers` `:105-106`,
|
||
`MGP_FIELDS_MGPBufferRange` `:123-124`, `MGP_FIELDS_MGPShaderBuffers` `:126-127`.
|
||
`MGP_VERIFY_PAYLOAD_LIST` at `:302-319` is the emission order — **`gen_pipe.py` reads this list to
|
||
know what to emit**, so a new payload must be added there too.
|
||
|
||
`MobileGL/MG_Pipe/FillPoints.def` — `MGP_FILL_VERB_LIST(X)` `:73+`, one row per function-pointer
|
||
member of `MG_Backend::GLFunctionsTable` (`BackendObject.h`) **in declaration order**;
|
||
`gen_pipe.py` parses that struct and refuses a row set that is not exactly its member set (`:71-72`).
|
||
Nine verb classes are in use (`kDraw`, `kClear`, `kBlitOrCopy`, `kTextureOp`, `kReadback`,
|
||
`kDispatch`, `kQuery`, `kXfbSpan`, plus the class field masks). Note `:60-64`: retiring a
|
||
class-field-mask row would need the poison omission run across the **full CTS caselist on both
|
||
devices**, not the desktop corpus — and that is explicitly **recorded as P3a work**.
|
||
Formatting constraint: `gen_pipe.py`'s block regexes end at a blank line, so keep the empty line
|
||
after each macro (`:67`).
|
||
|
||
`MobileGL/MG_Pipe/PipeMutation.h` — `MGP_NOTE_MUTATION(Field)` `:79-80` and
|
||
`MGP_NOTE_AGGREGATE(Aggregate)` `:81-82`, both `((void)0)` in a pull build `:84-85`.
|
||
`enum class MGPipeAggregate` `:56-74`: `VaoAttribute` 0 (any VAO attribute format / buffer / enable
|
||
moved), `FramebufferAttachment`, `TextureContent`, `TextureParams`, **`BufferChange`** (any buffer
|
||
object contents moved), `VertexAttribDefault`. Counters are members of the owning `MG_State`
|
||
container, all under `MOBILEGL_PIPE_PUSH so the pull build's state objects do not change size (G1)`
|
||
(`:46-48`); the macro goes through a free function that finds the live `GLContext` because objects
|
||
have no back-pointer to their state (`:48-51`). **Monotonic and never reset** — the tracker widens and
|
||
compares, never subtracts (`:53-55`). Buffer bump sites are already in place:
|
||
`BufferState/BufferObject.cpp:47` (`NotifyRespecify`), `:55` (`NotifySubData`), `:65`
|
||
(`NotifyFlushMappedRange`), each also bumping `m_changeSerial`.
|
||
|
||
`MobileGL/MG_Pipe/DirtySurface.def` — the G9 completeness map. Verdict kinds include `kImmediate`,
|
||
`kExplicitDestroy`, `kUnpublishedDestroy`, `kNoBackendRead` (`:75`); `kExplicitDestroy` means the
|
||
mutation is published by the `delete_*` / `resource_destroy` call the Track H slice adds (`:98`).
|
||
Buffer/VAO rows: `MarkBufferObjectForDeletion → kExplicitDestroy` `:252`,
|
||
`MarkVertexArrayForDeletion → kExplicitDestroy` `:260` (and the other four kinds at `:253-259`).
|
||
`MGP_DIRTY_SURFACE_UNDECIDED_LIST` is **empty** today (`:285`) — a row can be parked there when the
|
||
scanner cannot answer. The TransformFeedbackBinding reasoning at `:239-249` is the worked example of
|
||
how a binding that moves no shutter is argued.
|
||
|
||
`MobileGL/MG_Pipe/MGPipe.h:87-121` shows what a generator run produces and where each `.inc` lands
|
||
inside the namespace: G1 `PipeTables.inc` (`:92`), G2 `PipeThunks.inc` (`:101`), G3 `PipeWire.inc`
|
||
(wire records, size assertions **and the applier's bounds precondition**, `:104`), G4
|
||
`PipeVerify.inc` (`:107`), G5 `PipeFilled.inc` (`:110`), G5b `PipeFillPoints.inc` (`:115`), G6
|
||
`PipeCoverage.inc` (`:118`), G7 `PipeSpanTable.inc` (`:121`). All eight are committed in
|
||
`MobileGL/MG_Pipe/generated/` — deliberately, so **the build never depends on python**.
|
||
|
||
---
|
||
|
||
## 3. The gates as they stand after P2
|
||
|
||
### 3.1 `scripts/check_include_closure.py` — interface purity
|
||
|
||
Four probes, `PROBES` at `:73-138`; each carries a `Why` printed in the summary, and `Allow` entries
|
||
are deliberately awkward — each needs a Reason printed on every run so a whitelist entry has to be
|
||
argued in the PR (`:70-72`). All four have empty `Allow` today.
|
||
|
||
| probe | header | forbidden | text limits |
|
||
|---|---|---|---|
|
||
| `value-header` `:74-88` | `MG_Pipe/MGPipeValueTypes.h` | `MG_State/`, `MG_Impl/`, `MG_Backend/`, `MG_Remote/` | — |
|
||
| `artifacts-header` `:89-108` | `MG_State/GLState/ProgramState/ProgramArtifacts.h` | `ShaderObject.h`, `MG_Util/ShaderTranspiler/`, `Config.h`, `MG_Backend/`, `BufferState/`, prefix `ProgramState/Shader` | `glslang:: ≤ 2` |
|
||
| `mutation-header` `:109-127` | `MG_Pipe/PipeMutation.h` | `MG_Impl/`, `MG_State/GLState/Core.h`, `MG_Remote/` | — |
|
||
| `wire-header` `:128-137` | `MG_Remote/Transport/ITransport.h` | `MobileGL/Includes.h` | — (the gate's own canary) |
|
||
|
||
`REQUIRED_PROBE_NAMES = ("value-header", "artifacts-header")` `:141` — deleting a probe must be red,
|
||
not quietly green. Modes `:35-40`: `text` (transitive walk of literal `#include` lines, no compiler),
|
||
`clang` (`-H -E` on a one-line probe TU, the ground truth), `both` (runs both and additionally fails
|
||
if they disagree about the violations). `--require-all` `:42-45` turns every SKIP (a probe whose
|
||
header does not exist yet) into a failure — the ratchet the integrator flips as headers land.
|
||
CI invocation, `.github/workflows/test.yml` job `include-graph-check` (`:738`, name "Include-closure
|
||
purity gate"): `python3 scripts/check_include_closure.py --mode both --compiler clang++-20
|
||
--self-test --require-all`, after `git submodule update --init include/ska 3rdparty/xxHash
|
||
3rdparty/Vulkan-Headers` and installing `clang-20 libx11-dev`. It does not depend on `build-linux`.
|
||
**`check_include_closure.py` does NOT probe `MG_Backend` headers** — which is exactly why
|
||
`SlotTables.h`'s client/server minting debt (§1.5) is uncaught.
|
||
|
||
### 3.2 `scripts/symbol_report.py --threshold 0` — G1
|
||
|
||
G1 is spelled `added == removed == resized == renamed == 0` and `.text` delta 0 (`:36-40`); the
|
||
canonical invocation is `--threshold 0 --fail-on-symbol-set-change --fail-on-added-bytes 0` (`:40`).
|
||
`--fail-on-symbol-set-change` covers **all four buckets, not just added/removed**: a resize at zero
|
||
net delta is what a same-size rewrite produces (`:42-44`), and it always compares at threshold 0
|
||
whatever `--threshold` says (`:404-410` — `--threshold` is a *report* control, and a gate reading the
|
||
thresholded buckets would quietly weaken itself). `bucket()` `:176-207`; `gate_failures()`
|
||
`:251-269`; a `--self-test` (`:294-332`) pins the buckets and the three shapes that used to walk
|
||
through (a shrunk `.text` under a zero budget, a resize at zero net delta, …).
|
||
|
||
The **four admitted resizes** are the integrator's, not the script's — `wsl_p2_gate.sh:24`:
|
||
`RenderState::RenderState`, `RenderState::SetCapability`, `RenderState::IsCapabilityEnabled`,
|
||
`_GLOBAL__sub_I_DirectGLES.cpp`. The gate script runs
|
||
`symbol_report.py --before ~/w7/p2-before-libMobileGL.so --after build-linux/libMobileGL.so
|
||
--threshold 0 --markdown ~/w7/p2g-symbols.md` (`:25`) and then prints the Resized table (`:26`) for
|
||
the operator to compare against that list by eye. The CI counterpart is the `monolith-symbol-report`
|
||
job (`test.yml:1359`), **`workflow_dispatch` only**, which builds the baseline in a worktree at
|
||
`inputs.baseline_sha`, default `"087685d1"` (`test.yml:14-21` — "P1's G1 says the pull build is
|
||
byte-identical to `feat/disaggregated@087685d1`").
|
||
|
||
The gate script also pins the pull build's `SyncRenderState` body by sha256 of the
|
||
`namespace RenderStateImpl` block in `DirectGLES.cpp` against `~/w7/p2-before-syncrenderstate.sha`
|
||
(`wsl_p2_gate.sh:27-28`), and asserts `grep -rc pGLContext MobileGL/MG_Backend` is empty (`:23`).
|
||
|
||
### 3.3 The generator gates — CI job `pipe-gates` (`test.yml:1538-1617`)
|
||
|
||
`name: MGPipe generators and hygiene gates`, `runs-on: ubuntu-latest`, **deliberately independent of
|
||
`build-linux`** — source-level, seconds, and a broken build must not hide a drifted interface
|
||
(`:1541-1542`). Steps:
|
||
|
||
1. `Regenerate the MGPipe interface (G1-G7)` `:1553-1556`: `python3 scripts/gen_pipe.py` then
|
||
`git diff --exit-code -- MobileGL/MG_Pipe/generated`.
|
||
2. `The MGPipe generators' checks can still fail` `:1562-1563`: `gen_pipe.py --self-test`. Rationale
|
||
`:1558-1561`: regenerate-and-diff cannot see a check that silently stopped checking — a broken
|
||
gate and a clean tree produce the same green. The controls are at `gen_pipe.py:1207-1246` — seven
|
||
of them, each must trip, and **zero trips is itself an error** (`:1241-1242`), plus a mismatch
|
||
count check `:1243-1244` and a positive control `:1240`. They cover: a struct member with no
|
||
`F(...)`, an `F(...)` that is not a member, a payload with no struct, a verb missing from
|
||
`FillPoints.def`, a verb that is not a `GLFunctionsTable` member, a field row naming a
|
||
non-accessor, and **an emitted row naming a call that does not exist in `PipeCalls.def`**
|
||
(`:1230-1234`) — the enum-generation guard the `bb2a236d` merge trap sits next to.
|
||
The two structural checks it drives are `check_field_lists_cover_struct_members` `:416-421` and
|
||
`check_call_payloads_have_field_lists` `:479-481`, **both of which run in `--check` mode too**.
|
||
`parse_coverage` refuses an emitted field that is not an accessor `:522-523` or listed twice
|
||
`:525`; `gen_emitted_by` `:809-845` refuses an emitted row whose call is not real `:817-819`.
|
||
3. `The symbol report's buckets and gates can still fail` `:1566-1567`:
|
||
`symbol_report.py --self-test`.
|
||
4. `No stdio instrumentation in MG_Backend or MG_State` `:1576-1583`: greps for
|
||
`fprintf(stderr|stdout)`, bare `printf(`, `puts(`, `std::cout|cerr`. **Zero exceptions today**, and
|
||
any addition needs a PR reason rather than a quiet whitelist entry (`:1569-1575`) — per-draw
|
||
instrumentation has been committed by accident before, once inside a mutex critical section.
|
||
5. `MGPipe dirty-surface mapping is complete (G9)` `:1601-1604`:
|
||
`gen_pipe_dirty_surface.py --check` then `--self-test`. `--check` **fails both directions**
|
||
(`:1586-1588`): a mutator the scanner finds with no row in the def, *and* a row naming a mutator
|
||
the scan no longer finds — so a deleted mutator cannot leave a stale row claiming coverage. The
|
||
self-test is not optional (`:1590-1594`): two canned negative controls (a mutator withheld, a row
|
||
naming a function that does not exist). What it does **not** cover, stated in `DirtySurface.def`'s
|
||
header rather than left implicit (`:1596-1600`): a mutation inside a lambda is attributed to the
|
||
enclosing function, a mutation published through a helper reads as deferred, and it scans only
|
||
`MG_Impl/GLImpl`, so the four `MGP_NOTE_MUTATION` sites in `MG_State` are outside it entirely. It
|
||
is a completeness gate over what the scanner can see; **the semantic proof is the verify lane.**
|
||
6. `Documentation citation lint` `:1609-1617`: `check_doc_citations.py docs/Disaggregated/*.md`,
|
||
**warning only** (`|| true`) until the documents settle.
|
||
|
||
Also independent of `build-linux`: `flatc-check` (`test.yml:710`) regenerates
|
||
`MG_Remote/Protocol/generated/protocol_generated.h` and `git diff --exit-code`s it.
|
||
|
||
### 3.4 The verify lane and the retraces
|
||
|
||
Compile-time: `MOBILEGL_PIPE_VERIFY` is an *option*, and `PipeInputs.h` derives `MOBILEGL_PIPE_POISON`
|
||
from it (`test.yml:313-314`, `:375-381`). Job `build-linux-verify` (`:315`) configures with
|
||
`-DMOBILEGL_PIPE_VERIFY=ON` (`:396`) and then has a hard artifact check,
|
||
**"The verify library really carries the comparator"** `:415-424`: if `libMobileGL.so` defines no
|
||
`MGPipeVerifyInputs` it errors with "…every lane that consumes this artifact would run the
|
||
comparator-free library and pass having compared nothing". It publishes
|
||
`mobilegl-linux-runtime-verify`.
|
||
|
||
Job `integration-verify` (`:484`) unpacks that runtime and runs:
|
||
- `ctest -L integration-verify` (`:524-549`) — 818 entries per the P2 brief.
|
||
- `Unit tests on the verify runtime (G6, G10)` `:568-570` — `ctest -L unit`, because
|
||
`MGPipeRenderStateSpans.cpp` / `PipeApply.cpp` are appended to `SOURCE_FILES` only inside the
|
||
`if (MOBILEGL_PIPE_PUSH)` block, and the push-only tests `GTEST_SKIP()` elsewhere (`:555-559`).
|
||
- `The handle-ABA and CSO-content-addressing controls (G8, G12)` `:589-600` —
|
||
`ctest -L integration-gpu -R 'HandleRecycle|CsoContentAddressing'`. This is the **only** CI job
|
||
that unpacks a `MOBILEGL_PIPE_PUSH` build (`:572-577`).
|
||
- `The verify lanes armed the comparator` `:615+` — catches what ctest cannot: an arming entry that
|
||
*skipped* still reports green (`:612-614`).
|
||
- **Negative control A** `:641-656`: `MOBILEGL_PIPE_VERIFY_CORRUPT: GetRenderRateParameters`
|
||
(`GetRenderStateParameters`) — the step passes when **ctest FAILS** (`if ctest …; then error`),
|
||
the only shape that can catch a comparator that stopped comparing (`:633-637`). It counts matched
|
||
tests first `:651` because an empty selection would also exit non-zero under `--no-tests=error`.
|
||
The knob reaches the process through the **job** environment, not a ctest `ENVIRONMENT` property
|
||
(`:637-640`) — the property-overrides-job-env trap.
|
||
- **Negative control B** `:670`: an omitted fill point must turn the lane red on that verb
|
||
(`MOBILEGL_PIPE_POISON_OMIT`, `PipeFill.h:46-52`).
|
||
|
||
Retrace: `trace-cases` (`:961`) emits three matrices from `tools/trace_replay/trace_cases.json` —
|
||
**40 cases total, 39 CI-enabled, 77 full matrix entries, 8 verify cases → 16 verify matrix entries**
|
||
(computed by running `trace_cases.py` against the tree). `verify: true` is validated where the
|
||
manifest is parsed rather than where the matrix is built, so a typo is a loud manifest error in every
|
||
consumer (`trace_cases.py:29-37`), and a case marked `verify` but excluded from CI raises (`:35-37`).
|
||
Job `retrace-verify` (`:1202`) runs that 16-entry matrix, `max-parallel: 4`, `timeout-minutes: 240`,
|
||
needing `build-linux-verify` + `build-retrace` + `trace-cases` + `trace-fixtures`; it unpacks the
|
||
verify runtime over `build-retrace`'s frozen absolute library path (`:1259-1261`).
|
||
|
||
**The 79-case sweep is the integrator's local one, not CI's.** `~/w7/notes/p2/BRIEF-P2.md:37` (G3)
|
||
defines it: "79 desktop cases: 40 × 2 minus `iterationrp × DirectGLES`", driven by
|
||
`~/w7/retrace_gate.py` — a standalone script that parses the reference `build-retrace`
|
||
`CTestTestfile.cmake` for case parameters and per-test `ENVIRONMENT`, rewrites library/fixture/output
|
||
paths onto the tree under test, applies the CI per-case env, and runs `cmake -P run_trace_case.cmake`
|
||
with bounded parallelism, writing JSON + text summaries; exit 0 only when every selected case passes.
|
||
`wsl_p2_gate.sh:52-59` runs it twice (verify then push) and reports "verify armed: N of M" by
|
||
grepping for `MGPipe verify:` and lists every log carrying `Fatal{`.
|
||
|
||
Trigger note: `test.yml:4-12` — `push` on `dev`, `Feat/Backend-Direct-GLES`,
|
||
`Feat/Backend-Direct-Vulkan` and **`feat/disaggregated`**, the last marked
|
||
"TEMPORARY, remove before merging the MGPipe work into dev … so a phase's landing is not gated on
|
||
someone remembering to dispatch the workflow by hand", plus `workflow_dispatch`.
|
||
|
||
### 3.5 The HandleRecycle lanes and the G7 negative control
|
||
|
||
`MG_IntegrationTest/Scenarios/HandleRecycleScenario.cpp` (`MG_IntegrationTest/CMakeLists.txt:132`) is
|
||
registered **four times** — `DirectGLES.HandleRecycle.Handles.` `:877-878`,
|
||
`DirectVulkan.HandleRecycle.Handles.` `:886-887`, `DirectGLES.HandleRecycle.Legacy.` `:895-896`,
|
||
`DirectVulkan.HandleRecycle.Legacy.` `:904-905` — all filtering `HandleRecycleScenario.*`. The
|
||
`Handles` arm needs a backend keyed on `{slot, gen}` (packages C and D, `:326`); the CMake emits
|
||
explicit warnings when a configuration will make an arm SKIP (`:418`, `:445`, `:456`, `:459`) and
|
||
re-checks a marker before either arm asserts so a hand-forced configuration cannot pass silently
|
||
(`:376`). `:814` records that the scenario is meaningful in a pull build too (lifetimeId + weak_ptr
|
||
guards), so `ctest -R HandleRecycle` selects sensibly in both.
|
||
|
||
The arm selection is `ClassifyEsprytSlotArm(subsystemBitSet, legacyMemosEnabled)`
|
||
(`Managers.cpp:226-237`): with `MOBILEGL_PIPE_LEGACY_MEMOS`, bit 5 set → `Handles`, else
|
||
`PipeLegacyMemos` → `Legacy` else `NoArm`; without it, `Handles` is the only arm.
|
||
`ResolveEsprytSlotTablesArm()` `:255-292` resolves **at the first twin lookup, not at bring-up** —
|
||
deliberately, and it is the fix for a lane that went green by skipping: bring-up runs inside
|
||
`eglMakeCurrent`, which the harness pre-flights in a forked child, and a child that aborts is
|
||
reported as "no usable GPU" and skips every scenario (`:261-267`). `NoArm` is
|
||
`Fatal{PipeLegacyMemosDisabled, …}` + `std::abort()` `:278-282`, because returning instead would run
|
||
the very arm the operator disabled and hand back a green measured on it — "which is exactly the lever
|
||
`HandleRecycleScenario`'s arms are selected with" (`:269-277`). The recent fix `55d2af9b` makes the
|
||
ABA control construct its own collision and defeat the `{slot, gen}` generation.
|
||
|
||
**G7 negative control — `scripts/g7_negative_control.sh`.** Not a CI lane; it rebuilds the library
|
||
twice and is run by hand and by the integrator at the five-part gate (`:31-32`). It breaks the
|
||
pipeline/dynamic split on purpose — moves `ColorMasks` out of pipeline chunk P1 into a dynamic chunk
|
||
by inserting boundaries at `ColorMasks` and `FramebufferSrgbEnabled` (`:19-25`) — deliberately a break
|
||
the compiler **cannot** catch, since the chunks still ascend, do not overlap and cover
|
||
`[0, sizeof(RenderStateParameters))`, so every structural `static_assert` still holds. What breaks is
|
||
meaning: `glColorMask` bumps `m_pipelineStateVersion` but no longer moves the pipeline-subset hash,
|
||
and `RenderStateSpansTest`'s SetterConsistency has to **name `SetColorMask`**. The four measurement
|
||
pins (7/8 chunks, 396/772 bytes) are relaxed by the same patch, because leaving them would turn the
|
||
control into a build break — proving the assertions compile rather than that the test still checks
|
||
(`:27-29`). Exit codes `:44-51`: **0** = tripped *and* named `SetColorMask` (or, under
|
||
`--verify-patch-only`, the patch compiled); **1** = did not answer — either it stayed green on a
|
||
demoted member, or it went red without naming `SetColorMask` so the red cannot be attributed
|
||
(both are findings about the test, and both leave the tree restored and rebuilt); **2** = could not
|
||
run the control at all. Usage: `g7_negative_control.sh <build-dir> [--verify-patch-only]`, and
|
||
`<build-dir>` must carry the push-only unit tests since `MGPipeRenderStateSpans.cpp` compiles only
|
||
under `MOBILEGL_PIPE_PUSH` (`:37-39`).
|
||
|
||
### 3.6 `wsl_p2_gate.sh` — the integrator's gate script
|
||
|
||
`//wsl.localhost/Arch/home/swung/w7/notes/tools/wsl_p2_gate.sh`, 61 lines, run in `~/w7/pipe`.
|
||
Usage `wsl_p2_gate.sh [quick]` — `quick` skips the two 79-case retrace sweeps (`:3`).
|
||
|
||
**The fail-fast rule, `:4` and `:19`:** three builds are made first — `build-linux` (pull),
|
||
`build-push` (`-DMOBILEGL_PIPE_PUSH=ON`), `build-verify` (`-DMOBILEGL_PIPE_VERIFY=ON
|
||
-DMOBILEGL_ITEST_REQUIRE_GPU=ON`) — and **if any returns non-zero the script prints
|
||
`BUILD FAILED - gate aborted (no stale-binary verdicts)`, echoes `P2_GATE_DONE` and exits 1.**
|
||
"Results from a stale binary must never look like a verdict." It also prints the first two `error:`
|
||
lines of each build log (`:18`). Common flags `:10`: Ninja + clang/clang++ + ccache, `Release`,
|
||
`MOBILEGL_LOG_ACTIVE_LEVEL=INFO`, tests and integration tests ON, **`BENCHMARK=OFF`**, mesa EGL
|
||
vendor json and lvp Vulkan ICD, `CMAKE_POLICY_VERSION_MINIMUM=3.5`.
|
||
`export CCACHE_BASEDIR=/home/swung/w7` `:6`.
|
||
|
||
Parts:
|
||
- **Part 1, interface purity** `:21-29`: `check_include_closure.py`; `pGLContext` must not appear
|
||
anywhere under `MG_Backend`; the G1 symbol report with the four admitted resizes named in the echo
|
||
(`:24`); the `SyncRenderState` sha comparison; `HandleRecycle` under `build-verify`.
|
||
- **Part 5, coverage/poison/handle discipline** `:31-34`: `gen_pipe.py --check` and `--self-test`;
|
||
`gen_pipe_dirty_surface.py --check` and `--self-test`; `ctest -R 'RenderStateSpans\.|Residual'` in
|
||
`build-push`.
|
||
- **Part 3, behavioural A/B** `:36-48`: G2 — a `ctest -N` **name diff between pull and push must be
|
||
zero lines** (`:39`); G14 — names removed/added versus `~/w7/p2-before-ctest-names.txt` (`:40`);
|
||
`ctest -L unit` in all three builds; `ctest -L integration-gpu` in pull and push with a
|
||
`--rerun-failed` pass; **`MOBILEGL_PIPE_PUSH=0` on the push build** (`:44`); the
|
||
render-state-sensitive subset `ClipDistance|SampleMaskScope|SampleVariables|DualSourceBlend|
|
||
ViewportArray|PrimitiveRestart` (`:45`); `g7_negative_control.sh build-push` (`:46`);
|
||
`CsoContentAddressing` (`:47`); the controls `PoisonOmitted\.|VerifyCorrupted\.|HandleRecycle`
|
||
under `build-verify` (`:48`).
|
||
- **Part 2, semantic shadow comparison** `:50-60`: `ctest -L integration-verify` counting `Fatal{`
|
||
lines and the top five `Fatal{Kind, "detail"}` by frequency; then, unless `quick`, the two
|
||
`retrace_gate.py` sweeps described in §3.4, with `MOBILEGL_PIPE_VERIFY=1` on the verify one, and
|
||
the two summaries copied out before the output trees are deleted.
|
||
- Terminator: `echo P2_GATE_DONE` `:61`.
|
||
|
||
Sibling scripts in the same directory: `wsl_p2_bench.sh`, `wsl_p2_tree.sh`, `wsl_integrate_p2.sh`,
|
||
`p2_ab.sh`.
|
||
|
||
---
|
||
|
||
## 4. Measurement infrastructure P3a inherits — for RECORDING, not gating
|
||
|
||
### 4.1 `tools/trace_replay/run_android_retrace_local.py --benchmark`
|
||
|
||
`--benchmark` (`:383-387`) replays each case end to end as a frame-timing benchmark instead of
|
||
comparing images. Companions: `--benchmark-repeats` `:389`, `--benchmark-tail-frames` `:395`,
|
||
`--benchmark-no-finish` `:401`, `--benchmark-timeout-seconds` `:407-410` ("a benchmark replays the
|
||
whole trace, not just up to `target_call`"). `run_benchmark_case` `:312-361` passes `--benchmark`,
|
||
`--benchmark-tail-frames`, `--benchmark-finish 0|1`, deletes the stale `benchmark.json` first `:332`,
|
||
files each run as `benchmark-run<N>.json` (`read_benchmark` `:214-225`) and prints per-run plus
|
||
best-of lines `:344-361`.
|
||
|
||
`benchmark.json` carries the **whole `frameCpuTimesMs[]` array** on purpose (`cpu_tail` `:265-281`):
|
||
the device computes no p99, so p99 is a **host-side reduction over an artefact that already exists**.
|
||
The window is the same trailing `tailFrames` the device summarised, so the host numbers sit beside
|
||
the device's own rather than describing a different set of frames. `nearest_rank_percentile`
|
||
`:247-262` uses nearest rank, not an interpolating percentile, "so that every number printed here is a
|
||
frame that was actually observed" and so a host p95 agrees **exactly** with the device's for the same
|
||
window; `series_median` `:240-244` recomputes p50 by the device's own median rule so it agrees with
|
||
`medianFrameCpuMs` on the same run rather than merely sitting next to it (commit `af20dba6`).
|
||
`format_benchmark` `:284-302` prints `frames / total / tail / mean / median / p95 / fps` and then the
|
||
CPU half on the same line — **"it is what the disaggregation A/B is actually read on"**, because wall
|
||
time under `--benchmark-no-finish` still contains everything the retrace thread waited for
|
||
(`:294-296`). Per-frame thread CPU time was added by commit `e9499d38`
|
||
("record per-frame thread CPU time beside wall time so a paired A/B can be read as CPU cost").
|
||
|
||
### 4.2 `//wsl.localhost/Arch/home/swung/w7/notes/tools/p2_ab.sh` — the paired A/B driver
|
||
|
||
`p2_ab.sh <serial> [case ...]`, run from **Windows Git Bash** with `adb.exe` on PATH (`:6`).
|
||
Design (`:2`): `{pull, push} APK × {no-finish, finish} × cases × backends`, reboot-clean once, pinned
|
||
for the whole session with the pin **verified and retried**, one device-lock hold per run. Outputs go
|
||
to a Windows-local scratchpad dir because **Git Bash cannot create directories on `//wsl.localhost`**
|
||
(`:3-5`, and I hit exactly that: `mkdir //wsl.localhost/... → Read-only file system`, though the
|
||
`Write` tool and shell redirection into an existing directory both work); `copy_ab.sh` moves them into
|
||
`~/w7/notes/p2/ab/<serial>/`. **Do not export `MSYS_NO_PATHCONV`/`MSYS2_ARG_CONV_EXCL` globally here**
|
||
(`:7-8`): the runner passes `/c/...` paths to Windows python and relies on MSYS converting them.
|
||
|
||
Defaults `:10-16`: runner tree `…/MobileGL-disagg` ("must be at the integrated commit"), APKs read
|
||
over UNC from `~/w7/notes/p2/apk/trace-{pull,push}.apk`, pin helper from
|
||
`~/w7/notes/p2/devices/pin_device.sh`, package `top.mobilegl.plugin.trace`, four default cases:
|
||
`minecraft-1.21.4-in-world`, `minecraft-1.21.4-fabric-iris-bsl-in-world`,
|
||
`improved-transparency-minecraft-26.3`, `minecraft-1.21.4-startup`.
|
||
Session start `:24-35`: reboot, wait for device, poll `sys.boot_completed`, poll for root (24 × 5 s),
|
||
sleep 20, wake + unlock keyevent, uninstall the package, then **pin up to 3 times with a
|
||
`check` after each and exit 43 if none verified**. Device lock is a `mkdir` mutex with a 900 s timeout
|
||
and an owner file, exit 42 on timeout `:20-21`; `trap … EXIT` unlocks and unpins `:22`.
|
||
Per-run `:39-52`: `pin check` before and after, install the arm, `--benchmark-no-finish` for the
|
||
`nofinish` mode, then
|
||
`ANDROID_SERIAL=$SER python tools/trace_replay/run_android_retrace_local.py --case … --backend …
|
||
--benchmark $extra --benchmark-repeats 3 --benchmark-tail-frames 200 --env MOBILEGL_PIPE_STATS=1
|
||
--env MOBILEGL_PIPE_STATS_PERIOD=120`, copies `benchmark*.json` / `mobilegl.log` / `result.json` out
|
||
of `.trace-work/android-retrace-result/*-<backend>/`, and prints a one-line summary carrying
|
||
`rc`, `pin=<before>/<after>`, elapsed seconds, the `cpu mean=… p99=…` extract, and the count of
|
||
`MGPipe stats: frames` windows in the device log. Terminator `AB_DONE <serial>`.
|
||
`7a2e2561` is the commit that lets the trace APK be built in the push shape for this A/B.
|
||
|
||
### 4.3 `MobileGL/MG_Benchmark/Driver/run_driver_bench.sh` — DriverBench
|
||
|
||
`./run_driver_bench.sh native|espryt|magma [<libMobileGL.so>] [bench args…]` (`:2-5`). The bench
|
||
**dlopens exactly one EGL provider** through `DRIVERBENCH_EGL_LIB` — the system `libEGL.so.1` for
|
||
native, or the given `libMobileGL.so` for a backend — with **no `LD_LIBRARY_PATH` shadowing**, so
|
||
MobileGL's own loader still finds the real driver underneath (`:6-9`). Vendor libraries are pinned
|
||
explicitly (`:11-15`): a bare `libEGL.so.1` on a glvnd system picks whatever
|
||
`eglGetDisplay(EGL_DEFAULT_DISPLAY)` resolves first, which is Mesa/llvmpipe — "a software rasteriser
|
||
silently replacing the GPU under a benchmark"; override `MGL_EGL_VENDOR` / `MGL_VK_ICD` to test
|
||
another driver (defaults are the NVIDIA json/ICD, `:19-20`). `espryt` sets
|
||
`MOBILEGL_BACKEND_TYPE=DirectGLES`; `magma` sets `DirectVulkan` plus `VK_ICD_FILENAMES` (`:30-38`).
|
||
Binary override: `DRIVERBENCH_BIN` (`:18`). Sources: `Driver/DriverBench.c`,
|
||
`Driver/DriverBenchCases.inc`, and the on-device entry `MG_Util/SelfTest/DriverBenchJni.cpp`.
|
||
`Tracker.h:35-38` names DriverBench as the **only** source of absolute ns/draw, because it times whole
|
||
frames from outside the library and the tree forbids committing hot-path timers. Note that
|
||
`wsl_p2_gate.sh` configures with `-DMOBILEGL_BUILD_BENCHMARK=OFF`, so the gate build does not carry it.
|
||
|
||
### 4.4 `tools/device_bench/pin_device.sh` — the pin helper
|
||
|
||
`pin_device.sh <serial> pin|unpin|check` (`:2`). It exists because `bench.sh`'s
|
||
`pin_freqs()`/`unpin_freqs()` are MediaTek-legacy-only (`/proc/ppm` + `/proc/gpufreq`) and **neither
|
||
campaign device has those paths — on both of them `bench.sh`'s pin writes into nothing and exits 0**,
|
||
the silent "the run looks pinned but is not" failure the `PROFILE_VERIFIED` guard was built to catch
|
||
(`:4-9`). The prescribed sequence (`:12-15`): `pin`, then `bench.sh … --no-pin`, then `check ||
|
||
"PIN DRIFTED - discard this run"`, then `unpin`. All three actions print live big/little/GPU
|
||
frequencies, governors and the gate temperature, so the output of `pin` and `unpin` is itself the
|
||
before/after evidence (`:17-18`).
|
||
|
||
**`check` is deliberately three-valued** (`:20-30`), because "no pin at all" and "a pin that slipped"
|
||
are different facts: **0 PINNED** (every pinned node at its pin and every live frequency equal to it),
|
||
**1 DRIFT** (partly pinned, or a live frequency left its pin — *the dangerous state: a run overlapping
|
||
this is not comparable, discard it*), **2 UNPINNED** (no node at a pin this script set — the correct
|
||
state to leave a device in, and still non-zero so `pin_device.sh X check && measure` cannot silently
|
||
measure unpinned). UNPINNED is asserted against **our** pins, not the stock range, because ColorOS
|
||
moves `policy4`'s max on its own within seconds of a release and an exact-stock comparison reported
|
||
DRIFT on a correctly unpinned device (`:28-30`). Stock values are hardcoded from a 2026-09-07 reading
|
||
rather than sampled at pin time, because a restore reading "stock" off an already-pinned device would
|
||
make the pin permanent (`:32-36`). Git Bash hygiene: `export MSYS_NO_PATHCONV=1
|
||
MSYS2_ARG_CONV_EXCL='*'` so MSYS does not rewrite `/sys/...` and `/proc/...` arguments (`:39-40`).
|
||
Landed by `2d690754`; `13d7e32b` restored the executable bit on it and `profile.sh`.
|
||
Siblings in `tools/device_bench/`: `bench.sh`, `profile.sh`, `session.sh`, `devices/`, `README.md`.
|
||
|
||
**None of §4 gates anything.** The A/B numbers are recorded evidence; the only performance-shaped
|
||
acceptance criterion `ROADMAP.md:19` states for P3a is "MC 26.3 在 Adreno 上 p99 不变" — p99 unchanged,
|
||
read off `frameCpuTimesMs` through the host-side reduction in §4.1.
|
||
|
||
---
|
||
|
||
## 5. Short checklist for a P3a implementer
|
||
|
||
1. Flags/opcodes: edit `PipeCalls.def` in place for `kNeedsAck` (first use in the tree); **never**
|
||
reorder. Regenerate and commit `MG_Pipe/generated/*.inc`.
|
||
2. Payloads: add the `baseInstance` field to `MGPVertexBuffer` → update its `MGP_ASSERT_POD` size,
|
||
its `MGP_FIELDS_*` list, and (for a *new* payload) `MGP_VERIFY_PAYLOAD_LIST`.
|
||
3. Buffer sub-data: encode only through `MGPipeSetSubDataBufferRange` and **handle its `false`
|
||
return by splitting**; the tighter real bound is the ring's half capacity, not 2^32.
|
||
4. Tracker: give bits 5 / 9 / 10 exact shutters, allocate subsystem bits **7 and up** in ROADMAP
|
||
order, and wire `MGPipeSubsystemForDirty` + `SubsystemForEmitter` + the pairing `static_assert`
|
||
+ `kMGPipeWiredSubsystems` in the same commit. Reconcile bits 9/10's "P3b" comments with
|
||
`ROADMAP.md:19`.
|
||
5. Suppressor: `MGPipeSuppressorSlot::SetVertexBuffers` already exists — use it; hash 0 is reserved.
|
||
6. Death: decide `BufferBackendOps::OnDestroy` vs. a seventh `NotifyStateObjectDestroyed` raiser, and
|
||
respect the holder-list "resolve once, free the slot last" discipline.
|
||
7. Applier: add the new apply entry points and their per-context stores beside
|
||
`MGPipeApplierState`; anything the applier writes into the working block must either enter the
|
||
ledger or have a stated reason not to (the `set_patch_state` tautology precedent).
|
||
8. Residual: `MGL_RESIDUAL_BLOCK_SIZE` is **8** (`MGPipeTypes.h:546`), one `Uint64 CapabilityBits`
|
||
(`:521-533`). It only ever goes **down**; shrinking the block without lowering the number, or
|
||
growing it at all, is a build break (`:535-539`). **P3a must not add anything to
|
||
`ResidualValueBlock`** — buffer, VAO, vertex-buffer and index-buffer state gets a real call, and if
|
||
any of it is not ready it stays in the per-verb residual *fill loop* (`kMGPipeFieldEmittedBy` /
|
||
`CopyField`), which is a different mechanism from this block.
|
||
9. Gates before pushing: `gen_pipe.py --check --self-test`, `gen_pipe_dirty_surface.py --check
|
||
--self-test`, `check_include_closure.py --mode both --self-test --require-all`,
|
||
`symbol_report.py --self-test`, and the full `wsl_p2_gate.sh` (build push **and** verify — that is
|
||
where the `bb2a236d` merge trap surfaced).
|