MobileGL/docs/archive/notes/p5/scout-gpu-writes-and-persistent-map-push.md

P5 scout — GPU-written tracking and the persistent-map push

Tree read: /home/swung/w7/pipe, branch feat/disaggregated @ a29807cc (P4a landed). READ ONLY — nothing was edited, built or run. Every line number below was opened in this tree at that commit. Repo-relative paths are under MobileGL/ unless they start with docs/ or tools/.

P5's row is docs/Disaggregated/ROADMAP.md:21. The design of record for this subject is docs/Disaggregated/ARCHITECTURE.md sections 8.1 (lines 275-290), 8.2 (292-294) and 12 (479-502).

---

PART 1 — MarkGpuWritten / SyncGpuWrites

1.1 What they mean today

BufferObject::MarkGpuWritten() — MG_State/GLState/BufferState/BufferObject.cpp:364-367. Three lines, and it sets two flags:

m_hasDefinedContent = true;
m_gpuWritePending   = true;

Declared BufferState/BufferObject.h:185; the flag's own comment is at BufferObject.h:267 ("Set by MarkGpuWritten, cleared by SyncGpuWrites once the shadow is refreshed"). The contract at BufferObject.h:180-184: "the flag only says a GPU write is outstanding" — whether the answer is a pull-back or a wait is the backend's business.

BufferObject::SyncGpuWrites() — BufferObject.cpp:369-395:

• :370 early-out when !m_gpuWritePending;
• :372-374 clears the flag unconditionally, with the reason stated: "without a readback op the shadow can never catch up, and retrying on every subsequent read would only repeat the same no-op";
• :375-387 under MOBILEGL_PIPE_PUSH + MGPipeResourceSubsystemEnabled(): MGPipeEmitResourceReadback(*this) (:384) and return. The comment at :376-381 is the one P5 has to honour verbatim: the answer comes back through OnBufferWriteback, and "in monolith the whole sequence is synchronous inside the applier, so the caller sees the reconciled shadow on return".
• :389-394 legacy arm: g_bufferBackendOps->ReadbackFromGpu(*this).

1.2 The six producer sites (all backend-side today)

ARCHITECTURE.md:280 says "6 处 MarkGpuWritten". They are:

Espryt (3), all in MG_Backend/DirectGLES/DirectGLES.cpp:

line	function	what it means
DirectGLES.cpp:556-572	MarkShaderStorageBuffersGpuWritten	every SSBO binding point, once the points are bound and the draw/dispatch is about to go out. Push arm MarkBufferGpuWritten(obj) :566; pull arm obj->MarkGpuWritten() :570
DirectGLES.cpp:573-620	SyncAtomicCounterBuffers	every bound atomic counter (:616 push / :618 pull). Reason at :611-614: every conformance case reads the increment back with glMapBufferRange/glGetBufferSubData
DirectGLES.cpp:2588-2606	MarkWritableImageBufferTexturesGpuWritten	buffer textures on image units, only when Access != GL_READ_ONLY (:2578-2581), and deliberately from the draw/dispatch preparation and not from glBindImageTexture's eager sync (:2583-2586)

Magma (3):

line	function	what it means
MG_Backend/DirectVulkan/Renderer/UniformManager.cpp:1073-1076	ResolveStorageTexelBufferDescriptor	EnsureGpuResidentStorage() then MarkGpuWritten(), again only when Access != GL_READ_ONLY
UniformManager.cpp:1229-1231	ResolveStorageBufferDescriptor	SSBO block: EnsureGpuResidentStorage() then unconditional MarkGpuWritten()
Renderer/VulkanRenderer.cpp:11617-11618	BeginXfbCaptureForDraw	the XFB capture targets — "the capture is a GPU write like any shader's"

The push-arm funnel is one function: BufferImpl::MarkBufferGpuWritten — MG_Backend/DirectGLES/Managers.cpp:2509-2540. Three things there are contract:

• :2511-2514 with the subsystem off it falls straight through to bufferObject->MarkGpuWritten();
• :2516-2528 with the subsystem on and either the handle or gMGPipeCallbacks.OnGpuWritten missing it deliberately does not fall back — it logs MGLOG_E_ONCE and drops the announcement, so the A/B can see it;
• :2530-2539 the announcement is one range of {0, kMGPipeWholeBuffer}, never zero ranges, and the comment at :2533-2536 states the other half of the contract: the client's OnGpuWritten must set both m_hasDefinedContent and m_gpuWritePending, or the next resource_respecify carries HasDefinedContent = 0, Ops_H_Respecify orphans instead of uploading, and the shader-written contents are dropped with nothing saying so.

Handle lookup is HandleOfBuffer — Managers.cpp:2491-2502, which goes through the twin table's single-entry front memo (its comment names MarkBufferGpuWritten as one of the three hot callers).

1.3 The client half that already exists

MG_Impl/Pipe/ResourceTracker.h:583-604 — MGPipeClientOnGpuWritten:

• :584-592 asserts rangeCount == 1 && ranges != nullptr, and says why in as many words: "zero will mean a fully narrowed set — nothing is dirty at P8/P9", so a zero-range announcement must not be read as "mark the whole buffer".
• :593-599 an unresolvable handle is a dropped MarkGpuWritten, i.e. "a stale shadow read back as if it were current" — MGLOG_E_ONCE.
• :600 buffer->MarkGpuWritten().

Installed by MGPipeInstallClientResourceCallbacks — ResourceTracker.h:606-614, and only over a slot the backend did not claim.

ResourceTracker.h:577-581 states the direction: OnGpuWritten is a NARROWING channel — the client builds a conservative pending set at its own emission points and the callback only ever removes from it — but "P3a's implementation marks exactly what the three Espryt MarkGpuWritten sites mark today ... The narrowing itself is P8/P9's."

1.4 The consumers — where SyncGpuWrites is called

docs/Disaggregated/MEASUREMENTS.md:111 records the census as "SyncPersistentMappedRange / SyncGpuWrites = 20 / 6, 与计划一致". The six backend consumers:

• MG_Backend/DirectGLES/Managers.cpp:4922 — SyncFloat64AttributeAsFloat32 (legacy-memos arm only)
• MG_Backend/DirectGLES/DirectGLES.cpp:6186 — the primitive-restart rewrite's CPU read of the source EBO
• MG_Backend/DirectGLES/MultiDraw.cpp:512 — same shape, multi-draw rebase
• MG_Backend/DirectVulkan/Renderer/VulkanRenderer.cpp:3541, :4012, :4346

Frontend consumers (not in that 6 — they are inside the object / MG_Impl):

• BufferObject.cpp:451 and :466 — the two "no resident op" fallbacks inside LandBytesIntoResidentStore
• BufferObject.cpp:515 — FillSubData (a clear is ordered after earlier GPU writes)
• BufferObject.cpp:547 — CopyDataFrom, on the source
• BufferObject.cpp:561 — AcquireMemory (glMapBuffer)
• BufferObject.cpp:639 — AcquireMemoryRange, skipped for the one map shape that looks at nothing (non-persistent write map with an invalidate bit over an adopted store — :626-638)
• MG_Impl/GLImpl/Buffer/GL_Buffer.cpp:957 and :995 — GetBufferSubData_State / GetNamedBufferSubData_State

1.5 What "client-side conservative MarkGpuWritten" has to become

The whole of today's machinery runs backend-side: all six producers read backend-visible state (MGB_CTX->GetBufferBindingPoint(...) for Espryt, descriptor resolution for Magma). In a split build the backend is the server, so every one of those six is on the wrong side of the line for the decision the client has to make synchronously at SyncGpuWrites (BufferObject.cpp:369) when the app calls glMapBuffer or glGetBufferSubData. Asking the server "did you write this?" is a round trip the design forbids in steady state.

So P5 owes a client-side pending set. Five concrete consequences:

1. The set is built from state the client already owns. Each of the six sites has a client-side twin: SSBO binding points, atomic-counter binding points, image-unit bindings whose Access != GL_READ_ONLY, XFB targets. ARCHITECTURE.md:575 already names the component: MG_Remote/Client/... GpuWritePending [P5+].
2. Two producers are NEW at P5 and are not among the six. ARCHITECTURE.md:508 lists them under the zero-round-trip column: glReadPixels into a pack PBO becomes fire-and-forget + client-side MarkGpuWritten ("严格优于 monolith 的无条件停等"), and glEndTransformFeedback drops its unbounded fence wait and instead sets MarkGpuWritten on the capture targets. Both are client edits with no server participation.
3. The rangeCount == 1 assert at ResourceTracker.h:587-592 has to be revisited on the same day. It is the exact statement "a zero-range announcement is illegal"; the narrowing channel needs zero to become legal and to mean "nothing dirty". Two readings: (a) P5 keeps the assert because P5 only adds the client set and leaves the server announcement at whole-buffer, deferring the narrowing to P8/P9 as ResourceTracker.h:579-581 says; (b) P5 has to relax it because a client that already marked the buffer conservatively will get a server announcement it must be allowed to answer with zero. Reading (a) is what the docs say, and the ROADMAP row does not mention narrowing — the brief should say so explicitly, because a package that reads ResourceTracker.h:577-581 alone will assume it owns the narrowing too.
4. SyncGpuWrites clearing the flag unconditionally (BufferObject.cpp:372-374) does not survive a transport unchanged. Today there are two states (pending / not pending) and the clear is safe because the readback is synchronous inside the applier. Under split there is a third state — the readback was emitted and the answer has not arrived — which this function cannot express: if it clears and the reply is deferred, the shadow is silently stale for the object's life. ARCHITECTURE.md:509 lists "GPU-write pending 的 buffer 首次 CPU 读" among the unavoidable blocking points ("monolith 本来就 glFinish()"), so the intended shape is block until OnBufferWriteback lands, matching P5's "阻塞 read_pixels" row. The reverse-channel drain points the client must service while blocking are enumerated at ARCHITECTURE.md:472: glGetError, glGetQueryObject*, glClientWaitSync, glGetSynciv, eglSwapBuffers, glMapBuffer*/glGetBufferSubData/glCopyBufferSubData, and every iteration of every wait loop.
5. ARCHITECTURE.md:292-294 (section 8.2) is the ordering rule that makes this correctness and not performance: every WritebackFromBackend is followed by BumpBufferMutationEpoch(), and under split the epoch bump must be applied by the server after the writeback and before any later command that reads that handle — "反向通道需要与正向通道相同的有序保证". PipeApply.cpp:1815-1846 (MGPipeApplyResourceReadback) already states its half: no serial moves, and the hook is called synchronously so the writeback and the bump have both happened before the caller reads.

---

PART 2 — The persistent-map path, and what "block-granularity push" means

2.1 What P3a landed

Three adoption entry points, all of which call the same emitter under push:

site	trigger	line
BufferObject::TryAdoptLargeStorage()	every Respecify / AllocateImmutableStorage of a store >= 16 MiB	BufferObject.cpp:228-244; threshold kLargeBufferAdoptBytes = 16u*1024u*1024u at :229; emitter at :238
BufferObject::EnsureGpuResidentStorage()	backend-initiated (Magma calls it on the SSBO / texel-buffer / XFB paths just before MarkGpuWritten)	BufferObject.cpp:592-614; emitter at :603
BufferObject::AcquireMemoryRange()	the app's own glMapBufferRange(PERSISTENT|WRITE) without FLUSH_EXPLICIT	BufferObject.cpp:645-664; emitter at :657

All three are guarded against a live mapping (:233, :600-602) — adoption releases the CPU shadow and a live mapping may be that shadow, so freeing it under the application is a use-after-free (BufferObject.cpp:594-599). TryAdoptLargeStorage is additionally gated by MG_Config::Features.DisableLargeBufferAdoption (BufferObject.cpp:232, declared Config.h:208, env MOBILEGL_DISABLE_LARGE_BUFFER_ADOPTION at ConfigLoader.cpp:229).

SyncPersistentMappedRange() — BufferObject.cpp:341-353. It is the per-draw push for the emulated (non-adopted) persistent map only. Early-outs in order: not mapped :342; GPU-resident :346 ("this is the whole point of the persistent-map path — the per-draw whole-buffer re-upload that used to run here is gone"); not Persistent :347; not Write :348; FlushExplicit :349; empty range :350. Otherwise it calls NotifySubData(mappedRange) :352, which under push emits resource_subdata (BufferObject.cpp:82-94).

FlushMemoryRange → NotifyFlushMappedRange — BufferObject.cpp:97-115, emitting MGPipeEmitResourceFlushRange at :107 and carrying the application's real, unnormalised Flags<BufferMappingAccessBit> (:103-106; emitter MG_Impl/Pipe/PipeFill.cpp:736-748; applier MG_Pipe/PipeApply.cpp:1787-1813, with :1808-1812 repeating that merging the flags would take the upload shape decision away from the side that pays for it).

Wire + ops:

• MG_Pipe/PipeCalls.def:84 — X(MapPersistent, MGPHandleOnly, kScreen, kReplySlot|kOptional)
• PipeCalls.def:85 — X(UnmapPersistent, MGPHandleOnly, kScreen, kOptional)
• PipeCalls.def:137 — X(ResourceFlushRange, MGPFlushRange, kCtxObject, kNone)
• PipeApply.h:95-96 — void* (*MapPersistent)(MGPipeHandle res, Uint64 size, const void* seedBytes); and void (*UnmapPersistent)(MGPipeHandle res);
• applier PipeApply.cpp:1893-1927 / :1929-1953; client emitter PipeFill.cpp:772-786.
• UnmapPersistent has no producer and that is deliberate — PipeFill.cpp:764-771: there is no backend unmap hook to convert, PipeResource::ReleasePersistentMap() (from RedefineStorage, BufferObject.cpp:~155) tells the backend nothing, and emitting one would be new behaviour under D-J. MGPipeApplyUnmapPersistent is the only one of the four buffer-only calls with a kind discriminator, and it Fatals on a mistyped kind (PipeApply.cpp:1938-1946).

2.2 The three Espryt persistent-mapped rings

Managers.cpp:871-882 declares struct PersistentRing (store + retired + frameMarks + the immutable knobs). The three instances:

• g_uboRing — Managers.cpp:883, "Global-UBO ring", alignment taken from GL_UNIFORM_BUFFER_OFFSET_ALIGNMENT at store-creation time (fixedAlignment == 0, see :877-879).
• g_unpackRing — Managers.cpp:884-890, "Texture unpack ring".
• g_uploadRing — Managers.cpp:899-906, "Buffer upload ring", 4 MiB initial / 64 MiB max / 64-byte alignment (:830-832). Its rationale at :890-898 is the WAR story in one paragraph: Mali's glBufferSubData resolves the hazard by blocking in the call (osup_sync_object_wait) until every referencing job retires, which under 26.3's per-frame UBO and chunk-mesh SubData streams serialized whole frames (~1 fps while chunks stream); staging into this ring and issuing glCopyBufferSubData keeps the hazard on the GPU timeline where it is just job ordering.

Allocation discipline: monotone head/tail linear cursors (Managers.cpp:838-844), RingAllocate :3320, slow path :3343, RingOnPresent :3427, and the three per-present drains at Managers.cpp:3482/3500/3502 called from DirectGLES.cpp:12460-12462.

2.3 The >=16 MiB adoption story, and why P5 breaks it

BufferObject.cpp:206-227 is the primary source for the motivation and is worth quoting to the brief in full: Minecraft 26.3 streams chunk meshes into 128 MB vertex arenas with plain glNamedBufferSubData — the one write API with no synchronization hint — and on Mali every route that hands the driver a write into a busy mutable store either parks the calling thread (glBufferSubData, and glMapBufferRange even with GL_MAP_UNSYNCHRONIZED_BIT) or ghost-copies the whole destination on a driver worker (~167 ms per touched arena, the recurring in-world hiccup). Backing the arenas with immutable stores also kills the ghost but eagerly commits every arena's full extent (+hundreds of MB), which LMK'd the device.

Measured: MEASUREMENTS.md:87 — "≥16 MiB 可变 store 定义时采纳为 coherent persistent map 后 p99 163→21 ms、 稳态 40→115 fps、省 ~400 MB". Restated at ARCHITECTURE.md:481 with "整个 monolith 改造期一动不动 （D-B4），只有 IPC 那一步会打破它", and MEASUREMENTS.md:471 calls the number "没动过的东西是否真的没动" 的最直接读数. The P3a and P4a A/Bs both re-read it and both stayed in the 21-26 ms band: MEASUREMENTS.md:465 (3) (25.457 → 26.322, +3.4%) and MEASUREMENTS.md:598 (25.297 → 26.841, +6.1%).

Why a split build cannot keep it. MGPipeApplyMapPersistent returns a raw void* that the client stores as the store's base (m_resource.AdoptPersistentMap(base), BufferObject.cpp:238 / :605 / :658). Across a process boundary that pointer is meaningless. ARCHITECTURE.md:483-490 is the tier table; P5 runs at tier T2 (ARCHITECTURE.md:490: "AcquirePersistentMap 返回 nullptr，前端已在三处容忍" — those three places are exactly BufferObject.cpp:238, :603-606, :657-660) and at T2 the client-side push is mandatory (ARCHITECTURE.md:496: "client 侧 persistent map 推送三件套（T2 档强制，P5）"). T0/T1 are P11's (ROADMAP.md:28, MEASUREMENTS.md:23-34 for the spike-B evidence).

One genuine ambiguity for the brief. Under inproc the server is the same process, so MapPersistent could legitimately return a usable pointer and adoption would still work. Two readings:

• (a) P5's inproc keeps adoption alive and only exercises the push through a forced-T2 negative control;
• (b) P5 forces T2 even under inproc, so inproc and spawn are the same code path.

(b) is the reading the gates force, and this is the single most decision-shaped thing in this report: the P5 exit gate says "persistent-map-push 出数" (ROADMAP.md:21), and that counter is structurally zero if adoption survives — PipeStats.cpp:68-70 says so ("today a persistent map is a permanent address space donation ... so there is no push to count"). InProcessTransport.h:11-16 argues the same way from the other end ("It is not a test double ... inproc is a delivery mode of its own"). The knob that would express (a) as a negative control, MOBILEGL_IPC_ADOPT_TIER (ARCHITECTURE.md:494, :615), does not exist anywhere in the tree — a full-tree grep finds it only in those two doc lines. Evidence that would settle it beyond doubt: whether the brief wants LargeArenaAdoptionScenario (MG_IntegrationTest/Scenarios/LargeArenaAdoptionScenario.cpp:450) to stay green under inproc — it asserts an adoption happens, and it cannot be green at T2 and produce persistent-map-push bytes at the same time.

2.4 What has to cross, at what granularity

ARCHITECTURE.md:496-500 is the spec, three items. Restated concretely with the tree's own line numbers.

(1) A hasLiveHostWrites bit — zero new record kinds

ARCHITECTURE.md:498: the server only needs to know "does this resource have a live host writer right now", which is what IsBufferDrawClean is trying to say, so the bit rides on the ResourceRespecify / ResourceSubData payload.

The applier-side field already exists: MGPipeResourceRecord::HasLiveHostWrites, PipeApply.h:225, with the comment "ALWAYS FALSE IN P3a, AND WRITTEN BY NOBODY ... a verify build pins that it is false, so that phase cannot land a silent semantic change under it."

The wire field does not. MGPResourceDesc (MG_Pipe/MGPipeTypes.h:283-317, MGP_ASSERT_POD(..., 88) at :318) carries HasDefinedContent at :301 and ImageBindableHint at :302 but no live-host-writes bit; MGPSubData (MGPipeTypes.h:997-1010, MGP_ASSERT_POD(..., 72) at :1011) likewise. Both structs have free padding — MGPResourceDesc's Uint16 Pad0 at :303 and Uint32 Pad1 at :313; MGPSubData's Uint8 Pad0[3] at :1004 and Uint32 Pad1 at :1008 — so P5 can take a byte out of a pad and the size asserts do not move. But: MGPipeTypes.h:304-310 defines the storage-defining-vs-metadata rule, and a new bit is a metadata field (a respecify that moves only it must not force a reallocation ack or clear PendingUploads); it has to be added to the field list stated beside MGPipeResourceRespecifyNeedsAck (P4a ID-18 M4), or the first push of the bit costs a spurious reallocation.

The pins P5 must lift, all four of them:

• PinNoLiveHostWrites — PipeApply.cpp:839-850 (verify body) / :852 (no-op body), called at :883 (ApplyBufferWrite), :1630 (resource_respecify), :1804 (resource_flush_range), :1832 (resource_readback) and :1908 (map_persistent). PipeApply.cpp:1904-1907 names map_persistent as "THE ONE CALL A LATER PHASE ATTACHES THE PRODUCER TO".
• Managers.cpp:2669-2674 — MOBILEGL_ASSERT(!record->HasLiveHostWrites, "...P3a has no producer for it") inside IsBufferDrawCleanByHandle, plus the live if (record->HasLiveHostWrites) return false; at :2674.
• Managers.cpp:2675-2681 — the last frontend read in that function, frontend->IsMapped(). Its comment at :2643-2657 is written directly to P5: "The frontend read retires the moment P5 gives HasLiveHostWrites a producer, and it is the last frontend read in this function."
• The regression that comment records is the one P5 will re-commit if it gets this wrong: the first cut of the handle arm answered HasLiveHostWrites alone, an emulated persistent map read draw-clean forever, SyncPersistentMappedRange was never reached again, and the frame drew the last uploaded bytes with no diagnostic (Managers.cpp:2650-2655; unit gate MG_Test/SanityTest.cpp:4583, narrative :4566-4582).

(2) The dirty bytes, in blocks

ARCHITECTURE.md:499, restated concretely:

• The set: the tracker keeps m_livePersistentMaps = buffers that are Persistent + Write + not FlushExplicit + not GpuResident. That predicate is literally SyncPersistentMappedRange's early-out chain (BufferObject.cpp:346-349) read as a membership test. m_livePersistentMaps does not exist in the tree — the only hit is that doc line.
• The trigger: at every validate point, for every member reachable by this operation — VAO / index / indirect / UBO / SSBO / atomic / XFB target, i.e. "the union of the backend's 20 SyncPersistentMappedRange sites".
• The block size: MOBILEGL_IPC_PERSISTENT_BLOCK_KB, default 64 (ARCHITECTURE.md:499 and the env inventory at :615), i.e. 64 KiB blocks. The env var does not exist in the tree either (ConfigLoader.cpp has no such parse; the only MOBILEGL_IPC_* mention anywhere is in the docs).
• Keyed on: the buffer's MGPipeHandle + the block index within the mapped span (offset = blockIndex × blockBytes). The natural delivery vehicle is the existing resource_subdata record — no new record kind — which the client already splits by a destination-box cap through MGPipeForEachSubDataRecordRange (PipeFill.cpp:694-713; a record's offset caps at 2^31-1, :707-712).
• Phase 1 (P5): conservative — treat the whole mapped span as dirty and split it into blocks. Phase 2: precise — shadow-in-shm 64 KiB dirty bits with memcmp first (MOBILEGL_IPC_SHADOW_SHM, default 1 from Phase 2, ARCHITECTURE.md:615). ARCHITECTURE.md:499 grants Phase 2 the right to be pulled forward if Phase 1 is unacceptable on the Create/Flywheel fixtures, and calls it "计划里唯一允许因测量改变阶段顺序的地方".

The 20 sites, enumerated (I count 21 call lines in non-test code, not 20 — caveat below):

Espryt (9): DirectGLES.cpp:361 (ResolveIndirectCommandBytes), :6185 (primitive-restart source), :6439, :6440, :6541, :6542 (indirect-count draw + parameter buffer, two pairs); Managers.cpp:2817, :2994; MultiDraw.cpp:511.

Magma (12): DirectVulkan.cpp:281, :472, :796; UniformManager.cpp:2024; VulkanRenderer.cpp:3542, :3621, :4013, :7428, :12423, :12424; VkBufferManager.cpp:628, :679.

Caveat, flagged rather than resolved: MEASUREMENTS.md:111 records 20/6 as "与计划一致", and Managers.cpp:5047-5048 speaks of "the eleven Espryt SyncPersistentMappedRange / SyncGpuWrites sites" where my Espryt count is 9 + 3 = 12. Both published counts are one below mine, so one specific line is excluded by a convention I could not find — most likely DirectGLES.cpp:361, which is a shared helper rather than a draw-path site (guess). The evidence that would settle it is the per-site attribution table §5.7 that ARCHITECTURE.md:290 refers to ("20 处 SyncPersistentMappedRange + 6 处 SyncGpuWrites 按 §5.7 逐站点归属") — I did not find such a table in the tree, and the brief writer should not assume it exists.

(3) The ordering property the push must preserve

In monolith, SyncPersistentMappedRange → NotifySubData → MGPipeEmitResourceSubData is a memcpy on the same thread as the draw that immediately follows, so the bytes the app wrote before the draw call are the bytes the draw sees. Under split, the block push and the draw both travel on SEG_CMD, in order, so the ring preserves it — provided the push is emitted at the validate point and not lazily. A push that is deferred past the draw record is exactly the C-1 regression above, re-committed at the transport layer.

MOBILEGL_COHERENT_AS_FLUSH keeps working in split mode unchanged (ARCHITECTURE.md:502): the two coherent_as_flush: true Create fixtures take the same buffer path in split and monolith, which is the only reason a by-name comparison between them means anything.

---

PART 3 — The persistent-map-push counter

It already exists and does not need to be added. It needs to be WIRED.

• Enum member: MG_Util/Metrics/PipeStats.h:72 — PersistentMapPush, comment at :71 ("Bytes pushed because a persistently mapped range was published to the backend").
• Long name: PipeStats.cpp:171 — "persistent-map-push", in kByteClassNames.
• Short name: pmap — PipeStats.cpp:~203, kByteClassShort index 7 (the array reads "buf","tex","ubog","ubon","vtxc","idxc","icmd","pmap","resid"). That is the token that appears inside the summary line's bytes/f[...] bracket.
• Test pin: MG_Test/Util/PipeStatsTest.cpp:289 — EXPECT_STREQ(PS::NameOf(PS::ByteClass::PersistentMapPush), "persistent-map-push").
• Not wired, and the non-wiring is itself a contract: PipeStats.cpp:68-70 — "persistent-map-push Not wired in P0: today a persistent map is a permanent address space donation (D4/D-B4) that survives the whole monolith track, so there is no push to count until the IPC track breaks it." Repeated at ARCHITECTURE.md:619, which adds that the site inventory at PipeStats.cpp:16-100 "那份清单是契约" — so P5 must edit PipeStats.cpp:68-70 in the same commit that adds the AddBytes call, or the inventory is lying. Related: PipeStats.cpp:24-27 already says stage-buffer explicitly does not cover "bytes an app writes THROUGH a persistent map ... see persistent-map-push", so the two classes must not double-count.

Good news for G1: PersistentMapPush sits at PipeStats.h:72, i.e. before the #if MOBILEGL_PIPE_PUSH block that opens at :75 (guarding CsoBlobBytes at :84). It is already in both the pull and the push build, so wiring it resizes no array and moves no pull symbol.

mpr today, and how it differs

mpr is a different axis entirely — a CallClass, not a ByteClass:

• CallClass::MapPersistentRoundtrips — PipeStats.h:141, inside the #if MOBILEGL_PIPE_PUSH block that opens at :117; the rationale comment runs PipeStats.h:130-140. Doc correction for the brief: ARCHITECTURE.md:492 cites PipeStats.h:126 for this — that line number is stale at a29807cc; it is :141.
• Long name "map-persistent-roundtrips" (PipeStats.cpp:~178), printed as mpr= at PipeStats.cpp:443.
• Counted at the client emitter, PipeFill.cpp:781-784, behind PipeStats::Enabled(); the applier bumps its own copy first and unconditionally at PipeApply.cpp:1900.
• Definition: every MapPersistent EMISSION — mint OR decline. The reasoning is spelled out three times (PipeApply.cpp:1893-1901, PipeFill.cpp:776-780, ARCHITECTURE.md:492): counted as "round trips actually taken" it is 0 by construction in monolith and could never go red for the reason it exists; counted as attempts it is the same number in both modes, equals exactly "one per storage definition", and a regression that acquires per-draw shows up on the first window.
• Gates: StorageBufferRegrowScenario.cpp:255 (NStorageDefinitionsCostNMapPersistentRoundtripsNotOnePerDraw) and LargeArenaAdoptionScenario.cpp:450 (AnAdoptionCostsExactlyOneMapPersistentRoundtrip). Both skip outside their own ctest lane (StorageBufferRegrowScenario.cpp:172, LargeArenaAdoptionScenario.cpp:226).
• Device readings on file (MEASUREMENTS.md:465 (4)): 26.3 = 8 on both devices (first window 4, then 2+2 — all ≥16 MiB store definitions); sodium 1; rd12 and create-instancing 0; the P2 arm always 0.

The difference P5 must publish, in one sentence: mpr counts acquisition attempts (calls, one per storage definition, unchanged by the split), while persistent-map-push counts bytes the client had to ship because the acquisition was declined. They are anti-correlated: at tier T2 every MapPersistent declines, mpr stays exactly where it is today, and pmap goes from 0 to whatever the Phase-1 conservative push costs. A P5 run where pmap is still 0 has not reached T2 — see §2.3's ambiguity.

---

PART 4 — PersistentCoherentMapScenario

IT DOES NOT EXIST. A full-tree grep for PersistentCoherentMap returns exactly two hits, both docs: docs/Disaggregated/ARCHITECTURE.md:500 and docs/Disaggregated/ROADMAP.md:21. There is no such file in MG_IntegrationTest/Scenarios/ (85 scenario files; none matches) and no such name in MG_IntegrationTest/CMakeLists.txt. P5 must write it. The gate cannot "pass unchanged under inproc" because there is nothing to pass.

The spec, all of it, is ARCHITECTURE.md:500: map PERSISTENT|WRITE|COHERENT, write through the pointer, make no other GL call, draw, read back and check. "门从第一天就有" — it is meant to exist before the push does.

Shapes to copy from:

• MG_Test/SanityTest.cpp:4583 — TEST(DirectGLESBufferDrawProbe, ALiveHostMapKeepsTheHandleArmProbeDirtyBetweenTwoDraws), the unit-level version of exactly this hazard, with the narrative at :4566-4582 and an EsprytSlotTablesEnabled() skip at :4590. It builds the applier record by hand "because this case is about the PROBE".
• Scenarios/LargeArenaAdoptionScenario.cpp (adoption + mpr), Scenarios/StorageBufferRegrowScenario.cpp (per-definition roundtrips), Scenarios/ResidentIndexScenario.cpp:40 (names SyncPersistentMappedRange and the acquire/memo interaction), Scenarios/CrossFrameBufferScenario.cpp plus StreamedArenaScenario (the recycle cases MEASUREMENTS.md:523 names as the hedge for the two-arm flush ladder).

A trap to write into the scenario on day one. A scenario-sized buffer is far under the 16 MiB kLargeBufferAdoptBytes (BufferObject.cpp:229), so TryAdoptLargeStorage never fires — but AcquireMemoryRange's own adoption does fire for PERSISTENT|WRITE without FLUSH_EXPLICIT (BufferObject.cpp:655-661), subject only to whether the backend mints. So the same test lands in the adopted arm or the emulated arm depending on the driver (glBufferStorageEXT presence) and on the build, and those two arms exercise completely different code (SyncPersistentMappedRange returns at :346 in one and pushes at :352 in the other). MOBILEGL_DISABLE_LARGE_BUFFER_ADOPTION does not separate them — it is read only at BufferObject.cpp:232, inside TryAdoptLargeStorage. The scenario must assert which arm it is in, or it will silently test the wrong one on half the devices.

What it would newly catch under inproc: the client pushes blocks at validate points and the server applies them on mgl-srv-apply; a push that loses the race with its draw record turns the scenario red. That is exactly why the ROADMAP puts this gate in P5 and not in P11.

---

PART 5 — WAR / flush hazards that get harder when write and use are on different threads

All three named hazards are instances of the same shape: a shadow of driver/GPU state, kept on the thread that will use it. Split moves the use to mgl-srv-apply and leaves the write on the app thread. Two of the three get harder; the third is a role-isolation item, not a threading one.

5.1 The Mali SubData WAR stall and the three-tier flush ladder — gets harder

The ladder is documented at Managers.cpp:1047-1076 and implemented twice: FlushPendingRangesFrom(twin, hostBase, size) at Managers.cpp:1051 (the handle arm) and FlushPendingRangesNow at Managers.cpp:1316 (the pull arm, byte-frozen against 5cb826b0 by G1 — MEASUREMENTS.md:523 records why there are two, and ID-15 supersedes ID-13 on it; the in-tree note is at Managers.cpp:1162+).

Tiers, with their live conditions:

1. glMapBufferRange(WRITE | INVALIDATE_BUFFER-or-RANGE) + memcpy, taken when wholeBuffer or size >= kInvalidateRangeMinBytes = 128 KiB (Managers.cpp:1045, applied :1131-1143).
2. staging ring + glCopyBufferSubData (:1144-1152) — MOBILEGL_ESPRYT_DISABLE_INVALIDATE_FLUSH forces this tier as the map path's negative control (:1069-1070).
3. direct glBufferSubData (:1153), potentially stalling.

Stakes on file: 9 × 128 MB of ghosting per frame ≈ 380 ms, the measured 2-4 fps (Managers.cpp:1064-1070).

Why split makes it harder, three distinct edges:

• The bytes are the client's. Both arms read hostBase, which on the handle arm is the lambda liveHostBase re-evaluated at every use (Managers.cpp:2744-2748), precisely because two ordinary events move or free what an earlier base pointed at — a shadow resize (PipeResource::ResizeShadow is reserve+resize, so a grow past the reserve reallocates) and persistent-map adoption (the shadow is cleared and shrunk) — Managers.cpp:2739-2743. Under split the server cannot hold a pointer into the client's shadow at all, so "re-read at every use" necessarily becomes "snapshot into SEG_STAGE at emission", and the window between snapshot and apply is new.
• Tier 1's INVALIDATE_RANGE is a claim that the old bytes are dead, and it is only true if the bytes being copied are the newest. Managers.cpp:1126-1129 records that this edge has already drawn blood once: widening the map to page bounds "looked free and was not — the widened bytes clobbered GPU-written data (an SSBO counter beside the app's SubData) with the stale shadow". A late or widened snapshot taken on a different thread does the same thing, and unlike tier 3 it fails silently rather than by stalling.
• The flush granularity is deliberately not the union. Managers.cpp:1072-1076: ranges are flushed as queued because "bytes, not flush calls, are the cost axis here, and collapsing a scattered flush into its union re-copied nearly whole chunk-mesh arenas every frame". The 64 KiB block push of §2.4 is a different granularity policy landing on the same buffers, and the brief should say which one wins when both are live on one arena.

5.2 The g_uploadRing reset asymmetry — real, but probably not a live bug

OnBackendContextDestroyed (Managers.cpp:2583-2596) calls ResetRingForNewContext for g_uboRing (:2594) and g_unpackRing (:2595) and not for g_uploadRing (declared Managers.cpp:899-906).

Two readings:

• (i) a latent bug — the upload ring keeps a dead context's id and mappedPtr.
• (ii) harmless, and the eager pair is merely redundant — RingAvailable (Managers.cpp:3288-3299) lazily resets any ring whose store.contextGeneration != g_bufferContextGeneration (:3293-3295).

(ii) is right, and I checked it rather than guessing: every RingAllocate(g_uploadRing, ...) is guarded by a ringUsable computed from UploadRingUsableNow() → RingAvailable(g_uploadRing) in the same function — :1103 guards :1144, :1211 guards :1221, :1379 guards :1420, :1454 guards :1464; UploadRingUsableNow itself at :1035 and :1322 (one per arm). ResetRingForNewContext (Managers.cpp:912-925) also deliberately keeps store.generation across the wipe, because frame serials survive context recreation and a restarted counter could revalidate a stale per-program slot cache.

Why it still matters for P5. g_bufferContextGeneration is server state, and the re-open mechanism (BumpBufferMutationEpoch() at Managers.cpp:2573 and :2587) is server-local. A client that memoises "I already pushed blocks 3..7 of this arena" has no way to learn that the server's ES context died and its rings were dropped. Whatever epoch the client keys its push memo on must be re-opened by a server event on the reverse channel, not by a client-local counter. There is no callback for this in MGPipeCallbacks today — the ten are fixed and static_assert-pinned at MGPipeCallbacks.h:56-58 — so P5 either folds it into OnCapsInvalidated/OnSurfaceChanged or pays the eleventh-callback price that assert exists to make visible.

5.3 ScopedDefaultUnpackState::s_synced — a role-isolation item, not a threading one

Managers.cpp:5430-5491. The flag is a process-global static inline Bool at :5490, alongside five process-global value shadows (:5491-5496). EnsureShadowSynced (:5452-5470) pins the driver to the GL defaults (4/0/0/0/0/0) exactly once per process, and thereafter Apply (:5472-5480) is pure compare-and-set. The class comment (:5424-5429) states the invariant it rests on: "The backend unpack state is set ONLY by MobileGL's own save/restore helpers ... all of which restore to the resting default, so the shadow stays accurate."

Two consequences:

• The role-isolation audit undercounts. ARCHITECTURE.md:578 says MGPipe brings the process globals a role split must duplicate down from four (pGLContext, gBackendFunctionsTable, pActiveBackendObject, pDefaultFramebufferInfo) to two, and that this is "inproc 从'成本可疑的实验'变成'可交付形态'的直接 原因". s_synced plus its five value shadows is a sixth process global of exactly that kind, unnamed in that audit. In P5's reduced path the client role should never touch GL, so this is latent rather than live (guess — the P5 purity gates do not exist yet, so I could not check); it belongs on the brief's list regardless, because it is the shape those gates are meant to catch.
• It is never reset on context death. OnBackendContextDestroyed (Managers.cpp:2583-2596) resets the rings and the binding caches and not this. Benign today, because a lost context returns the driver to the GL defaults the shadow already claims; it stops being benign the day a server re-attaches to a context whose unpack state something else moved.

5.4 One more that the brief did not name, and that belongs on the list

IsBufferDrawClean / IsBufferDrawCleanByHandle do unlocked emptiness probes of two containers the apply side mutates: resource->pendingResidentWrites (Managers.cpp:2668, :2707) and resource->pendingRanges (:2676, :2712-2713), both flagged in-comment as "the same unlocked emptiness probe EnsureBufferResource's replay branch uses" (:2711-2712). Today the probe and the mutation are both on the context thread. With mgl-srv-io and mgl-srv-apply as two threads (ROADMAP.md:21) that is no longer automatic, and syncedChangeSerial is already an atomic read with acquire ordering (:2684) while these two are not.

---

Appendix — one-line answers

1. MarkGpuWritten = BufferObject.cpp:364; SyncGpuWrites = :369. Six backend producers (DirectGLES.cpp:570 / :618 / :2603, UniformManager.cpp:1075 / :1231, VulkanRenderer.cpp:11618), funnelled under push through Managers.cpp:2509, answered client-side at ResourceTracker.h:583. P5 must build the set client-side at its own draw/dispatch emission points, plus two new producers (glReadPixels→PBO and glEndTransformFeedback, ARCHITECTURE.md:508), and must give SyncGpuWrites either a third state or a block.
2. MapPersistent = PipeCalls.def:84 / PipeApply.cpp:1893; UnmapPersistent = :85 / :1929 (no producer, PipeFill.cpp:764-771); ResourceFlushRange = :137 / PipeApply.cpp:1787. Three rings g_uboRing / g_unpackRing / g_uploadRing at Managers.cpp:883 / :884 / :899. Adoption at 16 MiB (BufferObject.cpp:229), p99 163→21 ms (MEASUREMENTS.md:87). Split runs at T2 (ARCHITECTURE.md:490), push mandatory, 64 KiB blocks keyed on {MGPipeHandle, block index}, shipped as existing resource_subdata records, plus a hasLiveHostWrites metadata bit that exists in PipeApply.h:225 but not on the wire (MGPipeTypes.h:283 / :997 — use the pads at :303 / :1004).
3. The counter exists and is unwired: ByteClass::PersistentMapPush, PipeStats.h:72, short name pmap, inventory disclaimer at PipeStats.cpp:68-70 that P5 must edit. mpr is a call class (PipeStats.h:141, not :126 as ARCHITECTURE.md:492 says) counting acquisition attempts; it is unchanged by P5 and anti-correlated with pmap.
4. PersistentCoherentMapScenario does not exist — docs only. Spec at ARCHITECTURE.md:500; nearest relative SanityTest.cpp:4583; the trap is that a small buffer still adopts via AcquireMemoryRange (BufferObject.cpp:655), so the scenario must pin which arm it is testing.
5. Hardest across threads: the flush ladder's hostBase snapshot (Managers.cpp:1047-1076, :2739-2748, :1126-1129) and the client's push memo versus the server-local g_bufferContextGeneration / BumpBufferMutationEpoch (Managers.cpp:2573 / :2587 / :3293). s_synced (Managers.cpp:5490) is a role-isolation item. Bonus: the unlocked pendingRanges / pendingResidentWrites probes (Managers.cpp:2668 / :2676 / :2707 / :2712).