Files
MobileGL/docs/Disaggregated/notes/recovered/wf4/scout-generated-and-config.md
T
swung0x48 aba329cc53 [Docs] (Disaggregated): P6's plan and contract draft; the working notes move from a local directory into the repository
Two things land together: the plan and contract draft P6 needs before it starts, and the
working notes that until now existed on exactly one machine.

1. P6's plan and contract draft (neither started; not one line of code)

     docs/Disaggregated/P6-SPAWN-PLAN.md      the package plan
     docs/Disaggregated/P6-CONTRACT-DRAFT.md  the contract draft (moves to
                                              MG_Remote/CONTRACT-P6.md when c6 lands)

   The three findings that mattered, all written into the documents:

   a. P6 is SMALLER than its roadmap cell suggests. The transport primitives are already in
      the tree and already tested: SocketDoorbell including hangup detection and the two
      lost-wakeup fences (Doorbell.cpp:211-360, four cases in FdPassingTest), SCM_RIGHTS fd
      passing, ShmSegment::Adopt, and the SurfaceOp / WindowKind schema already defined in
      protocol.fbs. inproc uses a real second shm mapping rather than an alias, and
      SessionRings.h:22-28 says that was done so today is not the first time it runs. P6 is
      assembly plus a control plane plus a process, not "write a socket transport".

   b. The evidence for "P6 is only a transport swap" has EXPIRED. It was bought by P5c, whose
      audit found 59 direct memory accesses in a tree that already looked clean. P5e changed
      the tree again. So the first package, a6, is a read-only audit that writes no code, and
      every contract row that depends on it is marked PENDING a6 rather than decided in
      advance.

   c. P6 does not get a game running on the phone. ANativeWindow* is meaningless in the child,
      and protocol.fbs:186-196's own comment says Android transfers the window out of band -
      that band is P12. P6 lands pbuffer / surfaceless / offscreen, which is what HeadlessGL,
      the split-equivalent lane and trace replay need, and which is exactly what P6's own exit
      gate measures. A real window reaching the server is a named refusal. This gets its own
      section because "P6 is done" would otherwise read as "the game runs now".

   The contract adds rule G: a role may not name a process-local handle. It extends P5c's
   rule E (a role may not name the other role's memory) from memory to identity - EGLDisplay /
   EGLSurface / EGLContext / ANativeWindow* / fd number / pid / mapped address either cross as
   a token this contract defines or they do not cross, and a descriptor crosses only through
   SCM_RIGHTS, where the kernel renumbers it.

   What P5e left for P6 gets its own section. The latch semantics are already designed
   (ARCHITECTURE.md:504) and are copied unchanged. What is new is that after run-ahead the
   client no longer waits while the peer process can DIE: the client holds records that were
   published and will never be applied, and Android's freezer suspends the child without
   closing anything. So slow and dead must be distinguishable WITHOUT a timeout threshold.
   That is P6's only new design; everything else is carriage. It shares a predicate with E1's
   outstanding re-specification (ID-122), and the two should be designed together.

   Two gates carried over from P5e's lessons: G2 requires integration-spawn's test-name set to
   match integration-split's name for name, because a differing set means the lane is quietly
   running less; and the arm-proof gate requires every entry to record the child pid and
   transport=spawn in its OWN private log - ID-124 established that this kind of false green
   really happens, and a spawn lane that actually ran monolith would pass every other gate.
   S2's shape must be settled before it is written, and the document says why: E1 is the
   cautionary case.

2. The working notes move into the repository (docs/Disaggregated/notes/, 415 .md files)

   ROADMAP / CURRENT_STAGE_PROGRESS / MEASUREMENTS cite ruling numbers, audit line numbers and
   the provenance of gate figures from ~/w7/notes/, a directory that exists on one machine and
   is under no version control. A record cited hundreds of times that lives only locally is not
   a record, so it moves in whole, with its directory structure intact.

   Only .md moves. Scripts, run logs, census and gate result JSON, patches, APKs and nm dumps
   stay where they are: they are evidence DATA rather than documents - large, regenerated per
   run, and mostly carrying absolute paths and device serials that mean something only on the
   machine that produced them. The mapping and this split are written in
   docs/Disaggregated/notes/README.md.

   Two exceptions are recorded there too: P6's BRIEF has been promoted to a first-class
   document and keeps no copy under notes/, so the two cannot drift apart; and recovered/ holds
   material salvaged from failed workflow runs, which may duplicate the like-named phase
   directories and is kept because a few of those were the only complete version at the time.

   CI's citation lint takes docs/Disaggregated/*.md only (non-recursive), and notes/ is
   deliberately outside it: those notes' file:line citations were written against their own
   code heads, and resolving them against today's HEAD would fail wholesale - which is not an
   error, it is their correct state as a historical record. To check one, use the revision it
   declares (--rev).

3. Inconsistencies fixed in passing

   - README.md's status line still said P5e was in progress while the stage table already said
     closed.
   - CURRENT_STAGE_PROGRESS's next-step item 1 still listed the exit gate as pending, though
     (a) and (b) were run in the previous commit; rewritten to closed plus the one item that
     actually remains (E1).
   - ROADMAP's P6 row still had the pre-phase plan in three of its cells; it now carries the
     package order, the scope boundary and the two new gates.

Checked with check_doc_citations.py: 125 citations across docs/Disaggregated/*.md, 0 problems.
2026-09-18 23:31:39 -04:00

45 KiB
Raw Blame History

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 ### \`headings and table rows| line | kind | member | delta | (INVENTORY_ROW_REat: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_asserts 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 - 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.