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.
37 KiB
P1 implementation brief — PipeInputs strangler, per-verb fill points, poison generations, MOBILEGL_PIPE_VERIFY comparator + third CI mode
Tree: feat/disaggregated @ 087685d1 (worktree C:/Users/geekerwan/AndroidStudioProjects/FoldCraftLauncher/MobileGL-disagg, clean except untracked .trace-work/). WSL: base tree ~/w7/pipe and five package worktrees ~/w7/p1-<slug> on branches p1/<slug>, all created from the contract commit C0 (section B.1) that the integrator lands first; every tree gets a configured build-linux/ exactly as in the P0.5 brief (Release, /usr/sbin/clang++, ccache, MOBILEGL_BUILD_TEST=ON, MOBILEGL_BUILD_INTEGRATION_TEST=ON, MOBILEGL_BUILD_DISAGGREGATED=OFF, log level INFO) — that is the pull build; the core package additionally configures build-verify/ (section C.1).
Every file:line below was re-opened at 087685d1. Where a scout was wrong or incomplete the text says [correction] and the corrected fact is what the packages follow.
Corrections to the scouts, in one place:
- Boundary catalogue is incomplete.
MG_Impl/GLImpl/Drawing/GL_Drawing.cpp:1329aliases the table (auto& backendGL = MG_Backend::gBackendFunctionsTable.GL;) and lines1330-1334invokeFenceSync/ClientWaitSync/DeleteSyncthrough it; the "91 lines" count misses them. The complete boundary is 96 lines / 87 invocations (table in B.9). There is nopActiveBackendObject->path fromMG_Implinto a pull site: the only virtualsMG_Implcalls areGetDynamicParameters(35),GetFormatCapabilities(4),GetBackendType(1).Present/SetSwapIntervalare not invoked fromMG_Implat all (MG_Backend/Init.cpp:44copies the table; the EGL path calls the backend's own virtuals), and neither reads a field (DirectGLES.cpp:10550, catalogue "no pulls"). ShaderStorageBlockBindingdoes not callSyncNeccessaryTextures/SyncRenderState(scout-pull-sites §4.2).DirectGLES.cpp:7355-7372reads onlyValidateProgramName/GetProgramObject; the two sync calls at:7376/:7378belong toClearBufferfi(:7374). It is aPassiveverb (B.8).- Three lines outside the 58 need hand edits:
DirectGLES.cpp:144(static const MG_State::GLState::GLContext* g_fbSlotCacheContext) and:150(&ctx->GetFramebufferBindingSlot(...)— an arrow through a localGLContext*, invisible to everypGLContextgrep) change with:147; B.11 gives the exact text. - Counts in the docs vs the tree:
sedsites 277 (not 293), on 274 lines; non-arrow lines 58 (exact); distinct accessors 62 (+ one.get()), Espryt 32 / Magma 56 (doc: 55);PipeFilled.incfield set 61 → 62 (dropGetBoundTransformFeedbackName, addGetBoundTransformFeedbackLifetimeId+HasOpenTransformFeedbackSpan, both read atVulkanRenderer.cpp:11219/:11236, declaredCore.h:441/:450).SyncPersistentMappedRange20 /SyncGpuWrites6: exact. MOBILEGL_DEBUGdoes not exist (onlyARCHITECTURE.md:330spells it). The repo's debug gate isMOBILEGL_LOG_ACTIVE_LEVEL <= MOBILEGL_LOG_LEVEL_DEBUG(Defines.h:104-115). D9 below fixes the poison gate.- The dirty-surface mapping gate is P2, not P1 (
ROADMAP.md:18P2 row;ARCHITECTURE.md:172,568andtest.yml:871-874say P1). The ROADMAP table cell is the authority for what P1 delivers; P1 leavesgen_pipe_dirty_surface.py --summaryinformational and the integrator corrects the three P1 mentions (D.6). - The vendored inventory is not edited. The dead accessor is retired through a new
MGP_COVERAGE_RETIRED_LIST(D14) so G6 still maps its 477 rows; a live-tree cross-check ingen_pipe.py(D15) makes the field set follow the code from now on. PipeCatalogueTest.cpp:225pins 61 → 62;:213(477) is unchanged.
A. Goal and acceptance gate (verbatim, then decoded)
docs/Disaggregated/ROADMAP.md:17:
P1
PipeInputs替换与 verify harness | 10–13 |MG_Backend/MGPipe/PipeInputs.h(Espryt 32 / Magma 55 访问器);sed293 处 + 58 行非箭头清单逐条转换(显式交付物);逐 verb 类填充点(G5 表,~93 个边界站点);逐 verb 世代 poison;G4 影子比对器 + 第三种 CI 模式;20 处SyncPersistentMappedRange+ 6 处SyncGpuWrites的逐站点归属表 | pull 构建nm --defined-only不变、.text差异逐行归因(空守卫/三元重写推迟到 P2);40 trace + 全部集成测试在MOBILEGL_PIPE_VERIFY=1下零分歧;故意损坏一个快照字段能让 verify 变红;故意在glGenerateMipmap的填充表漏一个字段能在那条 verb 上触发 poison Fatal | P0.5
Supporting text every package must know: the strangler sketch and the three-phase table ARCHITECTURE.md:323-351 (§9.2; P1 = phase A + the scaffolding for phase B); gate 13.2-② ARCHITECTURE.md:501 (field-wise, never memcmp, first differing field + draw serial, ~5–10× slower, never shipped, survives P13); the P13 retention rule ARCHITECTURE.md:369 (delete MGB_CTX/MOBILEGL_PIPE_PUSH/the non-verify branch of SnapshotFromGLContext(), keep MOBILEGL_PIPE_VERIFY with its MG_State include); purity gate C ARCHITECTURE.md:500 greps the bare token pGLContext under MG_Backend/; the stale-index discipline table ARCHITECTURE.md:233-238 and open question #15 ROADMAP.md:88 (the *IndirectCount rows are recorded as they are, not fixed); ROADMAP.md:7 — every gate must be able to go red for the reason it exists; Windows is not a correctness gate.
Decoded into checkable statements (the integrator ticks each in D.5):
| # | statement | how it is checked |
|---|---|---|
| G1 | The pull build (both new CMake options OFF, Release/INFO, LTO off) has the same nm --defined-only symbol set as the P0.5 baseline 087685d1. |
scripts/symbol_report.py --json → added == [] and removed == []. |
| G2 | Every .text byte delta in that build is attributed to a named line of the 58-line conversion list (or to the three extra lines in correction 3). Empty-guard / ternary rewrites are not done in P1 — they are converted to a spelling with identical codegen (D4) and rewritten in P2. |
docs/Disaggregated/P1-symbol-attribution.md: one row per resized symbol with the line that caused it. Expected content: the five inliners of GetFramebufferBindingSlotFast (DirectGLES.cpp:1611,1905,2743,2858,2933 — the :147/:150 change) and nothing else. |
| G3 | On the verify build, all 40 traces (39 CI cases × 2 backends − 1 = 77 matrix entries; rd12-odinlite is ci:false, iterationrp is Magma-only) and every integration scenario (371 cases × 2 backends) run with MOBILEGL_PIPE_VERIFY=1 and report zero divergence: no Fatal{PipeVerifyDiffer and no Fatal{UnmigratedPipeInput in any log, every case green, and the library's arming line present in every log. |
ctest -L integration-verify (742 entries + the arming/negative lanes) and the retrace-verify matrix run with verify_retrace=full; run_trace_case.cmake fails a case whose mobilegl.log lacks MGPipe: verify armed (so a pull library under the lane cannot pass). |
| G4 | Negative control A: MOBILEGL_PIPE_VERIFY_CORRUPT=GetRenderStateParameters makes a verify run red, naming that field. |
Unit test (PipeInputsTest.CorruptedSnapshotFieldIsNamed), integration lane *.VerifyCorrupted.*, and an inverted CI step on one short scenario and one short trace. |
| G5 | Negative control B: omitting one field from GenerateMipmap's fill set raises Fatal{UnmigratedPipeInput, "GetTextureUnitObject@GenerateMipmap"} on that verb (the process aborts inside glGenerateMipmap, not at a later draw). |
Unit test (PipeInputsTest.OmittingOneFieldForOneVerbLeavesExactlyThatFieldStale, fork/waitpid ...AbortsNamingTheVerb), integration lane *.PoisonOmission.* (fork + glGenerateMipmap, both backends), and the literal control: delete the X(TextureOp, GetTextureUnitObject) row from FillPoints.def, regenerate, run — red on GenerateMipmap. |
| G6 | The 20 + 6 sync sites are tabulated per site with their §5.7 reconcile row. | docs/Disaggregated/SYNC_SITES.md (B.12), lint-clean under check_doc_citations.py. |
| G7 | Existing tests: no name removed (ctest -N diff vs baseline is additions-only), ctest -L unit and ctest -L integration-gpu green on the pull build, gen_pipe.py --check clean, check_include_closure.py --require-all green. |
D.5. |
B. Fixed design decisions (every package follows these; none is re-decided inside a package)
B.1 The contract commit C0 (integrator, before any package branches)
Two new headers, nothing else. Both are owned by p1-core afterwards; the other four packages only include them.
MobileGL/MG_Pipe/PipeStrangler.h (exact content; banner as MGPipe.h:1-7 with the path adjusted):
#pragma once
#ifndef MOBILEGL_MG_PIPE_STRANGLER_H
#define MOBILEGL_MG_PIPE_STRANGLER_H
// The P1 strangler alias (ARCHITECTURE.md section 9.2, phase A). Every backend read of
// frontend state is spelled MGB_CTX-> from P1 on. In the PULL build the three macros expand
// to exactly the tokens the backends used before P1, so the preprocessed token stream - and
// therefore .text - is unchanged. In the PUSH build (-DMOBILEGL_PIPE_PUSH=1) they resolve to
// the pushed PipeInputs block. This header deliberately lives OUTSIDE MG_Backend/ so that
// purity gate C (`grep -c pGLContext MG_Backend/ == 0`, ARCHITECTURE.md:500) is a statement
// about backend code, not about the alias; P13 deletes this file.
//
// MGB_CTX_PRESENT replaces the seven empty guards, the four ternary conditions and the
// six `!= nullptr` / `== nullptr` tests of the 58-line list: in the pull arm it is the
// same null test those lines performed (unique_ptr::operator bool IS `get() != nullptr`),
// in the push arm the block is always there. P2 removes the guards; P1 only respells them.
// MGB_CTX_IDENTITY replaces the one `.get()` capture (DirectGLES.cpp:147): an opaque
// identity that changes when the frontend context is recreated.
#if MOBILEGL_PIPE_PUSH
#include <MG_Backend/MGPipe/PipeInputs.h>
#define MGB_CTX (&::MobileGL::MG_Pipe::gPipeInputs)
#define MGB_CTX_PRESENT (true)
#define MGB_CTX_IDENTITY (::MobileGL::MG_Pipe::gPipeInputs.FrontendIdentity())
#else
#define MGB_CTX (::MobileGL::MG_State::pGLContext)
#define MGB_CTX_PRESENT (::MobileGL::MG_State::pGLContext != nullptr)
#define MGB_CTX_IDENTITY (static_cast<const void*>(::MobileGL::MG_State::pGLContext.get()))
#endif
#endif
The pull arm needs no include: every backend TU that spells MGB_CTX already includes what declares MobileGL::MG_State::pGLContext (Core.h:596, extern UniquePtr<GLState::GLContext>& pGLContext;). The push arm's MG_Pipe → MG_Backend include is a deliberate, documented layering exception that dies with the file at P13.
MobileGL/MG_Impl/Pipe/PipeFill.h (stub; core replaces the body, the macro name and the pull no-op are the contract):
#pragma once
// P1 fill points (ARCHITECTURE.md:348). One MGP_FILL_FOR(<Verb>) immediately before each
// backend-table invocation in MG_Impl. Pull build: nothing. Push build: an RAII verb scope
// that bumps the poison serial, fills gPipeInputs for the verb's class, runs the verify
// comparator when armed, and closes the verb on scope exit.
#if MOBILEGL_PIPE_PUSH
#include <MG_Pipe/MGPipe.h>
namespace MobileGL::MG_Pipe {
class MGPipeVerbScope {
public:
explicit MGPipeVerbScope(MGPipeVerb verb);
~MGPipeVerbScope();
MGPipeVerbScope(const MGPipeVerbScope&) = delete;
MGPipeVerbScope& operator=(const MGPipeVerbScope&) = delete;
};
}
#define MGP_PP_CAT2(a, b) a##b
#define MGP_PP_CAT(a, b) MGP_PP_CAT2(a, b)
#define MGP_FILL_FOR(Verb) \
::MobileGL::MG_Pipe::MGPipeVerbScope MGP_PP_CAT(mgpVerbScope_, __LINE__)(::MobileGL::MG_Pipe::MGPipeVerb::Verb)
#else
#define MGP_FILL_FOR(Verb) ((void)0)
#endif
MGPipeVerb is the generated verb enum (generated/PipeFillPoints.inc, D12), so in the stub state MGP_FILL_FOR only compiles in the pull arm — which is all the fill-points package can build anyway. Commit message for C0: [Feat] (Pipe): add the P1 strangler contract headers - MGB_CTX/MGB_CTX_PRESENT/MGB_CTX_IDENTITY in MG_Pipe/PipeStrangler.h and the MGP_FILL_FOR no-op in MG_Impl/Pipe/PipeFill.h.
B.2 Decisions
| # | decision | why / evidence |
|---|---|---|
| D1 | Two CMake options, both default OFF: MOBILEGL_PIPE_PUSH (→ -DMOBILEGL_PIPE_PUSH=1, selects the alias arm) and MOBILEGL_PIPE_VERIFY (→ -DMOBILEGL_PIPE_VERIFY=1; forces MOBILEGL_PIPE_PUSH ON with a message(STATUS)). The runtime MG_Config::Features.PipePush bitmap (Config.h:326) is not consumed in P1 (a P1 push build pushes every field of the verb's set at every fill point); the runtime Features.PipeVerify (Config.h:332, env MOBILEGL_PIPE_VERIFY) arms the comparators at run time inside a verify build and does nothing in any other build. |
Resolves scout R3: the #if in ARCHITECTURE.md:334 is the CMake macro; the bitmap is phase B's per-field yield (P2). Verify without push is meaningless: the poison lives in the accessors, which only exist in the push arm. |
| D2 | Namespaces and paths. struct PipeInputs and gPipeInputs live in namespace MobileGL::MG_Pipe (the doc's spelling ::MobileGL::MG_Pipe::gPipeInputs, ARCHITECTURE.md:331) and are declared in MobileGL/MG_Backend/MGPipe/PipeInputs.h (the doc's path, :325,:553), defined in MobileGL/MG_Backend/MGPipe/PipeInputs.cpp. The frontend-facing half (SnapshotFromGLContext, the fillers, MGPipeVerbScope, knob parsing, init) lives in MobileGL/MG_Impl/Pipe/PipeFill.{h,cpp} — the directory P2's tracker joins (ROADMAP.md:18 MG_Impl/Pipe/Tracker). MGPipeImpl_DirectGLES/DirectVulkan.cpp from the layout table ARCHITECTURE.md:553 are not created in P1 (they are the server-side table implementations, P5+); the integrator corrects the table cell to PipeInputs.h + PipeInputs.cpp [P1+]. |
Gate C: nothing under MG_Backend/ spells pGLContext after P1 (the pull arm's token lives in MG_Pipe/PipeStrangler.h, the filler in MG_Impl/). Gate A at P13 keeps MG_State includes for verify builds only. |
| D3 | Pull build is byte-for-byte the P0.5 library. Every new .cpp (PipeInputs.cpp, PipeFill.cpp) is wrapped whole in #if MOBILEGL_PIPE_PUSH … #endif (banner outside, everything else inside — no includes reachable in the pull arm); MGP_FILL_FOR is ((void)0); the three config knobs (D18) are declared and parsed under #if MOBILEGL_PIPE_PUSH; the Init.cpp hook is #if MOBILEGL_PIPE_PUSH; PipeStrangler.h is macros only. |
G1/G2. |
| D4 | The 58 non-arrow lines convert as: 43 MOBILEGL_ASSERT(… pGLContext …) lines deleted (34 DirectVulkan.cpp, 9 UniformManager.cpp; no-ops in INFO builds, Defines.h:113-115; under push the block cannot be null); 5 bare if (MG_State::pGLContext) and 2 && MG_State::pGLContext compounds → MGB_CTX_PRESENT; 4 ternary conditions (Managers.cpp:7192/7200/7203, DirectVulkan.cpp:1284) → MGB_CTX_PRESENT ? MGB_CTX->X() : default; != nullptr at DirectVulkan.cpp:1236, VulkanRenderer.cpp:12766 → MGB_CTX_PRESENT; == nullptr at VulkanRenderer.cpp:11267 → !MGB_CTX_PRESENT; the .get() at DirectGLES.cpp:147 → MGB_CTX_IDENTITY (with :144/:150, B.11); the comment VertexInputStateFactory.h:133 reworded. Exact per-line text in B.11. |
ARCHITECTURE.md:344 (~34 assert deletions, 7 guards, 3 ternaries, .get()+decltype, 14 != nullptr, 1 comment; the 9 UniformManager asserts are the doc's != nullptr overlap). Pull codegen identical: unique_ptr::operator bool is get() != nullptr. |
| D5 | Every accessor keeps the exact GLContext signature (name, parameters, return type, const-ness — Core.h lines in B.4). MGB_CTX->X(args) is therefore the only edit at 277 sites (sed 's/MG_State::pGLContext->/MGB_CTX->/g'), and GetRenderStateParameters() returns const RenderStateParameters& so SyncRenderState is untouched (GO/NO-GO item 2, ROADMAP.md:47). |
ARCHITECTURE.md:328 "阶段 A:类型与后端今天读到的完全一致". |
| D6 | Storage kinds (B.4 has the per-field assignment). (V) value copy: the accessor's result is copied into a PipeInputs member at fill and returned from the copy; the 1168-byte RenderStateParameters copy is the only memoised one — copied only when GetRenderStateParametersVersion() changed since the last fill (Espryt's own early-out trusts that version, DirectGLES.cpp:2026), stamped every time. (H) shared-pointer copy: SharedPtr copied at fill (GetBoundVertexArray, GetProgramForDraw, GetProgramForDispatch, GetTransformFeedbackProgram). (R) reference capture: for the five accessors returning a mutable reference into a frontend container, PipeInputs stores the container base pointer(s) captured at fill and the accessor indexes them, returning the same live reference the backend reads today (GetBufferBindingSlot — one pointer per GlobalBufferTargets entry; GetBufferBindingPoint — one base pointer per BufferBindPointTargets entry into the contiguous Array<BindingSlotRange1D<BufferObject>, 84> (BufferState.h:73); GetFramebufferBindingSlot — two pointers; GetTextureUnitObject — base of Array<TextureUnit, 192> (TextureState.h:128); GetImageTextureBinding — base of Array<ImageTextureBinding, 192> (:129)), plus GetCurrentVertexAttribute (base of the 32-entry Array<CurrentVertexAttributeValue, 32>, Core.h:513, replicating the out-of-range branch at Core.cpp:246-250). (P) pass-through: six accessors that are not pipe data forward to the frontend through a resolver (D8). No accessor derives its value from another field (no re-implementation of RenderState logic inside PipeInputs): the cost is ~1 KB of copies per verb in the push build, which P2's tracker replaces. |
Type identity for references cannot be met by a copy (GetImageTextureBinding returns ImageTextureBinding&; the backend only reads through it — DirectGLES.cpp:1728-1745, UniformManager.cpp:1016-1030, VulkanRenderer.cpp:9214-9224 verified — but a copy would still break .Bind() semantics if ever used). Derivation would duplicate RenderState.cpp rules (IsCapabilityEnabledIndexed at RenderState.cpp:471-490 has three branches); copying the accessor result cannot be wrong. Size: sizeof(PipeInputs) < 4 KiB (static_assert(sizeof(PipeInputs) <= 8192)), well under the doc's ~20 KB. |
| D7 | Poison = per-verb generation, exactly the P0 skeleton (PipeFilled.inc:293-307): PipeInputs embeds MGPipeFilledState m_filled plus MGPipeVerb m_currentVerb and Uint32 m_verbDepth. A fill stamps FilledGen[f] = CurrentVerbSerial. Every non-pass-through accessor begins with MGP_POISON_CHECK(Field) = if (!MGPipeInputFieldIsFresh(m_filled, Field)) MGPipeInputPoisonFatal(Field, CurrentVerbName()) under MOBILEGL_PIPE_POISON (D9). kMGPipeInputFieldSticky[] stays all false in P1: no sticky field was needed once the six pass-throughs stopped being poison fields (D8). |
ARCHITECTURE.md:349; scout R5 (each true must be argued — none is). |
| D8 | Six pass-through accessors declared in a new MGP_COVERAGE_PASSTHROUGH_LIST(X) in Coverage.def: GetProgramObject(Uint), GetTextureObject(Uint) (by-name lookups, Track H residue), HasOpenTransformFeedbackSpan(Uint64) (a query over the TF object table, XFB is P9), ValidateProgramName(Uint), InvalidateCompileEnv() (kClientResolved), RecordError(...) (kReverseChannel). They keep their MGPipeInputField ids (the enum stays "one id per accessor") but are neither stamped, poison-checked, compared, nor members of any fill set. They forward through GLContext* PipeInputs::Frontend() = m_frontendResolver() — a function pointer installed by MG_Impl::Pipe::Init() (D19) — with the same null tolerance the guarded pull sites had (if (auto* c = Frontend()) c->InvalidateCompileEnv();). FrontendIdentity() returns static_cast<const void*>(Frontend()). |
PipeInputs.h must not spell pGLContext (gate C); InitCapabilities (BackendObject_DirectVulkan.cpp:388-389) runs before any verb. |
| D9 | MOBILEGL_PIPE_POISON is derived in PipeInputs.h, not a CMake option: `#define MOBILEGL_PIPE_POISON (MOBILEGL_PIPE_VERIFY |
|
| D10 | Verb scope semantics (MGPipeVerbScope, push builds): ctor — if (m_verbDepth++ == 0) { ++CurrentVerbSerial; m_currentVerb = verb; } then SnapshotFromGLContext(gPipeInputs, kMGPipeFillSets[kMGPipeVerbClass[verb]], *pGLContext, verb) (fills + stamps the class's set; skips the stamp of the field named by the omission knob when verb matches), then, if Features.PipeVerify, the verb-level compare (D11). dtor — if (--m_verbDepth == 0) { ++CurrentVerbSerial; m_currentVerb = MGPipeVerb::kNone; }. Nested scopes (e.g. glEndTransformFeedback → EndTransformFeedback then FenceSync, GL_Drawing.cpp:1322-1336) fill into the enclosing verb without re-bumping. Closing the verb bumps the serial, so a field read outside any verb — including from a backend path no fill point covers — is Fatal{UnmigratedPipeInput, "<Field>@<outside any verb>"}: that is how a missing fill point is found (D.3). |
PipeFilled.inc:19-23: the poison must see "filled by the previous draw, read by the glTexSubImage that follows". |
| D11 | What the comparator compares and where it runs (verify builds, Features.PipeVerify set): (a) verb-level: at every fill point, after the fill, SnapshotFromGLContext(scratch, set, ctx, kNone) then MGPipeVerifyInputs(gPipeInputs, scratch, set, &field) over the verb's fill set; (b) read-level: every non-pass-through accessor, after the poison check, re-pulls the one field (argument-scoped: the unit, target, index asked for) into a thread-local scratch through SnapshotFromGLContext and compares it to the stored value. Per-field equality is MGPipeFieldEqual from PipeVerify.inc (float bitwise) for value fields, raw-pointer equality for (H), and a POD digest for (R): {bound.get(), GetVersion()} per slot, {base pointer, per touched point: bound.get(), GetRange()} for bind points, {per unit ≤ GetMaxTouchedTextureUnit(): 12 bound-texture pointers + sampler pointer} for texture units, {Texture.get(), Level, Layered, Layer, Access, Format, Version} per image unit, the 32 values for current attributes. A difference is MGLOG_F("MGPipe: Fatal{PipeVerifyDiffer, \"%s@%s\", verb=%llu}", field, verbName, serial) followed by std::abort() unless Features.PipeVerifyFatal == false (log and count). In P1 the pushed value and the snapshot come from the same source, so the comparator proves the harness, the fill-point placement (a frontend mutation between the fill and the read is red) and — through the corruption knob — its own sensitivity; P2's tracker is what gives it teeth. |
ARCHITECTURE.md:501; Config.h:327-332. Retention mode (texture dirty rects) is P3b, not P1. |
| D12 | Fill tables are data, generated. New hand-maintained MobileGL/MG_Pipe/FillPoints.def (B.8) with MGP_FILL_CLASS_LIST(X), MGP_FILL_VERB_LIST(X) (X(Verb, Class, Table), 71 rows: the 69 function-pointer members of GLFunctionsTable, BackendObject.h:117-289, plus Present/SetSwapInterval from GlobalBackendFunctionsTable, :293-300) and MGP_FILL_SET_LIST(X) (X(Class, Field)). gen_pipe.py grows G5b gen_fill_points → generated/PipeFillPoints.inc (included from MGPipe.h after PipeFilled.inc): enum class MGPipeVerb : Uint8 { …, kNone, kVerbCount }, kMGPipeVerbNames[], enum class MGPipeVerbClass : Uint8, kMGPipeVerbClass[], kMGPipeVerbClassNames[], struct MGPipeFieldSet { Uint64 Words[(kMGPipeInputFieldCount + 63) / 64]; constexpr Bool Has(MGPipeInputField) const; }, kMGPipeFillSets[kMGPipeVerbClassCount], and MGP_FILL_VERB_MEMBER_CHECK (expands to (void)&::MobileGL::MG_Backend::GLFunctionsTable::<Verb>, … / GlobalBackendFunctionsTable::Present — a test TU instantiates it, so a verb name that is not a table member is a compile error). Validation in both modes: every verb's class is declared; every set field is a non-pass-through accessor; every non-pass-through accessor is in ≥ 1 set; verb count == MGP_FILL_VERB_DOCUMENTED_COUNT 71. |
ARCHITECTURE.md:348 ("G5 从 PipeCalls.def 生成…可能读哪些字段"); the inverse relation is not derivable from Coverage.def (scout-generated §10.3), so it is a new source of truth. |
| D13 | Verb classes (9): Draw (20), Dispatch (4), Clear (9), BlitOrCopy (3), TextureOp (4), Readback (3), XfbSpan (6), Query (4), Passive (18). B.8 lists the members and the initial field sets. The doc's eight validate entries map onto the first eight; Passive collects the entries that read nothing (sync, timer, occlusion, GetIntegeri_v, PatchParameteri, ShaderStorageBlockBinding, DeleteBackendQuery, IsTimerQuerySupported, GetGpuTimestampNs, Present, SetSwapInterval) and still bumps the serial. |
ARCHITECTURE.md:153. |
| D14 | Coverage.def changes: delete row X(GetBoundTransformFeedbackName, SetStreamOutputTargets) (Coverage.def:34); add X(GetBoundTransformFeedbackLifetimeId, SetStreamOutputTargets) and X(HasOpenTransformFeedbackSpan, SetStreamOutputTargets) in alphabetical position; add MGP_COVERAGE_PASSTHROUGH_LIST(X) (six X(Accessor, Reason) rows, D8) and MGP_COVERAGE_RETIRED_LIST(X) with one row X(GetBoundTransformFeedbackName, SetStreamOutputTargets, "D21 rekey (bd2b4158) replaced the name with the lifetime id + open-span query; inventory row VulkanRenderer.cpp:11137"). G6 joins retired names as mapped (so kMGPipeInventoryUnmapped stays 0 and PipeCatalogueTest.cpp:213 keeps 477); G5 excludes them from the enum. The GetBufferBindingSlot split by target (Coverage.def:36-39) stays a comment: in P1 the field is keyed by BufferTarget inside PipeInputs; the split into four wire calls is a P5 concern. |
Correction 4/7. |
| D15 | Live cross-check check_live_accessor_set() in gen_pipe.py (both modes): scan MobileGL/MG_Backend/**/*.{cpp,h} for \b(?:pGLContext|MGB_CTX)\s*->\s*(\w+) (comments masked with the same masker gen_pipe_dirty_surface.py:46-85 uses — copy the function); the set of names must equal ACCESSOR_LIST ∪ PASSTHROUGH_LIST; any retired name found live, any live name not listed, or any listed name not found is sys.exit. This is what makes PipeCatalogueTest's 62 a fact about HEAD instead of about the vendored snapshot. |
Scout-generated §10.1 drift. |
| D16 | Field lists for the four memcmp-fallback types land in PipeFields.def: MGP_FIELDS_RenderStateParameters (every member of MGPipeValueTypes.h:239-…, in declaration order), MGP_FIELDS_PixelStoreParameters (8), MGP_FIELDS_PerBufferBlendState (7), MGP_FIELDS_StencilFaceState (7), MGP_FIELDS_DynamicBackendParameters (every data member of BackendObject.h:316-549, 84 lines match the member regex — enumerate by reading), MGP_FIELDS_MGHostSpan (MGPipeHostSpan.h:126-137). MEMCMP_FALLBACK_TYPES becomes empty and the fallback branch is deleted from gen_verify — a payload member without a field list is then a compile error in PipeVerify.inc, which is the "comparator coverage asserted" promise of PipeFields.def:15-17. Two dispatcher additions in gen_verify: std::array<T, N> iterates like the C-array overload; the Vec types (VecBase::operator== at VectorTypes.h:41 is IEEE ==, so a NaN patch level would false-DIFFER) compare bitwise through a trait MGPipeIsBitwiseComparable<T> specialised for FloatVec2/3/4, IntVec4, UintVec4, BoolVec4 (all padding-free). |
Scout R7; PipeVerify.inc:9-23 NaN rule; P0.5 D8 deferred exactly this. |
| D17 | PipeCatalogueTest edits: :225 61 → 62; new expectations that kMGPipeVerbCount == 71, kMGPipeVerbClassCount == 9, MGP_FILL_VERB_MEMBER_CHECK compiles, every non-pass-through field is in ≥ 1 fill set, kMGPipeVerifiedPayloadCount == 69 (63 + 6). |
|
| D18 | Three new runtime knobs, declared in Config.h after PipeVerify and parsed in ConfigLoader.cpp after :246, all under #if MOBILEGL_PIPE_PUSH: Bool PipeVerifyFatal = true (MOBILEGL_PIPE_VERIFY_FATAL, QueryEnvQuirkOverride(...) != ForceOff), String PipeVerifyCorrupt (MOBILEGL_PIPE_VERIFY_CORRUPT=<FieldName>, perturbs the snapshot arm's field after every snapshot), String PipePoisonOmit (MOBILEGL_PIPE_POISON_OMIT=<VerbName>:<FieldName>, skips the stamp — not the value — of that field when that verb fills). Names are validated against kMGPipeInputFieldNames / kMGPipeVerbNames at MG_Impl::Pipe::Init(); an unknown name is MGLOG_F + std::abort() so a typo cannot disarm a control. |
scout-test-infra B3/B4. |
| D19 | Init: MobileGL/Init.cpp calls MG_Impl::Pipe::Init() right after MG_Util::PipeStats::Init() (Init.cpp:114), under #if MOBILEGL_PIPE_PUSH. It installs gPipeInputs.m_frontendResolver = +[] { return ::MobileGL::MG_State::pGLContext.get(); }, parses/validates the knobs, and logs once: MGLOG_I("MGPipe: push arm active: %u fields, %u verbs, %u classes; verify %s (fatal=%d)", …, Features.PipeVerify ? "armed" : "off", …). The exact substring the harness greps is MGPipe: verify armed (emitted only when Features.PipeVerify). A pull library never prints it, which is what fails a verify lane run against the wrong binary. |
scout-test-infra A3 arming idiom. |
| D20 | Third CI mode = job build-linux-verify (build-linux's steps with BUILD_DIR: build-linux kept — so the tarball layout is identical — plus -DMOBILEGL_PIPE_VERIFY=ON, own ccache key, artifact mobilegl-linux-runtime-verify), job integration-verify (ctest -L integration-verify --no-tests=error on that runtime, plus the two inverted negative-control steps), job retrace-verify (the retrace matrix shape, unpacking the verify tarball so build-linux/libMobileGL.so is the verify library, export MOBILEGL_PIPE_VERIFY=1, ctest --timeout 10800, timeout-minutes: 300; matrix = the 8 "verify": true cases by default, the full 77 when workflow_dispatch input verify_retrace=full), and run_trace_case.cmake's arming/divergence check. remove-artifact-clutter gains retrace-verify in needs. MOBILEGL_BUILD_DISAGGREGATED stays OFF in the verify build (poison comes from D9). |
scout-test-infra B1/B2; ENVIRONMENT-property trap (test.yml:252-259, MG_IntegrationTest/CMakeLists.txt:339-344). |
| D21 | Integration registrations (in MG_IntegrationTest/CMakeLists.txt, inside if (MOBILEGL_PIPE_VERIFY)): DirectGLES.Verify. / DirectVulkan.Verify. (all scenarios; LABELS integration-gpu integration-verify; TIMEOUT 900; env = backend + MOBILEGL_PIPE_VERIFY=1 + MOBILEGL_LOG_FILE_PATH=<binary dir>/pipe-verify-<backend>.log + the mandatory ${MGL_ITEST_COMMON_ENV} / ${MGL_ITEST_VULKAN_ENV} tail), *.VerifyCorrupted. (filter PipeVerifyArmingScenario.CorruptedFieldIsReported; adds MOBILEGL_PIPE_VERIFY_CORRUPT=GetRenderStateParameters and MOBILEGL_PIPE_VERIFY_FATAL=0), *.PoisonOmission. (filter PoisonOmissionScenario.*; adds MOBILEGL_PIPE_POISON_OMIT=GenerateMipmap:GetTextureUnitObject). Name parity: DirectGLES.Verify.<Suite>.<Case> ↔ DirectGLES.<Suite>.<Case>. |
ARCHITECTURE.md:503 by-name parity; 120 s TIMEOUT property cannot be raised by ctest --timeout (:393). |
| D22 | SnapshotFromGLContext signature: void SnapshotFromGLContext(PipeInputs& out, const MGPipeFieldSet& fields, MG_State::GLState::GLContext& ctx, MGPipeVerb omissionContext); declared in PipeInputs.h, defined in MG_Impl/Pipe/PipeFill.cpp. Its two callers are the two branches P13 talks about: the filler (MGPipeVerbScope, deleted at P13 with the tracker in place) and the comparator (kept). |
ARCHITECTURE.md:369. |
| D23 | Ownership of the 26 sync sites in P1: no code change. Every SyncPersistentMappedRange()/SyncGpuWrites() call stays where it is; the BufferObject it is called on is reached through an aliased or copied field, so the calls are unaffected by the arm. The deliverable is the table docs/Disaggregated/SYNC_SITES.md (B.12): per site, the verb class whose scope contains it, the §5.7 reconcile row it implements, and the phase that moves it. The *IndirectCount sites keep "only SyncPersistentMappedRange" verbatim (ROADMAP.md:88). |
ARCHITECTURE.md:294. |
| D24 | PipeStats counters are untouched: the AccessorCalls tallies (PipeStats.cpp:15-100 contract) count reads in either arm. The counter names are pinned by PipeStatsTest.CounterNamesAreStable. |
|
| D25 | Threading: gPipeInputs is a single global for the single GL thread (pGLContext is one global); the only backend reads that can run off the GL thread are pass-throughs (RecordError). AttachPassthroughTessControlStage (Managers.cpp:7184, reads patch state) runs from SyncToBackend at :8070 on the GL thread inside SyncCurrentProgram (a Draw). Package B re-confirms that call chain while converting the site. |
|
| D26 | Documentation is integrator-owned (D.6); packages do not edit docs/. feat/disaggregated stays off the push triggers (test.yml:3-9); CI runs are workflow_dispatch. |
P0.5 D10. |
B.3 PipeInputs shape (core writes this; the accessor list is the whole 62)
// MobileGL/MG_Backend/MGPipe/PipeInputs.h
#pragma once
#ifndef MOBILEGL_MG_BACKEND_MGPIPE_PIPE_INPUTS_H
#define MOBILEGL_MG_BACKEND_MGPIPE_PIPE_INPUTS_H
#include <MG_Pipe/MGPipe.h> // field ids, verbs, fill sets, poison helpers, comparators
#include <MG_Pipe/PipeStrangler.h>
#if MOBILEGL_PIPE_PUSH
#include <MG_State/GLState/Core.h> // phase A: the accessor types ARE the frontend's types.
// Gate A (P13) keeps this include in verify builds only.
#define MOBILEGL_PIPE_POISON (MOBILEGL_PIPE_VERIFY || MOBILEGL_BUILD_DISAGGREGATED || (MOBILEGL_LOG_ACTIVE_LEVEL <= MOBILEGL_LOG_LEVEL_DEBUG))
namespace MobileGL::MG_Pipe {
using MG_State::GLState::GLContext; // etc.
struct PipeInputs;
void SnapshotFromGLContext(PipeInputs& out, const MGPipeFieldSet& fields, GLContext& ctx, MGPipeVerb omissionContext);
Bool MGPipeVerifyInputs(const PipeInputs& pushed, const PipeInputs& snapshot, const MGPipeFieldSet& fields, const char** outField);
void ApplyVerifyCorruption(PipeInputs& snapshot, MGPipeInputField field);
struct PipeInputs {
// ---- accessors: 62, signatures verbatim from Core.h (B.4) ----
Int GetActiveTextureUnit() const; // V
const FloatVec4& GetBlendColor() const; // V
void GetBlendEquationIndexed(Uint, BlendEquation&, BlendEquation&) const; // V (stored per draw buffer)
…
BindingSlot<BufferObject>& GetBufferBindingSlot(BufferTarget); // R
BindingSlotRange1D<BufferObject>& GetBufferBindingPoint(BufferTarget, Uint); // R
TextureUnit& GetTextureUnitObject(Int); // R
ImageTextureBinding& GetImageTextureBinding(Int); // R (+ const overload)
const CurrentVertexAttributeValue& GetCurrentVertexAttribute(Uint) const; // R
const SharedPtr<VertexArrayObject>& GetBoundVertexArray(); // H
…
const SharedPtr<ProgramObject>& GetProgramObject(Uint); // P
void RecordError(ErrorCode, UniquePtr<ErrorInfo>); // P
// ---- identity / pass-through plumbing ----
GLContext* Frontend() const { return m_frontendResolver ? m_frontendResolver() : nullptr; }
const void* FrontendIdentity() const { return Frontend(); }
const char* CurrentVerbName() const;
// ---- storage (public: PipeFill.cpp fills it; the unit test corrupts it) ----
GLContext* (*m_frontendResolver)() = nullptr;
MGPipeFilledState m_filled{};
MGPipeVerb m_currentVerb = MGPipeVerb::kNone;
Uint32 m_verbDepth = 0;
Uint m_renderStateVersionCopied = ~0u; // memo key of the 1168-byte copy
RenderStateParameters m_renderState{};
… (one member per field, B.4)
};
extern PipeInputs gPipeInputs;
static_assert(sizeof(PipeInputs) <= 8192, "PipeInputs grew past the P1 budget; a field moved to the wrong storage kind");
}
#endif
#endif
Accessor body pattern (generated by hand, one per field; the macros live in PipeInputs.h):
inline const FloatVec4& PipeInputs::GetBlendColor() const {
MGP_POISON_CHECK(GetBlendColor); // no-op unless MOBILEGL_PIPE_POISON
MGP_VERIFY_READ(GetBlendColor); // no-op unless MOBILEGL_PIPE_VERIFY && Features.PipeVerify (read-level compare, D11 b)
return m_blendColor;
}
MGP_VERIFY_READ for an argument-taking accessor passes the argument so the re-pull is scoped (MGP_VERIFY_READ_ARG(GetTextureUnitObject, unit)); the implementation is PipeInputs::VerifyRead(field, …) in PipeInputs.cpp, which calls SnapshotFromGLContext(tls_scratch, MGPipeFieldSet::Of(field), *Frontend(), MGPipeVerb::kNone) and then the per-field compare.