mirror of
https://github.com/MobileGL-Dev/MobileGL
synced 2026-11-17 15:03:25 +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.
281 lines
45 KiB
Markdown
281 lines
45 KiB
Markdown
# Scout: the strangler scaffold that exists (P0/P0.5) and what P1 must add
|
||
|
||
Worktree: `C:/Users/geekerwan/AndroidStudioProjects/FoldCraftLauncher/MobileGL-disagg`, branch `feat/disaggregated` @ `5635e33f` ("[Docs] (Disaggregated): record the P0.5 landing"). Working tree clean except untracked `.trace-work/`.
|
||
|
||
Every claim below cites a file and a line I opened. Paths are repo-relative to the worktree root.
|
||
|
||
---
|
||
|
||
## 0. One-paragraph orientation
|
||
|
||
`MG_Pipe` is a leaf: it is a set of headers plus a `generated/` directory of seven `.inc` files, and **nothing in the shipped library compiles any of it today**. `grep` for `MG_Pipe/` outside `MobileGL/MG_Pipe/` returns exactly five hits: four `MG_State` headers include `<MG_Pipe/MGPipeValueTypes.h>` (`MG_State/GLState/FramebufferState/FramebufferObject.h:14`, `MG_State/GLState/RenderState/RenderState.h:11`, `MG_State/GLState/SamplerState/SamplerObject.h:11`, `MG_State/GLState/VertexArrayState/VertexArrayObject.h:13`) and one test includes `<MG_Pipe/MGPipe.h>` (`MG_Test/Pipe/PipeCatalogueTest.cpp:18`). `MobileGL/MG_Pipe` appears in `CMakeLists.txt` only as an include directory (`CMakeLists.txt:535`), never in `SOURCE_FILES` (which starts at `CMakeLists.txt:234` and is an explicit list, not a glob). **P1 is therefore the first change that makes the generated headers part of the library build**, and the first that gives `MG_Pipe`/`MG_Backend/MGPipe` a `.cpp`.
|
||
|
||
---
|
||
|
||
## 1. `scripts/gen_pipe.py` — the seven generators, read end to end (676 lines)
|
||
|
||
### 1.1 Inputs, outputs and paths
|
||
|
||
| what | where set |
|
||
|---|---|
|
||
| `REPO_ROOT` = parent of `scripts/` | `scripts/gen_pipe.py:37` |
|
||
| `PIPE_DIR` = `MobileGL/MG_Pipe` | `:38` |
|
||
| `GENERATED_DIR` = `MobileGL/MG_Pipe/generated` | `:39` (created if missing, `:641-642`) |
|
||
| `INVENTORY` = `scripts/data/backend_read_inventory.md` | `:40`; missing → `sys.exit` telling you to copy it from MobileGL-CS (`:219-220`) |
|
||
|
||
Sources of truth read: `PipeCalls.def`, `PipeFields.def`, `Coverage.def` (all under `MobileGL/MG_Pipe/`), plus the vendored inventory markdown. Docstring at `:9-30`.
|
||
|
||
Banner emitted at the top of every output: `:42-55`. It hard-codes the sentence **"This file is included from MG_Pipe/MGPipe.h inside namespace MobileGL::MG_Pipe."** — any new generated file P1 adds inherits that claim, so it must in fact be included from inside that namespace or the banner text has to be parameterised.
|
||
|
||
### 1.2 Parsers and the validation they perform in BOTH modes
|
||
|
||
- `parse_calls()` `:131-160`. Finds `#define MGP_CALL_LIST_DOCUMENTED_COUNT (\d+)` (`:133-135`), then scans from the line `#define MGP_CALL_LIST(X)` and stops at **the first line that does not end in a backslash** (`:149-150`). Row regex `CALL_RE` at `:128` = `X(Name, Payload, Class, Flags)` with `Flags` allowed to contain `|`. Index is 1-based position = wire opcode (`:146`). Exits if the parsed count ≠ the documented count (`:151-154`) or on a duplicate call name (`:155-159`).
|
||
- `parse_verify_payloads()` `:175-184`. Regex `#define MGP_VERIFY_PAYLOAD_LIST\(P\)(.*?)\n\n` — **terminated by a blank line**, so the list macro in `PipeFields.def` must be followed by an empty line. Exits if a listed payload has no `#define MGP_FIELDS_<name>(F)` (`:181-183`).
|
||
- `check_call_payloads_have_field_lists()` `:187-195`. Every payload named in `PipeCalls.def` must either have a field list or be in `MEMCMP_FALLBACK_TYPES` (`:167-172` = `RenderStateParameters`, `PixelStoreParameters`, `DynamicBackendParameters`, `MGHostSpan`). The comment at `:165-166` says explicitly: **"They … get field lists of their own in P1"**.
|
||
- `parse_coverage()` `:198-212`. Two macros, both blank-line-terminated: `MGP_COVERAGE_ACCESSOR_LIST(X)` → `X(Accessor, Call)` pairs (`:201-205`) and `MGP_COVERAGE_DELTA_LIST(X)` → `X(free text delta kind, Call)` (`:207-211`).
|
||
- `parse_inventory()` `:218-237`. Reads `### \`<file>\`` headings and table rows `| line | kind | member | delta |` (`INVENTORY_ROW_RE` at `:215`).
|
||
|
||
### 1.3 What each generator emits
|
||
|
||
| gen | function | output | content |
|
||
|---|---|---|---|
|
||
| G1 | `gen_tables` `:244-270` | `PipeTables.inc` (108 lines) | `struct MGPipeScreen` / `struct MGPipeContext` of function pointers, split by `Class == kScreen`; `kMGPipeScreenCallCount=11`, `kMGPipeContextCallCount=60`, `kMGPipeCallCount=71`; four `static_assert`s including "table size == count × sizeof(fnptr)" and "count == `MGP_CALL_LIST_DOCUMENTED_COUNT`". Signatures come from `Call.Signature` (`:113-125`): `const <Payload>* payload`, plus `const void* varTail, Uint32 varTailCount` if `kVarTail`, plus `MGPReplySlot* reply` if `kReplySlot`. |
|
||
| G2 | `gen_thunks` `:273-286` | `PipeThunks.inc` (302 lines) | one `inline void MGP_<Name>(...)` per call forwarding to `gMGPipeScreen.<Name>` / `gMGPipeContext.<Name>`. Example `PipeThunks.inc:20-22`. |
|
||
| G3 | `gen_wire` `:289-371` | `PipeWire.inc` (931 lines) | `MGPWireRecHeader` (8 bytes), `enum class MGPWireOp : Uint16` with `kInvalid=0` … `kOpCount=72`, one `struct alignas(8) MGPWireRec_<Name>` per call with a composition size assertion, `MGPipeWireProtocolFatal`, the `MGP_WIRE_CHECK_BOUNDS` macro and `MGPipeApplyWireRecord()` — a skeleton switch where **every arm validates bounds then `return false`** (`:350-357` comment). Oversize-record rule (chunking at `RingProducer::MaxRecordBytes() == Capacity()/2`) documented at `:305-311`. |
|
||
| G4 | `gen_verify` `:374-444` | `PipeVerify.inc` (573 lines) | `#include "../PipeFields.def"` (`:387`), a `MGPipeHasFieldVerifier<T>` trait, forward decls + specializations + one `MGPipeVerify(const P&, const P&, const char** outField)` per payload, the `MGPipeFieldEqual` dispatcher (`:399-418`) with the **memcmp fallback branch** and its "P1 gives them field lists … at which point this branch stops being reachable" comment (`:411-415`), the array overload (`:420-426`), the `MGP_VERIFY_FIELD` macro, and `kMGPipeVerifiedPayloadCount = 63` (tail of the file). Floats compare by bits (`:404-405`). |
|
||
| G5 | `gen_filled` `:447-510` | `PipeFilled.inc` (308 lines) | `enum class MGPipeInputField : Uint16` of the 61 Coverage.def accessors + `kFieldCount` (`PipeFilled.inc:28`), `kMGPipeInputFieldCount` + `static_assert(== 61)` (`:93-94`), `kMGPipeInputFieldNames[]` (`:96`), `kMGPipeInputFieldSticky[]` — **every entry `false`** with the note that each `true` must be argued for in P1 (`gen_pipe.py:478-484`, output at `PipeFilled.inc:163`), `kMGPipeInputFieldFilledBy[]` (`:229`, pseudo-calls marked with a trailing comment), `struct MGPipeFilledState { Uint64 CurrentVerbSerial; Uint64 FilledGen[61]; }` (`:293`), `MGPipeInputPoisonFatal()` (`:298`) and `MGPipeInputFieldIsFresh()` (`:304`). Header comment states plainly "P0 is the skeleton … **PipeInputs itself lands in P1**" (`gen_pipe.py:461-462`). |
|
||
| G6 | `gen_coverage` `:513-579` | `PipeCoverage.inc` (108 lines) | joins inventory rows against the accessor map (by `member`) then the delta map (by `delta`); pseudo-calls `{kClientResolved, kReverseChannel, kStructuralHandle}` at `:515`; exits if a Coverage.def call is neither a catalogue call nor a pseudo-call (`:518-520`). Emits `kMGPipeCoverage[]` (63 entries, sorted by key), `kMGPipeInventoryReadPoints=477`, `MappedToCall=299`, `ClientResolved=5`, `ReverseChannel=6`, `StructuralHandle=167`, `Unmapped=0` (`PipeCoverage.inc:96-102`) and the "every row lands in exactly one bucket" assertion (`:104-108`). |
|
||
| G7 | `gen_span_table` `:582-616` | `PipeSpanTable.inc` (67 lines) | `kMGPipePipelineStateMembers[]` — the 24 names hard-coded in **python** at `gen_pipe.py:67-92` (taken from `VulkanRenderer::ComputePipelineStateHash`), the count, and two `extern const MGPStateChunk kMGPipePipelineChunks[]/kMGPipeDynamicChunks[]` declarations whose definitions land in `MG_Pipe/MGPipeRenderStateSpans.cpp` **in P2** (`PipeSpanTable.inc:64-67`). Three deliberate absences are named as P2 questions (`gen_pipe.py:592-601`): `FramebufferSrgb`/`DepthClamp` (no storage at all), `ProvokingVertexModeSetting`, `FrontFaceModeSetting`/`ClipOrigin`/`ClipDepthMode`. |
|
||
|
||
### 1.4 `write()` and `--check`
|
||
|
||
`write(path, text, check, changed)` `:619-626`: reads the existing file, returns if byte-identical, otherwise appends the repo-relative path to `changed` and — **only when not in check mode** — writes with `encoding="utf-8", newline="\n"` (LF, deliberate; the repo is developed on Windows).
|
||
|
||
`main()` `:629-671`: parses everything first (so **all validation above runs in `--check` too** — docstring `:28-29` says so explicitly), makes `GENERATED_DIR`, then writes the seven files in the fixed order `Tables, Thunks, Wire, Verify, Filled, Coverage, SpanTable` (`:646-652`), prints two summary lines and one line per UNMAPPED row (`:654-662`), and in `--check` returns **1** with `gen_pipe: OUT OF DATE: <files>` on stderr when anything would change (`:664-667`).
|
||
|
||
Consequence for P1: `--check` coverage of a NEW output is automatic *if and only if* the new file is produced through `write(...)` inside `main()`. A generator that writes with `open()` directly, or that emits into a path outside `GENERATED_DIR`, is invisible to both `--check` and the CI `git diff` (which only diffs `MobileGL/MG_Pipe/generated`, see §6).
|
||
|
||
---
|
||
|
||
## 2. The generated outputs as they stand
|
||
|
||
All seven live in `MobileGL/MG_Pipe/generated/` and are **committed**. Line counts: `PipeCoverage.inc` 108, `PipeFilled.inc` 308, `PipeSpanTable.inc` 67, `PipeTables.inc` 108, `PipeThunks.inc` 302, `PipeVerify.inc` 573, `PipeWire.inc` 931 (2397 total).
|
||
|
||
They are consumed in exactly one place, in this order, all **inside `namespace MobileGL::MG_Pipe`**:
|
||
|
||
```
|
||
MG_Pipe/MGPipe.h:65 #include "PipeCalls.def"
|
||
:68 #include "generated/PipeTables.inc"
|
||
:72-73 inline MGPipeScreen gMGPipeScreen{}; inline MGPipeContext gMGPipeContext{};
|
||
:77 #include "generated/PipeThunks.inc"
|
||
:80 #include "generated/PipeWire.inc"
|
||
:83 #include "generated/PipeVerify.inc"
|
||
:86 #include "generated/PipeFilled.inc"
|
||
:89 #include "generated/PipeCoverage.inc"
|
||
:92 #include "generated/PipeSpanTable.inc"
|
||
```
|
||
|
||
`MGPipe.h:10` includes `<Includes.h>` and `:12-15` the four sibling headers. `PipeVerify.inc` additionally does `#include "../PipeFields.def"` from inside the namespace.
|
||
|
||
**What compiles them today:** only `MG_Test/Pipe/PipeCatalogueTest.cpp` (target `PipeCatalogueTest`, `MG_Test/Pipe/CMakeLists.txt:3-28`; include dirs include `${MGL_ROOT}/MobileGL/MG_Pipe` at `:11`; `/Zc:preprocessor` on MSVC at `:23-25`; registered `gtest_discover_tests(... LABELS unit)` at `:28`). Registered from `MG_Test/CMakeLists.txt:88-90`.
|
||
|
||
Notable shapes P1 will build on:
|
||
|
||
- `PipeTables.inc:17-29` — the screen table ends with `FenceWaitServer`; the context table ends with `QueryTimestamp` / `QueryCounter` (tail of the file). Table member order is **catalogue order within a class**, which is *not* opcode order for the three appended calls.
|
||
- `PipeWire.inc` gives `MGPWireOp::SetSwapInterval == 68`, `QueryTimestamp == 69`, `QueryCounter == 70`, `FenceWaitServer == 71`, `kOpCount == 72` (pinned by `PipeCatalogueTest.cpp:164-170`).
|
||
- `PipeVerify.inc` — the `MGPipeFieldEqual` memcmp fallback is **reachable today**: `MGP_FIELDS_ResidualValueBlock` (`PipeFields.def:145-146`) names `F(RenderState)` (type `RenderStateParameters`) and `F(Pack)` (`PixelStoreParameters`); `MGP_FIELDS_MGPCaps` (`:39-40`) names `F(Dynamic)` (`DynamicBackendParameters`); `MGP_FIELDS_MGPPixelPackState` (`:139-140`) names `F(Pack)`. None of those three types defines `operator==` — `grep -n "operator==" MobileGL/MG_Pipe/MGPipeValueTypes.h` returns nothing — so all four fields fall to `std::memcmp`, which is exactly the padding-false-positive case the harness must not have.
|
||
|
||
---
|
||
|
||
## 3. `MobileGL/MG_Pipe/*.h` and the two `.def` sources
|
||
|
||
- **`MGPipe.h`** (93 lines). `enum MGPipeCallClass : Uint8 { kScreen, kCtxCso, kCtxState, kCtxObject, kCtxVerb, kCtxQuery, kCallClassCount }` at `:29-37` (unscoped on purpose so `PipeCalls.def` can be read by both cpp and python, `:27-28`). `enum MGPipeCallFlags : Uint32` at `:39-55` (`kNone/kNeedsAck/kHasBlob/kVarTail/kHostSpan/kReplySlot/kOptional`). Forward declaration `struct MGPipeRenderStateSpans;` at `:61` (defined in P2).
|
||
- **`MGPipeTypes.h`** (33 KB, ~800 lines). `MGP_ASSERT_POD(T, Size)` at `:44-46`. Includes `<MG_Backend/BackendObject.h>` at `:33` — this is the reason purity gate A asserts `MGPipeValueTypes.h` and not this header (`:25-32`). `using MG_Backend::DynamicBackendParameters; using MobileGL::PixelStoreParameters; using MobileGL::RenderStateParameters;` at `:37-41`. `MGPCaps` `:126-146` (composition-based size assert at `:145`). `MGPProgramDesc` `:300-311` — `MGPBlobRef Spirv[6]` + `MGPBlobRef Reflection`, the reflection blob being "the whole LinkArtifacts + SpirvArtifacts archive" (`:297-299`). `ResidualValueBlock` `:516-527`; `#define MGL_RESIDUAL_BLOCK_SIZE 1248` at `:536` with the ratchet assertion `:537-539`. Buffer-range-in-the-box helpers `MGPipeSetSubDataBufferRange` `:593`, `MGPipeSubDataBufferOffset` `:602`, `MGPipeSubDataBufferSize` `:607`.
|
||
- **`MGPipeValueTypes.h`** (23 KB, 548 lines). `#pragma once` **and** an include guard `MOBILEGL_MG_PIPE_VALUE_TYPES_H` at `:10-11`, with the comment "belt and braces: this file is reachable both as `<MG_Pipe/...>` and `<...>` (CMakeLists.txt:531,535)". Purity contract stated at `:23-25`. Contents: the render-state/pixel-store/sampler enums and `PixelStoreParameters` (`:208`), `PerBufferBlendState` (`:219`), `StencilFaceState` (`:229`), `RenderStateParameters` (`:239`), `SamplerParameters` (`:447`), and `namespace MG_State::GLState { VertexAttribute (:476), VertexBufferBindingPoint (:517), VertexAttributeVersion (:525) }` — i.e. it re-opens `MG_State::GLState` from inside `MG_Pipe` so old spellings still compile.
|
||
- **`MGPipeHandles.h`** (98 lines). `enum class MGPipeKind : Uint8` `:24-40`; `struct MGPipeHandle {Uint32 Slot; Uint32 Gen;}` `:54-61` with size/align asserts `:63-65`; `kMGPipeNullHandle{0,0}` / `kMGPipeDefaultFramebuffer{0,1}` `:72-73`; `kMGPipeFirstAllocatableSlot=1` `:81`; composite ShaderCso band `:88-94`.
|
||
- **`MGPipeHostSpan.h`** (57 lines). `kMGHostSpanSegNone=0` `:119`, `kMGHostSpanSegFromServerIndexMirror=0xFFFFFFFF` `:124`, `struct MGHostSpan` (32 bytes) `:126-137`, `MGPipeSegmentResolver` + `gMGPipeSegmentResolver = nullptr` `:144-145`, `MGPipeHostBytes()` `:148-154`.
|
||
- **`MGPipeCallbacks.h`** (61 lines). `struct MGPipeCallbacks` with the ten reverse-channel function pointers `:182-206` (`OnGlError`, `OnGpuWritten`, `OnBufferWriteback`, `OnTextureWriteback`, `OnTexturePullRequest`, `OnMipLevelsGenerated`, `OnSurfaceChanged`, `OnCapsInvalidated`, `OnLog`, `OnXfbScatterReady`), `kMGPipeCallbackCount = 10` + size assert `:210-212`, `inline MGPipeCallbacks gMGPipeCallbacks{}` `:215`.
|
||
- **`PipeCalls.def`** (177 lines). `#define MGP_CALL_LIST_DOCUMENTED_COUNT 71` at `:69`; the list `:72-160`; per-class counts documented `:29-37`; explicit non-migrations `:163-177`.
|
||
- **`PipeFields.def`** (238 lines). 63 `MGP_FIELDS_*` macros `:21-219`; `MGP_VERIFY_PAYLOAD_LIST(P)` `:223-236`. Header note `:15-17`: "Adding a field to a payload without adding it here makes the comparator blind to it; **that gap closes in P1**, when the verify harness goes live and the comparator's coverage is itself asserted."
|
||
- **`Coverage.def`** (106 lines). `MGP_COVERAGE_ACCESSOR_LIST(X)` `:29-97` (61 `X(Accessor, Call)` rows, including the three pseudo-call rows `InvalidateCompileEnv → kClientResolved` `:95`, `ValidateProgramName → kClientResolved` `:96`, `RecordError → kReverseChannel` `:97`); `MGP_COVERAGE_DELTA_LIST(X)` `:102-104` (`handle-ify (wire handle) → kStructuralHandle`, `Buffer ops delta → ResourceRespecify`). Comment at `:36-39` flags `GetBufferBindingSlot` as polymorphic over `BufferTarget` and says its rows split into four calls "**once the inventory carries the target argument (P1)**".
|
||
|
||
---
|
||
|
||
## 4. `scripts/gen_pipe_dirty_surface.py` (202 lines) — report today, gate in P1
|
||
|
||
Scans `MobileGL/MG_Impl/GLImpl` (`SCAN_ROOT` `:34`) for functions that BOTH mutate through `pGLContext->` with one of the prefixes `Add|Set|Mark|Bump|Allocate|Truncate|Record|Notify|Begin|End` (`MUTATOR_PREFIXES` `:37-38`, `MUTATOR_RE` `:40`) AND reach the backend via `gBackendFunctionsTable.GL.*` or `pActiveBackendObject->` (`BACKEND_RE` `:41`) in the same braced body (`FUNCTION_RE` `:42-43`, `function_bodies` `:88-103`). Comments/strings are masked first (`mask_comments_and_strings` `:46-85`). Output is a human report or `--summary` counts (`:138-141`, `:180-198`); every mutator prints `UNMAPPED` (`:178`) and the closing line says "the aggregate-generation mapping file **lands in P1**, and this report is what it has to cover" (`:193-195`). Known limits are printed by the script itself (`:196-198`): lambda bodies attributed to the enclosing function, helper-published mutations read as deferred.
|
||
|
||
Docstring `:21-22`: "P1 adds the mapping file and CI regenerates it with `git diff --exit-code` and zero unmapped mutators, **the same shape as gen_pipe.py's G6**." There is no mapping file and no `--check` flag today; `argparse` accepts only `--summary`.
|
||
|
||
---
|
||
|
||
## 5. `MG_State/GLState/ProgramState/ProgramArtifacts.h` (576 lines) — the P0.5 archive
|
||
|
||
Types: `TypeFacts` `:31`, `ResourceReflection` `:63` with the four aliases `UniformReflection`/`BlockReflection`/`PipeInputReflection`/`PipeOutputReflection` `:88-91`, `XfbVarying` `:95`, `LinkArtifacts` `:160`, `SpirvArtifacts` `:359`. Purity contract in the header banner `:16-19` (no `ShaderObject.h`, no `SpvcSession.h`, no `ShaderTranspiler/`, no `Config.h`, no `MG_Backend/`, no `BufferState/`; probe name `artifacts-header`; the token `glslang::` may appear exactly twice). Generic archive via `VisitFields(Self&, V&&)` overloads — `LinkArtifacts` visits **57 fields** (closing comment at `:534`), `SpirvArtifacts` visits **8** (`:539-547`). Size trip wires `:550-575`: `MGL_RESOURCEREFLECTION_SIZE 128`, `MGL_XFBVARYING_SIZE 128`, `MGL_LINKARTIFACTS_SIZE 1056`, `MGL_SPIRVARTIFACTS_SIZE 88`, pinned per-STL (libstdc++ only today; the libc++ branch at `:558-560` is inert until the integrator pins it). This is what `MGPProgramDesc::Reflection` (`MGPipeTypes.h:310`) will carry; nothing serializes it yet.
|
||
|
||
---
|
||
|
||
## 6. Config knobs — exact semantics, defaults and every read site
|
||
|
||
Declared in `MobileGL/Config.h` under the comment banner at `:319`:
|
||
|
||
| field | line | default | env | parsed at |
|
||
|---|---|---|---|---|
|
||
| `Uint64 PipePush` | `Config.h:326` | `0` | `MOBILEGL_PIPE_PUSH` (decimal or `0x`) | `ConfigLoader.cpp:245` (`QueryEnvUint64`) |
|
||
| `Bool PipeVerify` | `:332` | `false` | `MOBILEGL_PIPE_VERIFY` | `ConfigLoader.cpp:246` (`QueryEnvFlag`) |
|
||
| `Bool PipeStats` | `:335` | `false` | `MOBILEGL_PIPE_STATS` | `ConfigLoader.cpp:247` |
|
||
| `Bool PipeLegacyMemos` | `:340` | `true` | `MOBILEGL_PIPE_LEGACY_MEMOS` | `ConfigLoader.cpp:251-252` — **tri-state**: `QueryEnvQuirkOverride(...) != QuirkOverride::ForceOff`, i.e. only an explicitly falsy value turns it off |
|
||
| `Uint32 PipeTexelRetainMb` | `:344` | `0` (0–4096) | `MOBILEGL_PIPE_TEXEL_RETAIN_MB` | `ConfigLoader.cpp:253` |
|
||
| `Uint32 PipeIndexMirrorMb` | `:349` | `64` (0–4096) | `MOBILEGL_PIPE_INDEX_MIRROR_MB` | `ConfigLoader.cpp:254` |
|
||
| `Uint32 PipeStatsPeriod` | `:354` | `120` (1–1000000) | `MOBILEGL_PIPE_STATS_PERIOD` | `ConfigLoader.cpp:255` |
|
||
| `String PipeStatsFile` | `:358` | `""` (no dump) | `MOBILEGL_PIPE_STATS_FILE` | `ConfigLoader.cpp:256` (`QueryEnvVariable`) |
|
||
|
||
`ConfigLoader.cpp:242-244` notes that no allow-list edit is needed: every `MOBILEGL_`/`LIBGL_` prefixed variable is accepted by construction. The hex/decimal parser's rules (a leading `0` is not octal; a `-` anywhere is rejected) are documented at `ConfigLoader.cpp:165`.
|
||
|
||
**Read sites outside Config/ConfigLoader — measured, whole tree:**
|
||
|
||
- `PipeStats` → `MG_Util/Metrics/PipeStats.cpp:257` (`Init()` latches `g_pipeStatsEnabled`).
|
||
- `PipeStatsPeriod` → `PipeStats.cpp:258-260` (0 is coerced to `kDefaultSummaryFramePeriod`).
|
||
- `PipeStatsFile` → `PipeStats.cpp:235-265` (`WriteJsonDump()` + the Init log line).
|
||
- **`PipePush`, `PipeVerify`, `PipeLegacyMemos`, `PipeTexelRetainMb`, `PipeIndexMirrorMb`: read NOWHERE.** They are parsed and then unused — pure P0 placeholders. P1 is the first consumer of `PipeVerify` and `PipePush`.
|
||
|
||
There is **no CMake option and no compile-time macro** named `MOBILEGL_PIPE_VERIFY` (`grep` over `CMakeLists.txt` and all `*.txt/*.cmake` returns nothing; `option(` list is `CMakeLists.txt:5-24,108,219`). ARCHITECTURE.md:579 lists it as "计划(P1;构建期开关…)", so P1 must add the CMake option itself and decide how it interacts with the already-parsed runtime `Features.PipeVerify`.
|
||
|
||
Likewise **`MOBILEGL_DEBUG` does not exist anywhere in the tree** — the only hit is the plan snippet `docs/Disaggregated/ARCHITECTURE.md:330` (`#if MOBILEGL_DEBUG || MOBILEGL_BUILD_DISAGGREGATED`). The repo's real debug gate is `#if MOBILEGL_LOG_ACTIVE_LEVEL <= MOBILEGL_LOG_LEVEL_DEBUG` (`MobileGL/Defines.h:105`, and `MOBILEGL_ASSERT` compiles to nothing otherwise at `:113-115`). **P1 must use that spelling, not `MOBILEGL_DEBUG`.** Consequence worth stating: because `MOBILEGL_ASSERT` is already a no-op in INFO builds, deleting the ~43 `MOBILEGL_ASSERT(...pGLContext...)` lines in `MG_Backend` cannot move `.text` in an INFO build.
|
||
|
||
`MOBILEGL_BUILD_DISAGGREGATED` (`CMakeLists.txt:23`) appends `-DMOBILEGL_BUILD_DISAGGREGATED=1` (`CMakeLists.txt:524-526`) and the `MG_Remote` sources (`:455-490`), and gates `MG_Test/Wire` (`MG_Test/CMakeLists.txt:103-105`).
|
||
|
||
---
|
||
|
||
## 7. `MG_Util/Metrics/PipeStats.{h,cpp}` — counters P1 must keep alive
|
||
|
||
Header (192 lines). Enum `ByteClass` `:46-77`: `StageBuffer, StageTexture, StageUboGlobal, StageUboNamed, StageVertexClient, StageIndexClient, StageIndirectCmd, PersistentMapPush, ResidualValueBlock(placeholder, 0 until P2 — :73-75), Count`. Enum `CallClass` `:81-102`: `Draws, AccessorCalls, TextureUploadEmissions, TextureUploadBoxEmissions, TextureUploadRectEmissions, TextureUploadJobs, Count`. Enum `Gate` `:107-122`: `EsprytRenderState, EsprytTextureSyncList, EsprytUnitBindingsEpoch, MagmaDrawFastPath, MagmaPipelineMemo, MagmaDynamicTail, Count`. `kPayloadHistogramBuckets = 24` `:129` — the histogram is a **placeholder**: "MGPipe emits no records yet, so nothing in the backends calls `RecordDrawPayloadBytes`. The bucketing and the reporting are implemented and unit-tested so that the first generator to emit records only has to add the one call" (`:124-128`). API: `Enabled()` `:141`, `Init()` `:145`, `Shutdown()` `:149`, `AddBytes/AddCalls/CountGate/RecordDrawPayloadBytes` `:151-154`, `OnPresent()` `:159`, introspection `:162-173`, `FormatWindowLine()` (pure) `:179`, `AdvanceSummaryWindow()` `:183`, `FormatJson()` `:185`, test hooks `:189-190`.
|
||
|
||
Implementation (488 lines). The **site inventory** — "this list is the contract" — is `PipeStats.cpp:15-100`; it names what is NOT wired (compressed-texture upload, readback direction, persistent-map pushes, Magma's absent indirect array) and explains that `accessor-calls` is a **lower bound**: static tallies at ~10 hot entry points, "NOT a wrapper around all 293 `pGLContext->` sites" (`:76-88`). Counter storage `:112-124` (relaxed atomics + plain window bases). `PayloadBucketOf` `:142-152`. Name tables `:168-180`. `Init()` `:255-267`, `SummaryFramePeriod()` `:269`, `RecordDrawPayloadBytes` `:303`, `OnPresent` `:305`, `NameOf` `:362-364`, `FormatWindowLine` `:366`, `AdvanceSummaryWindow` `:434`, `FormatJson` `:448`. Called from `MobileGL/Init.cpp:114` (`Init()`, right after config load) and `Init.cpp:50` (`Shutdown()`).
|
||
|
||
Live counting sites (all guarded by `if (MG_Util::PipeStats::Enabled())`): DirectGLES `DirectGLES.cpp:1416,1423,1428,1520,1553,1570,2039,2045,2969,3423,3446,4368,10593`; `Managers.cpp:783,896,970,1541,2573,2607,2705,4433`; `MultiDraw.cpp:176,218,432,548,754`; DirectVulkan `DirectVulkan.cpp:1337`; `UniformManager.cpp:2080,2297`; `VkBufferManager.cpp:237,374,391,465,492,532,605,660,743`; `VkTextureManager.cpp:3154`; `VulkanRenderer.cpp:5004,5013,5257,5924,5930,6408,6442,6451,6456`.
|
||
|
||
**P1 obligations here:** every site above sits in a function whose `pGLContext->` reads P1 rewrites, so the tallies (`AddCalls(AccessorCalls, N)`) must be re-audited when reads move behind `PipeInputs` — the literal N at e.g. `VulkanRenderer.cpp:5273` (15) and `:6461` (3) counts accessor calls in that body. The counter NAMES are pinned by a test (§8) and are TracyPlot series names + JSON keys, so P1 must extend rather than rename; the natural P1 extension is finally calling `RecordDrawPayloadBytes` and lighting up `ResidualValueBlock`/`PersistentMapPush`.
|
||
|
||
---
|
||
|
||
## 8. The two unit suites
|
||
|
||
**`MG_Test/Pipe/PipeCatalogueTest.cpp` (322 lines).** Counting macros `:26-34`; per-payload POD asserts over both `MGP_CALL_LIST` and `MGP_VERIFY_PAYLOAD_LIST` `:38-44`. Tests: `HandleIsEightBytes` `:48`; `EntryCountMatchesTheDocumentedCount` `:65`; `GeneratedTablesHoldTheWholeCatalogue` `:72` (per-class 11/8/13/17/9/13 at `:86-91`); `UninstalledTablesAreAllNull` `:96`; `ResidualBlockSizeIsPinned` `:109`; `ValueTypeLayoutsArePinned` `:120` (`PixelStoreParameters` 28, `PerBufferBlendState` 28, `StencilFaceState` 28, `RenderStateParameters` **1168**, `SamplerParameters` 100, `VertexAttributeVersion` 6, `kMGMaxDrawBuffers` 8); `ResidualBlockIsExactlyItsTwoValueStructsPlusPatchTail` `:142` (offsets 0 / 1168 / 1200 / 1208); `WireOpcodesAreThePositionsInTheCatalogue` `:150`; `LateArrivalsAreAppendedWithoutRenumbering` `:164`; `ApplierAcceptsAWellFormedRecord` `:174`; `VerifyComparatorNamesTheDifferingField` `:184`; `CoverageAccountsForEveryInventoryRow` `:212` (477 rows, 0 unmapped); `PipeInputFieldsStartUnfilled` `:224` (**`EXPECT_EQ(kMGPipeInputFieldCount, 61u)` at `:225`** — this is the number that moves when P1 fixes the accessor set, see §9.1); `PipelineSubsetMembersArePinned` `:237`; `ReverseChannelHasTenCallbacks` `:244`; `HostSpanResolvesTheMonolithPointer` `:252`; `BufferRangeCarriesNoInlineHostSpan` `:271`; `SubDataBufferRangeRidesInTheUnionBox` `:297`.
|
||
|
||
**`MG_Test/Util/PipeStatsTest.cpp` (287 lines).** Fixture `:28`; `EnabledLatchIsTheOnlyGate` `:42`; `ByteClassesAccumulateIndependently` `:49`; `PresentClearsTheFrameButKeepsTheTotal` `:66`; `InitLatchesTheSummaryPeriodFromTheConfigAndNeverKeepsZero` `:81` (pokes `MG_Config::Features.PipeStatsPeriod` directly, `:85-92`); `GateHitsAndMissesAreSeparateCounters` `:96`; histogram tests `:112`, `:129`; `SummaryLineCarriesEveryClassAndGate` `:137`; `PerFrameFieldsKeepTwoDecimals` `:159`; `SummaryLinesReportDisjointWindows` `:174`; `FormattingTwiceDoesNotConsumeTheWindow` `:191`; zero-draw/zero-frame `:206`, `:221`; `JsonDumpNamesEveryCounter` `:234`; **`CounterNamesAreStable` `:260`** (pins all nine byte-class names and all six gate names verbatim — a rename is a breaking change); `SummaryPeriodIsOneHundredAndTwentyFrames` `:280`. Target defined at `MG_Test/Util/CMakeLists.txt:38-54`, registered `:58`.
|
||
|
||
---
|
||
|
||
## 9. CI: the `pipe-gates` job and its neighbours (`.github/workflows/test.yml`)
|
||
|
||
Jobs in the file: `build-linux:12`, `test:149`, `integration:205`, `flatc-check:304`, `include-graph-check:332`, `benchmark:351`, `build-retrace:407`, `trace-cases:552`, `trace-fixtures:572`, `retrace:637`, `retrace-summary:743`, `remove-artifact-clutter:784`, **`pipe-gates:835`**.
|
||
|
||
`pipe-gates` (`:835-887`), deliberately independent of `build-linux` (`:838-839`):
|
||
|
||
1. `:850-853` — **"Regenerate the MGPipe interface (G1-G7)"**: `python3 scripts/gen_pipe.py` then `git diff --exit-code -- MobileGL/MG_Pipe/generated`. Note it runs the *writing* mode and diffs, not `--check`; and the diff path is **scoped to `generated/`**.
|
||
2. `:862-869` — stdio-instrumentation grep gate over `MobileGL/MG_Backend` and `MobileGL/MG_State` (fprintf/printf/puts/std::cout|cerr), no exceptions.
|
||
3. `:873-874` — `python3 scripts/gen_pipe_dirty_surface.py --summary`, **informational**; the comment says "It becomes a gate in P1, when the mapping file exists to diff against."
|
||
4. `:879-887` — `scripts/check_doc_citations.py` on `docs/Disaggregated/*.md`, warning-only (`|| true`).
|
||
|
||
Other relevant lanes: `test` runs `ctest -L unit` (`:186-192`); `integration` runs `ctest -L integration-gpu` **and then a second, filtered pass with an inline env var** (`MOBILEGL_ESPRYT_DISABLE_INVALIDATE_FLUSH=1 ctest ... -R 'Buffer|Readback|...'`, `:281-288`) — this is the exact precedent shape for P1's third CI mode, and the comment at `:277-280` explains why an inline env works here while a ctest `ENVIRONMENT` property would not. `include-graph-check` (`:332-349`) runs `python3 scripts/check_include_closure.py --mode both --compiler clang++-20 --self-test --require-all`.
|
||
|
||
`scripts/check_include_closure.py` PROBES `:73-120`: `value-header` (`MG_Pipe/MGPipeValueTypes.h`, forbidding `MG_State/`, `MG_Impl/`, `MG_Backend/`, `MG_Remote/`), `artifacts-header` (`ProgramArtifacts.h`, plus `TextLimits {"glslang::": 2}`), `wire-header` (`MG_Remote/Transport/ITransport.h`, forbidding `Includes.h`). `REQUIRED_PROBE_NAMES = ("value-header", "artifacts-header")` at `:122` — deleting a probe is red. Also registered as a ctest at `MG_Test/Purity/CMakeLists.txt:9-12` (`--mode text`, label `unit`, with an explicit warning at `:11` that adding an `ENVIRONMENT` property would replace the job env).
|
||
|
||
---
|
||
|
||
## 10. P1 deliverables: what is partial, what is absent
|
||
|
||
### 10.1 `MG_Backend/MGPipe/PipeInputs.h` (accessors) — **nothing exists**; the field set is measurably stale
|
||
|
||
`MobileGL/MG_Backend/` contains only `BackendObject.cpp/.h`, `BackendObjects.h`, `Init.cpp`, `DirectGLES/`, `DirectVulkan/`. There is no `MGPipe/` directory.
|
||
|
||
Partial code that P1 builds on: the G5 tables (`PipeFilled.inc:28-306`) are the field id space; `MGPipeValueTypes.h` supplies the value types the phase-A accessors must return "with types identical to what the backend reads today".
|
||
|
||
**Measured today (whole `MobileGL/MG_Backend`, `*.cpp` + `*.h`):**
|
||
|
||
- `pGLContext->` occurrences: **277** (all spelled `MG_State::pGLContext->`). Per file: `DirectGLES/DirectGLES.cpp` 91, `DirectGLES/Managers.cpp` 15, `DirectGLES/MultiDraw.cpp` 5, `DirectGLES/Utils.cpp` 2, `DirectVulkan/BackendObject_DirectVulkan.cpp` 2, `DirectVulkan/DirectVulkan.cpp` 12, `DirectVulkan/Renderer/UniformManager.cpp` 14, `Renderer/VkClearManager.cpp` 1, `Renderer/VkRenderPassManager.cpp` 3, `Renderer/VkTextureManager.cpp` 2, `Renderer/VulkanRenderer.cpp` 127.
|
||
- Lines mentioning `pGLContext` without the arrow: **58** (matches the roadmap's "58 行非箭头清单"). Breakdown of those lines: 43 `MOBILEGL_ASSERT(...)`, 14 `!= nullptr`, 5 bare `if (MG_State::pGLContext)`, 1 `== nullptr`, 1 `.get()` (`DirectGLES/DirectGLES.cpp:147`: `MG_State::GLState::GLContext* ctx = MG_State::pGLContext.get();`).
|
||
- **ROADMAP.md:17 says "sed 293 处"; the tree has 277.** The 293 comes from the vendored inventory snapshot (`scripts/data/backend_read_inventory.md:9` "pGLContext accesses: 293"), taken before P0's D21 XFB counter-slot rekey. Implementers should work from the measured 277 + 58 and re-measure at the start of the task.
|
||
- Distinct accessors called: **62** overall — **Espryt 32** (`DirectGLES/`) and **Magma 56** (`DirectVulkan/`), against the plan's "Espryt 32 / Magma 55".
|
||
|
||
**Catalogue drift, the single most important finding for P1:** the live accessor set and `Coverage.def`/G5 disagree.
|
||
|
||
| accessor | status |
|
||
|---|---|
|
||
| `GetBoundTransformFeedbackLifetimeId` | **called** at `MG_Backend/DirectVulkan/Renderer/VulkanRenderer.cpp:11219`; declared `MG_State/GLState/Core.h:441`. **No row in `Coverage.def`, no field id in `PipeFilled.inc`.** |
|
||
| `HasOpenTransformFeedbackSpan` | **called** at `VulkanRenderer.cpp:11236`; declared `Core.h:450` (defined `Core.cpp:1278`). **No row, no field id.** |
|
||
| `GetBoundTransformFeedbackName` | **has** a row (`Coverage.def:34`, → `SetStreamOutputTargets`) and a field id, but is **no longer called anywhere in `MG_Backend`**; the inventory row that produced it is `backend_read_inventory.md:594` pointing at `VulkanRenderer.cpp:11137`, a line the D21 rekey replaced. `Core.h:429` still declares it (frontend use only). |
|
||
|
||
So P1's `PipeInputs` must serve **62** accessors, `kMGPipeInputFieldCount` moves from 61 to ~62–63, and `PipeCatalogueTest.cpp:225` (`EXPECT_EQ(kMGPipeInputFieldCount, 61u)`) plus `PipeFilled.inc:94`'s `static_assert(... == 61)` must be updated in the same commit. The vendored inventory itself is stale (477 rows / 293 accesses / 57 files, `backend_read_inventory.md:8-13`) and G6's `0 UNMAPPED` is therefore a statement about the snapshot, not about HEAD — re-vendoring it (or teaching G6 to also cross-check the live tree) is a real P1 decision.
|
||
|
||
Also pre-flagged by the sources themselves: `GetBufferBindingSlot` is polymorphic over `BufferTarget` and its 29 rows are supposed to split into `SetVertexBuffers`/`SetIndexBuffer`/`SetIndirectBuffers`/`SetShaderBuffers` "once the inventory carries the target argument (P1)" (`Coverage.def:36-40`).
|
||
|
||
### 10.2 `MGB_CTX` — **nothing exists**
|
||
|
||
No occurrence of `MGB_CTX` anywhere in the tree. The plan's sketch is `ARCHITECTURE.md:329-334`. Constraints P1 inherits: the gating macro must be `MOBILEGL_PIPE_PUSH` as a *compile-time* macro, which today exists only as the **runtime** `MG_Config::Features.PipePush` (`Config.h:326`) — P1 must decide whether the bitmap is compile-time (as the `#if` implies), runtime, or both, and `ConfigLoader.cpp:245` already parses the runtime one. Purity gate C is specified as `grep -c 'pGLContext' MG_Backend/ == 0` (`ARCHITECTURE.md:503`, gate 1-C) — note it greps `pGLContext`, **not** `pGLContext->`, so the 58 non-arrow lines have to go too, which is why they are an explicit deliverable.
|
||
|
||
### 10.3 Per-verb fill points — **table exists, generator does not**
|
||
|
||
`kMGPipeInputFieldFilledBy[]` (`PipeFilled.inc:229-291`) records *which call* is expected to have filled each field, derived from `Coverage.def`. What does **not** exist is the inverse table the plan asks for — "G5 从 PipeCalls.def 生成『每个 `kCtxVerb`/`kCtxObject` 调用可能读哪些字段』的表,在 MG_Impl 的 ~93 个边界站点生成 validate/fill 调用" (`ARCHITECTURE.md:344`). Building it needs a *per-call → field set* relation, which `Coverage.def` today provides only in the many-to-one direction (accessor → one call). Concretely: 61 accessors map onto 20 distinct calls; inverting that gives, e.g., `CreateRenderState` ← 13 fields, `SetDynamicState` ← 14, `SetSamplerViews` ← 8. Whether that inversion is the right "may read" set for a *verb* (`DrawVbo`, `Clear`, `Blit`, `GenerateMipmap`, …) is a judgement P1 must encode — it is not derivable from the current `.def` files, because the calls named in `Coverage.def` are mostly `kCtxState`/`kCtxCso`, not verbs.
|
||
|
||
The "~93 边界站点" figure is the `gBackendFunctionsTable.GL.*` call-site count in `MG_Impl` that G2's thunks target (`ARCHITECTURE.md` G2 row, `:76`).
|
||
|
||
### 10.4 Poison generations — **skeleton exists, unused, and its debug gate is wrong**
|
||
|
||
Exists: `MGPipeFilledState` (`PipeFilled.inc:293-296`), `MGPipeInputPoisonFatal()` (`:298-302`, message shape `Fatal{UnmigratedPipeInput, "<field>@<verb>"}`), `MGPipeInputFieldIsFresh()` (`:304-307`), `kMGPipeInputFieldSticky[]` (`:163-227`, **all 61 entries `false`**). Missing: any instance of `MGPipeFilledState`, any bump of `CurrentVerbSerial`, any read-side assertion, and any sticky classification. The generator emits the sticky table unconditionally as `false` and its own comment (`gen_pipe.py:478-480`) demands that every `true` be argued for in P1 — meaning P1 must extend `Coverage.def` (or add a new hand-maintained source) with a sticky column, and grow `gen_filled` to consume it.
|
||
|
||
Gate spelling: use `#if MOBILEGL_LOG_ACTIVE_LEVEL <= MOBILEGL_LOG_LEVEL_DEBUG` (`Defines.h:104-115`) and/or `MOBILEGL_BUILD_DISAGGREGATED` — **`MOBILEGL_DEBUG` does not exist**.
|
||
|
||
### 10.5 The shadow comparator (G4 / `MOBILEGL_PIPE_VERIFY`) — **comparators exist; harness, snapshot and coverage assertion do not**
|
||
|
||
Exists and works: 63 `MGPipeVerify()` overloads, the trait, the array overload, bit-exact float comparison, first-differing-field reporting, all in `PipeVerify.inc`; unit coverage at `PipeCatalogueTest.cpp:184-208` and `:285-291`.
|
||
|
||
Missing / must grow:
|
||
1. `SnapshotFromGLContext()` — does not exist anywhere.
|
||
2. The harness that calls the comparator per draw with a draw serial.
|
||
3. **Field lists for the four memcmp-fallback types** (`gen_pipe.py:167-172` names them; `PipeVerify.inc`'s fallback comment says P1 closes it). Today `ResidualValueBlock.RenderState` (1168 bytes), `.Pack`, `MGPCaps.Dynamic` and `MGPPixelPackState.Pack` all compare by `memcmp`, i.e. the comparator has exactly the padding false-positive property the design forbids. Adding `MGP_FIELDS_RenderStateParameters` / `_PixelStoreParameters` / `_DynamicBackendParameters` / `_MGHostSpan` to `PipeFields.def` and removing them from `MEMCMP_FALLBACK_TYPES` is a mechanical but load-bearing P1 edit; `RenderStateParameters` is defined at `MGPipeValueTypes.h:239` and is the big one.
|
||
4. "the comparator's coverage is itself asserted" (`PipeFields.def:15-17`) — no such assertion exists. A field added to a payload in `MGPipeTypes.h` without a `PipeFields.def` entry is silently invisible today; only the *payload* (not the field) is checked (`gen_pipe.py:187-195`).
|
||
5. The `MOBILEGL_PIPE_VERIFY` **CMake option** (absent, §6) and its interaction with the already-parsed runtime `Features.PipeVerify` (`Config.h:332`, currently read by nobody).
|
||
6. The retain mode for consume-and-clear groups (texture dirty rects) described at `ARCHITECTURE.md:502`.
|
||
|
||
### 10.6 The third CI mode — **precedent exists, job does not**
|
||
|
||
Nothing in `test.yml` sets any `MOBILEGL_PIPE_*` variable. The shape to copy is `integration:281-288` (a second `ctest` invocation with an inline env var, plus the `:277-280` caution that a ctest `ENVIRONMENT` property would *replace* rather than extend the job env — the same trap is called out in `MG_Test/Purity/CMakeLists.txt:11` and `ARCHITECTURE.md:567`). The gate text (`ROADMAP.md:17`) is: 40 traces + all integration tests under `MOBILEGL_PIPE_VERIFY=1` with zero divergence, plus two negative controls (corrupt one snapshot field → verify red; drop one field from `glGenerateMipmap`'s fill table → poison Fatal **on that verb**). Trace lanes to hook: `trace-cases:552`, `trace-fixtures:572`, `retrace:637`; retrace env passes through `--env K=V` → intent extra `mobilegl_env` → `setenv` before loading the library (`ARCHITECTURE.md:445`).
|
||
|
||
### 10.7 Which generator must grow, and how `--check` must cover it
|
||
|
||
| generator | P1 growth | `--check` coverage requirement |
|
||
|---|---|---|
|
||
| **G5 `gen_filled`** | (a) absorb the 2 missing / 1 dead accessor; (b) emit a **per-verb "may read" table** (new output, e.g. `PipeFillPoints.inc`); (c) emit real sticky flags from a new column in `Coverage.def`. | Any new file must be produced by a `write(os.path.join(GENERATED_DIR, ...), ...)` call added to `main()` between `:646` and `:652` — that is what makes both `--check` and the CI `git diff -- MobileGL/MG_Pipe/generated` see it. A new *input* column must also get its own `sys.exit` validation in `parse_coverage()` so a malformed row fails in `--check` rather than silently emitting a wrong table. |
|
||
| **G4 `gen_verify`** | consume the four new field lists; shrink/empty `MEMCMP_FALLBACK_TYPES` (`:167-172`); add a per-payload **field-count** assertion so a payload that grows a member without a `PipeFields.def` entry fails. | The field-count check needs a source of truth for "how many fields does this payload have" — the only mechanical one available is parsing `MGPipeTypes.h`, which the generator does not do today. Simplest honest form: emit `static_assert(sizeof(P) == <literal>)` next to each comparator so any layout change is red, and require the literal to be regenerated. |
|
||
| **G6 `gen_coverage`** | re-vendor `scripts/data/backend_read_inventory.md` at HEAD (or the accessor drift stays invisible); split `GetBufferBindingSlot` by target (`Coverage.def:36-40`). | Both modes already `sys.exit` on an unknown call name (`:518-520`) and on missing macros. Keep `kMGPipeInventoryUnmapped == 0` and `PipeCatalogueTest.cpp:212-220` in sync with the new row count. |
|
||
| **`gen_pipe_dirty_surface.py`** | add the mapping file + a `--check` mode with `git diff --exit-code` and zero unmapped mutators (its own docstring `:21-22`); promote `test.yml:873-874` from informational to a gate. | It has no `write()` helper and no `--check` at all today; both must be added, and the mapping file has to live somewhere the CI step diffs (choose a path and add it to the `git diff` argument list — the existing step only diffs `MobileGL/MG_Pipe/generated`). |
|
||
| **G7** | untouched in P1 (chunk table + setter-consistency test are P2, `PipeSpanTable.inc:64-67`). | — |
|
||
|
||
Also: since P1 is the first time the library compiles `MGPipe.h`, whatever new `.cpp` files land (`MG_Backend/MGPipe/MGPipeImpl_DirectGLES.cpp`, `..._DirectVulkan.cpp`) must be added by hand to the explicit `SOURCE_FILES` list (`CMakeLists.txt:234` ff., backend block at `:366-393`) — there is no glob.
|
||
|
||
---
|
||
|
||
## 11. Naming / namespace / include conventions the new files must follow
|
||
|
||
1. **File header.** Every source and generated file starts with the eight-line banner: `// MobileGL - <repo-relative path>`, the two-line copyright, three licence lines, `// SPDX-License-Identifier: LGPL-3.0-only`, `// End of Source File Header`. See `MG_Pipe/MGPipe.h:1-7`, `gen_pipe.py:42-48`.
|
||
2. **Include spelling.** `MG_Pipe` headers are reachable **both** as `<MG_Pipe/X.h>` (via `${CMAKE_SOURCE_DIR}/MobileGL` on the include path) and as `<X.h>` (via `${CMAKE_SOURCE_DIR}/MobileGL/MG_Pipe`, `CMakeLists.txt:531-535`). Because of that double reachability, `MGPipeValueTypes.h:10-11` carries **both** `#pragma once` and an `MOBILEGL_MG_PIPE_VALUE_TYPES_H` guard — new headers under `MG_Pipe/` that MG_Backend will include should do the same. `MG_Backend` headers are spelled `<MG_Backend/...>` (see `MGPipeTypes.h:33`), so the documented P1 path is **`<MG_Backend/MGPipe/PipeInputs.h>`** (`ARCHITECTURE.md:328`, build-layout table `:521`). Within `MG_Pipe` the sibling includes are relative quotes (`MGPipe.h:12-15`, `PipeVerify.inc:387` uses `"../PipeFields.def"`).
|
||
3. **Namespaces.** Pipe code lives in `namespace MobileGL::MG_Pipe` (`MGPipe.h:26`); value types live directly in `namespace MobileGL` (`MGPipeValueTypes.h:27`) with a re-opened `namespace MG_State::GLState` inside it (`:473`) for the vertex-attribute types; counters live in `namespace MobileGL::MG_Util::PipeStats` (`PipeStats.h:41`). Backend code is `namespace MobileGL::MG_Backend` (`BackendObject.h`). The plan's `gPipeInputs` is spelled `::MobileGL::MG_Pipe::gPipeInputs` in the `MGB_CTX` sketch (`ARCHITECTURE.md:331`) even though the header lives under `MG_Backend/MGPipe/` — resolve that inconsistency explicitly rather than by accident.
|
||
4. **Symbol naming.** Generated constants are `kMGPipe*`; generated types `MGPipe*` / `MGP*`; wire records `MGPWireRec_<CallName>`; thunks `MGP_<CallName>`; global tables `gMGPipe*`. Payload structs are `MGP<Noun>` and each gets `MGP_ASSERT_POD(T, Size)` (`MGPipeTypes.h:44-46`). Config fields are `Pipe<Thing>` on `MG_Config::Features` with env var `MOBILEGL_PIPE_<THING>`.
|
||
5. **Generated-file discipline.** Outputs go under `MobileGL/MG_Pipe/generated/`, extension `.inc`, LF line endings (`gen_pipe.py:625`), committed to the tree, carrying the "GENERATED by scripts/gen_pipe.py from <sources> - DO NOT EDIT" banner (`:52-53`). The banner also asserts inclusion from `MGPipe.h` inside the namespace — honour it or parameterise it.
|
||
6. **Logging.** `MGLOG_D` for non-critical (compiled out in INFO builds); `MGLOG_I` only with a stated reason (`PipeStats.cpp:224-231` is the precedent for an opt-in measurement line); `MGLOG_F` + `std::abort()` for the fatal shapes (`PipeFilled.inc:298-302`, `PipeWire.inc`'s `MGPipeWireProtocolFatal`). No `printf`/`fprintf`/`std::cout` anywhere under `MG_Backend` or `MG_State` — CI greps for it (`test.yml:862-869`).
|
||
7. **Commit messages.** `[Type] (Scope): description`, single line, no `Co-Authored-By` (repo convention; see `git log`).
|
||
|
||
---
|
||
|
||
## 12. Traps worth carrying into the implementation
|
||
|
||
- `parse_verify_payloads`, and both `parse_coverage` blocks, terminate their regex at a **blank line**; appending to those macros without keeping the trailing empty line silently truncates the parse (`gen_pipe.py:177`, `:201`, `:207`).
|
||
- `parse_calls` stops at the first line in `MGP_CALL_LIST` without a trailing backslash (`:149-150`) — a wrapped comment line inside the macro that loses its backslash silently truncates the catalogue, and the documented-count check is the only thing that catches it.
|
||
- `PipeCatalogueTest` hard-codes 61 (`:225`), 477 (`:213`), 24 (`:238`), 71/72 (`:151-169`), 11/8/13/17/9/13 (`:86-91`), 1168/1248 (`:110-124`) — every P1 change to the field set or the catalogue lands in this file too.
|
||
- `PipeStatsTest.CounterNamesAreStable` (`:260-279`) pins every counter name; extend, never rename.
|
||
- The CI regeneration step diffs only `MobileGL/MG_Pipe/generated` (`test.yml:853`); a generated file placed elsewhere (e.g. a dirty-surface mapping under `scripts/data/`) needs its own diff argument.
|
||
- `ctest` `ENVIRONMENT` properties **replace** the job environment (`MG_Test/Purity/CMakeLists.txt:11`, `test.yml:253-258`); the verify lane must set its env inline on the `ctest` command line, as the integration lane's second pass does.
|
||
- `MG_Test/Wire` and everything under `MG_Remote/` only exist under `MOBILEGL_BUILD_DISAGGREGATED` (`MG_Test/CMakeLists.txt:103-105`, `CMakeLists.txt:455-490`); P1's work must stay green in the default OFF build, where `MGPipe.h` is compiled by nothing but the unit test today.
|